# 通用架构：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*