概述
本笔记记录 Hermes Agent 通过 Tailscale 远程操作工作机上的 opencode serve 模式的架构方案。
┌──────────────────────────────────────────────────────────┐
│ Hermes → opencode serve 远程开发架构 │
│ 跨 Tailscale 局域网 · 编排远端 coding agent │
├──────────────────────────────────────────────────────────┤
│ ☁️ ARM 云服务器 arm.atibm.com │
│┌────────────────────────────────────────────────────────┐│
││ Docker Container (ghost_net) ││
││ ┌────────────────────────────────────────────────┐ ││
││ │ Hermes Agent │ ││
││ │ deepseek-v4-flash · 编排决策 │ ││
││ │ terminal() execute_code() │ ││
││ └────────────────────────────────────────────────┘ ││
││ ┌────────────────────────────────────────────────┐ ││
││ │ 🔒 Tailscale (userspace) │ ││
││ │ 出站连接 tailnet 节点 │ ││
││ └────────────────────────────────────────────────┘ ││
│└────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
├──────────────────────────────────────────────────────────┤
│ 🔗 Tailscale Tailnet │
│ WireGuard + MagicDNS + 点对点直连 │
│┌────────────────────────────────────────────────────────┐│
││ max2-at.tail9e6317.ts.net ││
│└────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
├──────────────────────────────────────────────────────────┤
│ 🖥 工作机 (max2) │
│┌────────────────────────────────────────────────────────┐│
││ ┌────────────────────────────────────────────────┐ ││
││ │ opencode serve :4096 │ ││
││ └────────────────────────────────────────────────┘ ││
││ 📁 项目文件（本地读写 · 无需 SCP） ││
││ 🧠 AI 推理（代码生成 · 测试运行） ││
││ 🔀 Git（本地仓库 · CI 集成） ││
│└────────────────────────────────────────────────────────┘│
├──────────────────────────────────────────────────────────┤
│ 工作流 │
│① 任务分解 → ② 远程调用 → ③ 代码生成 → ④ 结果回收 → ⑤ 交付│
├──────────────────────────────────────────────────────────┤
│ 三种操作模式 │
│ A. opencode --attach 指令推送 │
│ terminal("opencode run 'T' --attach http://...") │
│ B. HTTP API 直接调用 │
│ execute_code() 发送 HTTP 请求到 opencode API │
│ C. 多 worker 并行编排 │
│ 多台工作机同时 attach，并行任务 │
├──────────────────────────────────────────────────────────┤
│ 数据流 │
│ Hermes => [Tailscale] => max2:4096 => AI + 项目 => 结果 │
└──────────────────────────────────────────────────────────┘架构说明
架构分为三个层级：
1. 编排层 — Hermes Agent（ARM 云服务器）
- 运行在
arm.atibm.com的 Docker 容器内（ghost_net 网络） - 负责需求理解、任务切片、指令分发
- 通过
terminal()或execute_code()工具，使用opencode --attach或 HTTP 调用远程 opencode server
2. 网络层 — Tailscale
- Hermes Docker 容器内运行 Tailscale userspace 模式
- 通过 MagicDNS 解析工作机：
max2-at.tail9e6317.ts.net - WireGuard 端到端加密，点对点直连（同局域网低延迟）
- 出站连接能力已通过 MCP 端口（:9003）验证
3. 执行层 — opencode serve（max2 工作机）
- 工作机运行
opencode serve监听端口 4096 - 通过
--attach http://max2-at.tail9e6317.ts.net:4096接收远程指令 - 代码在工作机本地生成、读写项目文件，无需 SCP/同步
- AI 推理在工作机上进行（利用其 GPU/计算资源）
三种操作模式
| 模式 | 方法 | 适用场景 |
|---|---|---|
| A · --attach 指令推送 | terminal("opencode run '任务' --attach http://...") |
一次性编码任务，利用 opencode CLI 的完整能力 |
| B · HTTP API 直接调用 | execute_code() 发送 HTTP 请求到 opencode API |
精细化编排：Hermes 拆任务 → 逐个 POST → 取结果 → 整合 |
| C · 多 worker 并行编排 | 多台工作机同时 attach，Hermes 分配并行任务 | 大规模并行开发（特性分支并行实现） |
工作流
- 任务分解 — Hermes 理解需求，将任务拆分为可执行切片
- 远程调用 — 通过
opencode --attach发送指令到 max2:4096 - 代码生成 — opencode 在工作机进行 AI 推理，直接读写本地项目文件
- 结果回收 — 状态和日志通过返回流回到 Hermes
- 交付 — Hermes 审阅结果，整合交付用户
数据流路径
Hermes => [Tailscale] => max2:4096 => AI + 项目 => 结果注意事项
- opencode 新版本（v1.15+）端口动态分配，不支持 --port；如果 4096 能固定，可能是旧版或自行包装
- 务必设置
OPENCODE_SERVER_PASSWORD环境变量保护 serve 端口 - Tailscale userspace 模式仅支持出站连接，不支持入站 — 从工作机主动连 Hermes 不可信