docs: HANDOFF 加白名单门禁 + 授权流程章节（§十三）

- 角色（机器人本体 / owner）、门禁判定逻辑、授权交互（同意/拒绝） - .whitelist.json 格式 + 手动加白名单方法 - 引用回复授权的坑（type 57 appmsg，title + refermsg 提取） - 相关方法表 - TL;DR 加 step 0 白名单门禁；避雷清单加引用回复授权条目 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs: HANDOFF 加白名单门禁 + 授权流程章节（§十三）
- 角色（机器人本体 / owner）、门禁判定逻辑、授权交互（同意/拒绝） - .whitelist.json 格式 + 手动加白名单方法 - 引用回复授权的坑（type 57 appmsg，title + refermsg 提取） - 相关方法表 - TL;DR 加 step 0 白名单门禁；避雷清单加引用回复授权条目 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
yibo
1 parent 4cb28d27
Showing 1 changed file with 99 additions and 1 deletions
server/services/wechat/HANDOFF.md
@@ -3,7 +3,7 @@
 > **谁会读这份文档**：刚接手这台 Pixel 部署的 claude-run / 开发者，没有上下文。
 > **目标**：5 分钟搞清楚正在跑什么、文件在哪、怎么改、怎么验证。
 >
-> **生成时间**：2026-05-25（v2，加 FSM + 流式 + hermes 补丁章节）。请定期核对实际状态，
+> **生成时间**：2026-05-25（v3，加 FSM / 流式 / hermes 补丁 / 白名单授权 章节）。请定期核对实际状态，
 > 因为本文件不会随代码自动更新。
 ---
@@ -12,6 +12,7 @@
 Pixel 手机本地的微信自动回复机器人。当好友（如 `yibooo`）给本机微信账号（小火子 / `wxid_51ap3m6p9xs722`）发消息，系统会：
+0. **白名单门禁**（5/25 加）：只对白名单的群/私聊自动回；非白名单先转给 owner 请示授权（详见 §十三）
 1. **轮询微信加密 DB**（sqlcipher）拿到新消息
 2. **拉最近 N 条上下文**喂给 hermes-agent (`POST 127.0.0.1:8642/v1/chat/completions`)
 3. hermes 后端走 **Moonshot CN**（kimi-k2.6）生成回复（通过 Clash mixed port 出网）
@@ -299,6 +300,7 @@ pkill -f auto-reply.js
 | Hermes `/v1/runs` 长时间一片寂静、无任何 `[UTTER]` 事件输出，最后 `run.completed` 一次性给一大段总结 | Kimi-k2.6 在 hermes agentic mode 下 `assistant_message.content` 永远空，所有内容在 `reasoning_content`；`message.delta`/`interim_assistant_callback`/`message.complete` 都不 fire；只有 `reasoning.delta` 大量喷涌 | 短期开 `STREAM_REASONING=true` 让 reasoning 加 `🧠` 前缀作 utterance；长期改 hermes system prompt 让 Kimi 写 content 字段。详见 §十二.4 |
 | auto-reply node 进程被 keepalive 反复重启，CPU 占用高、log 文件被洪水般写入 | 流式场景下高频 `message.delta`/`reasoning.delta` 事件触发同步 `fs.appendFileSync` + 每条都 console.log，sync I/O 卡死 node；keepalive 检测心跳超时 → kill → restart | `log()` 去掉 `appendFileSync`（stdout 已由 start 脚本重定向到 log file）；诊断事件加节流（高频事件 5 秒打一次） |
 | Hermes `/v1/runs` 只输出"最终一条回复"，没多步进度 | hermes 默认 `/v1/runs` 只挂 `stream_delta_callback` + `tool_progress_callback`，缺 `reasoning_callback` + `interim_assistant_callback`（gateway 平台用 7+ 个回调） | 补丁 `gateway/platforms/api_server.py`，在 `_create_agent` 签名 + AIAgent 构造 + run handler 三处都加上缺的两个回调，emit `reasoning.delta` / `message.complete` SSE 事件。详见 §十二.3 |
+| owner 回「同意」授权后没生效、pending 没清 | owner 用微信**引用回复**发「同意」，content 是 type=57 appmsg XML（`<title>同意</title>` + `<refermsg>`），不是纯文本，`parseApprovalCommand` 正则匹配不上 | parseApprovalCommand 检测 `<appmsg>`/`<refermsg>` → 提取 `<title>` 作回复文本 + `<refermsg>` 作 quotedContext 匹配目标。详见 §十三.6 |
 ---
@@ -439,4 +441,100 @@ auto-reply.js                  hermes (/v1/runs)            Moonshot CN
 ---
