diff --git a/docs/reference/spec-v01-validation.md b/docs/reference/spec-v01-validation.md index 61f23dd..a80153f 100644 --- a/docs/reference/spec-v01-validation.md +++ b/docs/reference/spec-v01-validation.md @@ -79,6 +79,7 @@ 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`。 +- `workspaceRef` 必须指向 runner 容器或受控 runner process 可访问的真实工作区;不存在的 path、只存在于 manager pod 的临时目录或未挂载的 host path 都不能作为综合联调通过证据。若因此导致 backend spawn 失败,应先按无效 workspace 前置条件归因,再排查 provider 或镜像依赖。 - `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` 单调递增,分页重复读取不丢失也不重复。 @@ -125,7 +126,7 @@ CLI 与 RESTful API 可以复用同一个真实 run 做联调。若两者观察 ### 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。 +阅读 `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,其中 `workspaceRef` 必须是真实 runner 可访问路径;调用 `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 观察一致性