184 lines
8.5 KiB
Markdown
184 lines
8.5 KiB
Markdown
# 通用架构：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* |