+## 十三、白名单门禁 + 授权流程（5/25 新增）
+
+### 13.1 目的
+
+不再对任何人自动回复。只有**白名单**的群 / 私聊才自动回；非白名单的发信人，
+机器人先**转给主人（owner）请示**，owner 回「同意」才授权。
+
+### 13.2 角色
+
+| 角色 | wxid | 说明 |
+|------|------|------|
+| 机器人本体 | `wxid_51ap3m6p9xs722`（小火子） | 跑 auto-reply 的微信账号 |
+| **owner（主人/授权者）** | `yibooo`（火星人） | 收授权请求 + 发「同意/拒绝」指令；**永远在白名单** |
+
+ENV：`OWNER_WXID`（默认 `yibooo`）、`OWNER_NICKNAME`（默认 `火星人`，A11y 搜索用）。
+
+### 13.3 门禁判定（`handleMessage` 内，replyType 判定之后）
+
+```
+senderWxid = 群聊 ? content 前缀里的发送者 wxid : talker
+isFromOwner = senderWxid==OWNER || talker==OWNER
+
+if isFromOwner:
+    parseApprovalCommand(content) 命中 → handleApproval（同意/拒绝），return
+    否则放行（owner 普通聊天）
+elif !whitelist.isAllowed(talker):
+    requestAuthorization（转 owner 请示），return   ← 不回复发信人
+else:
+    generateAndSendReply（正常流程）
+```
+
+注意：**白名单 key 是 talker**（私聊=对方 wxid，群聊=chatroom id），即"授权这个会话"。
+群里只要 chatroom 在白名单，任何人 @ 都会自动回。owner 在任何群 @ 都放行（按 senderWxid 判断）。
+
+### 13.4 授权交互
+
+- **请示**：`requestAuthorization` 给 owner 发
+  `【授权请求】X 给我发消息了：「...」回复「同意」我就自动回复 TA；回复「拒绝」忽略。`
+  并记入 pending（同一 talker 不重复请示）。
+- **同意**：owner 回 `同意` / `同意 宜创AI全员群`（指定）→ 加白名单 + **自动回复 TA 刚才那条 pending 消息** + 给 owner 发确认。
+- **拒绝**：owner 回 `拒绝` / `忽略` → 移除该 pending。
+- 指令动词：`同意|授权|批准|approve|allow|yes` vs `拒绝|忽略|不同意|deny|no`。
+
+### 13.5 `.whitelist.json` 格式
+
+位于 `~/hermes-wechat/.whitelist.json`（持久化，重启不丢）：
+
+```json
+{
+  "allowed": ["yibooo", "34576206251@chatroom"],
+  "pending": {
+    "wxid_g240cr5svks122": {
+      "senderName": "",
+      "content": "好的哈[社会社会]",
+      "displayName": "马锐模",
+      "ts": 1779684269591
+    }
+  }
+}
+```
+
+- `allowed`：已授权的 wxid（私聊）+ chatroom id（群）。owner wxid 启动时自动加入。
+- `pending`：待授权请求，key 是 talker，value 含 senderName / 原始 content / displayName / 时间戳。
+- 手动加白名单：直接编辑此文件加到 `allowed` 数组，重启 auto-reply 生效。
+
+### 13.6 ⚠️ 引用回复授权的坑
+
+owner 如果用微信**引用回复**发「同意」（而不是直接打字），content 不是纯文本
+「同意」，而是 **type=57 appmsg XML**：
+
+```xml
+<msg><appmsg><title>同意</title><type>57</type>
+  <refermsg>...被引用的"【授权请求】宜创AI全员群..."原文...</refermsg>
+</appmsg></msg>
+```
+
+`parseApprovalCommand` 必须：
+1. 检测 `<appmsg>`/`<refermsg>` → 从 `<title>` 提取真正的回复文本（"同意"）
+2. 从 `<refermsg>` 提取 `quotedContext` → 匹配是"同意哪条 pending"（引用了哪条授权请求）
+
+`handleApproval` 目标匹配优先级：显式 target → quotedContext 里出现的 pending
+displayName → 最近一个 pending。
+
+### 13.7 相关方法（auto-reply.js）
+
+| 方法 | 作用 |
+|------|------|
+| `WhitelistStore` | 持久化 allowed/pending |
+| `parseApprovalCommand(content)` | 解析授权指令（含引用回复 XML 提取），返回 `{approve, target, quotedContext}` |
+| `requestAuthorization(talker, senderName, content)` | 转 owner 请示 + 记 pending |
+| `handleApproval(cmd)` | 同意→加白名单+回复 pending；拒绝→移除 |
+| `generateAndSendReply({...})` | 抽出来的回复生成（白名单通过 / 授权后复用） |
+| `sendPlainTo(toUser, displayName, text)` | 给 owner 发纯文本（不走 hermes） |
+
+---
+
 **END OF HANDOFF** — 改动这份文档时记得更新顶部生成时间。