diff --git a/AGENTS.md b/AGENTS.md index 3aa9ab8..176d83c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,5 +46,6 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓 - `docs/reference/spec-v01-cicd.md`：v0.1 分支、workspace、namespace、GitOps、registry、CI/CD 和发布验收规格。 - `docs/reference/spec-v01-postgres.md`：v0.1 Postgres durable store、schema migration 和 SecretRef 规格。 - `docs/reference/spec-v01-secret-distribution.md`：v0.1 Code Agent API Key 和运行时 Secret 分发规格。 +- `docs/reference/spec-v01-validation.md`：v0.1 两层验证模型，自测试允许 mock，综合联调必须 100% 真实。 - `docs/reference/architecture.md`：AgentRun 产品边界、服务架构、MVP 阶段、RESTful API 模型和数据模型。 - `docs/reference/cli.md`：按 `cli-spec` 固化的 CLI 与服务 API 约束。 diff --git a/docs/reference/spec-v01-documentation-governance.md b/docs/reference/spec-v01-documentation-governance.md index 30dee00..0ecde4a 100644 --- a/docs/reference/spec-v01-documentation-governance.md +++ b/docs/reference/spec-v01-documentation-governance.md @@ -29,6 +29,7 @@ - `spec-v01-cicd.md`：版本 lane、GitOps、namespace、registry 和发布验收。 - `spec-v01-postgres.md`：Postgres durable store、schema migration 和 DB SecretRef。 - `spec-v01-secret-distribution.md`：Code Agent API Key、Postgres DSN 和运行时 Secret 分发。 +- `spec-v01-validation.md`：两层验证模型、自测试和综合联调验收。 - 未来新增单服务规格必须使用 `spec-v01-.md`，例如 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`。 - `v0.2` 或更高版本的规格不得写入 `spec-v01-*`；只能在对应版本 lane 中创建自己的 `spec-v02-*`、`spec-v03-*`。 - 每个可实现规格应包含“测试规格”小节；测试编号写在对应 spec 内，不创建或恢复根目录 `TEST.md`。 @@ -52,11 +53,12 @@ - 服务总览规格：[spec-v01-services.md](spec-v01-services.md)。 - Postgres durable store 规格：[spec-v01-postgres.md](spec-v01-postgres.md)。 - Secret/API Key 分发规格：[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。 +- 验证模型规格：[spec-v01-validation.md](spec-v01-validation.md)。 ## 验收标准 - `AGENTS.md` 索引本文和其他 `spec-v01-*` 规格。 -- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md`、`spec-v01-cicd.md`、`spec-v01-postgres.md` 和 `spec-v01-secret-distribution.md`。 +- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md`、`spec-v01-cicd.md`、`spec-v01-postgres.md`、`spec-v01-secret-distribution.md` 和 `spec-v01-validation.md`。 - `AGENTS.md` 和 `docs/reference/` 不得把旧 `agentrun_dev`、`agentrun_prod`、`G14:/root/agentrun` 或 `/root/agentrun` 写成当前工作区、namespace、发布目标或验收目标；只允许在废弃说明和历史背景中提及。 - `docs/` 根目录不新增临时 Markdown 报告或 JSON dump。 - 仓库根目录不存在 `TEST.md`；测试场景维护在对应 `spec-v01-*.md` 的“测试规格”小节。 diff --git a/docs/reference/spec-v01-services.md b/docs/reference/spec-v01-services.md index 7e71448..02283b5 100644 --- a/docs/reference/spec-v01-services.md +++ b/docs/reference/spec-v01-services.md @@ -139,6 +139,7 @@ Manager 负责校验、保存和返回这些字段；runner 只能消费已保 | CI/CD lane 规格 | 已定义 | 见 [spec-v01-cicd.md](spec-v01-cicd.md)。 | | Postgres durable store 规格 | 已定义 | 见 [spec-v01-postgres.md](spec-v01-postgres.md)。 | | Secret 分发规格 | 已定义 | 见 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。 | +| 两层验证规格 | 已定义 | 见 [spec-v01-validation.md](spec-v01-validation.md)。 | | `agentrun-mgr` 实现 | 未实现 | 需后续单服务 spec 和代码实现。 | | `agentrun-runner` 实现 | 未实现 | 需后续单服务 spec 和代码实现。 | | 第一真实 backend | 未实现 | 默认候选 Codex，需后续 backend spec。 | diff --git a/docs/reference/spec-v01-validation.md b/docs/reference/spec-v01-validation.md new file mode 100644 index 0000000..5169383 --- /dev/null +++ b/docs/reference/spec-v01-validation.md @@ -0,0 +1,93 @@ +# 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 分类、API Key 不进 event/log。 +- CLI：默认 JSON、空 stdout 失败、长操作短返回、错误结构化。 +- Postgres adapter：migration、事务、run/command/event round-trip、重启后可查询。 +- Secret 分发：SecretRef schema、missing secret failure、redaction。 + +自测试输出可以是 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 API Key。 +- 真实 `agentrun-mgr`、runner Job 或受控 runner process、真实 backend adapter。 +- 至少一个真实 Code Agent provider turn；如果 API Key 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 中没有 API Key、DSN password、token 或 URL credential 明文。 + +## 发布判定 + +`v0.1` 发布通过必须同时满足： + +- 相关组件自测试通过。 +- Tekton/Argo CI/CD 链路通过，source branch 不含自动构造物。 +- 综合联调通过。 + +以下结果不能单独作为发布通过证据： + +- mock backend run 成功。 +- 本地临时 Postgres 或 sqlite 测试成功。 +- GitOps branch 已推送但 Argo 未同步。 +- Argo Synced 但没有真实 run terminal_status。 +- provider API Key 缺失时的跳过结果。 +- 只读 health 成功但没有完成真实 Code Agent turn。 + +## 测试规格 + +### T1 自测试归类 + +阅读本文，然后检查每个组件 spec 的“测试规格”是否明确属于自测试，且 mock/fake/fixture 只出现在自测试层。 + +### T2 综合联调真实性 + +阅读本文，然后执行一次综合联调，确认所有关键依赖均为真实 `agentrun-v01` runtime、Postgres、SecretRef、runner、backend 和 provider API Key；任何缺失必须返回 blocked 或 failed。 + +### T3 发布判定 + +阅读本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，确认发布结论同时引用自测试、Tekton/Argo 和综合联调证据；不得用 mock pass 替代综合联调。 + +## 规格的实现情况 + +| 规格项 | 状态 | 说明 | +| --- | --- | --- | +| 两层验证模型 | 已定义 | 本文为 v0.1 验证权威。 | +| 自测试 task | 未实现 | 需要后续随组件实现补齐。 | +| 综合联调 task/runbook | 未实现 | 需要 runtime、Postgres、SecretRef 和真实 backend 就绪后补齐。 | +| mock 作为发布证据 | 不采用 | mock 只能证明自测试通过。 |