# PJ2026-010205 HWLAB接入

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。

## 正文

## PJ2026-010205 HWLAB接入需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010205 |
| 短名 | HWLAB接入 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-17-r0; draft-2026-06-25-p0-session-warm-runner-contract; PJ2026-010401080313 Workbench实时权威 draft-2026-07-14-p0-pure-kafka-authority |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB 通过 AgentRun 执行 Code Agent 的接入目标、合同边界、术语、系统边界、内部分工和原子需求。

## 2. 目的和范围

### 2.1 目的

HWLAB接入负责把 HWLAB Cloud API、Workbench、CLI、HWPOD 运行上下文和 AgentRun durable execution 合同连接起来，使 HWLAB 能以手动调度 API 完成 Code Agent canary，并逐步收敛到可续跑、可取消、可追踪、可映射结果的 AgentRun 执行路径。

HWLAB接入不拥有 AgentRun run、command、runner job、lease 或 terminal status 的执行事实。HWLAB 只负责在 admission 阶段生成业务 session/turn/message/trace 标识和 AgentRun 委托请求，并在后续通过 AgentRun durable events/result/diagnosis API 消费执行事实，再交给 WorkbenchProjectionWriter/Finalizer 写入 HWLAB 用户态投影。manager rolling、runner stale、terminal report delayed 或不可恢复 blocker 都必须先在 AgentRun 写侧形成 durable facts 或 diagnostic，HWLAB 不得通过 GET、result polling、trace tail、Web reducer 或人工 resubmit 补造执行状态。

Workbench 多 turn 接入还必须保持 session execution lane。HWLAB adapter 不得把同一 Workbench session 的连续 prompt、steer、cancel 和 retry 映射成彼此无关的 AgentRun run-scoped runner Job，再用 `sessionPolicy`、thread metadata 或 PVC 复用标称为 runner reuse。若当前 AgentRun 能力只能通过同一 run 多 command 让 runner 继续 poll 后续 command，HWLAB 应复用该 run/session command channel；若采用未来 warm runner lease，也必须把 lease/channel identity 和 command handoff 暴露给 Workbench projection diagnostic。

### 2.2 范围内

- HWLAB 业务 dispatcher 创建 AgentRun run、command 和 runner job 的字段映射。
- `POST /api/v1/runs/:runId/runner-jobs` 手动调度 API、idempotency、短返回和 runner job identity。
- HWLAB session/provider/profile、conversation、workspace、gitbundle、promptRefs、requiredSkills 和 toolCredentials 的接入口径。
- HWLAB HWPOD/runtime 短期上下文通过 transientEnv 或 tool credential 进入 runner job 的边界。
- AgentRun events、command result、terminal status、failureKind 和 result envelope 到 HWLAB trace/result 的映射。
- AgentRun rolling/reconciler/outbox diagnostic 到 Workbench projection diagnostic 的接入边界。

### 2.3 范围外

- HWPOD 设备身份、inventory、租约、健康和硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。
- CaseRun 评价、pass/fail、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。
- HWLAB 用户鉴权、组织、API key、额度和账本归 [用户管理](PJ2026-0105-user-management.md)。
- Web/CLI 展示、管理页和用户交互归 [客户端](PJ2026-0104-client.md)。
- 自动 scheduler 和跨 backend 自动路由不是 HWLAB canary 前置条件。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| HWLAB dispatcher | HWLAB Cloud API 中完成业务鉴权、资源选择和 AgentRun 委托调用的服务端组件。 |
| 手动调度 API | AgentRun 为已存在 run/command 显式创建 runner Job 的短返回 API。 |
| HWLAB canary | HWLAB v0.2 通过 AgentRun 执行真实 Code Agent turn 的最小接入闭环。 |
| result envelope | AgentRun command result 的结构化输出，包含 status、terminalStatus、reply、failureKind、events 和 artifact 摘要。 |
| Workbench事件映射器 | [PJ2026-010401080313 Workbench实时权威](PJ2026-010401080313-workbench-realtime-authority.md) 定义的 direct publish 组件，把 `agentrun.event.v1` 归一化为 `hwlab.event.v1`，不以内联 PostgreSQL 投影或 outbox 作为前置。 |
| HWPOD runtime context | HWLAB dispatcher 为单次 runner job 提供的 owner-scoped 硬件运行上下文。 |
| transientEnv | 单次 runner job 的短期 env 上下文，由 AgentRun 转为短期 Secret 投影并脱敏输出。 |
| 自然语言单一路由 | `/v1/agent/chat` 中自然语言请求统一进入 AgentRun Code Agent turn，不由 Cloud API 做关键词分流或文本 fallback。 |
| AgentRun durable facts | AgentRun 写侧持久化的 run、command、event、runner job、lease、terminal report state、result 和 diagnosis，是 HWLAB 接入消费执行状态的唯一上游事实。 |
| session execution lane | HWLAB Workbench session 到 AgentRun run/session command channel 或 warm runner lease 的稳定映射，用于承载连续 prompt、steer、cancel 和 retry。 |
| warm runner contract | 连续 turn 不重复支付完整 runner Job 冷启动成本的执行合同；同一 session 内后续 command 应由同一 run runner loop、session runner lease 或等价机制承接。 |

