hmo/wechat-hermes-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
wechat-hermes-gateway/README.md
T

17 KiB
Raw Permalink Blame History

🤖 WeChat Hermes Gateway

Windows 微信机器人 ↔ Linux Hermes AI，全自动双向聊天。

最终架构

┌──────────────────────────────────────────────────────────────┐
│ Windows 192.168.0.111                                        │
│                                                              │
│  ┌──────────────────┐      ┌───────────────────────────┐    │
│  │ 微信 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.0.103                                          │
│                                                              │
│  ┌──────────────────────────────┐                            │
│  │ 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.0.111: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.0.111:5801/hermes-msg
  → wechat_agent.py 写入日志和 inbox 文件

人物 / ID

角色 微信名 wxid 说明
老爸 莫语不语 wxid_c0a6izmwd78y22 用户，主人
莫荷/莫小荷 modachenchen wxid_7onnerpx2s2l22 Hermes AI，老爸专属称呼"莫小荷"
小小莫 — — Sisyphus，Windows 运维，通过 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 :8642，session 固定 sisyphus
  • 回复服务 — 5801 端口收 Hermes 消息
  • 看门狗 — 120s 无消息刷新 webhook；API 挂了才重注入 DLL
  • 双向通道 — 莫荷通过 opencode run --attach 与小小莫沟通

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

使用 Python 3.10（Miniconda3 Python 3.13 的 encodings 模块损坏）：

cd D:\F\NewI\opencode\daily-workspace\projects\wechat-hermes-gateway
$python = "C:\Users\hmo\AppData\Local\Programs\Python\Python310\python.exe"
Start-Process -WindowStyle Hidden -FilePath $python -ArgumentList "scripts\wechat_agent.py"

Linux（如重启后）

source /home/hmo/hermes-agent/.venv/bin/activate
hermes gateway restart

验证：

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 写入 temp/hermes_inbox.txt
老爸 ↔ Hermes 微信聊天 自动通过 wechat_agent.py 桥接

项目文件

wechat-hermes-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 服务器，可以直接查询微信聊天记录。

启动方式

cd D:\F\NewI\opencode\daily-workspace\projects\wechat-hermes-gateway
scripts\start_history_api.bat

或：

$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}

响应格式

{
  "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": "消息内容..."
    }
  ]
}

典型用法

# 获取老爸的最近聊天记录
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 接口查询微信历史聊天记录，供程序化读取和记忆系统使用。

启动

cd D:\F\NewI\opencode\daily-workspace\projects\wechat-hermes-gateway
scripts\start_history_api.bat

或直接：

$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 最近有消息的联系人列表

响应格式

{
  "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 示例

# 健康检查
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.py，Windows 直接调 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，1.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 无消息刷新 webhook，API 挂了自动重注入 DLL
昵称识别 ✅ 从 getContactList 获取
联系人列表查询 ✅ wxhelper /api/getContactList
历史聊天记录查询 ✅ [HISTORY:wxid:count] 标签 → MSG0.db SQL

未实现 / 不可行

功能 原因
语音消息(STT) wxhelper 不支持语音提取
发送本地图片/文件 功能已通，回复链路待完善
换头像/改资料 wxhelper 无相关 API
群管理 wxhelper 群 API 有限
iLink 官方 bot 接口 限制太多，弃用
多人独立会话 目前全部共享 sisyphus 单会话

灾难恢复流程

场景：Windows 重启

按顺序执行：

1. 双击 start-opencode-serve.bat（项目根目录）
   → 启动 opencode serve（:4096，莫荷连接用）
   → 启动后台守护（自动清理僵尸连接）

2. 打开经典微信 3.9.5.81（用修复过低工具扫码登录）
   → 扫码登录机器人号 modachenchen

3. wechat_agent.py 在登录后自动注入 wxhelper_official_39581.dll
   → 自动开始转发消息
   → 日志在 projects/wechat-hermes-gateway/logs/

验证：微信上给 modachenchen 发条消息，看 Hermes 是否回复。

场景：Linux 重启

# 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 → 我来处理。

已知问题

问题 状态
Gateway 偶尔 hang 已修复 --replace 冲突，改用 systemd 管理
生图 API 有时较慢 商汤 SenseNova，首次调用需加载模型
语音转文字 wxhelper 不支持语音提取，暂不可行

注意事项

  • 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 刷新 webhook，API 挂了自动重注入
  • Python 请用 Python 3.10（Miniconda3 3.13 的 encodings 模块损坏）
  • 全尺寸图片 OCR：依赖 downloadAttach + decodeImage API，仅 3.9.5.81+ 支持
  • 如果微信登录后没反应，等 1-2 分钟看门狗会自动处理
Reference in New Issue View Git Blame Copy Permalink