# Bridge Runtime Design

本文档描述 `xworkmate-bridge` 当前的收敛后运行模型。

## 1. 角色定义

`xworkmate-bridge` 被明确限定为：

**APP-facing ACP control plane and provider compatibility layer**

它不是：

- 通用 reverse proxy
- ingress gateway
- stdio runtime 本体

## 2. 三层边界

### Bridge Core

bridge core 保留：

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

### Provider Compatibility / Adapter Runtime

adapter/runtime 保留：

- codex compat
- opencode compat
- gemini compat
- hermes compat
- JSON-RPC over stdio
- process lifecycle / restart / stderr
- provider-specific framing / upstream session mapping

### Outer Gateway

APISIX / Caddy 这类外层网关负责：

- TLS
- ingress
- path routing
- rate limit
- audit / access logging

## 3. Transport 选择

bridge 当前采用：

- App-facing canonical transport: `GET /acp` WebSocket upgrade
- HTTP JSON-RPC fallback: `POST /acp/rpc`

设计含义：

- WebSocket 是 App 运行时主链
- HTTP RPC 只用于 CI、脚本、调试和兼容 fallback
- provider / gateway alias route 不再属于 public surface

## 4. 模块边界

### `bridge_contract`

负责：

- JSON-RPC request / response envelope
- hybrid mode shaping
- common error mapping
- `session.update` notification envelope

### `capability_catalog`

负责：

- `providerCatalog`
- `gatewayProviders`
- `availableExecutionTargets`
- `providerProbeSummary`

### `routing_engine`

负责：

- routing normalize
- execution target resolve
- provider selection
- unavailable shaping

### `session_orchestrator`

负责：

- session state
- turn state
- history
- notification dispatch
- normalized output

### `provider_compat`

负责：

- codex compat
- opencode compat
- gemini compat
- hermes compat

### `gateway compat`

负责：

- openclaw connect / request / disconnect

## 5. 数据流

1. app 默认通过 `/acp` WebSocket 发送 JSON-RPC request
2. bridge contract decode request
3. `acp.capabilities` 从 catalog 读取 bridge-owned truth
4. `xworkmate.routing.resolve` 由 routing engine 计算
5. `session.*` 进入 orchestrator
6. orchestrator 将 provider 差异分发到 compat 层
7. compat 与实际 adapter/runtime 通信
8. bridge 统一归一化结果，并通过 `session.update` 发通知

## 6. 当前约束

- app 不应感知 provider-specific upstream URL
- app 不应感知本地端口或 service 名
- routing 逻辑不得散落到各 provider handler
- session 语义不得被 provider-specific 分支污染
- 新增 JSON-RPC over stdio provider 时，应只增加 compat/runtime，不改 bridge core
