feat: 支持 v0.1 deepseek backend profile

2026-05-29 18:44:24 +08:00
parent 5375ce37f7
commit 5cc8146800
28 changed files with 303 additions and 50 deletions
@@ -110,6 +110,6 @@ POST  /api/v1/commands/:commandId/ack
 | `agentrun-mgr` 服务规格 | 已定义 | 本文为 v0.1 manager 权威。 |
 | Manager REST API | 已实现/已通过主闭环 | 已有 run、command、event、backends、runner register、claim、lease heartbeat、poll、ack、status、runner Job 创建和 health/readiness 的 HTTP JSON API；真实 runtime 已通过 RESTful API 主闭环。 |
 | Tenant policy boundary | 已实现最小边界 | v0.1 已做 schema、tenant/backend allowlist、executionPolicy 和 secretScope 结构校验；业务授权仍由 UniDesk/HWLAB 自己判定。 |
-| `deepseek` backendProfile allowlist | 已定义/待实现 | 需要扩展 manager validation、backend capability 和 matching SecretRef 校验。 |
+| `deepseek` backendProfile allowlist | 已实现/待真实联调 | Manager validation、backend capability 和 matching SecretRef 校验已支持 `deepseek`；真实 runtime 需经 CI/CD 发布后确认 Postgres migration `002_v01_backend_profiles` 应用。 |
 | Postgres durable adapter | 已实现/已通过主闭环 | live runtime 通过 `DATABASE_URL` 使用 Postgres durable store；memory store 仅用于显式 self-test/dev。见 [spec-v01-postgres.md](spec-v01-postgres.md)。 |
 | Observability 最小合同 | 已实现主路径 | events append-only、terminal status、failureKind、health/readiness store 状态、runner claim/lease/backend events 和 Secret/DSN redaction 已进入 manager；集中 trace 和部署级观测仍属后续工作。 |
@@ -112,4 +112,4 @@ Runner 日志必须实时 flush 到文件或 pod log，CLI 启动 runner 时必
 | host process runner | 已实现 | `runner start` 和 `src/runner/main.ts` 进入同一套 `runOnce`，可通过 manager register/claim/poll/report 执行自测试。 |
 | claim/lease/report client | 已实现 | 已拆出 runner manager API client，覆盖 register、claim、lease heartbeat、poll command、ack、append event 和 terminal status；live runtime 通过 manager 写入 Postgres durable store。 |
 | runner redaction | 已实现主路径 | runner/backend event 和 Job 输出使用 redaction；复杂审计仍按 [spec-v01-validation.md](spec-v01-validation.md) 的人工验收抽查。 |
-| `deepseek` profile runner selection | 已定义/待实现 | 需要按 run `backendProfile` 选择 matching SecretRef、projection、`CODEX_HOME` 和 backend metadata。 |
+| `deepseek` profile runner selection | 已实现/待真实联调 | Runner Job 和 host runner 已按 run `backendProfile` 选择 matching SecretRef、projection、`CODEX_HOME` 和 backend metadata；真实 Kubernetes Job 联调需发布后执行。 |
@@ -35,7 +35,7 @@ Adapter 输入必须来自 manager 保存的 run/command 和 Kubernetes Secret p
 | 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` 真实联调。 |
+| `deepseek` | `codex-app-server-stdio` | `codex-app-server-jsonrpc-stdio` | `stdio` | `codex app-server --listen stdio://` | 已实现 profile；必须用独立 SecretRef 和 profile-scoped `CODEX_HOME` 完成真实联调。 |

 Registry 只表达能力和选择边界，不读取 Secret 值。Manager 负责校验 `backendProfile` 是否在 allowlist 内，并校验 `executionPolicy.secretScope.providerCredentials` 是否存在匹配 profile 的 SecretRef；runner 只为当前 run 选择的 profile 准备 Secret projection 和 runtime home。

@@ -101,8 +101,8 @@ Adapter 必须把 backend 错误映射为稳定 failureKind：
 | 规格项 | 状态 | 说明 |
 | --- | --- | --- |
 | Backend adapter 合同 | 已定义 | 本文为 v0.1 adapter 权威。 |
