Lyon
9.6 KiB
PJ2026-010103 HWPOD服务
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010103 HWPOD服务需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010103 |
| 短名 | HWPOD服务 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0101 硬件池 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWPOD 服务的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
HWPOD服务负责服务端资源注册、健康、租约、占用释放、权限交接、请求接收、节点路由和结果归属，使 HWPOD 工具和上层任务能通过服务端 authority 访问真实硬件资源。
本课题的目标状态是：服务端只路由已声明、可用、已授权且租约一致的资源，并把每次操作结果归属到明确 HWPOD、node、租约和调用方。
在 Web CaseRun 场景中，HWPOD服务是 Cloud API、HarnessRL、AgentRun 和用户 PC 侧 HWPOD node 之间唯一的硬件资源 authority。Cloud Web、web-probe、CLI 和 Agent 都不得直接连接本地 gateway 或旧运行面来判定硬件成功。
2.2 范围内
- HWPOD registry、资源注册、spec 摘要、authority 和版本来源。
- HWPOD node 心跳接入、健康状态、可用性、能力摘要和路由状态。
- 租约、占用、释放、冲突处理、超时释放和写操作保护。
- 工具/API 请求接收、目标解析、节点路由、超时和错误分类。
- operation result 的归属、查询、摘要和对 HarnessRL/Agent编排/客户端的交接。
- Web CaseRun 对 HWPOD readiness、租约、路由、operation result、capability mismatch 和结构化 blocker 的消费边界。
2.3 范围外
- HWPOD spec 字段和能力模型归 PJ2026-010101 HWPOD标准。
- CLI 命令形态、工具输出和 workspace 内调用归 PJ2026-010102 HWPOD工具。
- 节点侧适配器执行和原始硬件事实生产归 PJ2026-010104 AI网关。
- 用户身份、API key、额度和租户策略归 用户管理。
3. 术语表
| 术语 | 定义 |
|---|---|
| registry | 服务端维护的 HWPOD 资源目录，包含身份、spec 摘要、状态和路由信息。 |
| authority | 对 HWPOD 资源事实具有当前解释权的服务端或配置来源。 |
| 租约 | 一次资源占用关系，约束调用方、HWPOD、操作类型、超时和释放。 |
| 路由 | 服务端把 HWPOD 操作请求转发到正确 HWPOD node 或 AI 网关的过程。 |
| operation result | 服务端接收并归属的一次硬件操作结果。 |
| CaseRun 调用方 | HarnessRL 为一次 CaseRun 持有的硬件操作调用上下文，至少携带 runId、caseId、actor、HWPOD 和租约摘要。 |
4. 系统边界和接口
本规格把 HWPOD服务作为硬件池的服务端资源管理层看待；本章只描述输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | HWPOD工具、Agent编排、HarnessRL、客户端、用户管理、平台管理员。 |
| 外部输入 | HWPOD spec、node 心跳、能力上报、租约请求、操作请求、用户/任务上下文、释放请求和节点结果。 |
| 受控资源 | registry、资源状态、租约、路由表、操作请求、operation result 和错误分类。 |
| 外部输出 | 资源列表、健康状态、租约状态、路由结果、操作结果、错误语义和结果查询摘要。 |
| 用户接口 | HWLAB runtime API、HWPOD 服务端接口、工具调用接口和 CaseRun/Agent 消费接口。 |
| 系统边界 | HWPOD服务负责服务端硬件资源真相和路由归属；不定义 spec 字段、命令行体验、节点适配器内部实现或 Harness 评价。 |
5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-01010301 | 资源注册 | 本规格 6.1 | registry、spec 摘要、authority 和资源状态 | HWPOD标准、平台配置 | 工具、客户端、Agent编排 |
| PJ2026-01010302 | 租约占用 | 本规格 6.2 | 租约、占用、释放、冲突处理和写操作保护 | 用户管理、资源注册 | Agent编排、CaseRun |
| PJ2026-01010303 | 节点路由 | 本规格 6.3 | 请求接收、目标解析、node 路由、超时和错误分类 | AI网关、租约占用 | HWPOD工具、HarnessRL |
| PJ2026-01010304 | 结果归属 | 本规格 6.4 | operation result 归属、查询和摘要交接 | 节点路由、Agent上下文 | HarnessRL、客户端、用户管理 |
| PJ2026-01010305 | 71FREQ预装 | PJ2026-01010305 71FREQ预装 | D601/v03 71-FREQ preinstalled HWPOD spec、运行发现、MDTODO source 和验收切片 | HWPOD标准、YAML运维、AI网关 | HWPOD工具、HarnessRL、客户端 |
6. 原子需求
6.1 HWPOD-SVC-REQ-001 资源注册
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-SVC-REQ-001 | 资源注册 | PJ2026-01010301 资源注册 | PJ2026-010101 HWPOD标准、客户端 |
HWPOD服务应维护 HWPOD registry，使已声明资源、spec 摘要、authority、状态、能力和路由信息能够被工具、客户端和上层任务查询。
Registry 必须以 HWPOD 标准解释资源事实。缺失 HWPOD spec 的真实设备不能被服务端当作可写资源暴露；客户端可以展示不可用或待配置状态，但不能把临时端点当作资源真相。
6.2 HWPOD-SVC-REQ-002 租约与占用
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-SVC-REQ-002 | 租约占用 | PJ2026-01010302 租约占用 | 用户管理、Agent编排 |
HWPOD服务应提供租约、占用、释放、冲突处理和超时恢复能力，使真实硬件写操作不会被多个任务并发破坏。
租约只定义硬件资源占用事实。用户管理提供调用主体和权限约束，Agent编排提供任务上下文，HWPOD服务负责把这些约束落实到资源可用性和写操作保护。
CaseRun 触发的 build、download、reset、UART 或 workspace 写操作必须绑定明确 runId、caseId、hwpodId、nodeId、actor 和租约。相同 HWPOD 在已有写租约期间不得被另一条 Web CaseRun、CLI 诊断或旧 runner 静默复用；冲突必须作为可查询 blocker 返回给 HarnessRL 和客户端。
6.3 HWPOD-SVC-REQ-003 节点路由
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-SVC-REQ-003 | 节点路由 | PJ2026-01010303 节点路由 | PJ2026-010104 AI网关、PJ2026-010102 HWPOD工具 |
HWPOD服务应把已授权且租约一致的操作请求路由到正确 HWPOD node，并把目标不存在、node 离线、路由超时、协议连接失败和节点返回失败区分输出。
节点路由必须禁止错误 HWPOD 复用。工具请求某个 hwpod-id 时，服务端只能使用该资源声明绑定的 node 和能力；无法找到声明或路由时必须返回明确失败。
HWPOD 服务端只作为云端请求接收、租约校验、目标解析和网关路由 authority；Cloud Web、Agent 和 CLI 不应直接连接用户 PC 上的 gateway。网关主动出站后，服务端仍必须把命令领取、in-flight、超时、gateway_busy 和节点返回失败归一为可查询的 operation 状态，避免调用方把 HTTP dispatch timeout 误判为硬件动作结果。
Web CaseRun 的所有硬件动作都必须通过 HWPOD 服务节点路由。服务端应在 route 摘要中暴露目标 hwpodId、nodeId、声明 capability、node 上报 capability、route authority、request id 和必要 trace 关联，使 HarnessRL 能区分 workspace missing、node offline、capability mismatch、probe mismatch、gateway busy、adapter failure 和硬件动作失败。
6.4 HWPOD-SVC-REQ-004 结果归属
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-SVC-REQ-004 | 结果归属 | PJ2026-01010304 结果归属 | HarnessRL、客户端、用户管理 |
HWPOD服务应把每次 operation result 归属到明确的 HWPOD、node、租约、调用方、操作类型和时间上下文，使 HarnessRL、客户端和账务统计能消费同一结果事实。
结果归属不是长证据归档。服务端只负责保存和交接必要操作结果、摘要和查询指针；CaseRun 评价、回放、训练反馈和用户展示由对应模块在此事实上继续处理。
Web CaseRun 消费的 operation result 至少应能被 HarnessRL 引用到同一 run stage，并携带 op 类型、target path 或 probe 摘要、returnCode 或失败分类、日志/证据指针、valuesRedacted、requestId/trace 关联和 node-reported capability 摘要。HWPOD服务不生成 CaseRun aggregate，但必须提供足够稳定的 operation result 引用，使 aggregate、artifact manifest、Web run 卡和 web-probe report 指向同一硬件事实。