## 4. 系统边界和接口

本规格把 HWLAB接入作为 HWLAB 到 AgentRun 的服务端委托系统看待；本章只描述输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | HWLAB Cloud API、HWLAB Cloud Web、HWLAB CLI、AgentRun核心、Runtime装配、后端Profile、硬件池和 HarnessRL。 |
| 外部输入 | HWLAB 用户任务、session/conversation、workspace/ref、provider profile、HWPOD/runtime context、resourceBundleRef、promptRefs、requiredSkills 和 trace correlation。 |
| 受控资源 | AgentRun run/command/runner job 映射、manual dispatch payload、transientEnv Secret projection、event/result mapping 和 cancel/session continuation。 |
| 外部输出 | runId、commandId、runnerJobId、attemptId、jobName、terminalStatus、reply/finalResponse、failureKind、blocker、artifact summary 和 HWLAB trace 指针。 |
| 用户接口 | HWLAB Agent API、Cloud Web/CLI Agent 入口和 AgentRun manual dispatch API。 |
| 系统边界 | HWLAB接入负责服务端委托与结果映射；AgentRun 不解释 HWPOD 权限，不判断 HWLAB 用户授权，不把业务 token 固化为 durable fact。 |

## 5. 内部分工与规格索引

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-01020501 | 手动调度 | 本规格 6.1 | runner-jobs API、idempotency、短返回和 job identity | AgentRun Core run/command | HWLAB canary |
| PJ2026-01020502 | 字段映射 | 本规格 6.2 | HWLAB task/session/workspace/profile 到 AgentRun run/command 映射 | 客户端、用户管理、Runtime装配 | AgentRun Core、Backend Profile |
| PJ2026-01020503 | 结果映射 | 本规格 6.3 | events/result/terminal/failureKind 到 HWLAB trace/result | AgentRun Core、Backend Profile | 客户端、HarnessRL |
| PJ2026-01020504 | 硬件上下文 | 本规格 6.4 | HWPOD/runtime transientEnv 和 tool credential 边界 | 硬件池、Runtime装配 | Runner job、Agent 执行 |
| PJ2026-01020505 | 取消续跑 | 本规格 6.5 | durable cancel、SessionRef 和 same-run multi-command 接入 | Queue会话、Runtime装配 | HWLAB Workbench、CLI |
| PJ2026-01020506 | 单一路由 | 本规格 6.6 | 自然语言请求统一委托 AgentRun Code Agent，显式控制 API 不截获聊天 | API契约、Backend Profile、Runtime装配 | Web工作台、HWLAB CLI |

## 6. 原子需求

### 6.1 AR-HWLAB-REQ-001 手动调度入口

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-HWLAB-REQ-001 | 手动调度 | PJ2026-01020501 手动调度 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) |

HWLAB接入应通过 AgentRun 手动调度 API 为已创建的 run/command 显式创建 runner Job，并快速返回 job identity、attempt、logPath 或 pod identity 以及后续轮询入口。