-| 通用 adapter 模块 | 已实现最小形态/待扩展 profile | `src/backend/adapter.ts` 作为 runner 进程内 adapter 入口；当前已路由真实 `codex` profile，仍需扩展 `deepseek` profile 但不应复制第二套 stdio 协议实现。 |
+| 通用 adapter 模块 | 已实现 profile 形态 | `src/backend/adapter.ts` 作为 runner 进程内 adapter 入口；`codex` 与 `deepseek` 均路由到同一 Codex stdio backend kind，不复制第二套协议实现。 |
 | 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 手动验收。 |
-| `deepseek` profile | 已定义/待实现 | v0.1 要求作为同一 Codex stdio backend kind 的 profile 进入 registry、validation、runner secret selection 和综合联调。 |
+| `deepseek` profile | 已实现/待真实联调 | 已进入 registry、validation、runner Secret selection、backend_status metadata、CLI secret render 和 fake stdio 自测试；真实综合联调按 [spec-v01-validation.md](spec-v01-validation.md) T8 执行。 |
 | 多 backend 路由 | Deferred | 跨 backend kind 的自动路由和 scheduler capacity selection 不进入 v0.1。 |
@@ -48,7 +48,7 @@ Profile 切换规则：

 - `backendProfile` 是 run 的显式字段，manager 不得静默改写。
 - runner/backend 只读取与 `backendProfile` 同名的 provider credential；缺失则 `secret-unavailable`。
- 每次 run 必须使用 profile-scoped writable `CODEX_HOME`。Kubernetes Job 可以把选中 profile 的 Secret projection 复制到该 Job 独占的 `/home/agentrun/.codex`；host process 或复用进程必须使用 run/profile 独占目录，避免 `codex` 与 `deepseek` 互相污染。
+- 每次 run 必须使用 profile-scoped writable `CODEX_HOME`。Kubernetes Job 默认把选中 profile 的 Secret projection 复制到该 Job 独占的 `/home/agentrun/.codex-<profile>`；host process 或复用进程必须使用 run/profile 独占目录，避免 `codex` 与 `deepseek` 互相污染。
 - `deepseek` 不得 fallback 到 `codex` Secret、模型或 upstream；`codex` 也不得读取 `deepseek` Secret。
 - command payload 中显式提供 model 时可以透传给 Codex turn；未显式提供时以 profile `config.toml` 为 authority，不在 adapter 中写死默认模型。

@@ -130,5 +130,5 @@ Run 的 `executionPolicy.secretScope` 应引用与 `backendProfile` 匹配的 pr
 | Codex adapter | 已实现/已通过主闭环 | 当前代码已实现受控 `codex app-server --listen stdio://`、`initialize`/`thread/start`/`thread/resume`/`turn/start` response 校验、stderr 有界诊断、spawn/JSON parse/response invalid/timeout/provider 5xx availability failureKind，以及包含 retry error notification 的 fake app-server 自测试。 |
 | 错误可观测与脱敏 | 已实现主路径 | child env、cwd、workspace 和 Codex home 只输出摘要；stderr tail 有界且标记截断；事件和 failure 统一走 redaction。 |
 | 真实 provider turn | 已通过主闭环 | 真实 Codex provider turn 已经通过 RESTful API 和 CLI 综合联调；每次发布仍按 [spec-v01-validation.md](spec-v01-validation.md) 手动复验。 |
-| `deepseek` profile | 已定义/待实现 | 需要作为同一 Codex stdio backend kind 的 profile 实现，使用 `agentrun-v01-provider-deepseek` 和独立 `CODEX_HOME` 完成真实联调。 |
+| `deepseek` profile | 已实现/待真实联调 | 代码已支持 `agentrun-v01-provider-deepseek`、独立 `CODEX_HOME`、同一 `codex app-server --listen stdio://` 协议和 profile metadata；真实联调需在发布后用 Kubernetes SecretRef 执行。 |
 | hostPath `~/.codex` | 不采用 | 只能通过 Kubernetes Secret projection 注入。 |
@@ -93,4 +93,4 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
 | CLI 调 manager REST | 已实现 | CLI 通过 `ManagerClient` 调 manager REST；自测试可用内存 manager，综合联调必须指向真实 `agentrun-v01` manager。 |
 | runner start/job | 已实现 | `runner start` 可执行 host process runner；`runner job --dry-run` 可渲染 Kubernetes Job JSON；`runner job` 正式路径通过 manager REST 创建 Kubernetes Job 并快速返回 job identity、SecretRef、retention 和轮询命令。 |
 | CLI 测试规格 | 已定义/已验证主闭环 | 综合联调见 [spec-v01-validation.md](spec-v01-validation.md)；每次发布仍按手动交互验收复跑。 |
