ai-workspace-lab/xworkmate-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document live xworkmate bridge topology

Browse Source
This commit is contained in:
Haitao Pan 2026-04-20 17:20:05 +08:00
parent 1e6c644a92
commit 0a07c03f85
5 changed files with 38 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/acp-public-validation-2026-04-09.md
View File

@ -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.

2
docs/api-reference.md
View File

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

30
docs/architecture/acp-forwarding-topology.md
View File

@ -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/<br/>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/<br/>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

14
docs/architecture/bridge-runtime-design.md
View File

@ -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。

3
docs/internal-reference.md
View File

@ -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` |
### 包职责