# API Interface Reference

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

当前定位：

- `xworkmate-bridge` 是 **APP-facing ACP control plane and provider runtime layer**
- App-facing canonical HTTP transport 是 `POST /acp/rpc`
- `GET /acp` WebSocket 仅保留为 ACP transport variant
- `/acp-server/*`、`/gateway/openclaw` 不再是 public API，也不再提供 alias handler

## 1. Runtime Entry Points

二进制入口定义在 [main.go](../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 | 是 | JSON-RPC WebSocket transport |
| `/acp/rpc` | `POST` | 是 | App-facing JSON-RPC HTTP transport |
| `/acp/rpc` | `OPTIONS` | 否 | CORS preflight |

其他路径返回 `404 Not Found`。

## 3. Auth / Origin

环境变量：

- `BRIDGE_AUTH_TOKEN`
- `ACP_ALLOWED_ORIGINS`

规则：

- `/acp` 与 `/acp/rpc` 都做 origin allowlist 校验
- 空 `Origin` 默认允许
- `/api/ping`、`/acp`、`/acp/rpc` 在 `BRIDGE_AUTH_TOKEN` 非空时都要求 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。

请求：

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

成功响应：

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

通知：

```json
{
  "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。

返回示例：

```json
{
  "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 示例：

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

unavailable 示例：

```json
{
  "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`

返回：

```json
{ "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 实现细节