pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md

# PJ2026-010205 HWLAB接入

## 修改历史

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

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

## 正文

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

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010205 |
| 短名 | HWLAB接入 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-17-r0; PJ2026-0104010803 唯一投影 draft-2026-06-18-p0-unique-projection |
| 需求规格模板 | [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 执行路径。

### 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 的映射。

### 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 projection writer | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的唯一写入组件，在 HWLAB接入中把 AgentRun result envelope 和 events 写成 Workbench session、message、part、turn 和 trace facts。 |
| 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。 |

## 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 或结构化失败。

### 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 result 和 events 投影为 HWLAB 自己的 Turn、Message、Part 和 TraceEvent 事实。AgentRun 是 execution backend，Web Workbench 的会话事实由 HWLAB 的 session/turn/message/trace model 承担；Web、CLI 和 REST snapshot 只能重放该投影，不能分别从 runnerTrace、terminalEvidence、workspace snapshot 或 result polling 生成多套 final response。

[PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 是 HWLAB接入中 AgentRun -> Workbench facts 的唯一专项规格。dispatcher、adapter、compat wrapper、Workbench GET、result polling 和 trace polling 都不能直接写 session summary、assistant message、turn terminal、trace terminal 或 final response；它们只能把 normalized facts 交给 projection writer/finalizer，或通过 read model 重放 durable projection。AgentRun terminal result 到达时，终态提交、checkpoint、diagnostic 和重启恢复语义以专项 SPEC 为准。

同一次用户提交、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 状态。

### 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。