docs: 固化 runner 多轮执行规格
This commit is contained in:
Codex
@@ -11,6 +11,7 @@
|
||||
- 执行最小 tenant policy boundary：只做 schema、allowlist、idempotency、secret scope 和 executionPolicy 范围检查；不内建 UniDesk/HWLAB 的业务授权。
|
||||
- 使用 Postgres 保存 runs、commands、events、runners、backends、leases 和 migration ledger。
|
||||
- 输出结构化 health/readiness、failureKind、redacted SecretRef 和 trace correlation。
|
||||
- 可观测性只能定位和验证状态，不能替代缺失能力实现；如果 HWLAB canary 需要的 final reply、command result、runner 多 turn、SessionRef 或 cancel 能力缺失，manager 必须补 durable API/状态机，而不是只补 trace 文案。
|
||||
|
||||
## 内部架构
|
||||
|
||||
@@ -57,6 +58,7 @@ GET /api/v1/runs/:runId/commands?afterSeq=0&limit=20
|
||||
POST /api/v1/runs/:runId/events
|
||||
PATCH /api/v1/runs/:runId/status
|
||||
POST /api/v1/commands/:commandId/ack
|
||||
PATCH /api/v1/commands/:commandId/status
|
||||
```
|
||||
|
||||
所有 API 成功和失败响应都必须是 JSON。失败响应至少包含 `failureKind`、`message` 和 trace correlation；不得出现空 stdout/空 response 被误判为成功的情况。
|
||||
@@ -103,7 +105,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
|
||||
## 最小 Observability 合同
|
||||
|
||||
- events append-only，单 run 内 `seq` 单调递增。
|
||||
- 每个 run 必须最终出现唯一 authoritative `terminal_status`，或保持明确 non-terminal status 并可查询 lease/heartbeat；assistant partial、stdout、transport close 或 idle timeout 不能替代 terminal completed。
|
||||
- command terminal 与 run terminal 必须分离。普通 turn completed 只终结对应 command，run 可以保持 `claimed/running` 以继续接收后续 command；每个 command result 必须能从 command record 与 command-scoped events 得到 authoritative terminal。run 级 `terminal_status` 只用于 run cancel、runner 级不可恢复失败或明确 run terminal；assistant partial、stdout、transport close 或 idle timeout 不能替代 terminal completed。
|
||||
- failureKind 至少能区分 `schema-invalid`、`tenant-policy-denied`、`secret-unavailable`、`runner-lease-conflict`、`backend-failed`、`provider-auth-failed`、`provider-unavailable`、`infra-failed`、`cancelled`。
|
||||
- health/readiness 必须返回 Postgres reachable、schema migration ready、SecretRef redacted 状态和 build/source metadata。
|
||||
- 日志、event、trace、health 和 diagnostics 不得输出 provider credential、Codex auth/config 内容、DSN password、token 或 URL credential。
|
||||
@@ -125,6 +127,8 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
|
||||
|
||||
`assistant_message` partial、`command_output` 存在、stdout 非空、backend transport close 或 idle timeout 都不能单独让 result 进入 `completed`。
|
||||
|
||||
当 `commandId` 已指定，result envelope 必须只聚合该 command 的 assistant/output/error/terminal 事件；同一 run 的其他 command reply 不能串入当前 command result。未指定 `commandId` 时可默认选择最新 command。
|
||||
|
||||
## 测试规格
|
||||
|
||||
### T1 Manager health/readiness
|
||||
@@ -147,6 +151,10 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
|
||||
|
||||
阅读本文和 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md)，然后用 RESTful API 创建 `tenantId=hwlab` 的 run、提交 command、调用 `POST /api/v1/runs/:runId/runner-jobs`。确认响应短返回 JSON，包含 `runId`、`commandId`、`attemptId`、`jobName`、namespace、log/pod identity 和后续 poll 入口；重复 idempotency key 不创建重复 job。
|
||||
|
||||
### T6 command/run terminal 分离
|
||||
|
||||
阅读本文和 [spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md)，然后在同一 run 内让两个 command 依次 completed。确认第一条 command completed 不会把 run 标为 terminal，`GET /commands/:id/result` 只返回对应 command 的 reply/terminal，run cancel 才会把 run 和未完成 command 一起收敛到 cancelled。
|
||||
|
||||
## 规格的实现情况
|
||||
|
||||
| 规格项 | 状态 | 说明 |
|
||||
@@ -155,8 +163,9 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
|
||||
| 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 主闭环。 |
|
||||
| 手动 runner Job API | 已实现 | `POST /api/v1/runs/:runId/runner-jobs` 已可创建 Kubernetes runner Job，并固化 idempotency、持久 runner job record、响应 schema 和 cancel 前置检查。 |
|
||||
| runner Job 状态查询 | 已实现 | `GET /api/v1/runs/:runId/runner-jobs` 和 `GET /api/v1/runs/:runId/runner-jobs/:runnerJobId` 返回 attempt/job/log/phase/terminal 摘要，业务客户端无需直连 Kubernetes 做最小定位。 |
|
||||
| command/run terminal 分离 | 已实现最小闭环 | `PATCH /api/v1/commands/:commandId/status` 终结 command 并更新 SessionRef；普通 turn completed 不终结 run，run status 仅由 run cancel 或 runner 级不可恢复失败终结。 |
|
||||
| Tenant policy boundary | 已实现最小边界 | v0.1 已做 schema、tenant/backend allowlist、executionPolicy 和 secretScope 结构校验；业务授权仍由 UniDesk/HWLAB 自己判定。 |
|
||||
| `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 和部署级观测仍属后续工作。 |
|
||||
| Observability 最小合同 | 已实现主路径 | events append-only、command-scoped terminal status、failureKind、health/readiness store 状态、runner claim/lease/backend events 和 Secret/DSN redaction 已进入 manager；集中 trace 和部署级观测仍属后续工作。 |
|
||||
| durable cancel API | 已实现最小闭环 | 已提供 run/command cancel API；pending command cancel 阻止新 runner Job，running runner 轮询 cancel 并中止 Codex stdio backend，终态使用 `cancelled`。 |
|
||||
|
||||
Reference in New Issue
Block a user