pikasTech-agentrun/docs/reference/spec-v01-validation.md

v0.1 两层验证规格

本文定义 AgentRun v0.1 的测试、联调和验收模型。v0.1 只保留两层验证：组件自测试和综合联调。自测试允许 mock，用于快速迭代；综合联调必须 100% 真实，用于判断能否交付或发布。

两层模型

层级	目的	是否允许 mock	运行位置	通过含义
自测试	单个组件内部快速反馈，覆盖纯函数、schema、状态机、错误分类和 redaction。	允许	本地或 Tekton Task	组件内部逻辑没有明显回归。
综合联调	验证 v0.1 runtime 的真实闭环。	禁止	G14 k8s agentrun-v01 + Tekton/Argo	当前版本可作为真实运行面候选。

除这两层外，不新增单独的“半真实”“准联调”“dry-run pass”或“模拟上线”验收层。mock 结果只能证明自测试通过，不能作为综合联调或发布通过证据。

自测试

自测试属于每个组件自己的 spec-v01-*.md 的“测试规格”子项。它可以使用 mock、fake backend、临时 Postgres、内存对象、fixture 和本地进程，但必须明确标记为自测试。

自测试应覆盖：

• agentrun-mgr：Run schema、tenant fields、idempotency、command 状态机、event seq、claim/lease 冲突、failureKind。
• agentrun-runner：claim/poll/report client、heartbeat、backend event normalization、interrupt/cancel、logPath、Secret redaction。
• backend adapter：输入输出转换、assistant/tool/error/terminal event、provider auth failure 分类、provider credential 不进 event/log。
• CLI：默认 JSON、空 stdout 失败、长操作短返回、错误结构化。
• Postgres adapter：migration、事务、run/command/event round-trip、重启后可查询。
• Secret 分发：SecretRef schema、missing secret failure、redaction。

自测试应使用 Bun + TypeScript 运行，Codex 相关自测试可以使用 fake app-server JSON-RPC client 模拟 initialize、thread/start、thread/resume、turn/start、assistant 输出、协议错误、timeout 和 transport close。

