docs: define v0.1 integration standards
This commit is contained in:
Codex
@@ -52,6 +52,34 @@
|
||||
7. 重启 `agentrun-mgr` 后，run、command、events 和 terminal_status 仍可从 Postgres 查询。
|
||||
8. 日志、event、CLI 输出和 health 中没有 API Key、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` 或后续固定 CLI 入口完成 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 不得输出 API Key、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 API Key 完成一个 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。
|
||||
|
||||
CLI 与 RESTful API 可以复用同一个真实 run 做联调。若两者观察到的 run id、command id、state、terminal_status、failureKind、event seq 或 redaction 结果不一致，综合联调不通过。
|
||||
|
||||
## 发布判定
|
||||
|
||||
`v0.1` 发布通过必须同时满足：
|
||||
@@ -83,6 +111,18 @@
|
||||
|
||||
阅读本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，确认发布结论同时引用自测试、Tekton/Argo 和综合联调证据；不得用 mock pass 替代综合联调。
|
||||
|
||||
### T4 CLI 交互联调
|
||||
|
||||
阅读 `AGENTS.md`、本文和 [cli.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 输出不得出现 API Key、DSN password、token 或 URL credential 明文。最后重启或滚动 `agentrun-mgr`，再用 CLI 查询同一个 run，确认 command state、events 和 terminal_status 仍可见。
|
||||
|
||||
### T5 RESTful API 交互联调
|
||||
|
||||
阅读 `AGENTS.md`、本文和 [spec-v01-services.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](cli.md) 和 [spec-v01-services.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 结果必须一致。
|
||||
|
||||
## 规格的实现情况
|
||||
|
||||
| 规格项 | 状态 | 说明 |
|
||||
@@ -90,4 +130,6 @@
|
||||
| 两层验证模型 | 已定义 | 本文为 v0.1 验证权威。 |
|
||||
| 自测试 task | 未实现 | 需要后续随组件实现补齐。 |
|
||||
| 综合联调 task/runbook | 未实现 | 需要 runtime、Postgres、SecretRef 和真实 backend 就绪后补齐。 |
|
||||
| CLI 交互联调标准 | 已定义 | 必须只使用正式 CLI，验证真实 run 生命周期和可观测输出。 |
|
||||
| RESTful API 交互联调标准 | 已定义 | 必须直连真实 manager HTTP JSON API，验证服务合同和 durable facts。 |
|
||||
| mock 作为发布证据 | 不采用 | mock 只能证明自测试通过。 |
|
||||
|
||||
Reference in New Issue
Block a user