docs: 同步 v0.1 backend profile 规格

2026-05-29 18:05:05 +08:00
parent e955eace58
commit 526faff3f2
12 changed files with 161 additions and 62 deletions
@@ -4,7 +4,7 @@ Backend adapter 是 runner 与具体 Code Agent 工具之间的适配层。它

 ## 在系统中的职责划分

- 根据 `backendProfile` 选择具体 backend 实现；`v0.1` 必须至少证明一个真实 Agent backend，默认是 `codex`。
+- 根据 `backendProfile` 选择具体 backend profile；`v0.1` 必须支持 `codex` 与 `deepseek`，两者共享同一个 `codex-app-server-stdio` backend kind。
 - 接收 manager 持久化后的 run、command 和 executionPolicy；不得自行扩大 workspace、network、approval 或 secret scope。
 - 调用具体 backend，并把 backend 输出归一化为 AgentRun events。
 - 负责 provider/auth/backend/protocol 错误到 failureKind 的映射。
@@ -24,9 +24,20 @@ finalize(executionContext) -> terminal status
 redact(value) -> redacted value
 ```

-Adapter 输入必须来自 manager 保存的 run/command 和 Kubernetes Secret projection；不得从 CLI 参数、临时环境变量或 Git 文件读取 provider credential 明文。
+Adapter 输入必须来自 manager 保存的 run/command 和 Kubernetes Secret projection；不得从 CLI 参数、临时环境变量或 Git 文件读取 provider credential 明文。`resolveProfile(profile)` 必须返回 profile、backendKind、protocol、transport、command、requiredSecretKeys 和 isolation policy；不得把 unknown profile 静默映射到默认 `codex`。

-`v0.1` 的第一真实 adapter 是 Codex adapter。它必须走 Codex CLI app-server JSON-RPC over stdio；adapter 合同把 Codex 的 thread、turn、notification、tool lifecycle 和 stderr/exit 信息归一化为 AgentRun 标准 events。
+`v0.1` 的第一真实 adapter 是 Codex stdio adapter。它必须走 Codex CLI app-server JSON-RPC over stdio；adapter 合同把 Codex 的 thread、turn、notification、tool lifecycle 和 stderr/exit 信息归一化为 AgentRun 标准 events。`codex` 与 `deepseek` 只是该 adapter 的 profile/config/SecretRef 选择，不允许复制两套协议实现。
+
+## Backend Profile Registry
+
+`GET /api/v1/backends` 和 adapter 内部 registry 至少报告以下 profile：
+
+| profile | backendKind | protocol | transport | command | v0.1 状态 |
+| --- | --- | --- | --- | --- | --- |
+| `codex` | `codex-app-server-stdio` | `codex-app-server-jsonrpc-stdio` | `stdio` | `codex app-server --listen stdio://` | 已有主闭环，必须保持默认兼容。 |
+| `deepseek` | `codex-app-server-stdio` | `codex-app-server-jsonrpc-stdio` | `stdio` | `codex app-server --listen stdio://` | 待实现 profile；实现后必须用独立 SecretRef 和 `CODEX_HOME` 真实联调。 |
+
+Registry 只表达能力和选择边界，不读取 Secret 值。Manager 负责校验 `backendProfile` 是否在 allowlist 内，并校验 `executionPolicy.secretScope.providerCredentials` 是否存在匹配 profile 的 SecretRef；runner 只为当前 run 选择的 profile 准备 Secret projection 和 runtime home。

 ## 标准事件

@@ -79,14 +90,19 @@ Adapter 必须把 backend 错误映射为稳定 failureKind：

 ### T3 真实 backend 联调

-阅读本文、[spec-v01-backend-codex.md](spec-v01-backend-codex.md) 和 [spec-v01-validation.md](spec-v01-validation.md)，然后用真实 Codex backend 完成一个最短 turn。确认 adapter 输出真实 assistant/backend_status/terminal_status events，且没有 Secret 泄露。
+阅读本文、[spec-v01-backend-codex.md](spec-v01-backend-codex.md) 和 [spec-v01-validation.md](spec-v01-validation.md)，然后分别用 `backendProfile=codex` 与 `backendProfile=deepseek` 完成真实最短 turn。确认 adapter 输出真实 assistant/backend_status/terminal_status events，事件中包含 profile/backendKind/protocol 摘要，且没有 Secret 泄露。
+
+### T4 Profile isolation 自测试
+
+阅读本文，然后用 fake Codex app-server 和两个不同的 profile Secret fixture 做自测试。确认 adapter 只选择 run 指定 profile 的 SecretRef 和 `CODEX_HOME`，`deepseek` 缺失时失败为 `secret-unavailable`，不会 fallback 到 `codex`。

 ## 规格的实现情况

 | 规格项 | 状态 | 说明 |
 | --- | --- | --- |
 | Backend adapter 合同 | 已定义 | 本文为 v0.1 adapter 权威。 |
-| 通用 adapter 模块 | 已实现最小形态 | `src/backend/adapter.ts` 作为 runner 进程内 adapter 入口，`v0.1` 只路由真实 `codex` profile；多 backend 路由仍 deferred。 |
+| 通用 adapter 模块 | 已实现最小形态/待扩展 profile | `src/backend/adapter.ts` 作为 runner 进程内 adapter 入口；当前已路由真实 `codex` profile，仍需扩展 `deepseek` profile 但不应复制第二套 stdio 协议实现。 |
 | event normalization | 已实现主路径 | Codex backend 已把 backend_status、assistant_message、tool_call、command_output、error 和 terminal_status 归一化为 manager events；复杂事件审计按人工验收抽查。 |
 | failure mapping | 已实现主路径 | Codex backend 已覆盖 missing secret、auth/rate/availability、protocol、JSON parse、invalid response、spawn、timeout 和 cancel 分类；真实负向场景按 [spec-v01-validation.md](spec-v01-validation.md) T7 手动验收。 |
-| 多 backend 路由 | Deferred | v0.1 只要求一个真实 backend 闭环。 |
+| `deepseek` profile | 已定义/待实现 | v0.1 要求作为同一 Codex stdio backend kind 的 profile 进入 registry、validation、runner secret selection 和综合联调。 |
+| 多 backend 路由 | Deferred | 跨 backend kind 的自动路由和 scheduler capacity selection 不进入 v0.1。 |