微信通用通道

安装后将下文 <SKILL_ROOT> 替换为本 Skill 的实际绝对路径，先在安装目录执行 python -m pip install -r requirements.txt、node scripts/cli.mjs add --account main --label 我的微信，再按使用者要求执行 doctor、login。代码、配置、凭据、状态和测试都在本 Skill 内。仅适用于微信官方 ClawBot 私聊。

能力与入口

统一命令：node <SKILL_ROOT>/scripts/cli.mjs <命令>。

功能	命令	行为与边界
查看所有微信	accounts	列出稳定英文别名、默认账号、运行状态和推送是否就绪；不输出微信 ID 或凭据
新增微信账号	add --account work --label 工作微信，然后 login --account work	独立端口、凭据、接收游标、上下文和发送记录；默认仅接收推送
扫码绑定	login --account main	自动启动该账号服务；打开返回的本机地址扫码，手机确认后生效
更换微信	login --account main --replace	新扫码确认后才替换；其他别名不受影响；旧推送上下文清空
取消扫码	cancel-login --account main	保留原绑定；过期二维码或迟到的确认不能再生效
手机数字验证	verify --account main --code 123456	只在扫码要求输入验证码时使用
选择默认管理账号	use --account work	仅改变省略账号时的管理默认值；发送始终显式选择账号
接到 Codex 任务	route --account work --mode chat --thread UUID --rollout FILE	先停止该账号；用已核实的现有任务与对应运行记录。每个聊天账号使用独立任务
引用回复回原对话	发送默认记录 CODEX_THREAD_ID；可用 send --source-thread UUID 显式指定已核实来源	本人引用已登记消息后只投递来源对话，并带上当时内容；普通消息仍进默认聊天，不切换全局路由
微信图片入站	聊天模式自动接收，无需新增扫码或修改账号路由	下载解密后传递当前聊天的本地图片路径；识图前用 view_image；失败必须明确说明；实现与实收验证状态分别核对 [入站图片](references/integration.md#入站图片)
只接收推送	route --account work --mode push	先停止该账号；微信消息只更新推送上下文并回复通道状态，不投递 Codex
启动/停止/状态/检查	start/stop/status/doctor --account main	隐藏后台服务、已保存绑定复用、Python/任务检查
文字推送	send --account main --id UNIQUE --text 内容	必须指定账号和本次业务唯一编号；支持 --text-file UTF-8 文件
图片推送	send --account main --id UNIQUE --text 摘要 --image 完整图片路径	PNG/JPEG、最多 5 张、每张最多 20 MiB；校验允许输出目录，先上传成功再发摘要
文件推送	send --account main --id UNIQUE --file 完整文件路径	可重复 --file，可附文字；图片与文件合计最多 5 项、每文件 1 字节至 20 MiB；从独立文件输出白名单读取，先上传再发送
Markdown 报告推送	send --account main --id UNIQUE --markdown-file 完整报告路径	提取本地图片并分开发送文字/图片，适合库存摘要和合并长图
预检	给 send 增加 --dry-run	校验账号、图片/文件、内容和上下文，不上传、不发送、不占用唯一编号
明确补发失败报告	原 send 命令增加 --retry-failed	仅在用户已要求恢复投递、原记录明确失败且提交 0 部分、失败后收到新消息时使用；同编号同内容同绑定，保留原失败记录
结果查询	receipt --account main --id UNIQUE	查持久化记录，不重发
处理未完成消息	pending --account main；resolve --account main --id UUID --outcome received 或 discarded	仅在用户确认已收到或明确放弃后，结束失败/结果未知的入站消息；不重发、不丢弃正在运行的任务

完整接口、故障处理、定时任务接入见 [调用与集成](references/integration.md)。官方协议来源与限制见 [协议边界](references/protocol.md)。

引用回复

使用者明确要求启用引用回复后，才将本人在微信引用消息的新回复送回该来源对话，并把该轮最终答复回传本人微信。引用中保存的原文仅为数据，新回复才是本轮指令。仅转发包含该入站编号的轮次；不监听或转发原对话的其他工作。来源与绑定账号隔离，引用失败不回落到默认聊天猜测。

发送使用现有 send / pushMessage，默认从 CODEX_THREAD_ID 记录来源；非 Codex 调用者需要显式提供已核实的 --source-thread / sourceThreadId。禁止根据内容、货号、日期或最新文件猜来源。引用优先精确匹配官方 ref_msg.svr_id，为空时兼容 ref_msg.message_item.msg_id（可仅有 type=0 和编号）；同时识别本次已提交的服务器 ID 与客户端发送 ID。旧客户端没有任何编号时仅完整内容唯一匹配才兼容，标题摘要、截取片段、多义和未登记旧消息都明确返回未执行。旧回执没有保存服务器消息 ID，不能承诺升级前的消息可路由，也不能重发采购或业务报告来补记录。

快照以 Windows DPAPI 加密保存在本账号状态，保留 30 天、最多 10000 个消息部分；附件仍在原产物目录，发送时保存 SHA256，引用时重新核验。原对话归档、附件缺失或变化则停止，不另开对话替代。未引用的写入指令如“按今天早上的采购”，只有当前对话能唯一确定清单才执行；不能扫描其他对话或选最新文件补齐，应请用户引用具体消息。

消息处理规则：

微信消息	投递与归档处理
引用已登记消息	回到实际发送它的来源对话；忙则等待，归档则明确停止，不另开替代对话
没有引用	进入该账号当前配置的默认聊天；不延续上一条引用的来源
默认聊天已归档	仅当该账号已授权并启用 autoNewChatOnArchive，下一条普通消息才创建独立聊天；新聊天不带旧历史
/ping	本机立即回复并刷新推送上下文，不启动 Codex，也不触发新建聊天

“按早上的清单”“把那个撤销”等写入请求必须能从当前对话唯一确定目标，否则请用户引用具体消息。这是传给 Codex 的执行规则，不是桥接层对业务目标的硬性校验；不能宣称能阻止所有误操作。

测试入口：node --test <SKILL_ROOT>/tests/quote-routing.test.mjs。协议与离线测试不能替代真实手机引用验收；实收状态见 [引用路由验证](references/integration.md#引用路由验证)。

执行规则

1. 用户已经要求绑定、换绑或给指定微信推送时，按其范围执行。调用前用 accounts 确认账号；多个微信时不能猜收件人，定时任务固定显式别名，禁止自动群发。
2. 新增微信用新别名；换绑现有别名才用 --replace。扫码需账号持有人在手机确认，不能代扫或在无确认时报告绑定成功。可在 Codex 中打开命令返回的本机连接页。
3. 绑定后请用户从该微信向 ClawBot 发送 /ping。它会立即在本机处理并回复，不占用 Codex 任务；这也更新主动推送所需的上下文。新账号、换绑或缺少该账号的上下文时需要刷新；本机不按收到消息的时间限制主动推送。
4. submitted 只表示微信 API 接受了各部分，不等于手机已显示；deliveryConfirmed 始终为 false。真实到达需用户确认。failed 报告明确失败，uncertain 表示发送结果未知。未知结果不自动重发；使用原编号查记录。 state=connected 只表示接收连接在线。pushState 区分 unverified（已有会话凭据，尚无本上下文发送结果）、accepted、rejected、failed 和 uncertain；后三者的 pushReady=false，lastPush 给出脱敏阶段与错误码，不能仅凭连接在线声称可以推送。收到新的有效入站消息后重新判断，历史失败和未知回执不会被删除或自动重放；不按未经核实的 24/48 小时规则失效凭据，也不将 -2 直接认定为过期。
5. 一个业务运行固定一个 --id，例如 inventory-20260921-0900；同编号同内容只返回原记录，同编号不同内容或换绑后返回冲突。不要为了绕过失败记录自动生成新编号。同一条报告往不同账号发送须分别得到明确目标授权。 用户已要求补发或恢复本次投递时，先核对原 receipt，只对 failed 且 partsSubmitted=0 的记录使用 --retry-failed；必须先收到晚于失败时间的新消息，使用原编号和原内容，不能重跑业务。未知、部分提交、提交中和已成功记录仍冻结或返回原回执。定时任务不能因为看到该选项就自动补发。
6. 凭据由当前 Windows 用户 DPAPI 加密，状态目录只授权本人和 SYSTEM。不输出或复制 token、上下文、凭据文件、扫码原始链接；日志只记录必要元数据。不能将其他任务的对话自动转发到微信。
7. 入站支持文字、有转写的语音，以及单独或混排的图片（PNG/JPEG/GIF/WebP，最多 5 张，每张最多 20 MiB）。桥接先下载并按官方 AES-128-ECB 协议解密，保存至该账号 state/accounts/<别名>/inbound/<绑定ID>/<消息ID>/，将本地绝对路径传递当前 Codex 聊天；收到图片时先用 view_image 查看全部图片再回答。图片下载参数和密钥仅在待处理期间以 DPAPI 加密保存，日志不含图片内容、地址或密钥。读取失败须明确说明，不能猜测内容。旧版已转换为提示且未保存下载参数的附件不承诺恢复；无转写语音、文件和视频入站仍提示改用文字。出站支持文字、PNG/JPEG 和文件附件；视频消息与群聊不在当前能力内。文件通过正式 send --file 发送，不临时解密凭据另建发送脚本；旧服务缺少文件能力时先安全重启该账号，再用 --dry-run 核验。
8. 后台服务需本机运行；双向聊天另需 Codex 桌面在线。默认不启用 autoNewChatOnArchive；使用者明确授权并设置该账号选项后：原聊天归档后，下一条普通微信消息自动新建并切换到专用聊天，原聊天保持归档；新对话不携带旧历史。先判断归档，再检查旧轮次是否结束；旧轮次未确认的回复保留为 archived_reply_unconfirmed，不重放、不阻塞新聊天。新建前先读取发起聊天；旧聊天已无法读取时明确报 desktop_caller_unavailable，由当前修复聊天按既有授权恢复，不把它误报成已执行新建。/ping 在本机处理，不触发新建，也不能代替双向聊天验收。真正的创建结果未知时冻结，禁止重复新建；具体恢复规则见故障处理。其他账号默认不启用。当前未设置开机自启。需要新增/修改定时任务时使用 Codex 自动化工具，不手写调度器配置。

数据归属与验证

• scripts/：通用接口、账号、协议、图片与文件、桌面适配和管理页；Node 24，Python 需 pywin32、opencv-python、psutil，doctor 检查现有依赖。
• config/accounts.json：别名、端口、任务路由、图片输出目录 allowedImageRoots 和文件输出目录 allowedFileRoots；旧账号未设置文件目录时只允许本 Skill 的 outputs/，不扩展整个桌面或 Home。默认账号仅供管理。
• state/accounts/<别名>/：该账号的 DPAPI 凭据、状态、发送结果及日志；state/tests/ 仅存本 Skill 测试临时文件，测试自动清理。
• outputs/：本 Skill 测试图片及验收结果；快麦等业务报告继续保留在各自目录，只按配置读取。
• tests/：node --test <SKILL_ROOT>/tests/*.test.mjs。覆盖多账号隔离、换绑/取消、去重、异常恢复、图文/文件协议、附件范围和大小、报告适配、HTTP 保护和桌面消息归属。
• 图片接收的当前验证证据及限制见 [入站图片验证](references/integration.md#入站图片验证)；离线通过、服务在线、主动上传测试和真实微信入站是不同证据，不可互相替代。
• 文件发送说明及真实 ZIP 接口受理证据见 [文件附件](references/integration.md#文件附件)。20 MiB 是本实现的保护限额，不声称是微信官方的最大附件限制。
• 修改后先跑离线测试，再做真实 /ping、文字与图片到达确认；多账号与真实换绑需要对应手机扫码。未完成手机步骤时必须明确标记待验证，不能以模拟测试代替真实到达。