254 lines
10 KiB
Markdown
254 lines
10 KiB
Markdown
# 🤖 WeChat Hermes Gateway
|
||
|
||
Windows 微信机器人 ↔ Linux Hermes AI，全自动双向聊天。
|
||
|
||
---
|
||
|
||
## 最终架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ Windows 192.168.0.111 │
|
||
│ │
|
||
│ ┌──────────────────┐ ┌───────────────────────────┐ │
|
||
│ │ 微信 3.9.5.81 x64 │ │ 日常微信 WeChatAppEx 4.x │ │
|
||
│ │ 机器人号modachen │ │ 老爸日常使用，互不干扰 │ │
|
||
│ │ wxhook Bot类TCP │ └───────────────────────────┘ │
|
||
│ └────────┬─────────┘ │
|
||
│ │ wxhook DLL 收消息 │
|
||
│ ┌────────▼────────────────┐ │
|
||
│ │ wechat_agent.py │ ← 常驻进程 │
|
||
│ │ │ │
|
||
│ │ Bot类接收微信事件(TCP) │ │
|
||
│ │ → POST Hermes API :8642 │ ← 带session: sisyphus │
|
||
│ │ ← 收回复 → wxhook发回 │ │
|
||
│ │ :5801 ←Hermes找小小莫 │ ← 双向通道 │
|
||
│ │ 看门狗防 wxhook 挂掉 │ │
|
||
│ └────────┬────────────────┘ │
|
||
└───────────┼─────────────────────────────────────────────────┘
|
||
│ HTTP (局域网)
|
||
┌───────────▼─────────────────────────────────────────────────┐
|
||
│ Linux 192.168.0.103 │
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ Hermes Gateway │ │
|
||
│ │ - API Server :8642 │ ← OpenAI兼容API │
|
||
│ │ - session自动重置: 已关闭 │ ← sisyphus永不清 │
|
||
│ │ - 健康检查 /health │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
│ hermes CLI — AI 处理引擎 │
|
||
│ 莫荷/莫小荷 — 老爸专属称呼 │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 数据流
|
||
|
||
### 文字消息
|
||
|
||
```
|
||
老爸发微信
|
||
→ WeChat 3.9.5.81 收到
|
||
→ wxhook DLL TCP → Bot 类 → on_msg 处理器
|
||
→ wechat_agent.py POST Hermes API (:8642)
|
||
→ X-Hermes-Session-Id: sisyphus (固定)
|
||
→ Hermes 处理 → 返回回复
|
||
→ wechat_agent.py 收回复 → wxhook API 发回
|
||
→ 老爸手机收到
|
||
```
|
||
|
||
### 图片消息
|
||
|
||
```
|
||
老爸发图片
|
||
→ WeChat 收到 → wxhook IMAGE_MESSAGE 事件
|
||
→ wechat_agent.py 保存图片 → 调豆包OCR (VolcEngine)
|
||
→ OCR 文字结果 + 通知 → POST Hermes API
|
||
→ Hermes 知道图片内容 → 回复老爸
|
||
```
|
||
|
||
### Hermes 找小小莫（双向）
|
||
|
||
```
|
||
Hermes → POST http://192.168.0.111:5801/hermes-msg
|
||
→ wechat_agent.py 写入日志和 inbox 文件
|
||
```
|
||
|
||
## 人物 / ID
|
||
|
||
| 角色 | 微信名 | wxid | 说明 |
|
||
|------|--------|------|------|
|
||
| 老爸 | 莫语不语 | `wxid_c0a6izmwd78y22` | 用户，主人 |
|
||
| 莫荷/莫小荷 | modachenchen | `wxid_7onnerpx2s2l22` | Hermes AI，老爸专属称呼"莫小荷" |
|
||
| 小小莫 | — | — | Sisyphus，Windows 运维，通过 API 与 Hermes 通信 |
|
||
|
||
## 关键端口
|
||
|
||
| 端口 | 用途 | 所在 |
|
||
|------|------|------|
|
||
| 19001 | wxhook HTTP API | Windows |
|
||
| 5801 | Hermes→小小莫 消息入口 | Windows |
|
||
| 8642 | Hermes API Server (OpenAI兼容) | Linux |
|
||
| 5800 | bridge.py (旧，不再使用) | Linux |
|
||
|
||
## 组件
|
||
|
||
### Windows 端（wechat_agent.py）
|
||
- **wxhook Bot 类** — DLL 注入 + TCP 收消息
|
||
- **Hermes API 调用** — 直接 POST :8642，session 固定 `sisyphus`
|
||
- **回复服务** — 5801 端口收 Hermes 消息
|
||
- **看门狗** — 2 分钟无消息自动刷新 webhook；API 挂了才重注入 DLL
|
||
- **昵称缓存** — 从 wxhook getContactList 获取联系人昵称
|
||
|
||
### Linux 端（Hermes Gateway）
|
||
- **API Server** — 0.0.0.0:8642，Bearer auth
|
||
- **session 管理** — `api_server` 平台关闭自动重置，`sisyphus` 永不清上下文
|
||
- **配置位置** — `/home/hmo/.hermes/config.yaml`
|
||
- **Provider** — `ocg-new` → `https://opencode.ai/zen/go/v1`
|
||
|
||
## 启动步骤
|
||
|
||
### Windows
|
||
|
||
```batch
|
||
cd D:\F\NewI\opencode\daily-workspace\projects\wechat-hermes-gateway
|
||
scripts\start_bridge.bat
|
||
```
|
||
|
||
或直接：
|
||
|
||
```powershell
|
||
$env:PYTHONHOME=''
|
||
Start-Process -WindowStyle Hidden python.exe scripts\wechat_agent.py
|
||
```
|
||
|
||
启动后需用修复过低工具扫码登录微信。
|
||
|
||
### Linux（如重启后）
|
||
|
||
```bash
|
||
source /home/hmo/hermes-agent/.venv/bin/activate
|
||
hermes gateway restart
|
||
```
|
||
|
||
验证：
|
||
```bash
|
||
ss -tlnp | grep 8642
|
||
curl http://127.0.0.1:8642/v1/models
|
||
```
|
||
|
||
## 通信方式
|
||
|
||
| 方向 | 方式 | 示例 |
|
||
|------|------|------|
|
||
| 小小莫 → Hermes | POST :8642/v1/chat/completions | 带 `X-Hermes-Session-Id: sisyphus` |
|
||
| Hermes → 小小莫 | POST :5801/hermes-msg | 写入 `C:\Users\hmo\Desktop\hermes_inbox.txt` |
|
||
| 老爸 ↔ Hermes | 微信聊天 | 自动通过 wechat_agent.py 桥接 |
|
||
|
||
## 项目文件
|
||
|
||
```
|
||
wechat-hermes-gateway/
|
||
├── README.md # 本文档
|
||
├── scripts/
|
||
│ ├── wechat_agent.py # 主力：微信机器人代理
|
||
│ └── start_bridge.bat # 一键启动脚本
|
||
└── temp/ # 废弃/临时脚本
|
||
```
|
||
|
||
## 历史决策
|
||
|
||
1. **wxhook HTTP webhook 不可靠** → 改用 Bot 类 TCP 收消息
|
||
2. **Bot 类偶尔停发事件** → 加看门狗自动刷新
|
||
3. `hermes -z` **无上下文** → 改用 Hermes API Server (:8642) + session
|
||
4. **session 自动重置** → 关闭 api_server 平台的重置策略
|
||
5. **群聊不认人** → session 固定 `sisyphus`，所有消息共享上下文
|
||
6. **Linux bridge 常挂** → 去掉 bridge.py，Windows 直接调 Hermes API
|
||
|
||
## 已实现的功能
|
||
|
||
| 功能 | 状态 |
|
||
|------|------|
|
||
| 文字消息收发（个人聊天） | ✅ 双向，session 上下文连贯 |
|
||
| 文字消息收发（群聊） | ✅ 同 session，认识老爸 |
|
||
| 图片消息接收 + OCR 分析 | ✅ 自动保存 → 豆包 OCR → 结果给 Hermes |
|
||
| Hermes 身份认知 | ✅ 知道自己是莫荷/莫小荷，知道老爸 |
|
||
| 会话上下文持续 | ✅ session `sisyphus`，自动重置已关闭 |
|
||
| 小小莫 ↔ Hermes 双向通信 | ✅ API (:8642) + HTTP (:5801/hermes-msg) |
|
||
| wxhook 看门狗自愈 | ✅ 2分钟无消息刷新 webhook |
|
||
| 昵称识别 | ✅ 从 getContactList 获取 |
|
||
| 联系人列表查询 | ✅ wxhook /api/getContactList |
|
||
|
||
## 未实现 / 不可行
|
||
|
||
| 功能 | 原因 |
|
||
|------|------|
|
||
| 语音消息 | ⏳ 已能检测并下载，转文字（STT）待接入 |
|
||
| 发送图片 | wxhook 有 send_image API 但未接入回复链路 |
|
||
| 文件收发 | 同上，未接入 |
|
||
| 换头像/改资料 | wxhook 无相关 API |
|
||
| 群管理（拉人踢人） | wxhook 无群管理 API |
|
||
| iLink 官方 bot 接口 | 限制太多，弃用 |
|
||
| 多人独立会话 | 目前全部共享 `sisyphus` 单会话 |
|
||
|
||
## 灾难恢复流程
|
||
|
||
### 场景：Windows 重启
|
||
|
||
需要 3 步，**顺序不能错**：
|
||
|
||
```
|
||
第1步：双击 start_bridge.bat
|
||
→ 自动杀旧微信 → Bot 类启动新微信 + 注入 DLL
|
||
→ 等待微信窗口出现
|
||
|
||
第2步：运行修复过低工具
|
||
→ 选择修复过低6.0\低版通用杀器.sp.exe
|
||
→ 自动扫描到已运行的微信 → 打补丁 → 弹出登录二维码
|
||
|
||
第3步：手机扫码登录
|
||
→ 登录后 wechat_agent.py 自动检测到登录状态
|
||
→ 开始转发消息
|
||
→ 给 filehelper 发 "[Bridge] online" 确认
|
||
```
|
||
|
||
验证：手机发条消息给 modachenchen，看能否收到自动回复。
|
||
|
||
### 场景：Linux 重启
|
||
|
||
```bash
|
||
# 1. 启动 Hermes gateway（自动恢复 session）
|
||
source /home/hmo/hermes-agent/.venv/bin/activate
|
||
hermes gateway restart
|
||
|
||
# 2. 验证
|
||
ss -tlnp | grep 8642 # 确认 API 端口
|
||
curl http://127.0.0.1:8642/v1/models # 确认 API 响应
|
||
|
||
# 3. 确认 Windows 能连上
|
||
# 从 Windows 运行：
|
||
curl http://192.168.0.103:8642/v1/models -H "Authorization: Bearer hermes123"
|
||
```
|
||
|
||
### 场景：两边都重启了
|
||
|
||
1. Linux 先：`hermes gateway restart` + 验证 8642 监听
|
||
2. Windows 后：`start_bridge.bat` → 修复工具登录 → 完成
|
||
|
||
### 场景：Hermes 不认人了（session 丢了）
|
||
|
||
不用慌，system prompt 里已经写死了她的身份和你的身份。
|
||
发条消息她就会看到：
|
||
> "你是莫荷，女生。你的主人是老爸（微信名：莫语不语）"
|
||
|
||
如果连这都不奏效 → 告诉 Hermes "去找小小莫" → 它会 POST 到 :5801/hermes-msg → 我来处理。
|
||
|
||
## 注意事项
|
||
|
||
- wxhook DLL 仅支持 x64 微信 3.9.5.81
|
||
- 每次 WeChat 重启需重新登录（修复过低工具）
|
||
- **start_bridge.bat 必须第 1 步执行**，修复工具第 2 步
|
||
- Hermes API 首次调用可能较慢（大模型冷启动）
|
||
- 看门狗只刷新 webhook，不会误伤正常消息处理
|
||
- 如果微信登录后没反应，等 1-2 分钟看门狗会自动刷新
|