-| `deepseek` profile CLI | 已定义/待实现 | 需要扩展 secret render、backends list、run create examples 和 runner start/job 的 profile 可见性。 |
+| `deepseek` profile CLI | 已实现/待真实联调 | `secrets codex render --profile deepseek`、`backends list`、`runner start --backend` 和 JSON 错误可见性已实现并通过 CLI smoke；真实 CLI 联调需发布后执行。 |
@@ -74,7 +74,7 @@ Secret 名称和 key 可以在实现时按 Kubernetes 命名限制微调，但
 | --- | --- | --- |
 | Postgres durable store 规格 | 已定义 | 本文为 v0.1 存储权威。 |
 | StatefulSet/Service/PVC | 已实现/已通过主闭环 | `agentrun-v01-postgres` StatefulSet、Service 和 PVC 已由 GitOps runtime 提供，作为 `agentrun-v01` durable store。 |
-| migration ledger | 已实现/已通过主闭环 | `agentrun-mgr` 启动 Postgres adapter 时幂等创建 `agentrun_schema_migrations` 并记录 migration id/checksum；readiness 必须显示 migration ready。 |
+| migration ledger | 已实现/已通过主闭环 | `agentrun-mgr` 启动 Postgres adapter 时幂等创建 `agentrun_schema_migrations` 并记录 migration id/checksum；当前最新 migration 为 `002_v01_backend_profiles`，用于 upsert `codex`/`deepseek` backend capability；readiness 必须显示 migration ready。 |
 | manager Postgres adapter | 已实现/已通过主闭环 | `agentrun-mgr` 通过 `DATABASE_URL` 启用 Postgres adapter，持久化 runs、commands、events、runners、backends 和 leases；缺少 `DATABASE_URL` 时 live runtime fail fast，memory 只允许显式 self-test/dev。 |
 | health/readiness store 状态 | 已实现 | health/readiness 返回 adapter、reachable、migrationReady、migrationId、failureKind 和 redacted Secret 状态，不输出 DSN 明文。 |
 | file/sqlite durable store | 不采用 | 只可用于临时本地测试，不作为 v0.1 runtime truth。 |
@@ -54,9 +54,9 @@
 | Secret key | `auth.json`，来自 `~/.codex/auth.json` |
 | Secret key | `config.toml`，来自 `~/.codex/config.toml` |
 | Projection path | 只读 Secret projection 挂到 `/var/run/agentrun/secrets/<profile>-<index>/auth.json` 和 `config.toml`；该路径只作为 credential source。 |
-| Runtime config path | runner 启动时把当前 `backendProfile` 授权的 Secret projection 复制到 writable `CODEX_HOME`，Kubernetes Job 默认可以使用该 Job 独占的 `/home/agentrun/.codex/auth.json` 和 `config.toml`；复用进程必须使用 run/profile 独占目录。 |
+| Runtime config path | runner 启动时把当前 `backendProfile` 授权的 Secret projection 复制到 writable `CODEX_HOME`，Kubernetes Job 默认使用该 Job 独占的 `/home/agentrun/.codex-<profile>/auth.json` 和 `config.toml`；复用进程必须使用 run/profile 独占目录。 |
 | Projection mode | 只读，建议 `0400` 或等价最小权限 |
-| Runtime env | `HOME=/home/agentrun`，`CODEX_HOME=/home/agentrun/.codex`，`AGENTRUN_CODEX_SECRET_HOME=<projection path>`；不得 fallback 到节点宿主机 home。 |
+| Runtime env | `HOME=/home/agentrun`，`CODEX_HOME=/home/agentrun/.codex-<profile>`，`AGENTRUN_CODEX_SECRET_HOME=<projection path>`；不得 fallback 到节点宿主机 home。 |

 Secret 创建和轮换必须通过 Kubernetes 密钥管理完成。`deploy/deploy.json` 只写 SecretRef 名称、key 和 mount intent；`v0.1-gitops` rendered manifests 只引用 Secret，不包含 Secret data。

