PackingProof 微信录像机器人

这是一个独立运行的 PackingProof external-adapter 扩展。它通过 PackingProof 扩展 API v1 查询和下载录像，不读取数据库、录像目录或 NAS 凭据。机器人核心与聊天平台解耦：内置企业微信频道和本地调试频道，新增平台只需按 Channel 契约实现一个适配器文件。

本仓库遵循 PackingProof 扩展市场协议 v1：payload/ 是可运行的独立机器人，manifest.json 描述安装包。

功能

• 群内 @机器人并发送快递单号 → 查询 PackingProof 录像
• 未超限录像直接下载原片；超过平台上限（默认 45 MB）时请求主机生成受控转码副本，不改动原片
• 逐段上传并回复到原群聊，带标题「单号 打包录像 N/M」
• 多频道并发：BOT_CHANNELS=wecom,console 可同时连接多个平台，共用同一套核心逻辑
• 会话级限流（默认每分钟 6 次）、扩展 API 心跳保活、授权失效自动停止并提示重新授权

频道

频道 ID	说明	必需配置
wecom	企业微信智能机器人（官方 API 模式 → 长连接，不使用个人微信 Hook 或非官方协议）	WECOM_BOT_ID、WECOM_SECRET
console	本地调试频道，终端输入单号、终端输出回复，零配置	无

安装（PackingProof 扩展）

1. 在 GitHub Release 下载 369431.wechat-recording-bot-1.0.0.ppext，或从 PackingProof 扩展市场 安装
2. 在 PackingProof 的「设置 → 扩展与联动」中开启「启用扩展 API」
3. 导入并安装扩展；外部适配器需要手动启动（payload/start.cmd）
4. 首次启动时在 PackingProof 弹窗中批准录像查询、下载和交付副本权限

手动运行（开发模式）

要求 Node.js 20 或更高版本，以及支持扩展 API v1 的 PackingProof Desktop。

1. 在企业微信智能机器人后台选择「API 模式 → 长连接」
2. 进入 payload/，复制 .env.example 为 .env，填写 WECOM_BOT_ID 和 WECOM_SECRET
3. 在 PackingProof 的「设置 → 扩展与联动」中开启「启用扩展 API」
4. 在 payload/ 目录执行 npm install 和 npm start
5. 首次启动时在 PackingProof 弹窗中批准录像查询、下载和交付副本权限
6. 在企业微信群中 @机器人并发送快递单号

没有企业微信配置时联调

.env 中设置 BOT_CHANNELS=console 后运行 npm start，直接在终端输入快递单号即可验证「查询 → 下载/转码 → 回传」全流程：

[进度] 正在查询单号 YT123456 的录像…
[回复] 找到 1 段录像，正在准备上传…
[上传] yt123456.mp4（12.3 MB）→ console-media-1
[视频] YT123456 打包录像 1/1（由 PackingProof 查询并发送，mediaId=console-media-1）

配置项

变量	默认值	说明
BOT_CHANNELS	wecom	启用的频道，逗号分隔可多选
PACKINGPROOF_BASE_URL	http://127.0.0.1:5280	PackingProof 扩展 API 地址
MAX_VIDEO_SIZE_MB	45	转码目标上限，也是「超过即转码」阈值（1–200）
RATE_LIMIT_PER_MINUTE	6	每会话每分钟查询上限（1–600）
HEARTBEAT_SECONDS	15	扩展 API 心跳间隔（5–60）
PACKINGPROOF_EXTENSION_INSTANCE_ID	自动生成	固定扩展实例 ID，用于测试或工位绑定
WECOM_BOT_ID / WECOM_SECRET	—	wecom 频道必需
CONSOLE_CHAT_ID	console	console 频道会话标识

扩展性

机器人核心（payload/src/bot-core.js）与聊天平台解耦，通过 Channel 契约接入不同平台。新增平台时在 payload/src/channels/ 实现频道适配器（导出 meta 与 create），在 channels/registry.js 登记一行，即可复用查询、下载、转码、限流和回传逻辑。详细步骤和契约见 DESIGN.md。

安全说明

• 不使用个人微信 Hook、桌面注入或非官方协议
• 密钥、授权凭据和运行状态均被 Git 忽略（.env、.state/、node_modules/），状态文件权限为 0600
• 不把企业微信密钥、PackingProof 凭据或录像真实路径写入源码、日志和消息
• 对群消息按会话限流，并限制单号长度和字符集（6–64 位字母数字）
• 收到授权撤销或凭据轮换错误时停止重试，要求重新授权

测试

cd payload
npm run check
npm test

测试全部离线运行：协议测试使用本地 HTTP 主机逐请求重算 HMAC 签名，不依赖 PackingProof 或企业微信。

开发文档

架构设计、Channel 契约和「新增频道」步骤见 DESIGN.md。

许可证

AGPL-3.0-only