# AGENTS.md — 微信自动回复 bot 维护入口

> 接手维护这台 Pixel 微信自动回复 bot 的 agent，先读这份，再读 `HANDOFF.md`（完整细节，尤其 **§零 环境须知**）。
> 这个文件夹 `~/hermes-wechat/` 同时是**运行时**和**唯一源**（手机上无 git，改完要同步回 Mac repo）。

## 这是什么

Pixel 本机的微信自动回复机器人（账号「小火子」`wxid_51ap3m6p9xs722`）。链路：
轮询微信加密 DB（sqlcipher）拿新消息 → 调本机 hermes 网关 `127.0.0.1:8642` 生成回复 → `am broadcast` 触发 `HermesAccessibilityService` → A11y UI 自动化点微信（搜联系人→进聊天→输入→发送）。**唯一能真把消息发出去的方式 = A11y UI 自动化。**

## 协作分工（混合模式：claude-run + hermes）

| 角色 | 跑在 | 能力 | 干什么 |
|------|------|------|--------|
| **claude-run（Claude）= 脑子** | proot 容器 | 能编辑本目录 `*.js`、读 `auto-reply.log`、读改 `.whitelist.json`；**不能 su**，但可 `touch .restart-request` 让 keepalive 代为重启 | 写 / 改 / 审代码、看日志诊断 |
| **hermes（Kimi）= 手** | Termux（能 su） | 能 `su -c` 拿 Magisk root | 跑需要 root 的设备操作：重启 bot、查微信 DB、发测试消息、logcat、重开 A11y |

> claude-run 在 proot 里够不到 Magisk root，也看不到微信 DB（没挂载）。需要 root 的步骤交给 hermes 或 Termux shell 执行。

## 核心文件（bot 实跑只这三个，别被目录里其他文件带偏）

- `auto-reply.js` — 主程序（消息 FSM、白名单门禁/授权、流式 SSE、引用回复 normalize）
- `android-wechat-tracker-sqlcipher.js` — 轮询微信加密 `EnMicroMsg.db` 检测新消息
- `android-wechat-sender.js` — `am broadcast` → A11y service 发送
- `HANDOFF.md` — 完整部署地图 / 命令速查 / 避雷清单 / 架构 / 白名单授权
- 其余 `index.js / wechat-*.js / *-frida.js / *-sqlite.js / test-*.js / *.apk / *.dex` **都不参与 bot 运行**

## 环境铁律（细节见 HANDOFF §零）

1. **bot 以 root 跑、agent 以 u0_a327 跑** → 看进程 / 读 root 文件 / 查微信 DB / 重启 都要 `su -c`（只有 Termux 侧能 su；proot 里的 claude-run 不行）。
2. **唯一 live 日志 = 本目录 `auto-reply.log`**。别处任何同名副本都是死的（曾坑过接手者误判「bot 没在跑」）。
3. claude-run 的 Bash 若报 `EACCES: permission denied, mkdir '/root/.claude/session-env'`：是 `~/.claude` 被 chown 成 root 了。在 **Termux shell**（不是 claude）跑 `su -c 'chown -R u0_a327:u0_a327 /data/data/com.termux/files/home/.claude'`，再重开 claude-run。

## 改代码 → 生效（内循环）

1. **改**：claude-run 直接编辑本目录 `*.js`。
2. **重启**（让新代码生效）：
   - **claude-run（无 su）**：`touch ~/hermes-wechat/.restart-request` —— keepalive（每 15s 巡检、已是 root）看到这个 flag 就杀掉 auto-reply 并用新代码重启，~15s 内生效。**这是 claude-run 自助重启的唯一方式**（它在 proot 里杀不了 root 进程）。
   - **hermes / Termux（有 su）**：直接 `su -c 'pkill -f auto-reply.js'`，keepalive 随即重启。
   - 确认新进程：`su -c 'ps -ef | grep -E node.auto-reply.js | grep -v grep'`（**别用 `pgrep -f`，会自匹配 su shell**）。
3. **看**：`tail -f ~/hermes-wechat/auto-reply.log`（claude-run 不带 su 也能读，日志 644）。
4. **同步回 Mac**：手机无 git，改完把改动同步回 Mac repo `server/services/wechat/`，否则下次 Mac 跑 `deploy-to-phone.sh` 会覆盖你的改动。

## 调试设备状态的常用 su 命令（交给 hermes / Termux）

```bash
# 查微信 DB 最近消息（确认 tracker 是否捕获/被过滤）
su -c 'cp /data/data/com.tencent.mm/MicroMsg/653cdc2320abb089e149a3f7a7683fcf/EnMicroMsg.db ~/_chk.db'
sqlcipher ~/_chk.db "PRAGMA key=\"e03ce81\"; PRAGMA cipher_compatibility=1; SELECT msgId,type,isSend,talker,substr(content,1,60) FROM message ORDER BY msgId DESC LIMIT 10;"
# 手动发测试消息
su -c "am broadcast -a com.hermes.wechat.SEND_MSG --es toUser yibooo --es toUserDisplayName 火星人 --es content 'test'"
# A11y service 实际 UI 操作日志
su -c 'logcat -s HermesA11y:*'
# A11y 被关了重新启用
su -c 'settings put secure enabled_accessibility_services com.hermes.wechat.xposed/com.hermes.wechat.xposed.accessibility.HermesAccessibilityService; settings put secure accessibility_enabled 1'
```

## 已知 bug / TODO

见 `HANDOFF.md` §八（避雷清单）和 §七（待办）。bot 回复模型当前是 hermes 默认的 Kimi-k2.6（claude-run 用 Claude 写代码；hermes 因 Anthropic 第三方计费策略不复用订阅 token）。