# 通用架构：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.1.16                     �?�?                                                                 �?�? ┌──────────────────────�?                                      �?�? �?微信 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*