手动调度只启动当前 run/command 的 runner Job，不扫描 pending queue，不等待完整模型 turn，也不把 Kubernetes Job 删除作为正式取消语义。重复提交必须按 idempotency key 返回既有 job 或结构化失败。

手动调度入口只能作为创建或恢复 execution lane 的短返回控制面，不能在同一 Workbench session 的每个 turn 上无条件创建新的独立 run-scoped runner Job。若调用方显式请求新 run，响应或 diagnostic 必须能说明这是 fresh run、复用失败、runner lease 不可用还是策略要求；不能把每 turn fresh runner 标记为 reuse。

### 6.2 AR-HWLAB-REQ-002 HWLAB 到 AgentRun 字段映射

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-HWLAB-REQ-002 | 字段映射 | PJ2026-01020502 字段映射 | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[用户管理](PJ2026-0105-user-management.md)、[客户端](PJ2026-0104-client.md) |

HWLAB接入应把 HWLAB session、conversation、workspace、provider profile、resource bundle、promptRefs、requiredSkills、toolCredentials 和 trace correlation 映射为 AgentRun run、command 和 RuntimeAssembly 输入。

AgentRun `tenantId`、`projectId`、`providerId`、`backendProfile` 是 AgentRun policy 字段，不等同于 HWLAB Workbench project。HWLAB 业务 project/workspace 只能进入 metadata 或 workspaceRef 子字段，不能覆盖 AgentRun 的通用 policy 边界。