@@ -169,6 +169,6 @@ Secret 创建和轮换不由 source branch 自动生成；source branch 只声
 | Kubernetes SecretRef 注入 | 已实现/已通过主闭环 | runner Job dry-run 和正式 Job 创建路径已按 run `executionPolicy.secretScope.providerCredentials` 生成 Secret volume projection、writable runtime home 和 `AGENTRUN_CODEX_SECRET_HOME`；真实 Secret 与 Codex turn 已通过主闭环。 |
 | Codex Secret dry-run 工具 | 已实现 | `./scripts/agentrun secrets codex render --dry-run` 只输出 Secret 创建计划、hash 和 redacted manifest 摘要，不执行 apply。 |
 | Codex auth/config file projection | 已实现主路径 | backend readiness 检查 `auth.json`/`config.toml` 可读性，缺失时返回 `secret-unavailable`；真实 runner Job 将只读 projection 复制到 writable `CODEX_HOME`。 |
-| DeepSeek profile SecretRef | 已定义/待实现 | 需要新增 `agentrun-v01-provider-deepseek` render、Job projection、profile 选择和负向 missing-secret 验收。 |
+| DeepSeek profile SecretRef | 已实现/待真实联调 | 已新增 `agentrun-v01-provider-deepseek` render、GitOps/RBAC 引用、Job projection、profile 选择和负向 missing-secret 自测试；真实 Secret 创建和轮换由 Kubernetes 密钥管理流程完成。 |
 | redaction 最小规则 | 已实现主路径 | Secret dry-run 工具、event、Job dry-run 输出、self-test 和真实主闭环均不打印 Secret value；复杂审计按 [spec-v01-validation.md](spec-v01-validation.md) 人工抽查。 |
 | 外部 secret manager | 未采用 | 如需 Vault/ExternalSecrets/SOPS，后续单独更新规格。 |
@@ -183,5 +183,5 @@ Manager 负责校验、保存和返回这些字段；runner 只能消费已保
 | `agentrun-mgr` 实现 | 已实现/已通过主闭环 | 已有 REST API、Postgres durable store、migration ledger、runner claim/lease/report、health/readiness 和 self-test memory 模式；真实 `agentrun-v01` runtime 已通过 Postgres/GitOps/readiness 和 run lifecycle 主闭环。 |
 | `agentrun-runner` 实现 | 已实现/已通过主闭环 | host process runner 与 Kubernetes Job 共用 `runOnce`，runner 通过 manager API claim/poll/report，不直连 Postgres；真实 Kubernetes Job 已完成 Codex turn。 |
 | `codex` profile | 已实现/已通过主闭环 | Codex app-server stdio backend 已有协议、失败分类、脱敏和 fake self-test；真实 Codex provider turn 已通过 RESTful API 与 CLI 主闭环。 |
-| `deepseek` profile | 已定义/待实现 | 规格要求 DeepSeek 作为同一 Codex stdio backend kind 的 profile/config/SecretRef 选择进入 v0.1；实现和真实联调尚未完成。 |
+| `deepseek` profile | 已实现/待真实联调 | 代码已支持 DeepSeek 作为同一 Codex stdio backend kind 的 profile/config/SecretRef 选择；自测试覆盖 registry、runner Secret 选择、fake stdio turn 和无 fallback，真实 `agentrun-v01` 联调需在 CI/CD 发布后执行。 |
 | 自动 scheduler | Deferred | 不作为 `v0.1` 第一阶段验收目标。 |
@@ -166,5 +166,5 @@ T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend
 | CLI 交互联调标准 | 已定义 | 必须只使用正式 CLI，验证真实 run 生命周期和可观测输出。 |
 | RESTful API 交互联调标准 | 已定义 | 必须直连真实 manager HTTP JSON API，验证服务合同和 durable facts。 |
 | 真实主闭环 | 已通过 | 当前 v0.1 已通过真实 Tekton/Argo、Postgres、SecretRef、Kubernetes runner Job、Codex stdio turn、RESTful API 和 CLI 主闭环；每次发布仍需按本文手动复验。 |
-| `deepseek` profile 切换验收 | 已定义/待执行 | 实现 deepseek profile 后必须按 T8 做 100% 真实综合联调。 |
+| `deepseek` profile 切换验收 | 已定义/待真实执行 | 自测试和 CLI smoke 已覆盖 profile registry、Secret render、fake stdio turn、无 fallback 和结构化错误；PR 合并、CI/CD 发布后仍必须按 T8 做 100% 真实综合联调。 |
 | mock 作为发布证据 | 不采用 | mock 只能证明自测试通过。 |