v0.1 Backend Adapter 规格

Backend adapter 是 runner 与具体 Code Agent 工具之间的适配层。它隐藏 Codex、OpenCode、Claude Code、host-native 或 Windows-native 的内部协议，把输入、事件、错误和 terminal status 归一化为 AgentRun 公共模型。

在系统中的职责划分

根据 backendProfile 选择具体 backend 实现；v0.1 必须至少证明一个真实 Agent backend，默认是 codex。
接收 manager 持久化后的 run、command 和 executionPolicy；不得自行扩大 workspace、network、approval 或 secret scope。
调用具体 backend，并把 backend 输出归一化为 AgentRun events。
负责 provider/auth/backend/protocol 错误到 failureKind 的映射。
负责 backend 输出和错误中的 credential redaction。
暴露 backend capability 给 manager，用于 GET /api/v1/backends。

Adapter 合同

第一版可以把 adapter 实现为 runner 进程内 Bun/TypeScript 模块，不要求独立 Deployment。无论实现形态如何，对 runner 的逻辑合同必须稳定：

resolveProfile(profile) -> capability
prepare(run, command, secretProjection) -> executionContext
startTurn(executionContext) -> normalized event stream
interrupt(executionContext, command) -> backend interrupt attempt
finalize(executionContext) -> terminal status
redact(value) -> redacted value

Adapter 输入必须来自 manager 保存的 run/command 和 Kubernetes Secret projection；不得从 CLI 参数、临时环境变量或 Git 文件读取 provider credential 明文。

v0.1 的第一真实 adapter 是 Codex adapter。它必须走 Codex CLI app-server JSON-RPC over stdio；adapter 合同把 Codex 的 thread、turn、notification、tool lifecycle 和 stderr/exit 信息归一化为 AgentRun 标准 events。

标准事件

Adapter 输出给 runner 的 event 类型至少包括：

backend_status：backend 启动、模型/profile、能力和阶段状态，不包含 Secret 值。
assistant_message：模型回复的用户可见文本。
tool_call：工具调用摘要和 redacted 参数。
command_output：stdout/stderr 或命令输出摘要。
diff：代码变更摘要或 patch 片段；必须受长度限制。
error：结构化错误和 failureKind。
terminal_status：completed、failed、cancelled、blocked 等终态。

事件必须有上限和分页友好形态。大型日志、完整 stdout 或完整 trace 应进入 logPath 或后续 artifact，不得一次性塞入单个 event 造成输出爆炸。

Failure Mapping

Adapter 必须把 backend 错误映射为稳定 failureKind：

failureKind	典型来源
`secret-unavailable`	Secret projection 缺失、文件不存在、权限不可读。
`provider-auth-failed`	provider credential 或 auth file 无效、上游返回 401/403。
`provider-rate-limited`	上游限流或 quota 错误。
`provider-unavailable`	上游 provider availability/transient 失败，包括 HTTP 5xx/503、`Service Unavailable`、`responseStreamDisconnected` 携带 5xx 状态码、明确 `provider unavailable` 或 `temporary unavailable` 文案。
`backend-protocol-error`	backend 输出无法解析、协议字段缺失。
`backend-json-parse-error`	backend stdout 不是合法 JSON-RPC 行。
`backend-response-invalid`	backend JSON-RPC response/terminal notification 缺少必需字段。
`backend-spawn-failed`	backend app-server 进程无法启动。
`backend-failed`	backend 进程非零退出或 terminal error。
`backend-timeout`	executionPolicy timeout 触发。
`cancelled`	interrupt/cancel 生效。

Credential Boundary

Adapter 只能看到运行时投影出来的最小 Secret 文件或 env；不得枚举整个 namespace Secret。
Adapter 不得把 Secret 值写入 event、trace、日志、CLI 输出、health 或 Postgres。
Codex backend 的 auth.json 和 config.toml 整体按敏感文件处理，即使其中包含非敏感配置，也不得输出原文。
Provider base URL、model 名称和 profile 名称可以输出，但 URL credential、Authorization header、token、api_key、password 必须 redacted。

测试规格

T1 Adapter 自测试

阅读本文，然后用 mock backend 做组件自测试，确认 adapter 能把 assistant/output/error/terminal 输出归一化为标准 events，并能对 token、Authorization header、URL credential 和 Secret 文件内容做 redaction。该测试属于自测试，不作为综合联调通过证据。

T2 Failure mapping 自测试

阅读本文，然后用 mock 错误覆盖 missing secret、provider auth failure、rate limit、provider availability/transient failure、protocol error、timeout 和 cancel。provider availability/transient 样例必须至少包含 HTTP 503 Service Unavailable 或携带 5xx 的 responseStreamDisconnected，并确认不会被归类为 backend-failed。确认每类错误都映射到稳定 failureKind，且输出为 JSON 或结构化 event。

T3 真实 backend 联调

阅读本文、spec-v01-backend-codex.md 和 spec-v01-validation.md，然后用真实 Codex backend 完成一个最短 turn。确认 adapter 输出真实 assistant/backend_status/terminal_status events，且没有 Secret 泄露。

规格的实现情况

规格项	状态	说明
Backend adapter 合同	已定义	本文为 v0.1 adapter 权威。
通用 adapter 模块	未实现	需要后续代码实现。
event normalization	已定义/未实现	需后续实现和测试。
failure mapping	已定义/未实现	需后续实现和测试。
多 backend 路由	Deferred	v0.1 只要求一个真实 backend 闭环。

5.7 KiB Raw Blame History Unescape Escape