### 6.3 AR-HWLAB-REQ-003 结果与 Trace 映射

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-HWLAB-REQ-003 | 结果映射 | PJ2026-01020503 结果映射 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[后端Profile](PJ2026-010204-backend-profile.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

HWLAB接入应消费 AgentRun events、command result、terminal status、failureKind 和 result envelope，并转换为 HWLAB 可展示、可追踪、可供 HarnessRL 引用的执行结果。

HWLAB 不得用 partial assistant、stdout、transport close、idle timeout 或日志尾部推断 completed。`eventsCapped=true`、final assistant 截断或 command 未终态时，HWLAB 应继续读取 AgentRun events/trace，而不是把当前摘要当作完整归档。

HWLAB接入应把 AgentRun events 映射并 direct publish 为 `hwlab.event.v1` 的 Turn、Message、Part 和 TraceEvent typed events。AgentRun 是 execution backend，Kafka 是 Workbench 实时与回放的单一事件权威；Web、CLI 和 REST snapshot 不能分别从 runnerTrace、terminalEvidence、workspace snapshot、result polling 或数据库 outbox 生成多套 final response。

[PJ2026-010401080313 Workbench实时权威](PJ2026-010401080313-workbench-realtime-authority.md) 是 HWLAB接入中 AgentRun -> Workbench 的唯一专项规格。mapper 只负责 `agentrun.event.v1 -> hwlab.event.v1`；live SSE 与 refresh replay 都消费 `hwlab.event.v1`，并使用同一 reducer。dispatcher、compat wrapper、Workbench GET、result polling 和 trace polling 不得建立第二写权或替代 Kafka replay。

HWLAB 接入必须按 AgentRun Kafka event cursor 幂等消费并 direct publish。AgentRun `/result` 只用于终态补全或后台归档，不得作为 running turn 的主读源，也不得因为 `/result` 慢或超时阻断 Kafka event mapping、Workbench trace 进度或 terminal typed event 发布。

AgentRun manager rolling 或 runner terminal report delayed 时，HWLAB接入只能消费 AgentRun durable diagnosis、observation facts 和 terminalReportState，并把它们交给 Workbench projection diagnostic。若 AgentRun ledger 暂时 stale、runnerJob observation 尚未恢复或 terminal outbox 尚未提交，HWLAB 应输出 projecting/degraded/stalled/blocker 等可解释状态；不得在 dispatcher、compat wrapper、GET handler、CLI renderer、trace polling 或 Web reducer 中根据 Kubernetes Job phase、stdout、最后一条 event、elapsed timeout 或用户切换 session 推断 completed。

AgentRun 的 `failureObserved`、`retryScheduled`、`retryStarted`、`retryRecovered` 和 `retryExhausted` 必须由 mapper 无损转换为 `hwlab.event.v1`。映射至少保留故障域、组件、代码、脱敏摘要、可重试性、当前与最大次数、退让时长、下次重试时间、首次观察时间和执行标识。HWLAB 不得重新分类故障、重置重试计数、安排重试或从 elapsed time 推断耗尽。

同一次用户提交、steer 或 retry 应在 admission 时生成稳定 turnId、traceId、userMessageId 和 assistantMessageId。初发 UI 可以基于这些标识做 optimistic 展示；AgentRun events/result 到达后必须用同 ID 确认或更新对应 message/part/turn/trace，而不是创建另一条会话消息。页面刷新、session 切换、SSE 重连和 CLI inspect/result 都必须恢复同一组标识和同一语义结果。

### 6.4 AR-HWLAB-REQ-004 HWPOD Runtime Context

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-HWLAB-REQ-004 | 硬件上下文 | PJ2026-01020504 硬件上下文 | [硬件池](PJ2026-0101-hardware-pool.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) |

HWLAB接入应把 HWPOD/runtime 的短期、owner-scoped 执行上下文作为单次 runner job 的 transientEnv 或受控 tool credential 传入，使 Agent 能访问授权范围内的 HWLAB runtime 而不获得长期平台凭据。

AgentRun 只负责投影、脱敏和限制扩散，不解释 HWPOD 权限，也不把业务 token 写入 run、command、event、result 或通用授权配置。provider API key、GitHub token、UniDesk SSH token 和 SSH private key 不得通过 transientEnv 注入。

### 6.5 AR-HWLAB-REQ-005 取消与会话续跑

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-HWLAB-REQ-005 | 取消续跑 | PJ2026-01020505 取消续跑 | [队列会话](PJ2026-010203-queue-session.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md) |

HWLAB接入应使用 AgentRun durable cancel、SessionRef、thread continuation 和 same-run multi-command loop 实现用户可见的取消、follow-up、steer 和续跑。

取消必须幂等并写入 command/run 状态与 event；pending command 被取消后不得再创建 runner Job。会话续跑只认标准 SessionRef/threadId；无法续接时必须返回明确失败事实，不能拼接历史 prompt 或伪造继续会话。

取消、Steer、retry 和 follow-up 必须绑定明确 conversation/session/turn，不得通过“最新 session”、workspace selected、runner latest 或 trace polling 推断目标。命令输入区的发送、取消和 Steer 状态应来自 TurnSnapshot 与 message projection，而不是来自浏览器本地 pending 状态。

同一 Workbench session 的 follow-up、steer 和 retry 应优先进入已有 AgentRun run 的后续 command 或已声明的 session runner lease。若必须新建 run/runner Job，HWLAB接入必须把原因写入 durable input/command diagnostic，并让 Workbench CLI trace 视图能看到 fresh-run/fresh-runner 与 warm-runner 失效的边界。`workbench-dsflash-go-tool-call-10x` 这类多 turn 验收不能把每 turn fresh runner 当作通过。

### 6.6 AR-HWLAB-REQ-006 自然语言单一路由

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-HWLAB-REQ-006 | 单一路由 | PJ2026-01020506 单一路由 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[后端Profile](PJ2026-010204-backend-profile.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) |

HWLAB接入应把 `/v1/agent/chat` 的自然语言请求统一委托给 AgentRun Code Agent turn。Cloud API 只负责用户鉴权、显式 session、RuntimeAssembly 输入、trace/result 映射和结构化 blocker，不根据关键词把自然语言请求短路到 M3 Skill CLI、HWPOD shortcut、外网检查、普通 OpenAI 文本回复或其他旧路径。

显式 `/v1/m3/io`、HWPOD node-ops、gateway 诊断或管理 API 可以作为独立控制面存在，但不得自动截获聊天自然语言。AgentRun Code Agent 不具备运行条件时，HWLAB接入应返回 AgentRun readiness blocker；不能降级为 source-only、mock、文本解释或历史 fixture。