ai-workspace-lab/xworkmate-bridge

Fork 0

Haitao Pan 3b088f71e2 Route OpenClaw tasks through ACP RPC

2026-05-26 11:06:22 +08:00

2.7 KiB

Raw Blame History

ADR: Refocus xworkmate-bridge as ACP Control Plane

Status

Accepted

Context

xworkmate-bridge 历史上混入了三类职责：

app-facing ACP control plane
provider/gateway alias route
stdio/process/runtime implementation detail

这些职责混在一起后，bridge 容易退化成：

通用 reverse proxy
ingress path router
adapter runtime 容器

结果是：

provider catalog 真源不清晰
routing 逻辑容易散落
session 主语义被 provider-specific 分支污染
app 容易误依赖内部 URL / 端口 / service 名

Decision

我们将 xworkmate-bridge 收敛为：

APP-facing ACP control plane and provider compatibility layer

1. bridge 不是 just proxy

bridge 的核心资产不是纯转发，而是：

acp.capabilities
xworkmate.routing.resolve
session orchestration
xworkmate.gateway.*

因此 bridge 不再以 alias route 作为 public surface。

2. provider catalog 必须是 bridge-owned truth

app 只能通过 acp.capabilities 获取：

providerCatalog
gatewayProviders
availableExecutionTargets

app 不应依赖：

/acp-server/*
/gateway/openclaw 作为全局 ACP base endpoint
本地端口
systemd service 名

3. stdio runtime 必须留在 bridge core 之外

以下内容不是 bridge core：

JSON-RPC over stdio framing
process lifecycle
restart / stderr
provider-specific upstream session 映射

这些细节属于 adapter runtime / provider compat。

4. routing.resolve 与 session orchestration 是核心资产

bridge 继续保留：

独立 routing engine
统一 session orchestrator

provider-specific 逻辑只能存在于 compat layer，不得污染公共 handler。

5. App-facing WebSocket RPC

App-facing canonical transport 定义为：

GET /acp WebSocket upgrade

POST /acp/rpc 作为 HTTP JSON-RPC fallback 保留，用于 CI、脚本、调试和兼容场景，不主导 App 运行时路由。

Consequences

正向结果

public contract 更清晰
provider 扩展更便宜
app 不再依赖内部部署事实
bridge core 与 adapter runtime 职责清晰

有意删除

/acp-server/* public alias
/gateway/openclaw 作为 provider/gateway public alias 或全局 ACP base
multi-agent 作为 bridge core 路径
以 reverse proxy 为中心的 bridge 定位

OpenClaw session.start 与 follow-up session.message 使用 /acp/rpc 加 routing metadata； capabilities、routing、cancel、close 和 gateway control-plane method 也继续走 /acp 或 /acp/rpc。

后续规则

新增 JSON-RPC over stdio provider 时：

只增加 compat/runtime
不改 bridge core contract
不把 provider-specific URL 暴露给 app

2.7 KiB Raw Blame History Unescape Escape