195 lines
4.3 KiB
Markdown
195 lines
4.3 KiB
Markdown
# Internal Reference
|
||
|
||
本文档记录 `xworkmate-bridge` 当前内部模块边界，只覆盖当前保留的 control-plane 主链。
|
||
|
||
## 1. 总体分层
|
||
|
||
当前内部结构分为五层：
|
||
|
||
1. `bridge_contract`
|
||
2. `capability_catalog`
|
||
3. `routing_engine`
|
||
4. `session_orchestrator`
|
||
5. `provider_compat` / `gateway compat`
|
||
|
||
核心原则：
|
||
|
||
- bridge core 不再承担 reverse proxy public surface
|
||
- bridge core 不再承担 multi-agent 业务分叉
|
||
- stdio / process / framing / restart 细节下沉到 adapter runtime
|
||
|
||
## 2. `internal/acp`
|
||
|
||
### 包职责
|
||
|
||
APP-facing ACP control plane。
|
||
|
||
负责：
|
||
|
||
- `/acp` App-facing WebSocket JSON-RPC 主入口
|
||
- `/acp/rpc` HTTP JSON-RPC fallback / CI / 调试 / OpenClaw task submit 入口
|
||
- JSON-RPC / hybrid envelope
|
||
- `acp.capabilities`
|
||
- `xworkmate.routing.resolve`
|
||
- `session.*`
|
||
- `xworkmate.gateway.*`
|
||
|
||
### 关键类型
|
||
|
||
- `type Server struct`
|
||
- bridge 聚合根
|
||
- 持有 `routingEngine`、`providers`、`catalog`、`orchestrator`、`gateway`
|
||
|
||
- `type ProviderCompat interface`
|
||
- bridge 依赖的唯一 provider 接口
|
||
- 方法：
|
||
- `ID()`
|
||
- `Metadata()`
|
||
- `Probe(ctx)`
|
||
- `StartSession(...)`
|
||
- `SendMessage(...)`
|
||
- `CancelSession(...)`
|
||
- `CloseSession(...)`
|
||
|
||
- `type RoutingResult struct`
|
||
- routing 输出 contract
|
||
- 包括：
|
||
- `TargetID`
|
||
- `ProviderID`
|
||
- `GatewayProviderID`
|
||
- `Model`
|
||
- `Skills`
|
||
- `Status`
|
||
- `UnavailableCode`
|
||
- `UnavailableMsg`
|
||
|
||
- `type CapabilityCatalog struct`
|
||
- bridge-owned capabilities 真源
|
||
- 包括：
|
||
- `ProviderCatalog`
|
||
- `GatewayProviders`
|
||
- `AvailableExecutionTargets`
|
||
- `ProviderProbeSummary`
|
||
|
||
### 关键主链
|
||
|
||
- `func NewServer() *Server`
|
||
- 初始化 routing engine、catalog、providers、orchestrator、gateway manager
|
||
|
||
- `func (s *Server) Handler() http.Handler`
|
||
- 只挂载：
|
||
- `/`
|
||
- `/api/ping`
|
||
- `/acp`
|
||
- `/acp/rpc`
|
||
|
||
- `func (s *Server) handleRequest(...)`
|
||
- 统一分派：
|
||
- `acp.capabilities`
|
||
- `session.*`
|
||
- `xworkmate.routing.resolve`
|
||
- `xworkmate.gateway.*`
|
||
|
||
- `func (o *SessionOrchestrator) Process(...)`
|
||
- bridge session 主语义入口
|
||
- 流程：
|
||
- resolve routing
|
||
- get/create session state
|
||
- dispatch to gateway or provider compat
|
||
- normalize result
|
||
- emit `session.update`
|
||
- record project memory only when routing mode is explicitly auto
|
||
|
||
### 当前删除或收紧的旧路径
|
||
|
||
以下逻辑不属于当前 APP-facing contract：
|
||
|
||
- `/acp-server/*`
|
||
- `/gateway/openclaw`
|
||
- multi-agent 执行路径
|
||
- provider-specific alias handler
|
||
|
||
OpenClaw task submit 使用 `/acp/rpc` 和 routing metadata，不再保留独立 app-facing handler。
|
||
|
||
## 3. `provider_compat`
|
||
|
||
bridge 当前通过 compat 层吸收 provider 差异：
|
||
|
||
- `codex compat`
|
||
- `opencode compat`
|
||
- `gemini compat`
|
||
- `hermes compat`
|
||
|
||
这些 compat 共享同一套 external ACP 调用基座，但对 bridge core 暴露统一接口。
|
||
|
||
### compat 负责什么
|
||
|
||
- 调上游 ACP HTTP / WS
|
||
- 解析 JSON-RPC result / error
|
||
- 转换 upstream notification
|
||
- 吸收 provider transport 差异
|
||
|
||
### compat 不负责什么
|
||
|
||
- catalog ownership
|
||
- routing ownership
|
||
- session state ownership
|
||
- app-facing contract 设计
|
||
|
||
## 4. `routing_engine`
|
||
|
||
当前 routing 只围绕 bridge 核心能力做决策：
|
||
|
||
- `single-agent`
|
||
- `gateway`
|
||
|
||
不再升级到 multi-agent。
|
||
|
||
输入来源：
|
||
|
||
- prompt
|
||
- workingDirectory
|
||
- explicit routing
|
||
- preferred gateway provider
|
||
- available bridge providers
|
||
- available skills
|
||
- memory preferences
|
||
|
||
输出由 bridge 统一整形成 `RoutingResult`。
|
||
|
||
## 5. `gatewayruntime`
|
||
|
||
`internal/gatewayruntime` 仍负责 openclaw runtime 的连接态、请求配对、快照与 push event。
|
||
|
||
这个包是 gateway runtime 层，不是 public API 层。
|
||
|
||
bridge 只通过 `xworkmate.gateway.*` 把它暴露为 control-plane contract。
|
||
|
||
## 6. `internal/router`
|
||
|
||
任务：
|
||
|
||
- normalize routing intent
|
||
- resolve execution target
|
||
- resolve provider
|
||
- resolve gateway provider
|
||
- resolve skills
|
||
- shape unavailable reason
|
||
|
||
当前只产出：
|
||
|
||
- `single-agent`
|
||
- `gateway`
|
||
|
||
## 7. `internal/shared`
|
||
|
||
保留的 bridge_contract 基础能力：
|
||
|
||
- JSON-RPC request decode
|
||
- hybrid result/error envelope
|
||
- notification envelope
|
||
- CORS / origin helper
|
||
- shared HTTP / WS helper
|
||
|
||
这里是 envelope 与共用 transport helper，不承载 provider-specific 控制逻辑。
|