wechat-hermes-gateway/docs/通用架构-WeChat opencode 桥接.md

通用架构：WeChat ↔ opencode 双向桥接

2026-05-20 剥离 Hermes AI 依赖，建立 opencode serve 与微信账号之间的通用双向通道

---

核心理念

微信机器人本质是一套通用的消息路由系统：

微信 ←→ wxhelper ←→ 桥接代理 ←→ 任何 AI / 程序

不应该是"莫荷专属"。当前架构把 Hermes API 硬编码在桥接逻辑中，限制了通用性。

---

架构对比

当前（莫荷专用，双机）

你微信 → wxhelper TCP → wechat_agent → Hermes API (:8642, Linux) → 莫荷回复
                                            ↑
                                    消息路由硬编码，改一处都要动 agent

目标（通用，纯 Windows）

你微信 → wxhelper TCP → Bridge Agent ─┬→ opencode serve session (小小莫看到)
                                       │
                                       └→ HTTP API (:5801) 供任何程序消费
                                              ↑
                                     serve 里的 AI / 外部程序 POST 回复

关键变化：桥接代理不再"替 AI 做决定"，而是变成中立的消息通道：

功能	现状 (wechat_agent.py)	目标 (Bridge Agent)
收到微信消息	直接 POST Hermes API	写入 serve session + 提供 HTTP 消费接口
消息路由	硬编码 (call_hermes)	无业务逻辑，只负责转发
AI 是谁	只能是莫荷 (Hermes)	可以是 serve 里的任何人（Sisyphus、莫荷...）
外部调用	:5801 简陋收消息	http API 收消息

---

通用架构图

┌─────────────────────────────────────────────────────────────────┐
│                        Windows 192.168.0.111                     │
│                                                                  │
│  ┌──────────────────────┐                                       │
│  │ 微信 3.9.10.19 机器人 │                                       │
│  │ (wxid_xxxxxxxxx)     │                                       │
│  └────────┬─────────────┘                                       │
│           │ wxhelper TCP (:19099) → 收消息                       │
│           │ wxhelper HTTP (:19088) → 发消息                       │
│           ▼                                                     │
│  ┌────────────────────────────────────────────┐                 │
│  │         Bridge Agent (bridge.py v3)         │                 │
│  │                                            │                 │
│  │  ┌────────────────────────────────────┐   │                 │
│  │  │ 消息收 (TCP thread)               │   │                 │
│  │  │ 收到微信消息 → 写入 serve session  │   │   opencode       │
│  │  │              → 触发 webhook(可选) │──┼──→ serve :4096    │
│  │  └────────────────────────────────────┘   │                 │
│  │                                            │                 │
│  │  ┌────────────────────────────────────┐   │                 │
│  │  │ HTTP API 服务 (:5801)             │   │                 │
│  │  │ POST /send → 发微信               │   │                 │
│  │  │ POST /history → 查历史            │   │                 │
│  │  │ POST /inject → 写 serve 会话     │   │                 │
│  │  └────────────────────────────────────┘   │                 │
│  └────────────────────────────────────────────┘                 │
│           │                              ▲                      │
│           │  serve session 里的 AI        │ HTTP POST /send     │
│           ▼                              │                      │
│  ┌────────────────────────────────────┐  │                      │
│  │    opencode serve TUI              │  │                      │
│  │    (Sisyphus / 任何 Agent)         │──┘                      │
│  │                                    │                         │
│  │  「老莫：今天吃了吗」← 从 session 看到  │                        │
│  │  「回复：[xxm] 吃了」→ POST :5801   │                         │
│  └────────────────────────────────────┘                          │
└─────────────────────────────────────────────────────────────────┘

---

数据流

微信消息 → AI（上行）

1. 老莫发微信给机器人号
2. wxhelper DLL 通过 TCP (:19099) 推送给 Bridge Agent
3. Bridge Agent 收到消息，写入 serve session:
   subprocess.run(["opencode", "run", "--attach", 
                   "--message", "[老莫] 消息内容"])
4. 同时，消息可通过 :5801 HTTP API 被任何订阅者消费
5. serve session 里的 AI 在 TUI 或通过 session_search 看到

AI 回复 → 微信（下行）

1. AI 决定回复 → POST http://localhost:5801/send
   {"to": "wxid_xxx", "message": "回复内容"}
2. Bridge Agent 收到 → wxpost /api/sendTextMsg
3. wxhelper DLL 发送 → 老莫手机收到

---

Bridge Agent 接口规范

HTTP API (:5801)

方法	路径	用途	Body
POST	/send	发微信消息	{"to":"wxid","message":"text"}
POST	/history	查聊天记录	{"wxid":"...","count":20}
POST	/recent	最近联系人	无
POST	/inject	写 serve session	{"message":"[xxm] 内容"}
GET	/health	健康检查	无

输出到 serve session 的格式

[老莫] 消息内容          → 来自微信的普通消息
[老莫|昵称] 消息内容      → 带昵称
[系统] 新联系人 xxx      → 系统事件
[session:<id>] 启动签到  → Agent 上线通知

---

与 Hermes AI 的关系

Hermes 不再是架构的核心组件，而是可选的消息消费者之一：

                    ┌─→ opencode serve session → Sisyphus (小小莫)
老莫微信 → Bridge ──┤
                    └─→ 消费 HTTP API 的任意程序
                            │
                      ┌─────┴─────┐
                      │            │
                   Hermes AI    其他 AI
                   (莫荷)       (未来)

迁就策略：

1. 第一阶段：Bridge Agent 同时写 serve session + POST Hermes API（现状保留）
2. 第二阶段：Bridge Agent 只写 serve session，Hermes 通过 serve session 接入
3. 第三阶段：完全通用化，Hermes 只是 serve session 里的一个 AI 角色

---

实施原则

1. 不破坏现有链路 — Bridge Agent 改造期间，Hermes 消息路由不变
2. 增量迁移 — 先加新功能，再逐步替换旧逻辑
3. session 为主 — 所有消息以 serve session 为中心，HTTP API 为辅助
4. 最低依赖 — 纯 Windows 可运行，不需要 Linux 端 Hermes

---

开放问题

1. session ID 管理：Bridge Agent 如何知道当前有效的 session ID？
2. session write 方式：subprocess (opencode run --attach --message) 是否有更轻量的替代？
3. 消息去重：写 session + POST Hermes 可能导致重复处理？
4. serve 重启恢复：Bridge Agent 如何在 serve 重启后自动重连？
5. 历史消息：AI 上线后能否拉取 session 中已有的消息历史？

---

参考：projects/wechat-hermes-gateway/docs/老莫消息路由设计.md