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-19-p1-agentrun-incremental-cursor; draft-2026-06-25-p0-session-warm-runner-contract
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0102 Agent编排
规格治理索引	规格治理

本文采用 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、租约、健康和硬件事实归 硬件池。
• CaseRun 评价、pass/fail、回放和训练反馈归 HarnessRL。
• HWLAB 用户鉴权、组织、API key、额度和账本归 用户管理。
• Web/CLI 展示、管理页和用户交互归 客户端。
• 自动 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唯一投影 定义的唯一写入组件，在 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。
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核心、AgentRun发布Lane

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装配、用户管理、客户端

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核心、后端Profile、HarnessRL

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唯一投影 是 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 为准。

HWLAB 接入消费 AgentRun events 时必须按 Workbench 唯一投影的 durable cursor 执行增量拉取。运行中进度以 events?afterSeq=<lastSourceSeq> 和 command/window 过滤后的 normalized facts 为主读源；AgentRun /result 只用于终态补全或后台归档，不得作为 running turn 的主读源，也不得因为 /result 慢或超时阻断 events projection、Workbench trace 进度或 projection state 推进。

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。

同一次用户提交、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 硬件上下文	硬件池、Runtime装配

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 取消续跑	队列会话、Runtime装配、AgentRun核心

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契约、后端Profile、Runtime装配

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。