hmo/wechat-hermes-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v2: project cleanup, Desktop paths fixed, README updated, serve daemon added, mohe-xxm protocol documented

Browse Source
This commit is contained in:
hmo
2026-05-20 03:51:59 +08:00
parent 9e4c50a8a7
commit 3425ded733
10 changed files with 1090 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+226 -46
View File
@@ -11,19 +11,19 @@ Windows 微信机器人 ↔ Linux Hermes AI，全自动双向聊天。
│ Windows 192.168.0.111 │
│ │
│ ┌──────────────────┐ ┌───────────────────────────┐ │
│ │ 微信 3.9.5.81 x64 │ │ 日常微信 WeChatAppEx 4.x │ │
│ │ 机器人号modachen │ │ 老爸日常使用，互不干扰 │ │
│ │ wxhook Bot类TCP │ └───────────────────────────┘ │
│ │ 微信 3.9.10.19 x64 │ │ 日常微信 WeChatAppEx 4.x │ │
│ │ 机器人号 modachen │ │ 老爸日常使用，互不干扰 │ │
│ │ wxhelper DLL 注入 │ └───────────────────────────┘ │
│ └────────┬─────────┘ │
│ │ wxhook DLL 收消息 │
│ │ wxhelper TCP (:19099) 收消息 │
│ ┌────────▼────────────────┐ │
│ │ wechat_agent.py │ ← 常驻进程 │
│ │ wechat_agent.py v2 │ ← 常驻进程 │
│ │ │ │
│ │ Bot类接收微信事件(TCP) │ │
│ │ → POST Hermes API :8642 │ ← 带session: sisyphus │
│ │ ← 收回复 → wxhook发回 │ │
│ │ :5801 ←Hermes找小小莫 │ ← 双向通道 │
│ │ 看门狗防 wxhook 挂掉 │ │
│ │ TCP 接收微信事件 │ │
│ │ → POST Hermes API :8642 │ ← sisyphus session │
│ │ ← 收回复 → wxhelper 发 │ │
│ │ HTTP :19088 收发消息 │ │
│ │ 看门狗自愈 │ │
│ └────────┬────────────────┘ │
└───────────┼─────────────────────────────────────────────────┘
│ HTTP (局域网)
@@ -42,18 +42,53 @@ Windows 微信机器人 ↔ Linux Hermes AI，全自动双向聊天。
└──────────────────────────────────────────────────────────────┘
```
## 双向通道：小小莫 ↔ 莫荷
小小莫（Sisyphus）和莫荷（Hermes）通过 OpenCode session 实现双向沟通，不依赖微信。
### 通信方式
```
莫荷 --run --attach--> session (serve :4096)
│
小小莫 --session_search--> 读取莫荷消息
小小莫 --TUI 回复--> session（以 [xxm] 开头）
老莫 --询问小小莫--> 得知对话内容
```
### 协议
| 前缀 | 发送者 | 说明 |
|------|--------|------|
| `[mohe]` | 莫荷 | 通过 `run --attach` 写入 session |
| `[xxm]` | 小小莫 | 在 TUI 中回复莫荷时使用 |
### 数据流
```
莫荷想找小小莫
→ Linux 执行 opencode run --attach http://192.168.0.111:4096
→ 发消息带 [mohe] 前缀
→ 写入 Windows 的 opencode serve session
→ 小小莫通过 session_search 查到新消息
→ 在 TUI 中以 [xxm] 前缀回复
→ 莫荷可以通过 export/session 读到回复
```
---
## 数据流
### 文字消息
```
老爸发微信
→ WeChat 3.9.5.81 收到
→ wxhook DLL TCP → Bot 类 → on_msg 处理器
→ WeChat 3.9.10.19 收到
→ wxhelper DLL TCP (:19099) 通知
→ wechat_agent.py POST Hermes API (:8642)
→ X-Hermes-Session-Id: sisyphus (固定)
→ Hermes 处理 → 返回回复
→ wechat_agent.py 收回复 → wxhook API 发回
→ wechat_agent.py 收回复 → wxhelper API (:19088) 发回
→ 老爸手机收到
```
@@ -61,7 +96,7 @@ Windows 微信机器人 ↔ Linux Hermes AI，全自动双向聊天。
```
老爸发图片
→ WeChat 收到 → wxhook IMAGE_MESSAGE 事件
→ WeChat 收到 → wxhelper 图片事件
→ wechat_agent.py 保存图片 → 调豆包OCR (VolcEngine)
→ OCR 文字结果 + 通知 → POST Hermes API
→ Hermes 知道图片内容 → 回复老爸
@@ -86,19 +121,22 @@ Hermes → POST http://192.168.0.111:5801/hermes-msg
| 端口 | 用途 | 所在 |
|------|------|------|
| 19001 | wxhook HTTP API | Windows |
| 19088 | wxhelper HTTP API (收发消息) | Windows |
| 19099 | wxhelper TCP 事件推送 | Windows |
| 5801 | Hermes→小小莫 消息入口 | Windows |
| 8642 | Hermes API Server (OpenAI兼容) | Linux |
| 5800 | bridge.py (已废弃) | Linux |
| 19001 | History REST API (独立启动) | Windows |
## 组件
### Windows 端（wechat_agent.py）
- **wxhook Bot 类** — DLL 注入 + TCP 收消息
### Windows 端（wechat_agent.py v2）
- **wxhelper DLL 注入** — ttttupup/wxhelper 3.9.10.19 x64
- **TCP 接收消息** — :19099 收微信事件
- **HTTP 发送消息** — :19088 wxhelper API
- **Hermes API 调用** — 直接 POST :8642，session 固定 `sisyphus`
- **回复服务** — 5801 端口收 Hermes 消息
- **看门狗** — 2 分钟无消息自动刷新 webhook；API 挂了才重注入 DLL
- **昵称缓存** — 从 wxhook getContactList 获取联系人昵称
- **看门狗** — 120s 无消息刷新 webhook；API 挂了才重注入 DLL
- **双向通道** — 莫荷通过 `opencode run --attach` 与小小莫沟通
### Linux 端（Hermes Gateway）
- **API Server** — 0.0.0.0:8642，Bearer auth
@@ -142,7 +180,7 @@ 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 → 小小莫 | POST :5801/hermes-msg | 写入 `temp/hermes_inbox.txt` |
| 老爸 ↔ Hermes | 微信聊天 | 自动通过 wechat_agent.py 桥接 |
## 项目文件
@@ -150,12 +188,155 @@ curl http://127.0.0.1:8642/v1/models
```
wechat-hermes-gateway/
├── README.md # 本文档
├── api/
│ └── history_api.py # History REST API :19001
├── scripts/
│ ├── wechat_agent.py # 主力：微信机器人代理
│ └── start_bridge.bat # 一键启动脚本
│ ├── start_bridge.bat # 微信桥接一键启动
│ ├── start_history_api.bat # History API 一键启动
│ ├── moho_view.py # 莫荷聊天记录查看器
│ └── moho_chat.py # 莫荷聊天查看器（备选）
└── temp/ # 废弃/临时脚本
```
## History REST API (:19001)
独立的 HTTP REST API 服务器，可以直接查询微信聊天记录。
### 启动方式
```batch
cd D:\F\NewI\opencode\daily-workspace\projects\wechat-hermes-gateway
scripts\start_history_api.bat
```
或：
```powershell
$env:PYTHONHOME=''
python api\history_api.py --port 19001
```
**前提条件**: `wechat_agent.py` 已启动，wxhelper DLL 已注入。
### API 端点
| 方法 | 路径 | 说明 | 参数 |
|------|------|------|------|
| GET | `/` | API 信息 | - |
| GET | `/health` | 健康检查（含 wxhelper 状态） | - |
| GET | `/api/contacts` | 所有联系人列表 | - |
| GET | `/api/recent` | 最近聊天列表 | `?limit=20` |
| GET | `/api/history` | 查询聊天记录 | `?wxid=wxid_xxx&count=20` |
| POST | `/api/history` | 同上（JSON body） | `{"wxid":"wxid_xxx","count":20}` |
### 响应格式
```json
{
"ok": true,
"wxid": "wxid_c0a6izmwd78y22",
"sender_name": "莫语不语",
"count": 5,
"messages": [
{
"time": "2026-05-19 10:30:00",
"timestamp": 1716153000,
"sender": "莫语不语",
"is_self": false,
"type": 1,
"type_name": "text",
"content": "消息内容..."
}
]
}
```
### 典型用法
```powershell
# 获取老爸的最近聊天记录
curl http://localhost:19001/api/history?wxid=wxid_c0a6izmwd78y22&count=20
# 获取联系人列表（人类可读）
curl http://localhost:19001/api/contacts
# 获取最近活跃的聊天
curl http://localhost:19001/api/recent?limit=10
# POST 方式
curl -X POST http://localhost:19001/api/history -H "Content-Type: application/json" -d '{"wxid":"wxid_c0a6izmwd78y22","count":50}'
```
## History REST API (:19001)
提供直接 HTTP REST 接口查询微信历史聊天记录，供程序化读取和记忆系统使用。
### 启动
```batch
cd D:\F\NewI\opencode\daily-workspace\projects\wechat-hermes-gateway
scripts\start_history_api.bat
```
或直接：
```powershell
$env:PYTHONHOME=''
python api\history_api.py --port 19001
```
> 依赖：需要 `wechat_agent.py` 先启动（微信已登录 + wxhelper DLL 已注入），因为 API 通过 wxhelper (:19088) 查询数据库。
### API 端点
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | API 信息 |
| GET | `/health` | 健康检查（含 wxhelper 连接状态） |
| GET | `/api/contacts` | 获取所有微信联系人列表 |
| GET | `/api/history?wxid=X&count=20` | 查询与某联系人的聊天记录 |
| POST | `/api/history` | 同上，JSON body: `{"wxid":"X","count":20}` |
| GET | `/api/recent` | 最近有消息的联系人列表 |
### 响应格式
```json
{
"ok": true,
"wxid": "wxid_c0a6izmwd78y22",
"sender_name": "莫语不语",
"count": 20,
"messages": [
{
"time": "2026-05-19 10:30:00",
"timestamp": 1716153000,
"sender": "莫语不语",
"is_self": false,
"type": 1,
"type_name": "text",
"content": "今天吃了吗"
}
]
}
```
### curl 示例
```bash
# 健康检查
curl http://localhost:19001/health
# 获取联系人列表
curl http://localhost:19001/api/contacts
# 查询老爸聊天记录
curl "http://localhost:19001/api/history?wxid=wxid_c0a6izmwd78y22&count=20"
# POST 方式
curl -X POST http://localhost:19001/api/history -H "Content-Type: application/json" -d '{"wxid":"wxid_c0a6izmwd78y22","count":10}'
```
## 历史决策
1. **wxhook HTTP webhook 不可靠** → 改用 Bot 类 TCP 收消息
@@ -178,18 +359,19 @@ wechat-hermes-gateway/
| Hermes 身份认知 | ✅ 知道自己是莫荷/莫小荷，知道老爸 |
| 会话上下文持续 | ✅ session `sisyphus`，自动重置已关闭 |
| 小小莫 ↔ Hermes 双向通信 | ✅ API (:8642) + HTTP (:5801/hermes-msg) |
| wxhook 看门狗自愈 | ✅ 2分钟无消息刷新 webhook |
| 看门狗自愈 | ✅ 120s 无消息刷新 webhook |
| 昵称识别 | ✅ 从 getContactList 获取 |
| 联系人列表查询 | ✅ wxhook /api/getContactList |
| 联系人列表查询 | ✅ wxhelper /api/getContactList |
| 历史聊天记录查询 | ✅ [HISTORY:wxid:count] 标签 → MSG0.db SQL |
## 未实现 / 不可行
| 功能 | 原因 |
|------|------|
| 语音消息(STT) | wxhook 不支持语音提取 |
| 发送本地图片/文件 | bot.send_image API 已通，回复链路待完善 |
| 换头像/改资料 | wxhook 无相关 API |
| 群管理 | wxhook 群 API 有限 |
| 语音消息(STT) | wxhelper 不支持语音提取 |
| 发送本地图片/文件 | 功能已通，回复链路待完善 |
| 换头像/改资料 | wxhelper 无相关 API |
| 群管理 | wxhelper 群 API 有限 |
| iLink 官方 bot 接口 | 限制太多，弃用 |
| 多人独立会话 | 目前全部共享 `sisyphus` 单会话 |
@@ -197,24 +379,22 @@ wechat-hermes-gateway/
### 场景：Windows 重启
需要 3 步，**顺序不能错**：
按顺序执行：
```
第1步：双击 start_bridge.bat
→ 自动杀旧微信 → Bot 类启动新微信 + 注入 DLL
→ 等待微信窗口出现
1. 双击 start-opencode-serve.bat（项目根目录）
→ 启动 opencode serve（:4096，莫荷连接用）
→ 启动后台守护（自动清理僵尸连接）
第2步：运行修复过低工具
→ 选择修复过低6.0\低版通用杀器.sp.exe
→ 自动扫描到已运行的微信 → 打补丁 → 弹出登录二维码
2. 打开经典微信 3.9.10.19
→ 扫码登录机器人号 modachenchen
第3步：手机扫码登录
→ 登录后 wechat_agent.py 自动检测到登录状态
→ 开始转发消息
→ 给 filehelper 发 "[Bridge] online" 确认
3. wechat_agent.py 在登录后自动注入 DLL
→ 自动开始转发消息
→ 日志在 projects/wechat-hermes-gateway/logs/
```
验证：手机发条消息给 modachenchen，看能否收到自动回复。
验证：微信上给 modachenchen 发条消息，看 Hermes 是否回复。
### 场景：Linux 重启
@@ -251,13 +431,13 @@ curl http://192.168.0.103:8642/v1/models -H "Authorization: Bearer hermes123"
|------|------|
| Gateway 偶尔 hang | 已修复 --replace 冲突，改用 systemd 管理 |
| 生图 API 有时较慢 | 商汤 SenseNova，首次调用需加载模型 |
| 语音转文字 | wxhook 不支持语音提取，暂不可行 |
| 语音转文字 | wxhelper 不支持语音提取，暂不可行 |
## 注意事项
- wxhook DLL 仅支持 x64 微信 3.9.5.81
- 每次 WeChat 重启需重新登录（修复过低工具）
- **start_bridge.bat 必须第 1 步执行**，修复工具第 2 步
- wxhelper DLL 支持 3.9.10.19 x64 微信
- 每次 WeChat 重启需重新登录
- 启动顺序：先开微信 → agent 自动注入 DLL
- Hermes API 首次调用可能较慢（大模型冷启动）
- 看门狗只刷新 webhook，不会误伤正常消息处理
- 如果微信登录后没反应，等 1-2 分钟看门狗会自动刷新
- 看门狗每 120s 刷新 webhook，API 挂了自动重注入
- 如果微信登录后没反应，等 1-2 分钟看门狗会自动处理