pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-0101-hardware-pool.md

PJ2026-0101 硬件池

修改历史

版本	对应 commit id	更新日期	变更说明
v0.3	b5d8cee438	2026-06-14	将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。
v0.2	b0cbe9b721	2026-06-14	将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。
v0.1	37de91c653	2026-06-14	从迁移来源 pikasTech/HWLAB#1203 迁移到 UniDesk 项目管理目录。

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

正文

PJ2026-0101 硬件池需求规格

1. 文档控制

字段	内容
编号	PJ2026-0101
短名	硬件池
层级	L1 方向
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-01 HWLAB 总规格
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留硬件池的稳定使命、范围、术语、系统边界、内部分工和原子需求。

2. 目的和范围

2.1 目的

硬件池负责把真实板卡、debug probe、io probe、HWPOD node 和设备健康状态组织成可引用、可占用、可释放、可审计的硬件资源池。它是 HWLAB 的物理事实源，必须让上层 Agent、Harness 和客户端拿到真实硬件事实，而不是临时脚本输出或不可复验的运行副本。

2.2 范围内

• HWPOD 资源身份、四要素模型、能力声明、状态和错误语义。
• hwpod-id、HWPOD spec、资源 registry、authority 和版本来源。
• HWPOD 工具入口，包括 spec validate、inspect、build、download、UART、board-comm 和 ioProbe 操作。
• HWPOD 服务端注册、健康、inventory、租约、占用释放、冲突处理、路由和结果归属。
• HWPOD node / AI 网关的心跳、能力上报、受控命令执行、probe 校验和原始硬件事实回传。

2.3 范围外

• Agent run、command、session、provider profile 和 workspace 生命周期归 Agent编排。
• CaseRun 评价、pass/fail、回放和训练反馈归 HarnessRL。
• Web、CLI 和 HTTP API 的通用用户入口体验归 客户端。
• 用户身份、API key、额度、账本和租户策略归 用户管理。
• CI/CD、Git mirror、YAML-first 运维、发布、公开入口和 Prometheus 运维监控归 平台运维。

3. 术语表

术语	定义
HWPOD	由目标设备、workspace、debug probe 和 io probe 组成的硬件研发执行上下文。
HWPOD spec	描述 HWPOD 身份、硬件能力、node 绑定、probe 约束和操作能力的规格声明。
HWPOD node	靠近真实硬件的执行节点，负责按受控协议执行硬件操作并回传结构化结果。
debug probe	用于下载、调试或访问目标设备的调试探针。
io probe	用于采集板外输入输出、电压、电流、频率或其他外部物理状态的观测探针。
租约	对真实硬件资源的一次占用关系，用于避免多任务冲突并支持超时释放。

4. 系统边界和接口

本规格把硬件池作为 HWLAB 内部的硬件资源子系统看待；本章只描述该子系统的输入、输出和责任边界。

边界项	内容
外部使用者	Agent编排、HarnessRL、客户端、平台管理员和需要真实硬件的训练任务。
外部输入	HWPOD spec、hwpod-id、workspace、目标设备选择、probe 约束、HWPOD node 状态、硬件操作请求和租约上下文。
受控资源	真实板卡、debug probe、io probe、HWPOD node、资源 registry、租约和硬件操作记录。
外部输出	资源身份、能力声明、可用性、健康状态、占用释放状态、operation result、原始硬件事实和硬件错误语义。
用户接口	HWPOD 工具、HWLAB runtime API、HWPOD 服务端接口、HWPOD node / AI 网关协议。
系统边界	硬件池负责硬件事实和资源占用正确性；不定义 Agent 执行策略、Harness 评分、用户账本、客户端展示或平台发布流程。

5. 内部分工与规格索引

编号	模块或课题	规格文档	主责边界	上游依赖	下游支撑
PJ2026-010101	HWPOD标准	PJ2026-010101 HWPOD标准	HWPOD 身份、四要素、能力声明、状态和错误语义	L0 总规格、阶段 HWPOD 口径	HWPOD工具、HWPOD服务、AI网关、客户端
PJ2026-010102	HWPOD工具	PJ2026-010102 HWPOD工具	用户和 Agent workspace 内的硬件池操作入口	HWPOD标准、平台运行入口	Agent编排、HarnessRL、客户端
PJ2026-010103	HWPOD服务	PJ2026-010103 HWPOD服务	服务端资源注册、健康、租约、占用释放和路由	HWPOD标准、用户权限、平台运行面	Agent编排、HarnessRL、客户端
PJ2026-010104	AI网关	PJ2026-010104 AI网关	HWPOD node / 网关侧真实硬件动作执行和原始事实回传	HWPOD标准、平台连接能力	HWPOD服务、HarnessRL、Agent编排

6. 原子需求

6.1 HWPOD-L1-REQ-001 HWPOD 标准与资源身份

编号	短名	主责模块	关联模块
HWPOD-L1-REQ-001	HWPOD 标准	PJ2026-010101 HWPOD标准	客户端、Agent编排、HarnessRL

硬件池应定义并维护 HWPOD 标准，使每个真实硬件资源都有稳定的身份、四要素组成、能力声明、状态语义和错误语义。

该标准必须让设备、workspace、debug probe、io probe 和 HWPOD node 的关系可以被服务端、工具和上层任务一致解释。客户端可以展示这些事实，Agent编排和 HarnessRL 可以消费这些事实，但不得在各自模块重新发明硬件身份或能力模型。

6.2 HWPOD-L1-REQ-002 HWPOD 工具入口

编号	短名	主责模块	关联模块
HWPOD-L1-REQ-002	HWPOD 工具	PJ2026-010102 HWPOD工具	客户端、Agent编排

硬件池应提供 HWPOD 工具入口，使用户、Agent 或 CaseRun 能按同一 HWPOD 语义执行 spec validate、inspect、build、download、UART、board-comm 和 ioProbe 操作。

工具入口必须以 HWLAB runtime API 和 HWPOD authority 为准解析资源，不能依赖遗留环境变量或一次性脚本静默改写目标。客户端负责命令呈现和多端一致性，硬件池负责命令背后的硬件语义和资源事实。

6.3 HWPOD-L1-REQ-003 HWPOD 服务与租约

编号	短名	主责模块	关联模块
HWPOD-L1-REQ-003	HWPOD 服务	PJ2026-010103 HWPOD服务	用户管理、Agent编排、平台运维

硬件池应提供服务端资源管理能力，使真实设备能被注册、发现、查询健康、占用、释放、冲突处理并路由到正确的 HWPOD node。

服务端必须把租约、权限约束和资源状态统一到同一硬件池事实中。用户管理提供身份和额度约束，Agent编排消费分配结果，平台运维提供运行支撑；这些关联模块不接管硬件资源真相。

6.4 HWPOD-L1-REQ-004 HWPOD node 与 AI 网关

编号	短名	主责模块	关联模块
HWPOD-L1-REQ-004	HWPOD node	PJ2026-010104 AI网关	HarnessRL、平台运维、Agent编排

硬件池应通过 HWPOD node 或 AI 网关触达真实硬件，使下载、调试、UART、board-comm、ioProbe 和其他硬件动作在靠近设备的执行节点上受控执行。

HWPOD node 必须上报心跳、能力和健康状态，并在执行动作时返回结构化原始硬件事实。涉及 probe 绑定、外部 ioProbe 读数和板内 echo 的场景必须能区分物理事实来源，避免把错误设备、错误探针或不可复验输出当作成功硬件结果。