mirrors/pikasTech-agentrun
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define HWLAB manual dispatch target

Browse Source
This commit is contained in:
Codex
2026-06-01 08:34:25 +08:00
parent 4693a8bb54
commit eb5e0f57a6
6 changed files with 172 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/spec-v01-agentrun-mgr.md
+10
View File
@@ -5,6 +5,7 @@
## 在系统中的职责划分
- 提供 Manager 公共 API：创建和查询 run、提交 command、分页读取 events、查询 backend capability。
- 提供手动调度 API：为已创建的 run/command 显式创建 Kubernetes runner Job，并快速返回 job identity、attempt 和轮询入口。
- 提供 Runner 私有 API：runner register、claim run、lease heartbeat、poll commands、append events、ack command、上报 status。
- 校验并持久化 `tenantId`、`projectId`、`workspaceRef`、`providerId`、`backendProfile`、`executionPolicy` 和 `traceSink`。
- 执行最小 tenant policy boundary：只做 schema、allowlist、idempotency、secret scope 和 executionPolicy 范围检查；不内建 UniDesk/HWLAB 的业务授权。
@@ -34,9 +35,12 @@ GET /api/v1/runs/:runId
GET /api/v1/runs/:runId/events?afterSeq=0&limit=100
POST /api/v1/runs/:runId/commands
GET /api/v1/runs/:runId/commands/:commandId
POST /api/v1/runs/:runId/runner-jobs
GET /api/v1/backends
```
面向 HWLAB v0.2 canary 的手动调度 API 目标见 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md)。`runner-jobs` 只显式启动当前 run/command 的 runner Job，不扫描 pending queue，不等待完整模型 turn；自动 scheduler 仍是 deferred 能力。后续 durable cancel API 必须与同一 run/command 状态机衔接，不能让 HWLAB 直接删除 Kubernetes Job 作为正式取消语义。
Runner 私有 API 的 `v0.1` 范围：
```http
@@ -103,13 +107,19 @@ POST /api/v1/commands/:commandId/ack
阅读本文和 [spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md)，然后让两个真实 runner 尝试 claim 同一个 run。确认只有一个 owner 成功，另一个返回 `runner-lease-conflict` 或等价 failureKind；随后分页读取 events，确认 `seq` 单调、不重复、不丢失。
### T5 手动 runner Job 调度 API
阅读本文和 [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。
## 规格的实现情况
| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| `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；HWLAB canary 还需固化 idempotency、响应 schema 和 cancel 衔接。 |
| 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 和部署级观测仍属后续工作。 |
| durable cancel API | 待实现 | 类型和 `cancelled` failureKind 已存在；面向 HWLAB `/cancel` 还需 public cancel API、runner 观察和 backend interrupt 闭环。 |
docs/reference/spec-v01-hwlab-manual-dispatch.md
+138
View File
@@ -0,0 +1,138 @@
# v0.1 HWLAB 手动调度接入规格
本文定义 AgentRun `v0.1` 面向 HWLAB v0.2 的下一阶段服务目标：不以前置自动 scheduler 为条件，而是通过 `agentrun-mgr` 的手动调度 API 为 HWLAB 提供 canary Code Agent 执行服务。实施跟踪见 [pikasTech/agentrun#31](https://github.com/pikasTech/agentrun/issues/31)。
## 在系统中的职责划分
- HWLAB `hwlab-cloud-api` 是业务 dispatcher：继续负责用户登录、session owner、device-pod 授权、Workbench `/v1/agent/chat` 合同、result/trace/cancel 对外接口和业务权限判断。
- AgentRun `agentrun-mgr` 是执行事实 authority：负责 run、command、event、runner job、backend profile、SecretRef、terminal status 和手动调度 API。
- `agentrun-runner` 是短生命周期执行者：从 manager claim run、poll command、调用 backend adapter、append events、ack command、上报 terminal status。
- HWLAB 不直接写 AgentRun Postgres、不读取 AgentRun Secret、不直接创建 Kubernetes Job；所有跨服务操作只走 AgentRun RESTful API。
- AgentRun 不内建 HWLAB device-pod/gateway 业务授权；涉及硬件、用户授权或 device lease 的判断仍由 HWLAB 自己完成。
## 非目标
- 本阶段不要求自动 scheduler、pending scan、capacity selection 或长驻调度器。
- 不改变 HWLAB 对外 `/v1/agent/chat`、`/result`、`/trace`、`/cancel` 用户合同。
- 不使用 SSE、WebSocket、long-polling 或长同步 `turn` 请求替代 durable resource 模型。
- 不把 HWLAB 的 provider Secret、device token、gateway route 或 kubeconfig 复制给业务客户端。
- 不把 mock、fixture、source-only smoke 或 dry-run 结果当作 HWLAB canary 通过证据。
## 目标调用链
```text
HWLAB Workbench
-> hwlab-cloud-api /v1/agent/chat
-> HWLAB 用户/session/device 权限判断
-> AgentRun POST /api/v1/runs
-> AgentRun POST /api/v1/runs/:runId/commands
-> AgentRun POST /api/v1/runs/:runId/runner-jobs
-> agentrun-runner claim/poll/report
-> AgentRun events/command status/terminal_status
-> hwlab-cloud-api 映射为 HWLAB result/trace
```
HWLAB 应保存 `traceId -> runId/commandId/attemptId/jobName` 映射。用户轮询 HWLAB result/trace 时，HWLAB 从 AgentRun command status 与 run events 读取进展，再转换为 HWLAB 自己的前端 schema；浏览器不直接理解 AgentRun 内部 event schema。
## 手动调度 API
`POST /api/v1/runs/:runId/runner-jobs` 是 HWLAB canary 的正式手动调度入口。它只负责为一个已存在 run 和 command 显式创建 runner Job，不负责扫描 pending queue。
请求最小字段：
| 字段 | 规则 |
| --- | --- |
| `commandId` | 必填，必须属于 `runId`。 |
| `attemptId` | 可选；未提供时由 manager 生成，返回值必须可持久查询。 |
| `idempotencyKey` | HWLAB 必须用 `traceId`、`messageId` 或等价稳定 key；相同 key 和相同 payload 返回既有 job/attempt。 |
| `image` / `backendImageRef` | 只能来自 manager allowlist、GitOps/catalog 或受控默认值；客户端不能传任意镜像扩大执行面。 |
| `retention` / `ttlSecondsAfterFinished` | 可选；默认遵循 runner Job TTL 规格。 |
响应必须短返回 JSON，不等待完整模型 turn，至少包含：`runId`、`commandId`、`attemptId`、`jobName`、`namespace`、`runnerId`、`logPath` 或 `podIdentity`、后续 `commands show` 与 `events` 轮询入口。重复提交若 payload 不同，必须结构化失败，不能创建第二个同名业务 attempt。
## Run / Command 映射
HWLAB canary 创建 run 时应使用以下字段口径：
| 字段 | HWLAB canary 口径 |
| --- | --- |
| `tenantId` | `hwlab`。 |
| `projectId` | `pikasTech/HWLAB`。 |
| `providerId` | `G14`，只表示目标 provider，不授予 HWLAB 业务权限。 |
| `backendProfile` | `deepseek` 或 `codex`，由 HWLAB 显式选择；缺少 matching SecretRef 必须失败，不 fallback。 |
| `workspaceRef` | 必须引用 ResourceBundleRef 中的 Git-only full commit；不得由 runner 猜 host path。 |
| `executionPolicy` | sandbox、network、timeout、secretScope 必须显式，不得由 HWLAB 扩大 AgentRun Secret 范围。 |
| `traceSink` | 可指向 HWLAB trace adapter；为 `null` 时 HWLAB 仍可通过 AgentRun events 轮询。 |
Command 第一阶段只要求 `type=turn`。用户原始 prompt、conversation metadata、profile 选择和 HWLAB trace correlation 必须作为 command payload 的非敏感字段保存；不得把 cookie、session token、provider credential、device internal token 或 Secret value 写入 payload。
## 需要补齐的能力
### P0 trace/result 元语
AgentRun 标准 events 必须稳定到足以被 HWLAB 转换：
- `backend_status`：profile、backendKind、protocol、attempt、resource/session 摘要，不包含 Secret 值。
- `assistant_message`：用户可见 assistant 文本，允许分片但必须能聚合为最终 reply。
- `tool_call`：工具名、状态、bounded 参数摘要和 redacted correlation。
- `command_output`：stdout/stderr/diff 的 bounded summary、原始字节数、截断标记和 artifact/log 引用。
- `error`：`failureKind`、message、retryable、provider/infra/backend 分类和 redacted details。
- `terminal_status`：`completed`、`failed`、`blocked` 或 `cancelled`，是 completed 的唯一终态来源。
面向 HWLAB 的 result envelope 至少应能回答：`status`、`terminalStatus`、`reply`、`failureKind`、`blocker`、`lastSeq`、`eventCount`、`artifactSummary`、`runId`、`commandId` 和 `attemptId`。partial assistant 文本、transport close、idle timeout 或 stdout 存在都不能单独升级为 `completed`。
### P0 cancel
AgentRun 需要提供 durable cancel 能力，建议形态为 `POST /api/v1/runs/:runId/cancel` 或 `POST /api/v1/commands/:commandId/cancel`。cancel 必须幂等；已 terminal 的对象返回当前终态。pending command 被 cancel 后不得再创建 runner Job。running runner 必须通过 poll、lease 或 heartbeat 观察 cancel，并传播到 backend interrupt；backend 不支持 interrupt 时终止受控进程组。cancel 最终必须写入 event、command state 和 run status，`failureKind` 使用 `cancelled`。
### P1 SessionRef 持久化
`SessionRef` 需要从 `null/deferred` 升级为可选持久会话引用，支持 HWLAB `conversationId/sessionId/threadId` 到 AgentRun session identity 的映射。session 只能保存 backend thread/session/cache，不保存 API KEY、`auth.json`、`config.toml` 或完整 `CODEX_HOME`。session store 必须与 Secret projection、writable runtime home、Git workspace 分离。runner 启动时，有 SessionRef 则执行 `thread/resume`，没有则执行 `thread/start`；profile 隔离、TTL、GC 和跨 profile 污染防护必须可见。
### P1 ResourceBundleRef / bundle materialization
`ResourceBundleRef` 必须按 Git-only 模型落地：`repoUrl + full commitId` 是唯一内容身份。runner 只能 checkout 到允许 workspace 前缀，不能覆盖 `/app`、Secret projection、profile runtime home 或 session 目录。第一阶段支持 `subdir`、`sparsePaths`、`submodules=false`、`lfs=false`、`credentialRef` 的最小字段即可。HWLAB canary 只需要 `pikasTech/HWLAB` 固定 full commit 的普通 checkout；用户上传文件和对象存储 artifact 不进入 `v0.1`。
## 分阶段增强计划
| 阶段 | 目标 | 主要交付 | 验收重点 |
| --- | --- | --- | --- |
| 1 | 手动调度 API 固化 | `runner-jobs` request/response schema、idempotency、job identity、CLI 调同一 REST API | 重复 key 不重复创建；短返回；manager 重启后可查。 |
| 2 | trace/result 元语 | 标准 event 子集、terminal result envelope、bounded output metadata | HWLAB 可由 events 稳定生成 result/trace；partial 不误报 completed。 |
| 3 | cancel 闭环 | durable cancel API、runner cancel poll、backend interrupt/process group stop | pending/running/terminal 后 cancel 均幂等且可见。 |
| 4 | ResourceBundleRef materialization | Git-only checkout、workspace 前缀、commit/tree 摘要、failureKind | 使用 full commit；不接受 branch/tag/HEAD；不覆盖 Secret/session/runtime home。 |
| 5 | SessionRef 持久化 | session record/store、thread resume、TTL/GC、profile 隔离 | 同一 conversation 连续两轮可复用；不同 profile 不污染。 |
| 6 | HWLAB v0.2 canary | HWLAB dispatcher adapter、traceId 映射、result/trace 转换 | 普通自然语言最短 turn 真实 completed 且 reply 非空；device-pod 仍由 HWLAB 授权。 |
## 测试规格
### T1 手动调度 API
阅读本文和 [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)，然后在真实 `agentrun-v01` runtime 中用 RESTful API 创建 `tenantId=hwlab` 的 run、提交 `turn` command、调用 `POST /api/v1/runs/:runId/runner-jobs`。确认每个 API 返回 JSON、60 秒内返回、不等待完整 turn，并返回 job identity 与后续 poll 入口。
### T2 幂等和重复提交
阅读本文，然后用相同 `idempotencyKey` 重复调用 runner job API。相同 payload 必须返回同一 attempt/job；不同 payload 必须结构化失败，且不能创建第二个 runner Job。
### T3 trace/result 映射
阅读本文和 [spec-v01-backend-adapter.md](spec-v01-backend-adapter.md)，然后执行真实 Codex stdio turn，确认 events 中存在可转换为 HWLAB result/trace 的 `backend_status`、assistant 或 error、`terminal_status`，且 bounded output metadata 足够判断截断和 artifact 引用。
### T4 cancel
阅读本文，然后分别验证 pending cancel、running cancel、重复 cancel 和 terminal 后 cancel。确认 command/run 终态、events 和 failureKind 均为 `cancelled` 或当前既有 terminal 状态，日志不泄露 Secret。
### T5 SessionRef 与 ResourceBundleRef
阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后验证一次带 SessionRef 和 Git-only ResourceBundleRef 的 runner Job。确认 session 不含 credential 文件，bundle 使用 full commit checkout 到允许 workspace，event/result 能回答 session id、repo、commit 和 checkout 摘要。
## 实现状态
| 能力 | v0.1 状态 | 说明 |
| --- | --- | --- |
| 手动 runner Job API | 已有主路径/需固化 | `runner job` 已通过 manager REST 创建 Kubernetes Job；HWLAB canary 还需补 idempotency 和正式 schema。 |
| trace/result 元语 | 部分实现/待增强 | 现有 events 与 terminal status 可用，但需要稳定 HWLAB result envelope 和 bounded output 元数据。 |
| cancel | 规格待实现 | 类型和 failureKind 已存在，durable cancel API 与 runner/backend interrupt 闭环待补。 |
| SessionRef | 规格已定义/待实现 | 当前可为 `null`，持久 session store 与 resume 待补。 |
| ResourceBundleRef | 规格已定义/待实现 | Git-only 模型已定义，runner materialization 待补。 |
| HWLAB v0.2 canary | 待实现 | 需要 HWLAB dispatcher adapter 调 AgentRun 手动调度 API，并转换 result/trace。 |
docs/reference/spec-v01-runtime-assembly.md
+6 -3
View File
@@ -53,9 +53,11 @@ P0 最小 JSON 形态：
### SessionRef
- P0 允许 `sessionRef=null`，表示不持久化 backend session 文件。
- 面向 HWLAB 手动调度 canary，SessionRef 是 P1 必补能力：需要支持 `conversationId/sessionId/threadId` 到 backend session identity 的稳定映射。
- 一旦启用 session，必须只保存 backend session/cache，不保存 API KEY、`auth.json`、`config.toml` 或完整 `CODEX_HOME`。
- session 文件目录必须和 profile credential、Git workspace 分开。
- v0.1 先定义边界，不要求实现 PVC/session restore。
- runner 启动时，有 SessionRef 则执行 `thread/resume`，没有 SessionRef 则执行 `thread/start`；profile 切换不得复用另一 profile 的 session。
- v0.1 先定义边界；持久 session store、TTL、GC 和 resume 验收按 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md) 分阶段推进。
### ResourceBundleRef
@@ -64,6 +66,7 @@ P0 最小 JSON 形态：
- 可选扩展只允许 `subdir`、`sparsePaths`、`submodules=false`、`lfs=false`、`credentialRef`；默认不启用。
- `credentialRef` 只用于拉取私有 Git repo，不等同于 backend API KEY。
- 不支持上传文件、对象存储 artifact、任意 ConfigMap 文件袋或 inline env；后续需要时另写版本规格。
- 面向 HWLAB 手动调度 canary，runner materialization 必须把 Git-only bundle checkout 到允许 workspace 前缀，并在 event/result 中记录 repo、full commit、checkout path 和 tree 摘要；不得隐式使用 manager Pod、host path 或镜像内旧代码。
## 最简装配顺序
@@ -119,5 +122,5 @@ P0 最小 JSON 形态：
| --- | --- | --- |
| `BackendImageRef` | 部分实现 | CI/CD 已使用 digest-pinned runtime image；当前 runner/backend 仍复用 agentrun 镜像。 |
| `ProfileRef` | 已实现/已通过主闭环 | `codex` 与 `deepseek` 已通过 SecretRef、writable runtime home 和真实 stdio turn 验证。 |
| `SessionRef` | 规格已定义/P0 未实现 | 当前只持久化 run facts，不持久化 backend session 文件。 |
| `ResourceBundleRef` | 规格已定义/P0 Git-only/待实现 | 已明确最简 Git-only 模型，runner materialization 后续实现。 |
| `SessionRef` | 规格已定义/P1 待实现 | 当前只持久化 run facts，不持久化 backend session 文件；HWLAB canary 需要 session store、thread resume 和 profile 隔离。 |
| `ResourceBundleRef` | 规格已定义/P1 待实现 | 已明确最简 Git-only 模型；HWLAB canary 需要 runner materialization、checkout 摘要和 full commit 验收。 |
docs/reference/spec-v01-services.md
+11 -2
View File
@@ -15,6 +15,12 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Code Agent 执行基础设施。`
- RuntimeAssembly 是 runner/backend 启动前的四要素装配模型，负责把 backend image、profile、session 和 Git-only resource bundle 统一成受控 Job 输入；四要素权威规格见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。
- Scheduler 是后续自动派发能力；`v0.1` 可以保留规格和状态字段，但不把自动调度作为第一阶段验收目标。
## HWLAB 手动调度服务目标
`v0.1` 面向 HWLAB v0.2 的下一阶段目标是通过手动调度 API 提供 canary Code Agent 执行服务，而不是先实现自动 scheduler。HWLAB `hwlab-cloud-api` 作为业务 dispatcher，完成用户/session/device 权限判断后，显式调用 AgentRun REST API 创建 run、提交 command、启动 runner Job，并把 AgentRun events/terminal status 转换回 HWLAB result/trace。完整目标、非目标、缺口和增强计划见 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md)。
该目标要求优先补齐四类能力：SessionRef 持久化、Git-only ResourceBundleRef materialization、durable cancel、trace/result 元语。自动 scheduler、跨 backend 自动路由和独立 UI 仍然 deferred，不能成为 HWLAB canary 的前置条件。
## 语言与协议选型
AgentRun `v0.1` 的自研组件优先使用 Bun + TypeScript 实现：`agentrun-mgr`、`agentrun-runner`、backend adapter、Codex backend、AgentRun CLI 和后续 scheduler 都属于该边界。官方 TypeScript CLI 入口固定为 `scripts/agentrun-cli.ts`，入口只做参数解析和路由，复杂逻辑拆到 `scripts/src/` 与 `src/`；G14/CI/人工非交互命令使用 `./scripts/agentrun` launcher 启动同一入口。Postgres、Kubernetes、Tekton、Argo CD、YAML manifest 和 shell 级容器启动命令属于外部运行面或部署面，不受“必须 TypeScript 实现”的约束。
@@ -78,6 +84,7 @@ Runner inbound API 只允许本地或私有诊断，不作为业务客户端入
| Postgres durable store | 稳定外部服务 | 保留，P0 | 使用 `agentrun-v01-postgres` 保存 runs、commands、events、runners、backends、leases 和 migration ledger；不使用 file/sqlite 作为 v0.1 durable store。 | `spec-v01-postgres.md` |
| Secret distribution | 系统能力 | 保留，P0 | Provider credential 只通过 Kubernetes SecretRef、ServiceAccount/RBAC 和 runner env/file projection 分发；Codex 测试凭据使用 `~/.codex/auth.json` 与 `~/.codex/config.toml` 生成 Secret projection；source、GitOps、logs 和 events 不保存明文。 | `spec-v01-secret-distribution.md` |
| RuntimeAssembly | 系统能力 | 保留，P0 规格 | runner/backend 启动前的四要素装配模型：`BackendImageRef`、`ProfileRef`、`SessionRef` 和 Git-only `ResourceBundleRef`；P0 先定义模型，ProfileRef 已实现，SessionRef/ResourceBundleRef 按 deferred 子项推进。 | `spec-v01-runtime-assembly.md` |
| HWLAB 手动调度接入 | canary 集成目标 | 保留，P0 规格 | HWLAB `hwlab-cloud-api` 显式创建 run/command 并调用 runner Job API；AgentRun 提供 durable facts、events、cancel、bundle 和 session 能力。 | `spec-v01-hwlab-manual-dispatch.md` |
| Tenant policy boundary | Run schema 合同 | 保留，P0 | 作为 `Run` 的必填字段和最小校验存在，不做独立 policy engine；tenant 的业务授权仍由 UniDesk/HWLAB 判定。 | 并入 `spec-v01-agentrun-mgr.md` |
| Observability | 最小事件/日志合同 | 保留，P1 子项 | 作为 manager/runner 的 event、terminal status、failureKind、logPath 和 redaction 最小合同，不拆独立观测系统。 | 并入 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md` |
| `agentrun-scheduler` | 长驻调度器 | Deferred | M1-M3 稳定后再实现自动 pending scan、capacity selection 和 runner Job 创建。 | `spec-v01-scheduler.md` |
@@ -95,6 +102,7 @@ GET /api/v1/runs/:runId
GET /api/v1/runs/:runId/events?afterSeq=0&limit=100
POST /api/v1/runs/:runId/commands
GET /api/v1/runs/:runId/commands/:commandId
POST /api/v1/runs/:runId/runner-jobs
GET /api/v1/backends
```
@@ -149,8 +157,8 @@ Manager 负责校验、保存和返回这些字段；runner 只能消费已保
| M1 | 最小 runner + 一个 backend | 一个 turn 经过真实 backend，assistant/output/error/terminal events 被归一化。 |
| M2 | manager + runner claim | run create/query durable，claim 拒绝双 owner，events append-only。 |
| M3 | 手动 dispatch CLI | CLI 快速返回 runner process/job identity、log path 和轮询命令。 |
| M4 | 自动 scheduler | Deferred；pending 自动派发和 stale lease recovery 进入后续实现。 |
| M5 | UniDesk/HWLAB canary | Deferred；只在核心生命周期稳定后接入窄范围 canary。 |
| M4 | HWLAB 手动调度 canary | HWLAB 通过 REST API 显式启动 runner Job，并能轮询 result/trace 到终态。 |
| M5 | 自动 scheduler | Deferred；pending 自动派发、capacity selection 和 stale lease recovery 进入后续实现。 |
## 测试规格
@@ -176,6 +184,7 @@ Manager 负责校验、保存和返回这些字段；runner 只能消费已保
| Postgres durable store 规格 | 已定义 | 见 [spec-v01-postgres.md](spec-v01-postgres.md)。 |
| Secret 分发规格 | 已定义 | 见 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。 |
| RuntimeAssembly 规格 | 已定义 | 见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。 |
| HWLAB 手动调度接入规格 | 已定义 | 见 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md)。 |
| 两层验证规格 | 已定义 | 见 [spec-v01-validation.md](spec-v01-validation.md)。 |
| `agentrun-mgr` 服务规格 | 已定义 | 见 [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)。 |
| `agentrun-runner` 服务规格 | 已定义 | 见 [spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md)。 |
docs/reference/spec-v01-validation.md
+5
View File
@@ -162,6 +162,10 @@ T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend
阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后检查一次真实 runner Job 或 dry-run manifest，确认四个问题都有明确答案：用哪一个 digest-pinned image、用哪一个 profile/SecretRef、是否使用 session、使用哪一个 Git repo/full commit。P0 未启用 session 或 Git-only resource materialization 时，必须明确为 `null` 或 deferred，不能由 runner 隐式使用 host path。任何 Secret value、用户文件正文、env dump、branch/tag/HEAD 形式的 resource commit 都不能作为通过证据。
### T10 HWLAB 手动调度 canary 验收
阅读本文和 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md)，然后在真实 `agentrun-v01` runtime 中模拟 HWLAB dispatcher：创建 `tenantId=hwlab` 的 run，提交 `turn` command，调用 `POST /api/v1/runs/:runId/runner-jobs`，轮询 command 和 events 到 terminal。确认 API 全部短返回 JSON，runner Job identity 可见，events 能转换为 HWLAB result/trace，cancel、SessionRef 和 ResourceBundleRef 若未实现必须显式标记为待实现或 blocked，不能用 mock pass 替代真实 canary。
## 规格的实现情况
| 规格项 | 状态 | 说明 |
@@ -174,4 +178,5 @@ T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend
| 真实主闭环 | 已通过 | 当前 v0.1 已通过真实 Tekton/Argo、Postgres、SecretRef、Kubernetes runner Job、Codex stdio turn、RESTful API 和 CLI 主闭环；每次发布仍需按本文手动复验。 |
| `deepseek` profile 切换验收 | 已通过主闭环 | 自测试和 CLI smoke 已覆盖 profile registry、Secret render、fake stdio turn、无 fallback 和结构化错误；真实 `agentrun-v01` 已按 T8 完成 `codex -> deepseek -> codex` 切换综合联调。后续涉及 backend profile 的发布仍必须按 T8 复验。 |
| RuntimeAssembly 四要素验收 | 已定义 | T9 收敛为四个最简问题：image digest、profile/SecretRef、session null/deferred、Git-only repo/full commit；session/resource materialization 后续实现时必须补真实联调。 |
| HWLAB 手动调度 canary 验收 | 已定义 | T10 规定 HWLAB dispatcher 通过手动 runner Job API 使用 AgentRun 的真实联调口径；自动 scheduler 不是前置条件。 |
| mock 作为发布证据 | 不采用 | mock 只能证明自测试通过。 |