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

init: WeChat Hermes Gateway - wxhook + Hermes AI auto-reply bot

Browse Source
This commit is contained in:
hmo
2026-05-17 14:13:14 +08:00
commit 93f4273b3d
5 changed files with 564 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+253
View File
@@ -0,0 +1,253 @@
# 🤖 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 分钟看门狗会自动刷新