feat: 补齐 HWLAB 基线 AgentRun 执行元语
This commit is contained in:
Codex
@@ -39,6 +39,8 @@ POST /api/v1/runs/:runId/commands
|
||||
GET /api/v1/runs/:runId/commands/:commandId
|
||||
GET /api/v1/runs/:runId/commands/:commandId/result
|
||||
POST /api/v1/runs/:runId/runner-jobs
|
||||
GET /api/v1/runs/:runId/runner-jobs?commandId=<commandId>
|
||||
GET /api/v1/runs/:runId/runner-jobs/:runnerJobId
|
||||
POST /api/v1/commands/:commandId/cancel
|
||||
GET /api/v1/backends
|
||||
```
|
||||
@@ -101,7 +103,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
|
||||
## 最小 Observability 合同
|
||||
|
||||
- events append-only，单 run 内 `seq` 单调递增。
|
||||
- 每个 run 必须最终出现 `terminal_status`，或保持明确 non-terminal status 并可查询 lease/heartbeat。
|
||||
- 每个 run 必须最终出现唯一 authoritative `terminal_status`，或保持明确 non-terminal status 并可查询 lease/heartbeat；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。
|
||||
@@ -114,6 +116,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
|
||||
| --- | --- |
|
||||
| `status` | run/command 当前聚合状态，只能由 command state 和 terminal_status 推导。 |
|
||||
| `terminalStatus` | `completed`、`failed`、`blocked` 或 `cancelled`；没有 terminal event 时为 `null` 或 equivalent running 状态。 |
|
||||
| `completed` / `terminalSource` | `completed=true` 只能来自 terminal completed；`terminalSource` 标明来自 `terminal_status` event、run record 或暂无 terminal。 |
|
||||
| `reply` | 从 `assistant_message` 聚合的最终用户可见文本；没有 terminal completed 时不得伪造 completed reply。 |
|
||||
| `failureKind` / `blocker` | 结构化失败分类和摘要；必须 redacted。 |
|
||||
| `lastSeq` / `eventCount` | 支持调用方增量轮询和 result/trace reconciliation。 |
|
||||
@@ -151,6 +154,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
|
||||
| `agentrun-mgr` 服务规格 | 已定义 | 本文为 v0.1 manager 权威。 |
|
||||
| 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 做最小定位。 |
|
||||
| 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)。 |
|
||||
|
||||
@@ -44,6 +44,8 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
|
||||
./scripts/agentrun runner start --run-id <runId> --backend <backendProfile>
|
||||
./scripts/agentrun runner job --run-id <runId> --command-id <commandId> [--idempotency-key <key>]
|
||||
./scripts/agentrun runner job --dry-run --run-id <runId> --command-id <commandId> --image <image>
|
||||
./scripts/agentrun runner jobs --run-id <runId> [--command-id <commandId>]
|
||||
./scripts/agentrun runner job-status [runnerJobId] --run-id <runId>
|
||||
./scripts/agentrun secrets codex render --dry-run [--profile codex|deepseek] [--codex-home <dir>]
|
||||
./scripts/agentrun backends list
|
||||
./scripts/agentrun server start|status
|
||||
@@ -53,6 +55,7 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
|
||||
|
||||
- 创建类命令返回 `runId`、`commandId`、status 和下一步 poll command。
|
||||
- `runner start` 返回 attemptId、job/process identity、logPath 和后续 status/events 命令。
|
||||
- `runner jobs` / `runner job-status` 返回 manager 持久化的 runner Job 最小状态摘要，包括 attemptId、runnerId、namespace、jobName、phase、terminalStatus、logPath、retention 和 redacted Kubernetes identity；业务方不需要直连 Kubernetes 才能定位当前 attempt。
|
||||
- 查询类命令返回当前 state、terminal_status、failureKind、event cursor 或 logPath。
|
||||
- `events` 默认分页且有界，必须支持 `afterSeq` 和 `limit`。
|
||||
- `server logs` 返回有界日志摘要，并指向完整日志文件或 Kubernetes pod identity。
|
||||
@@ -96,6 +99,7 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
|
||||
| `scripts/agentrun-cli.ts` | 已实现 | 已提供 run/command/event/backend/server 基础命令和 JSON envelope；`scripts/agentrun` 是同一入口的 Bun 定位 launcher。 |
|
||||
| CLI 调 manager REST | 已实现 | CLI 通过 `ManagerClient` 调 manager REST；自测试可用内存 manager，综合联调必须指向真实 `agentrun-v01` manager。 |
|
||||
| runner start/job | 已实现 | `runner start` 可执行 host process runner；`runner job --dry-run` 可渲染 Kubernetes Job JSON；`runner job` 正式路径通过 manager REST 创建 Kubernetes Job，支持 `--idempotency-key` 并快速返回 job identity、SecretRef、retention 和轮询命令。 |
|
||||
| runner jobs/job-status | 已实现 | CLI 通过 manager REST 查询 runner Job 持久记录和最小状态摘要，不直连 Kubernetes、不读取 Secret 值。 |
|
||||
| result/cancel CLI | 已实现 | `runs result`、`commands result`、`runs cancel` 和 `commands cancel` 均调用 manager REST，不维护独立状态。 |
|
||||
| CLI 测试规格 | 已定义/已验证主闭环 | 综合联调见 [spec-v01-validation.md](spec-v01-validation.md)；每次发布仍按手动交互验收复跑。 |
|
||||
| `deepseek` profile CLI | 已实现/已通过主闭环 | `secrets codex render --profile deepseek`、`backends list`、`runner start --backend`、`runner job` 和 JSON 错误可见性已实现；真实 CLI/RESTful 联调已通过 `codex -> deepseek -> codex` 切换主闭环。 |
|
||||
|
||||
@@ -23,6 +23,7 @@
|
||||
- CLI：默认 JSON、空 stdout 失败、长操作短返回、错误结构化。
|
||||
- Postgres adapter：migration、事务、run/command/event round-trip、重启后可查询。
|
||||
- Secret 分发：SecretRef schema、missing secret failure、redaction。
|
||||
- HWLAB v0.2 基线承接：可以用 fake backend/临时 manager 做组件自测试，覆盖 event contract、result completed 防误判、bounded output、runner job status、SessionRef profile 隔离、ResourceBundleRef 失败分类和 backend preflight redaction；这些自测试不能替代真实 `agentrun-v01` CLI 交互验收。
|
||||
|
||||
自测试应使用 Bun + TypeScript 运行，Codex 相关自测试可以使用 fake app-server JSON-RPC client 模拟 `initialize`、`thread/start`、`thread/resume`、`turn/start`、assistant 输出、协议错误、timeout 和 transport close。
|
||||
|
||||
@@ -189,6 +190,7 @@ T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend
|
||||
| --- | --- | --- |
|
||||
| 两层验证模型 | 已定义 | 本文为 v0.1 验证权威。 |
|
||||
| 自测试 task | 已实现 | `src/selftest/run.ts` 自动发现 `src/selftest/cases/*.ts`；覆盖 redaction/Postgres contract、manager memory、runner Job render/create、Codex fake app-server stdio 和 Secret render。 |
|
||||
| HWLAB 基线承接自测试 | 已实现 | `src/selftest/cases/60-hwlab-baseline-contract.ts` 固化 event/result/failureKind/bounded output/runner job status/session/profile/bundle/preflight 的组件合同；综合联调仍必须走正式 AgentRun CLI 且不能使用 mock。 |
|
||||
| 综合联调验收规格 | 已增强 | 本文保留人工交互验收模型；T4-T8 定义 CLI、RESTful、一致性、负向场景和 backend profile 切换的手动验收标准，不新增自动脚本或门禁。 |
|
||||
| CLI 交互联调标准 | 已定义 | 必须只使用正式 CLI，验证真实 run 生命周期和可观测输出。 |
|
||||
| RESTful API 交互联调标准 | 已定义 | 必须直连真实 manager HTTP JSON API，验证服务合同和 durable facts。 |
|
||||
|
||||
Reference in New Issue
Block a user