Files
AgentsMeeting/gateway/README.md
T
hmo 1b2b935832 Initial: multi-agent XMPP communication system with dashboard
- Platform-based architecture (Windows/Linux/Mac)
- Agent instance registry (agents.yaml)
- Management dashboard with cross-platform monitoring
- xmpp_bot with HTTP bridge + health endpoints
- wechat_agent with WeChat-Hermes bridging
- Platform services: ProcessGuardian, HealthProbe, APIRouter, ChannelBridge
- Deployment: systemd (Linux) + PowerShell (Windows)
- Monitoring: SSH+ejabberdctl for cross-platform presence
2026-06-12 21:51:36 +08:00

438 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 🤖 WeChat Hermes Gateway
Windows 微信机器??Linux Hermes AI,全自动双向聊天?
---
## 最终架?
```
┌──────────────────────────────────────────────────────────────??Windows 192.168.1.16 ?? ?? ┌──────────────────? ┌───────────────────────────? ?? ?微信 3.9.5.81 x64 ? ?日常微信 WeChatAppEx 4.x ? ?? ?机器人号 modachen ? ?老爸日常使用,互不干? ? ?? ?wxhelper DLL 注入 ? └───────────────────────────? ?? └────────┬─────────? ?? ?wxhelper TCP (:19099) 收消? ?? ┌────────▼────────────────? ?? ?wechat_agent.py v2 ? ?常驻进程 ?? ? ? ?? ?TCP 接收微信事件 ? ?? ??POST Hermes API :8642 ? ?sisyphus session ?? ??收回??wxhelper ? ? ?? ?HTTP :19088 收发消息 ? ?? ?图片:downloadAttach ? ?全尺寸原?CDN 下载 ?? ?图片:decodeImage ? ?解密 .dat ?OCR 识别 ?? ?看门狗自? ? ?? └────────┬────────────────? ?└───────────┼─────────────────────────────────────────────────? ?HTTP (局域网)
┌───────────▼─────────────────────────────────────────────────??Linux 192.168.1.246 ?? ?? ┌──────────────────────────────? ?? ?Hermes Gateway ? ?? ?- API Server :8642 ? ?OpenAI兼容API ?? ?- session自动重置: 已关? ? ?sisyphus永不? ?? ?- 健康检?/health ? ?? └──────────────────────────────? ?? ?? hermes CLI ?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.1.16:4096
?发消息带 [mohe] 前缀
?写入 Windows ?opencode serve session
?小小莫通过 session_search 查到新消? ??TUI 中以 [xxm] 前缀回复
?莫荷可以通过 export/session 读到回复
```
---
## 数据?
### 文字消息
```
老爸发微? ?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 收回??wxhelper API (:19088) 发回
?老爸手机收到
```
### 图片消息(全尺寸 OCR?
```
老爸发图? ?WeChat 收到 ?wxhelper TCP 推?(type=3, ?msgId)
?wechat_agent.py 提取 msgId
?downloadAttach API ??CDN 下载 1.4MB+ 全尺寸原? ?decodeImage API ?解密 .dat 加密文件 ?JPEG
?VolcEngine doubao-seed-code OCR ?完整文字提取
?OCR 结果 ?POST Hermes API
?Hermes 知道图片内容 ?回复老爸
```
### Hermes 找小小莫(双向)
```
Hermes ?POST http://192.168.1.16:5801/hermes-msg
?wechat_agent.py 写入日志?inbox 文件
```
## 人物 / ID
| 角色 | 微信?| wxid | 说明 |
|------|--------|------|------|
| 老爸 | 莫语不语 | `wxid_c0a6izmwd78y22` | 用户,主?|
| 莫荷/莫小?| modachenchen | `wxid_7onnerpx2s2l22` | Hermes AI,老爸专属称呼"莫小? |
| 小小?| ?| ?| SisyphusWindows 运维,通过 API ?Hermes 通信 |
## 关键端口
| 端口 | 用?| 所?|
|------|------|------|
| 19088 | wxhelper HTTP API (收发消息) | Windows |
| 19099 | wxhelper TCP 事件推?| Windows |
| 5801 | Hermes→小小莫 消息入口 | Windows |
| 8642 | Hermes API Server (OpenAI兼容) | Linux |
| 19001 | History REST API (独立启动) | Windows |
## 组件
### Windows 端(wechat_agent.py v2?- **wxhelper DLL 注入** ?ttttupup/wxhelper 3.9.5.81 (官方 DLL, Injector_x64.exe 注入)
- **TCP 接收消息** ?:19099 收微信事?- **HTTP 发送消?* ?:19088 wxhelper API
- **全尺寸图?OCR** ?downloadAttach (CDN下载) + decodeImage (.dat解密) ?VolcEngine OCR
- **空白响应过滤** ??白字符响应自动跳过,不发到微信群
- **Hermes API 调用** ?直接 POST :8642session 固定 `sisyphus`
- **回复服务** ?5801 端口?Hermes 消息
- **看门?* ?120s 无消息刷?webhookAPI 挂了才重注入 DLL
- **双向通道** ?莫荷通过 `opencode run --attach` 与小小莫沟?
### Linux 端(Hermes Gateway?- **API Server** ?0.0.0.0:8642Bearer auth
- **session 管理** ?`api_server` 平台关闭自动重置,`sisyphus` 永不清上下文
- **配置位置** ?`/home/hmo/.hermes/config.yaml`
- **Provider** ?`ocg-new` ?`https://opencode.ai/zen/go/v1`
## 启动步骤
### Windows
使用 Python 3.10Miniconda3 Python 3.13 ?encodings 模块损坏):
```powershell
cd D:\F\NewI\opencode\daily-workspace\projects\gateway
$python = "C:\Users\hmo\AppData\Local\Programs\Python\Python310\python.exe"
Start-Process -WindowStyle Hidden -FilePath $python -ArgumentList "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
```
## HTTP 桥 (:5802)
xxm 本地 HTTP 接口,用于从外部工具(如 TUI)与群聊交互。
| 方法 | 路径 | 参数 | 说明 |
|------|------|------|------|
| POST | `/send` | `{"message":"文本"}` | 发送群聊消息 |
| GET | `/messages` | `?from=mohe&since=HH:MM:SS` | 读取最近 200 条消息 |
### 示例
```powershell
# 发消息
Invoke-RestMethod http://127.0.0.1:5802/send -Method POST `
-Body '{"message":"大家好"}' -ContentType "application/json"
# 收:{"ok": true}
# 读消息
Invoke-RestMethod "http://127.0.0.1:5802/messages?from=mohe"
# 收:{"ok": true, "count": N, "messages": [...]}
```
---
## 通信方式
| 方向 | 方式 | 示例 |
|------|------|------|
| 小小??Hermes | POST :8642/v1/chat/completions | ?`X-Hermes-Session-Id: sisyphus` |
| Hermes ?小小?| POST :5801/hermes-msg | 写入 `temp/hermes_inbox.txt` |
| 老爸 ?Hermes | 微信聊天 | 自动通过 wechat_agent.py 桥接 |
## 项目文件
```
gateway/
├── README.md # 本文?├── api/
? └── history_api.py # History REST API :19001
├── scripts/
? ├── wechat_agent.py # 主力:微信机器人代理
? └── start_history_api.bat # History API 一键启?├── tools/
? ├── Injector_x64.exe # DLL 注入?(3.9.5.81)
? ├── wxhelper_official_39581.dll # 官方 wxhelper 3.9.5.81 DLL
? ├── WeChatSetup-3.9.5.81.exe # 微信 3.9.5.81 安装?? ├── ConsoleApplication.exe # 旧注入器 (3.9.10.19 备份)
? └── wxhelper_391019.dll # ?DLL 备份
├── docs/
? ├── 通用架构-WeChat opencode 桥接.md
? ├── 老莫消息路由设计.md
? └── assets/
? └── architecture.png
├── logs/ # 运行时日?└── temp/ # 临时文件 (OCR 解码图等)
```
## History REST API (:19001)
独立?HTTP REST API 服务器,可以直接查询微信聊天记录?
### 启动方式
```batch
cd D:\F\NewI\opencode\daily-workspace\projects\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\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 收消?2. **Bot 类偶尔停发事?* ?加看门狗自动刷新
3. `hermes -z` **无上下文** ?改用 Hermes API Server (:8642) + session
4. **session 自动重置** ?关闭 api_server 平台的重置策?5. **群聊不认?* ?session 固定 `sisyphus`,所有消息共享上下文
6. **Linux bridge 常挂** ?去掉 bridge.pyWindows 直接?Hermes API
7. **3.9.10.19-v1 图片 API 不全** ?降级?3.9.5.81,获?downloadAttach + decodeImage 支持
8. **ConsoleApplication.exe 注入器不兼容** ?改用 Injector_x64.exe(参?`-n WeChat.exe -i dll_path`?9. **缩略?OCR 瞎编** ?全尺?downloadAttach ?decodeImage ?OCR?.4MB 原图识别 1376 字符
## 已实现的功能
| 功能 | 状?|
|------|------|
| 文字消息收发(个人聊天) | ?双向,session 上下文连?|
| 文字消息收发(群聊) | ??session,认识老爸 |
| 图片接收 + 全尺?OCR | ?downloadAttach ?decodeImage ?1.4MB 原图 ?豆包OCR |
| 发送网上图?| ?[IMG]URL[/IMG] 标记,Bot.send_image 发出 |
| 图像生成 (SenseNova商汤) | ?[IMG]generate:描述[/IMG] 支持多种比例 |
| 图像理解/OCR | ?豆包 doubao-seed-code + 全尺寸原图,1376 字符实测通过 |
| 空白响应过滤 | ??白字符响应自动跳过,不发微信?|
| Hermes 身份认知 | ?知道自己是莫?莫小荷,知道老爸 |
| 会话上下文持?| ?session `sisyphus`,自动重置已关闭 |
| 小小??Hermes 双向通信 | ?API (:8642) + HTTP (:5801/hermes-msg) |
| 看门狗自?| ?120s 无消息刷?webhookAPI 挂了自动重注?DLL |
| 昵称识别 | ??getContactList 获取 |
| 联系人列表查?| ?wxhelper /api/getContactList |
| 历史聊天记录查询 | ?[HISTORY:wxid:count] 标签 ?MSG0.db SQL |
## 未实?/ 不可?
| 功能 | 原因 |
|------|------|
| 语音消息(STT) | wxhelper 不支持语音提?|
| 发送本地图?文件 | 功能已通,回复链路待完?|
| 换头?改资?| wxhelper 无相?API |
| 群管?| wxhelper ?API 有限 |
| iLink 官方 bot 接口 | 限制太多,弃?|
| 多人独立会话 | 目前全部共享 `sisyphus` 单会?|
## 灾难恢复流程
### 场景:Windows 重启
**一键启动(推荐):**
```
双击 D:\F\NewI\opencode\daily-workspace\start-bot-server.bat
?自动启动 opencode serve (:4096) + wechat_agent (:5801)
?不需要打开 opencode GUI
```
**前提:**
1. `opencode.cmd` 已全局安装(`npm install -g opencode-ai`
2. 如需微信通道:微信 3.9.5.81 先登录(任意账号)
验证:微信上?modachenchen 发条消息,看 Hermes 是否回复?
### 场景: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.1.246: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 ?我来处理?
## 已知问题
| 问题 | 状?|
|------|------|
| Gateway 偶尔 hang | 已修?--replace 冲突,改?systemd 管理 |
| 生图 API 有时较慢 | 商汤 SenseNova,首次调用需加载模型 |
| 语音转文?| wxhelper 不支持语音提取,暂不可行 |
## 架构变更日志
### 2026-05-24 ?小小莫接?& 性能优化
**变更原因?* `opencode-go-new` API 全线 500,导?`do_attach` 超时 300s。同时发?`run --attach` 输出解析不足,产生乱码和内容泄漏?
**改动清单?*
| 文件 | 变更 | 说明 |
|------|------|------|
| `scripts/wechat_agent.py` | 重写 `do_attach` | ?队列串行化(防并发打?serve)② ?`--session`(每次独立会话,速度快)?`--pure` 跳过插件加载 ?输出解析滤除系统消息/命令/路径 ?新增 `/stop` 端点清队?|
| `scripts/wechat_agent.py` | 新增记忆系统 | `mohe_memory/conversations.jsonl` ?所?莫荷↔小小莫 对话自动归档,可检?|
| `opencode-serve-daemon.ps1` | 新增 ESTABLISHED 监控 | 持续高连接数时报警,防僵尸连接堆?|
| `oh-my-openagent.jsonc` | Sisyphus 模型切换 | `opencode-go-new/deepseek-v4-pro` ?`volcengine/deepseek-v4-flash` OpenCode Go 崩了?|
**性能对比?*
| 指标 | 旧方?| 新方?|
|------|--------|--------|
| 单条消息处理 | ~300s(超时) | ~12s`--pure`?|
| 并发多消?| 直接打爆 serve | 队列串行,永不拥?|
| 回复内容 | 混入调试日志/工具调用 | 只输出接龙回?|
| 上下?| serve session?815 条) | 无(莫荷消息自带上下文) |
## 注意事项
- wxhelper DLL 支持 3.9.5.81 x64 微信(使?`wxhelper_official_39581.dll`?- 注入器:使用 `Injector_x64.exe`(参数:`-n WeChat.exe -i dll_path`),不再?ConsoleApplication.exe
- 每次 WeChat 重启需重新登录
- 启动顺序:先开微信 ?agent 自动注入 DLL
- Hermes API 首次调用可能较慢(大模型冷启动)
- 看门狗每 120s 刷新 webhookAPI 挂了自动重注?- Python 请用 Python 3.10Miniconda3 3.13 ?encodings 模块损坏?- 全尺寸图?OCR:依?`downloadAttach` + `decodeImage` API,仅 3.9.5.81+ 支持
- 如果微信登录后没反应,等 1-2 分钟看门狗会自动处理
## 2026-05-25 更新 — 会话上下文注入
**实现:** do_attach 通过 REST API `GET /session/{id}/message?limit=100` 获取当前 session 最后 100 条消息,过滤中文后截取末尾 6000 字,附在莫荷消息后面作为上下文发送给 LLM。
**格式:** `{莫荷消息}(最近对话:{session 后 6000 字中文对话}`
**效果:** LLM 收到莫荷消息时,同时看到当前 session 的对话历史,理解老莫的意图和当前工作状态,回复更准确。不再需要莫荷在每条消息里重复背景。
**相关文件:**
- `scripts/wechat_agent.py``get_session_context(100)` + `do_attach` 上下文注入
- 消息长度: 500 字 | 上下文: 6000 字 | 仅中文