# 🤖 WeChat Hermes Gateway

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

---

## 最终架构

```
┌──────────────────────────────────────────────────────────────┐
│ Windows 192.168.0.111                                        │
│                                                              │
│  ┌──────────────────┐      ┌───────────────────────────┐    │
│  │ 微信 3.9.5.81 x64 │      │ 日常微信 WeChatAppEx 4.x  │    │
│  │ 机器人号modachen │      │ 老爸日常使用，互不干扰    │    │
│  │ wxhook Bot类TCP  │      └───────────────────────────┘    │
│  └────────┬─────────┘                                       │
│           │ wxhook DLL 收消息                                │
│  ┌────────▼────────────────┐                                │
│  │ wechat_agent.py         │  ← 常驻进程                    │
│  │                         │                                │
│  │ Bot类接收微信事件(TCP)  │                                │
│  │ → POST Hermes API :8642 │  ← 带session: sisyphus        │
│  │ ← 收回复 → wxhook发回   │                                │
│  │ :5801 ←Hermes找小小莫   │  ← 双向通道                   │
│  │ 看门狗防 wxhook 挂掉    │                                │
│  └────────┬────────────────┘                                │
└───────────┼─────────────────────────────────────────────────┘
            │ HTTP (局域网)
┌───────────▼─────────────────────────────────────────────────┐
│ Linux 192.168.0.103                                          │
│                                                              │
│  ┌──────────────────────────────┐                            │
│  │ Hermes Gateway              │                            │
│  │ - API Server :8642          │  ← OpenAI兼容API           │
│  │ - session自动重置: 已关闭   │  ← sisyphus永不清         │
│  │ - 健康检查 /health          │                            │
│  └──────────────────────────────┘                            │
│                                                              │
│  hermes CLI — AI 处理引擎                                    │
│  莫荷/莫小荷 — 老爸专属称呼                                  │
└──────────────────────────────────────────────────────────────┘
```

## 数据流

### 文字消息

```
老爸发微信
  → WeChat 3.9.5.81 收到
  → wxhook DLL TCP → Bot 类 → on_msg 处理器
  → wechat_agent.py POST Hermes API (:8642)
  → X-Hermes-Session-Id: sisyphus (固定)
  → Hermes 处理 → 返回回复
  → wechat_agent.py 收回复 → wxhook API 发回
  → 老爸手机收到
```

### 图片消息

```
老爸发图片
  → WeChat 收到 → wxhook IMAGE_MESSAGE 事件
  → wechat_agent.py 保存图片 → 调豆包OCR (VolcEngine)
  → 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 通信 |

## 关键端口

| 端口 | 用途 | 所在 |
|------|------|------|
| 19001 | wxhook HTTP API | Windows |
| 5801 | Hermes→小小莫 消息入口 | Windows |
| 8642 | Hermes API Server (OpenAI兼容) | Linux |
| 5800 | bridge.py (已废弃) | Linux |

## 组件

### Windows 端（wechat_agent.py）
- **wxhook Bot 类** — DLL 注入 + TCP 收消息
- **Hermes API 调用** — 直接 POST :8642，session 固定 `sisyphus`
- **回复服务** — 5801 端口收 Hermes 消息
- **看门狗** — 2 分钟无消息自动刷新 webhook；API 挂了才重注入 DLL
- **昵称缓存** — 从 wxhook getContactList 获取联系人昵称

### 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

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

或直接：

```powershell
$env:PYTHONHOME=''
Start-Process -WindowStyle Hidden python.exe scripts\wechat_agent.py
```

启动后需用修复过低工具扫码登录微信。

### Linux（如重启后）

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

验证：
```bash
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 | 写入 `C:\Users\hmo\Desktop\hermes_inbox.txt` |
| 老爸 ↔ Hermes | 微信聊天 | 自动通过 wechat_agent.py 桥接 |

## 项目文件

```
wechat-hermes-gateway/
├── README.md                    # 本文档
├── scripts/
│   ├── wechat_agent.py          # 主力：微信机器人代理
│   └── start_bridge.bat         # 一键启动脚本
└── temp/                        # 废弃/临时脚本
```

## 历史决策

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

## 已实现的功能

| 功能 | 状态 |
|------|------|
| 文字消息收发（个人聊天） | ✅ 双向，session 上下文连贯 |
| 文字消息收发（群聊） | ✅ 同 session，认识老爸 |
| 图片接收 + OCR 分析 | ✅ 自动 OCR → 结果给莫荷 |
| 发送网上图片 | ✅ [IMG]URL[/IMG] 标记，Bot.send_image 发出 |
| 图像生成 (SenseNova商汤) | ✅ [IMG]generate:描述[/IMG] 支持多种比例 |
| 图像理解/OCR | ✅ 豆包OCR + SenseNova 双引擎 |
| Hermes 身份认知 | ✅ 知道自己是莫荷/莫小荷，知道老爸 |
| 会话上下文持续 | ✅ session `sisyphus`，自动重置已关闭 |
| 小小莫 ↔ Hermes 双向通信 | ✅ API (:8642) + HTTP (:5801/hermes-msg) |
| wxhook 看门狗自愈 | ✅ 2分钟无消息刷新 webhook |
| 昵称识别 | ✅ 从 getContactList 获取 |
| 联系人列表查询 | ✅ wxhook /api/getContactList |

## 未实现 / 不可行

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

## 灾难恢复流程

### 场景：Windows 重启

需要 3 步，**顺序不能错**：

```
第1步：双击 start_bridge.bat
        → 自动杀旧微信 → Bot 类启动新微信 + 注入 DLL
        → 等待微信窗口出现

第2步：运行修复过低工具
        → 选择修复过低6.0\低版通用杀器.sp.exe
        → 自动扫描到已运行的微信 → 打补丁 → 弹出登录二维码

第3步：手机扫码登录
        → 登录后 wechat_agent.py 自动检测到登录状态
        → 开始转发消息
        → 给 filehelper 发 "[Bridge] online" 确认
```

验证：手机发条消息给 modachenchen，看能否收到自动回复。

### 场景：Linux 重启

```bash
# 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，首次调用需加载模型 |
| 语音转文字 | wxhook 不支持语音提取，暂不可行 |

## 注意事项

- wxhook DLL 仅支持 x64 微信 3.9.5.81
- 每次 WeChat 重启需重新登录（修复过低工具）
- **start_bridge.bat 必须第 1 步执行**，修复工具第 2 步
- Hermes API 首次调用可能较慢（大模型冷启动）
- 看门狗只刷新 webhook，不会误伤正常消息处理
- 如果微信登录后没反应，等 1-2 分钟看门狗会自动刷新