仓库内自测试入口必须保持可并行扩展：src/selftest/run.ts 只负责发现和调度 src/selftest/cases/*.ts，公共 fixture 和断言辅助放 src/selftest/harness.ts。新增组件自测试优先新增独立 case 文件，避免多个并行任务修改同一个总入口导致反复冲突。若某个 case 需要跨组件验证，可以依赖正式 manager/runner/backend API，但仍应作为独立 case 命名和维护。

自测试输出可以是 Tekton TaskRun result、JUnit、tap、JSON summary 或普通日志，但不得回写 source branch，也不得伪装成综合联调通过。

综合联调

综合联调必须在真实 agentrun-v01 运行面执行，且不得使用 mock 或 fake 替代核心链路。

综合联调必须使用：

• 真实 origin/v0.1 source commit。
• 真实 Tekton PipelineRun 构建和 promotion。
• 真实 v0.1-gitops artifact catalog 与 deploy/gitops/g14/runtime-v01/**。
• 真实 Argo CD Application agentrun-g14-v01 同步到 agentrun-v01。
• 真实 agentrun-v01-postgres StatefulSet、PVC、Service 和 migration ledger。
• 真实 Kubernetes SecretRef 注入 Postgres DSN 和 Code Agent provider credential；Codex 测试凭据必须来自 ~/.codex/auth.json 与 ~/.codex/config.toml 的 Kubernetes Secret projection。
• Codex Secret projection 必须先保持只读，再复制到 writable CODEX_HOME 后启动 app-server；综合联调不得把只读 Secret volume 直接当作 CODEX_HOME 的通过证据。
• 真实 agentrun-mgr、runner Job 或受控 runner process、真实 backend adapter。
• 至少一个真实 Code Agent provider turn；Codex backend 必须通过 codex app-server --listen stdio:// 的 JSON-RPC stdio turn 完成，mock、fixture、source-only、dry-run、fake provider、直接 Responses HTTP 或 codex exec 一次性输出不能作为通过证据。如果 provider credential SecretRef 缺失，综合联调必须标记 blocked，不能降级为 mock pass。

综合联调最小闭环：

1. Argo CD 已同步目标 GitOps revision，agentrun-v01 长驻 workload ready。
2. agentrun-mgr health/readiness 返回 Postgres ready、migration ready 和 SecretRef redacted 状态。
3. 使用 manager API 创建带 tenantId、projectId、workspaceRef、providerId、backendProfile、executionPolicy 和 traceSink 的 run。
4. 通过真实 runner claim 该 run。
5. runner 使用真实 SecretRef 调用真实 backend provider，完成一个最短 turn。
6. manager 可查询 command state、append-only events、terminal_status 和 redacted logPath/job identity。
7. 重启 agentrun-mgr 后，run、command、events 和 terminal_status 仍可从 Postgres 查询。
8. 日志、event、CLI 输出和 health 中没有 provider credential、DSN password、token 或 URL credential 明文。

CLI 交互联调标准

CLI 交互联调验证正式操作入口是否能支撑人工使用和自动脚本串联。它必须只调用正式 AgentRun CLI 命令，不使用 debug 子命令、临时 kubectl exec、数据库直连或 mock backend 作为通过证据。故障定位可以另行采样日志，但通过条件必须来自 CLI 输出、manager API 和 Postgres durable facts。

CLI 交互联调必须满足：

• 使用 bun scripts/agentrun-cli.ts 完成 create run、create command、start runner、show command 和 events polling。
• 每个 CLI 调用默认输出 JSON，stdout 不为空，且 60 秒内返回；长时间模型 turn 必须通过后续 status/events 命令观察。
• 创建类命令必须返回 runId、commandId、status、job/process identity、logPath 和下一步 poll command；查询类命令必须返回当前 state、terminal_status、failureKind 和 event cursor。
• CLI 输出、日志摘要和错误信息必须保留可观测性，不能只返回成功/失败布尔值；错误必须能区分 missing SecretRef、provider auth failure、runner lease conflict、backend failure 和 infra failure。
• CLI 不得输出 provider credential、Postgres DSN password、token、URL credential 或 Secret value；只能输出 redacted value 或 SecretRef。
• 重启或滚动 agentrun-mgr 后，CLI 仍能查询同一 run、command、events 和 terminal_status，证明结果来自 Postgres 而不是进程内存。

RESTful API 交互联调标准

RESTful API 交互联调验证 agentrun-mgr 对外 HTTP JSON 合同，而不是 CLI wrapper。它必须直接访问真实 agentrun-v01 runtime 中的 manager API，且使用同一个真实 runner、backend adapter 和 provider credential 完成一个 run 生命周期。

RESTful API 交互联调必须满足：

• health/readiness 返回 manager、Postgres migration 和 SecretRef redacted 状态；缺少关键 SecretRef 时必须结构化返回 blocked 或 failed，不能降级为 mock pass。
• POST /api/v1/runs 接受并持久化 tenantId、projectId、workspaceRef、providerId、backendProfile、executionPolicy 和 traceSink。
• POST /api/v1/runs/:runId/commands 创建 turn command 后立即返回 command id 和初始 state，不等待完整模型 turn。
• 真实 runner 通过 manager 私有 API claim run、poll commands、append events、ack command 并上报 status；API 联调不得绕过 manager 直接写数据库。
• GET /api/v1/runs/:runId/commands/:commandId 和 GET /api/v1/runs/:runId/events?afterSeq=N&limit=M 能轮询到 terminal_status，event seq 单调递增，分页重复读取不丢失也不重复。
• 所有成功和失败响应都必须是 JSON；失败响应必须包含可判定的 failureKind、message 和 trace correlation，且不得泄露 Secret value。

真实 provider 返回 HTTP 5xx/503、Service Unavailable、携带 5xx 的 responseStreamDisconnected 或明确 temporary/provider unavailable 文案时，综合联调结论应归类为外部 provider availability blocker，failureKind 使用 provider-unavailable。这类结果不能证明真实 turn 成功，但也不得被记录为本地 runner/backend 执行面 backend-failed blocker。

CLI 与 RESTful API 可以复用同一个真实 run 做联调。若两者观察到的 run id、command id、state、terminal_status、failureKind、event seq 或 redaction 结果不一致，综合联调不通过。

发布判定

v0.1 发布通过必须同时满足：

• 相关组件自测试通过。
• Tekton/Argo CI/CD 链路通过，source branch 不含自动构造物。
• 综合联调通过。

以下结果不能单独作为发布通过证据：

• mock backend run 成功。
• 本地临时 Postgres 或 sqlite 测试成功。
• GitOps branch 已推送但 Argo 未同步。
• Argo Synced 但没有真实 run terminal_status。
• provider credential 缺失时的跳过结果。
• 只读 health 成功但没有完成真实 Code Agent turn。

测试规格

T1 自测试归类

阅读本文，然后检查每个组件 spec 的“测试规格”是否明确属于自测试，且 mock/fake/fixture 只出现在自测试层。

T2 综合联调真实性

阅读本文，然后执行一次综合联调，确认所有关键依赖均为真实 agentrun-v01 runtime、Postgres、SecretRef、runner、backend 和 provider credential；Codex 测试凭据必须通过 Kubernetes Secret projection 注入 ~/.codex/auth.json 与 ~/.codex/config.toml。任何缺失必须返回 blocked 或 failed。

T3 发布判定

阅读本文和 spec-v01-cicd.md，确认发布结论同时引用自测试、Tekton/Argo 和综合联调证据；不得用 mock pass 替代综合联调。

T4 CLI 交互联调

阅读 AGENTS.md、本文和 cli.md，然后用 AgentRun CLI 手动测试以下内容：在真实 agentrun-v01 运行面创建 run，提交一个 turn command，启动或触发真实 runner，并轮询 command status 与 run events 直到出现 terminal_status。确认每个步骤只使用正式 CLI 命令，不使用 debug 子命令或 mock/fake backend；每次调用 60 秒内返回非空 JSON，包含 runId、commandId、status、job/process identity、logPath 或下一步 poll command；日志、event 和 CLI 输出不得出现 provider credential、DSN password、token 或 URL credential 明文。最后重启或滚动 agentrun-mgr，再用 CLI 查询同一个 run，确认 command state、events 和 terminal_status 仍可见。

T5 RESTful API 交互联调

阅读 AGENTS.md、本文和 spec-v01-services.md，然后用 RESTful API 手动测试以下内容：直接调用真实 agentrun-mgr HTTP JSON API，先检查 health/readiness，再调用 POST /api/v1/runs 创建带 tenant/project/workspace/provider/backend/execution/trace 字段的 run，调用 POST /api/v1/runs/:runId/commands 提交 turn command，使用真实 runner 完成 provider turn，并轮询 GET /api/v1/runs/:runId/commands/:commandId 与 GET /api/v1/runs/:runId/events?afterSeq=N&limit=M 直到 terminal_status。确认所有响应为 JSON，event seq 单调且分页无重复，缺少 provider SecretRef 时返回 blocked 或 failed 的结构化 failureKind，任何响应、event、trace 和日志都不得泄露 Secret value。

T6 CLI 与 RESTful 观察一致性

阅读本文、cli.md 和 spec-v01-services.md，然后对同一个真实 run 分别用 CLI 和 RESTful API 查询 run、command、events 和 terminal_status。确认 CLI 只是正式 API 的受控操作入口，不维护一套独立状态；两种交互面看到的 run id、command id、state、terminal_status、failureKind、event seq 和 redaction 结果必须一致。

规格的实现情况

规格项	状态	说明
两层验证模型	已定义	本文为 v0.1 验证权威。
自测试 task	未实现	需要后续随组件实现补齐。
综合联调 task/runbook	未实现	需要 runtime、Postgres、SecretRef 和真实 backend 就绪后补齐。
CLI 交互联调标准	已定义	必须只使用正式 CLI，验证真实 run 生命周期和可观测输出。
RESTful API 交互联调标准	已定义	必须直连真实 manager HTTP JSON API，验证服务合同和 durable facts。
mock 作为发布证据	不采用	mock 只能证明自测试通过。