ai-workspace-lab/xworkmate-bridge

Fork 0

Haitao Pan 17c0fa6f16 Refine bridge routing and remove fallback paths

2026-04-23 15:58:37 +08:00

6.8 KiB

Raw Blame History

API Interface Reference

本文档定义 xworkmate-bridge 当前对 xworkmate-app 暴露的稳定 contract。

当前定位：

xworkmate-bridge 是 APP-facing ACP control plane and provider compatibility layer
canonical transport 是 GET /acp 上的 JSON-RPC over WebSocket
POST /acp/rpc 保留为 secondary compatibility transport
/acp-server/*、/gateway/openclaw 不再是 public API

1. Runtime Entry Points

二进制入口定义在 main.go。

模式	命令	作用
Bridge HTTP / WS	`./build/bin/xworkmate-go-core serve`	启动 canonical bridge，暴露 `/acp` 与 `/acp/rpc`
ACP stdio	`./build/bin/xworkmate-go-core acp-stdio`	启动 stdio ACP bridge
Gemini adapter	`./build/bin/xworkmate-go-core gemini-acp-adapter`	Gemini compatibility/runtime
Hermes adapter	`./build/bin/xworkmate-go-core hermes-acp-adapter`	Hermes compatibility/runtime
Tool bridge	`./build/bin/xworkmate-go-core`	本地工具桥，不属于 APP-facing control plane

2. Public HTTP Surface

serve 模式对外暴露：

Path	Method / Protocol	Auth	用途
`/`	`GET`	否	纯文本运行状态
`/api/ping`	`GET`	否	发布版本探针
`/acp`	`GET` + WebSocket upgrade	是	canonical JSON-RPC transport
`/acp/rpc`	`POST`	是	secondary compatibility transport
`/acp/rpc`	`OPTIONS`	否	CORS preflight

其他路径返回 404 Not Found。

3. Auth / Origin

环境变量：

BRIDGE_AUTH_TOKEN
ACP_ALLOWED_ORIGINS

规则：

/acp 与 /acp/rpc 都做 origin allowlist 校验
空 Origin 默认允许
auth 使用 bearer header
BRIDGE_AUTH_TOKEN 为空时默认放行
BRIDGE_AUTH_TOKEN 非空时，接受裸 token 或 Bearer <token>

错误行为：

origin 不允许：HTTP 403，JSON-RPC error code -32003
bearer 缺失或不合法：HTTP 401，JSON-RPC error code -32001
非 POST 请求打到 /acp/rpc：HTTP 405，JSON-RPC error code -32600

4. JSON-RPC Envelope

WS 与 HTTP 都使用 JSON-RPC 2.0。为兼容现有 APP，bridge 继续输出 hybrid envelope。

请求：

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "acp.capabilities",
  "params": {}
}

成功响应：

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "success": true
  },
  "ok": true,
  "type": "res",
  "payload": {
    "success": true
  },
  "seq": 0
}

通知：

{
  "jsonrpc": "2.0",
  "method": "session.update",
  "params": {
    "turnId": "turn-1",
    "type": "status",
    "message": "session started"
  },
  "type": "event",
  "event": "session.update",
  "payload": {
    "turnId": "turn-1",
    "type": "status",
    "message": "session started"
  },
  "seq": 0
}

5. Canonical Method Family

bridge 对 app 的稳定 method family 只有：

acp.capabilities
xworkmate.routing.resolve
session.start
session.message
session.cancel
session.close
xworkmate.gateway.connect
xworkmate.gateway.request
xworkmate.gateway.disconnect

6. `acp.capabilities`

用途：返回 bridge-owned provider catalog、gatewayProviders、availableExecutionTargets。

返回示例：

{
  "singleAgent": true,
  "multiAgent": false,
  "availableExecutionTargets": ["agent", "gateway"],
  "providerCatalog": [
    { "providerId": "codex", "label": "Codex", "targets": ["agent"], "category": "native" },
    { "providerId": "opencode", "label": "OpenCode", "targets": ["agent"], "category": "protocol-adapter" },
    { "providerId": "gemini", "label": "Gemini", "targets": ["agent"], "category": "protocol-adapter" },
    { "providerId": "hermes", "label": "Hermes", "targets": ["agent"], "category": "protocol-adapter" }
  ],
  "gatewayProviders": [
    { "providerId": "openclaw", "label": "OpenClaw", "targets": ["gateway"] }
  ],
  "providerProbeSummary": [
    { "providerId": "codex", "available": true, "status": "ok" }
  ]
}

约束：

app 只能从这里获取 providerCatalog、gatewayProviders、availableExecutionTargets
app 不应依赖 bridge 内部 provider URL / 端口 / service 名

7. `xworkmate.routing.resolve`

用途：bridge control plane 独立做 routing intent resolve。

输入重点：

taskPrompt
workingDirectory
routing.routingMode
routing.explicitExecutionTarget
routing.explicitProviderId
routing.preferredGatewayProviderId
routing.explicitModel
routing.explicitSkills
routing.availableSkills

输出字段：

resolvedExecutionTarget
resolvedProviderId
resolvedGatewayProviderId
resolvedModel
resolvedSkills
status
unavailable
unavailableCode
unavailableMessage
skillResolutionSource
needsSkillInstall
skillInstallRequestId

available 示例：

{
  "resolvedExecutionTarget": "single-agent",
  "resolvedProviderId": "codex",
  "resolvedGatewayProviderId": "",
  "resolvedModel": "",
  "resolvedSkills": ["PPTX"],
  "status": "available",
  "unavailable": false
}

unavailable 示例：

{
  "resolvedExecutionTarget": "single-agent",
  "resolvedProviderId": "",
  "resolvedGatewayProviderId": "",
  "resolvedModel": "",
  "resolvedSkills": [],
  "status": "unavailable",
  "unavailable": true,
  "unavailableCode": "PROVIDER_UNAVAILABLE",
  "unavailableMessage": "explicit provider is unavailable"
}

8. `session.start` / `session.message`

用途：统一进入 session_orchestrator，由 bridge 控制 session state、turnId、history、notification、normalized result。

通用输入：

sessionId
threadId
taskPrompt
workingDirectory
routing

统一结果字段：

success
status
turnId
resolvedExecutionTarget
resolvedProviderId
resolvedGatewayProviderId
resolvedModel
resolvedSkills
output
summary

bridge 保证：

provider-specific 差异被 compat layer 吸收
bridge core 不暴露 stdio/runtime 细节
中间通知统一通过 session.update

9. `session.cancel` / `session.close`

{ "accepted": true }

语义：

session.cancel 调用当前 compat 的 cancel
session.close 调用当前 compat 的 close，并移除 bridge 内部 session state

10. `xworkmate.gateway.*`

gateway method family 保留为 control-plane contract：

xworkmate.gateway.connect
xworkmate.gateway.request
xworkmate.gateway.disconnect

对 app 的约束：

app 调 gateway runtime 时仍然只通过 bridge JSON-RPC methods
openclaw 是 bridge-owned gateway provider，不是 app-facing direct route

11. 非 Contract 内容

以下内容不是 app contract：

provider-specific upstream URL
本地端口
systemd service 名
stdio framing / process lifecycle / stderr / restart 语义
bridge 内部 compat/runtime 实现细节

6.8 KiB Raw Blame History Unescape Escape