Commit acdcc2b33f82a29d6d8b03c8228ce11aaca9154a
1 parent
20815fb3
docs(wechat-auto-reply): 系统总文档 README(数据流/文件清单/设计决策/运维/收尾)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Showing
1 changed file
with
92 additions
and
0 deletions
wechat_plain/scripts/auto-reply/README.md
0 → 100644
| 1 | +# 微信自动回复系统（Pixel 端上） | |
| 2 | + | |
| 3 | +> 2026-07-08 ~ 07-10 建成。别人给微信发消息（私聊 / 群@我 / 群引用我）时，Pixel 上的 Hermes | |
| 4 | +> 自动读上下文、按火星人口吻生成回复，走**确定性安全闸**判定：白名单直发，其余进本地 Web 审批页 | |
| 5 | +> 等人工点发送。全链路端上，不经 Mac/云。 | |
| 6 | + | |
| 7 | +## 数据流 | |
| 8 | + | |
| 9 | +``` | |
| 10 | +微信来消息 | |
| 11 | + │ | |
| 12 | +① watcher（7×24, inotify 事件驱动, Magisk service.d 自启 + 看门狗） | |
| 13 | + │ su 解密读 message → 分类(私聊/群@我/群引用我) → 写 incoming.jsonl → fire-and-forget 触发 ↓ | |
| 14 | +② orchestrator --drain（cursor 增量 + 单实例锁 + 首跑基线） | |
| 15 | + │ ├─ env2 查上下文：rcontact 身份(备注>昵称>别名) + 最近 N 条历史（一次拷库全批复用） | |
| 16 | + │ ├─ env3 生成：hermes -z（deepseek-v4-pro，SOUL.md=火星人手机助手口吻） | |
| 17 | + │ └─ env4 判定：policy.decide() 确定性安全闸（白名单读 circle.db） | |
| 18 | + │ ├─ auto → send_text_via_hook 直接发 + reply_queue(auto_sent) | |
| 19 | + │ └─ review→ reply_queue(pending) | |
| 20 | + │ | |
| 21 | +③ wechat-viewer（Flask, 手机端 :5000） | |
| 22 | + ├─ /approvals 待审列表 + 可编辑草稿 + 【✅发送】【🗑取消】 | |
| 23 | + └─ /whitelist 白名单增删（联系人 / 群） | |
| 24 | +``` | |
| 25 | + | |
| 26 | +## 文件清单 | |
| 27 | + | |
| 28 | +| 文件 | 位置 | 作用 | | |
| 29 | +|---|---|---| | |
| 30 | +| `wechat_reply_watcher.py` | 设备 `~/.hermes/wechat_reply/` | ① 通知触发：inotify 监听微信 DB → 增量读新消息 → 分类 → 写 `incoming.jsonl` → 触发编排器 | | |
| 31 | +| `wechat_reply_daemon.sh` | 同上 | watcher 监督器：root+Termux 环境、单实例、等微信登录、看门狗崩溃重启 | | |
| 32 | +| `service.d__wechat-reply-watcher.sh` | 设备 `/data/adb/service.d/wechat-reply-watcher.sh` | 开机拉起监督器 | | |
| 33 | +| `wechat_reply_orchestrator.py` | 设备 `~/.hermes/wechat_reply/` | ②③④⑤ 编排：消费队列→上下文→生成→判定→落地 | | |
| 34 | +| `wechat_reply_policy.py` | 同上 | ④ 确定性策略引擎 `decide()→skip|auto|review` | | |
| 35 | +| `wechat-viewer` 改动 | 设备 `~/wechat-viewer/`（Flask） | ④⑤ UI：`/whitelist` + `/approvals`，新表 `reply_whitelist`/`reply_queue`，发送复用 `send_text_via_hook`。详见 `wechat-viewer-changes.md` + `viewer_templates/` | | |
| 36 | +| `wechat-db-decrypt` skill | 设备 `~/.hermes/skills/` | ② 上下文查询配方 + 密钥推导（`skill/` 留档） | | |
| 37 | +| `SOUL.md` | 设备 `~/.hermes/SOUL.md` | ③ 人设=火星人手机助手（留档一份） | | |
| 38 | + | |
| 39 | +> 本目录是 Mac 侧留档 / 版本源；设备是运行时。`wechat-viewer` 在手机上有自己的 git 工作树， | |
| 40 | +> 那部分改动已部署但由用户自己在该 repo 提交（本仓库只存改动说明 + 新模板）。 | |
| 41 | + | |
| 42 | +## 关键设计决策 | |
| 43 | + | |
| 44 | +- **环节1 为何事件驱动**：定时轮询要每次拷 90MB 微信库，耗电。改用 ctypes inotify 监听 DB 文件写入（SELinux 放行，零轮询、空闲零 CPU），失败退回 stat mtime。 | |
| 45 | +- **环节2/3 为何不写模块**：Hermes 本身是有 shell+SQL 的 agent，查上下文=skill 配方，生成=它自己。只有编排器把这些串起来才需要代码。 | |
| 46 | +- **环节4 为何必须是确定性代码**：环节3 实测「SOUL.md 里的软约束会漏」（约饭案例模型仍主动接话）。安全门必须是 LLM 说服不动的硬规则：default-deny + 敏感词（钱/承诺/约时间/隐私，白名单也拉回）+ skip（群没@我/公众号/系统消息/自己发的）。 | |
| 47 | +- **账号自适应**：运行时 `MD5("mm"+uin)` 定位当前登录账号，`MD5("1234567890ABCDEF"+uin)[:7]` 推导 SQLCipher key，多账号切换自动跟随（不硬编码）。 | |
| 48 | +- **失败即静默**：生成超时/失败 → 无草稿 → policy skip → 不发。最坏情况是不回，绝不误发。 | |
| 49 | + | |
| 50 | +## 运维 | |
| 51 | + | |
| 52 | +**看状态** | |
| 53 | +```bash | |
| 54 | +adb shell 'su -c "pgrep -f wechat_reply_watcher.py"' # watcher 活着? | |
| 55 | +adb shell 'su -c "tail -5 ~/.hermes/wechat_reply/watcher.log"' # 采集日志 | |
| 56 | +adb shell 'su -c "tail -5 ~/.hermes/wechat_reply/orchestrator.log"' # 编排日志 | |
| 57 | +# 审批页：手机浏览器开 http://127.0.0.1:5000/approvals | |
| 58 | +``` | |
| 59 | + | |
| 60 | +**自检 / 手动跑** | |
| 61 | +```bash | |
| 62 | +python wechat_reply_watcher.py --selftest # 推导key/解密/inotify 是否 OK | |
| 63 | +python wechat_reply_watcher.py --once # 单读一遍新消息 | |
| 64 | +python wechat_reply_policy.py --demo # 策略 8 用例自检 | |
| 65 | +python wechat_reply_orchestrator.py --drain # 手动跑一轮编排 | |
| 66 | +``` | |
| 67 | + | |
| 68 | +**开启自动发（默认全审核）** | |
| 69 | +1. 在 `/whitelist` 加信任的联系人 / 群（`xxx@chatroom` 自动识别为群）。 | |
| 70 | +2. 把 `~/.hermes/wechat_reply/policy_config.json` 的 `auto_send_enabled` 设 `true`。 | |
| 71 | + - 敏感词（钱/承诺/约时间/隐私）即使白名单也仍会拉回人工审批。 | |
| 72 | + - 建议先审核模式跑几天，草稿质量稳了再放开。 | |
| 73 | + | |
| 74 | +## 真机验证（2026-07-10） | |
| 75 | + | |
| 76 | +- inotify 触发读取 → 写队列 → 自动拉起编排器 ✅ | |
| 77 | +- 真实猎头上下文 → 生成火星人口吻草稿「哈哈婷婷，我不是什么总，就是个写代码的，不负责招人这块哈」→ 进 /approvals ✅ | |
| 78 | +- 审批页发送 → `send_text_via_hook` 广播到 filehelper(sent)、取消(cancelled) ✅ | |
| 79 | +- 策略引擎 8/8、多账号自适应、生成失败静默不误发 ✅ | |
| 80 | +- 单实例防重、杀 watcher 自动重启、纯 root(boot 上下文) selftest ✅ | |
| 81 | + | |
| 82 | +## 待收尾（都非阻塞，系统已可用） | |
| 83 | + | |
| 84 | +1. **原生引用气泡 / 群@昵称前缀**：现发纯文本；微信原生引用（A11y 长按→引用）是环节5 增强。 | |
| 85 | +2. **日志轮转**：watcher/orchestrator log 24/7 会长（ponytail 已标）。 | |
| 86 | +3. **lifelog 人物增强**（二期）：回链 `com.lemon.lifelog` 的 Person 库让回复带人物记忆。 | |
| 87 | +4. **auto_send 开关搬进 viewer UI**：目前在 policy_config.json，可加到 /whitelist 页。 | |
| 88 | + | |
| 89 | +## 相关文档 | |
| 90 | +- `../../../md/wechat-auto-reply-requirements.md` — 需求 + 逐环节设计/状态 | |
| 91 | +- `wechat-viewer-changes.md` — viewer 集成改动全记录 | |
| 92 | +- `skill/wechat-db-decrypt-SKILL.md` — 微信 DB 解密 + 上下文查询配方 | ... | ... |