Codex
7.6 KiB
PJ2026-010103 HWPOD服务
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010103 HWPOD服务需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010103 |
| 短名 | HWPOD服务 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0101 硬件池 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWPOD 服务的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
HWPOD服务负责服务端资源注册、健康、租约、占用释放、权限交接、请求接收、节点路由和结果归属，使 HWPOD 工具和上层任务能通过服务端 authority 访问真实硬件资源。
本课题的目标状态是：服务端只路由已声明、可用、已授权且租约一致的资源，并把每次操作结果归属到明确 HWPOD、node、租约和调用方。
2.2 范围内
- HWPOD registry、资源注册、spec 摘要、authority 和版本来源。
- HWPOD node 心跳接入、健康状态、可用性、能力摘要和路由状态。
- 租约、占用、释放、冲突处理、超时释放和写操作保护。
- 工具/API 请求接收、目标解析、节点路由、超时和错误分类。
- operation result 的归属、查询、摘要和对 HarnessRL/Agent编排/客户端的交接。
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 | 服务端接收并归属的一次硬件操作结果。 |
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、客户端、用户管理 |
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服务负责把这些约束落实到资源可用性和写操作保护。
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 误判为硬件动作结果。
6.4 HWPOD-SVC-REQ-004 结果归属
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-SVC-REQ-004 | 结果归属 | PJ2026-01010304 结果归属 | HarnessRL、客户端、用户管理 |
HWPOD服务应把每次 operation result 归属到明确的 HWPOD、node、租约、调用方、操作类型和时间上下文，使 HarnessRL、客户端和账务统计能消费同一结果事实。
结果归属不是长证据归档。服务端只负责保存和交接必要操作结果、摘要和查询指针；CaseRun 评价、回放、训练反馈和用户展示由对应模块在此事实上继续处理。