From 0a07c03f85a31eac2925b9523dde3c0622f4c7ce Mon Sep 17 00:00:00 2001 From: Haitao Pan Date: Mon, 20 Apr 2026 17:20:05 +0800 Subject: [PATCH] Document live xworkmate bridge topology --- docs/acp-public-validation-2026-04-09.md | 4 ++- docs/api-reference.md | 2 ++ docs/architecture/acp-forwarding-topology.md | 30 ++++++++++++++------ docs/architecture/bridge-runtime-design.md | 14 +++++---- docs/internal-reference.md | 3 +- 5 files changed, 38 insertions(+), 15 deletions(-) diff --git a/docs/acp-public-validation-2026-04-09.md b/docs/acp-public-validation-2026-04-09.md index 549b92e..2d218f8 100644 --- a/docs/acp-public-validation-2026-04-09.md +++ b/docs/acp-public-validation-2026-04-09.md @@ -32,6 +32,7 @@ Verified public HTTP JSON-RPC endpoints: - Codex: `https://xworkmate-bridge.svc.plus/acp-server/codex/acp/rpc` - OpenCode: `https://xworkmate-bridge.svc.plus/acp-server/opencode/acp/rpc` - Gemini: `https://xworkmate-bridge.svc.plus/acp-server/gemini/acp/rpc` +- Hermes: `https://xworkmate-bridge.svc.plus/acp-server/hermes/acp/rpc` - OpenClaw: `https://xworkmate-bridge.svc.plus/gateway/openclaw/` The `.../acp` path remains reserved for WebSocket ACP. @@ -52,6 +53,7 @@ The ingress returned `200 OK` on all public routes after re-apply, and the deplo - `codex` -> `127.0.0.1:9001` - `opencode` -> `127.0.0.1:38992` - `gemini` -> `127.0.0.1:8791` +- `hermes` -> `127.0.0.1:3920` - `openclaw` -> `127.0.0.1:18789` (Host process) ### Codex @@ -200,7 +202,7 @@ For single-agent task execution: ### Provider-specific notes -- `codex`, `opencode`, and `gemini` are all now verified public task paths. +- `codex`, `opencode`, `gemini`, and `hermes` are all now verified public task paths. - `gemini` still depends on the adapter compatibility layer, not a native upstream Gemini ACP conversation method. - For multi-turn flows, apps should preserve and resend `routing` on every `session.message`. - `codex` and `opencode` currently require explicit `routing` on follow-up turns. diff --git a/docs/api-reference.md b/docs/api-reference.md index 9735ff0..e0005cd 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -7,6 +7,7 @@ - `xworkmate-go-core serve` 暴露的 bridge HTTP / WebSocket API - `xworkmate-go-core acp-stdio` 暴露的 stdio ACP bridge - `xworkmate-go-core gemini-acp-adapter` 暴露的 Gemini adapter HTTP / WebSocket API +- `xworkmate-go-core hermes-acp-adapter` 暴露的 Hermes adapter HTTP / WebSocket API - `main.go` 默认模式下 `toolbridge.Run` 暴露的本地工具桥协议 不覆盖： @@ -23,6 +24,7 @@ | Bridge HTTP / WS | `./build/bin/xworkmate-go-core serve` | 启动 canonical bridge，对外暴露 `/acp/rpc` 与 `/acp`，并附带健康检查。 | | ACP stdio | `./build/bin/xworkmate-go-core acp-stdio` | 通过 stdin/stdout 提供 ACP bridge。 | | Gemini adapter | `./build/bin/xworkmate-go-core gemini-acp-adapter` | 把 Gemini CLI / Gemini ACP stdio 封装成 HTTP / WebSocket ACP 服务。 | +| Hermes adapter | `./build/bin/xworkmate-go-core hermes-acp-adapter` | 把 Hermes stdio ACP 封装成 HTTP / WebSocket ACP 服务。 | | Tool bridge | `./build/bin/xworkmate-go-core` | 默认模式；暴露本地工具桥协议，不挂 bridge HTTP 路由。 | ## 2. Bridge `serve` Mode diff --git a/docs/architecture/acp-forwarding-topology.md b/docs/architecture/acp-forwarding-topology.md index 6d60adf..dccf45e 100644 --- a/docs/architecture/acp-forwarding-topology.md +++ b/docs/architecture/acp-forwarding-topology.md @@ -39,7 +39,7 @@ flowchart TD B6["xworkmate.gateway.*"] B7["bridge-owned provider catalog"] B8["bridge-owned routing"] - B9["bridge-owned gateway runtime"] + B9["bridge-owned gateway runtime"] A3 --> B1 A3 --> B2 @@ -58,16 +58,19 @@ flowchart TD C1["https://xworkmate-bridge.svc.plus/acp-server/codex/acp/rpc"] C2["https://xworkmate-bridge.svc.plus/acp-server/opencode/acp/rpc"] C3["https://xworkmate-bridge.svc.plus/acp-server/gemini/acp/rpc"] - C4["https://xworkmate-bridge.svc.plus/gateway/openclaw/"] + C4["https://xworkmate-bridge.svc.plus/acp-server/hermes/acp/rpc"] + C5["https://xworkmate-bridge.svc.plus/gateway/openclaw/"] end B7 --> C1 B7 --> C2 B7 --> C3 + B7 --> C4 B8 --> C1 B8 --> C2 B8 --> C3 - B9 --> C4 + B8 --> C4 + B9 --> C5 ``` ## Three-Layer View @@ -93,6 +96,7 @@ flowchart LR CAP1["codex"] CAP2["opencode"] CAP3["gemini"] + CAP4["hermes"] GW["Bridge-owned gateway routing"] GW1["gatewayProviderId=openclaw"] @@ -101,6 +105,7 @@ flowchart LR CAP --> CAP1 CAP --> CAP2 CAP --> CAP3 + CAP --> CAP4 BRIDGE --> GW GW --> GW1 @@ -110,7 +115,8 @@ flowchart LR U1["https://xworkmate-bridge.svc.plus/acp-server/codex/acp/rpc"] U2["https://xworkmate-bridge.svc.plus/acp-server/opencode/acp/rpc"] U3["https://xworkmate-bridge.svc.plus/acp-server/gemini/acp/rpc"] - U4["https://xworkmate-bridge.svc.plus/gateway/openclaw/
reported as xworkmate-bridge.svc.plus:443"] + U4["https://xworkmate-bridge.svc.plus/acp-server/hermes/acp/rpc"] + U5["https://xworkmate-bridge.svc.plus/gateway/openclaw/
reported as xworkmate-bridge.svc.plus:443"] end APPMETHODS --> BRIDGE @@ -118,7 +124,8 @@ flowchart LR CAP1 --> U1 CAP2 --> U2 CAP3 --> U3 - GW1 --> U4 + CAP4 --> U4 + GW1 --> U5 ``` Important distinction: @@ -132,7 +139,7 @@ Important distinction: - `acp.capabilities` is the single APP-facing source for task dialog modes and target-scoped provider catalogs - `providerCatalog` currently advertises the ACP single-agent providers: - `codex`, `opencode`, and `gemini` + `codex`, `opencode`, `gemini`, and `hermes` - `gatewayProviders` currently advertises the gateway-scoped providers, such as `openclaw` - `availableExecutionTargets` tells the app which first-level task dialog modes @@ -150,14 +157,15 @@ Important distinction: ### 核心真源映射 (Final Source of Truth) -为了消除冗余层（Bridge-on-Bridge）并提高就绪性响应速度，中心 Bridge 已配置为绕过 9010/3910 转发层，直接对接各核心服务端口： +为了消除冗余层（Bridge-on-Bridge）并提高就绪性响应速度，中心 Bridge 已配置为绕过旧的 9010/3910 转发层，直接对接各核心服务端口： | 服务名 | 核心端口 | 协议路径 | 角色定义 | | :--- | :--- | :--- | :--- | -| **`openclaw-gateway.service`** | **`18789`** | **`ws://127.0.0.1:18789/`** | **OpenClaw 独立网关服务（不使用 /acp）** | +| **`openclaw-gateway.service`** | **`18789`** | **`ws://127.0.0.1:18789/`** | **OpenClaw 独立部署网关服务（不使用 /acp）** | | **`acp-codex.service`** | **`9001`** | **`http://127.0.0.1:9001/acp/rpc`** | **Codex 核心 ACP 实现** | | **`acp-opencode.service`** | **`38992`** | **`http://127.0.0.1:38992/acp/rpc`** | **Opencode 核心 ACP 实现** | | **`acp-gemini.service`** | **`8791`** | **`http://127.0.0.1:8791/acp/rpc`** | **Gemini 协议转换适配器 (Category: protocol-adapter)** | +| **`acp-hermes.service`** | **`3920`** | **`http://127.0.0.1:3920/acp/rpc`** | **Hermes 协议转换适配器 (Category: protocol-adapter)** | 对 app 而言： @@ -169,6 +177,12 @@ Important distinction: - app traffic reaches upstream ACP and gateway services only through the bridge - app does not call `xworkmate-bridge.svc.plus/acp-server/*` or `xworkmate-bridge.svc.plus/gateway/openclaw/` directly +- `openclaw-gateway` is an independently deployed runtime mapped to `127.0.0.1:18789` +- internal provider routes remain bridge-owned validation targets: + - `xworkmate-bridge.svc.plus/acp-server/codex/acp/rpc` + - `xworkmate-bridge.svc.plus/acp-server/opencode/acp/rpc` + - `xworkmate-bridge.svc.plus/acp-server/gemini/acp/rpc` + - `xworkmate-bridge.svc.plus/acp-server/hermes/acp/rpc` - upstream auth stays bridge-internal: - `Authorization: Bearer $INTERNAL_SERVICE_TOKEN` - `acp.capabilities` is the provider / capability discovery source diff --git a/docs/architecture/bridge-runtime-design.md b/docs/architecture/bridge-runtime-design.md index b535505..9e62def 100644 --- a/docs/architecture/bridge-runtime-design.md +++ b/docs/architecture/bridge-runtime-design.md @@ -11,15 +11,17 @@ | `serve` | `acp.Serve` | 启动 bridge HTTP / WebSocket 服务，对外暴露 `/acp/rpc` 与 `/acp`，并附带健康检查路由。 | | `acp-stdio` | `acp.RunStdio` | 启动 stdio ACP bridge，适合被宿主进程以 stdin/stdout 驱动。 | | `gemini-acp-adapter` | `geminiadapter.Serve` | 启动 Gemini 专用 ACP adapter，把 Gemini CLI 包装成 ACP HTTP / WebSocket 服务。 | +| `hermes-acp-adapter` | `hermesadapter.Serve` | 启动 Hermes 专用 ACP adapter，把 Hermes stdio ACP 包装成 ACP HTTP / WebSocket 服务。 | | 默认模式 | `toolbridge.Run` | 启动 MCP 风格的本地工具桥，暴露 `chat`、`claude_review`、`vault_kv` 等工具。 | ｜服务 │ 外部入口 (HTTPS/WSS) │ 后端转发目标 (Local) │ 部署方式 │ ├──────────┼────────────────────────────────────────────────┼──────────────────────────┼─────────────┤ - │ Bridge │ xworkmate-bridge.svc.plus/ │ 127.0.0.1:8787 │ Docker 容器 │ - │ OpenClaw │ xworkmate-bridge.svc.plus/gateway/openclaw/ │ 127.0.0.1:18789 │ 主机进程 │ - │ Codex │ xworkmate-bridge.svc.plus/acp-server/codex/ │ acp-server-codex:3911 │ Docker 容器 │ - │ OpenCode │ http://127.0.0.1:38992/acp/rpc │ acp-opencode:38992 │ Docker 容器 │ - │ Gemini │ xworkmate-bridge.svc.plus/acp-server/gemini/ │ acp-server-gemini:3912 │ Docker 容器 + │ Bridge │ xworkmate-bridge.svc.plus/ │ 127.0.0.1:8787 │ 主机进程 │ + │ OpenClaw │ xworkmate-bridge.svc.plus/gateway/openclaw/ │ 127.0.0.1:18789 │ 独立部署 │ + │ Codex │ xworkmate-bridge.svc.plus/acp-server/codex/ │ 127.0.0.1:9001 │ 主机进程 │ + │ OpenCode │ xworkmate-bridge.svc.plus/acp-server/opencode/ │ 127.0.0.1:38992 │ 主机进程 │ + │ Gemini │ xworkmate-bridge.svc.plus/acp-server/gemini/ │ 127.0.0.1:8791 │ 主机进程 │ + │ Hermes │ xworkmate-bridge.svc.plus/acp-server/hermes/ │ 127.0.0.1:3920 │ 主机进程 │ 设计含义： @@ -27,6 +29,7 @@ - `main.go` 不承载业务决策，只做模式分发。 - APP-facing canonical bridge 只由 `serve` 模式提供。 - `gemini-acp-adapter` 是独立 adapter，而不是 bridge 主入口的一部分。 +- `hermes-acp-adapter` 也是独立 adapter，不是 bridge 主入口的一部分。 - 默认工具桥是本地工具执行面，不参与 APP-facing canonical path。 ## 2. 系统边界 @@ -50,6 +53,7 @@ single-agent provider 目录由 [internal/acp/provider_catalog.go](../../interna - `codex` - `opencode` - `gemini` +- `hermes` 这些 provider 的 endpoint 和 auth 归 bridge 所有。APP 只通过 `/acp/rpc` 和 `/acp` 与 bridge 交互，不直接依赖 provider-specific public URL。 diff --git a/docs/internal-reference.md b/docs/internal-reference.md index adb1cff..a82f9d1 100644 --- a/docs/internal-reference.md +++ b/docs/internal-reference.md @@ -19,7 +19,8 @@ | **`acp-codex.service`** | `9001` | HTTP | Codex 核心 ACP 控制面 | | **`acp-opencode.service`** | `38992` | HTTP | Opencode 核心 ACP 控制面 | | **`acp-gemini.service`** | `8791` | HTTP | Gemini 协议适配器 (protocol-adapter) | -| **`openclaw-gateway.service`** | `18789` | WS | OpenClaw 独立网关运行时 | +| **`acp-hermes.service`** | `3920` | HTTP | Hermes 协议适配器 (stdio ACP adapter) | +| **`openclaw-gateway.service`** | `18789` | WS | OpenClaw 独立部署网关运行时，映射到 `127.0.0.1:18789` | ### 包职责