Codex
7.7 KiB
PJ2026-010101 HWPOD标准
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010101 HWPOD标准需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010101 |
| 短名 | HWPOD标准 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0101 硬件池 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWPOD 标准的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
HWPOD标准负责定义真实硬件资源的身份、四要素、能力声明、状态语义和错误语义，使 HWPOD 工具、服务、AI 网关、Agent 和 HarnessRL 能围绕同一硬件事实执行。
本课题的目标状态是：任何可被 CaseRun 或 Agent 写入的真实设备，都必须先拥有明确 HWPOD spec、workspace authority、debug probe 绑定、io probe 绑定、board-comm 端点、恢复能力和可解释错误语义。
2.2 范围内
- HWPOD 身份、
hwpod-id、目标设备、workspace、debug probe、io probe 和 HWPOD node 的关系。 - 设备能力、操作能力、适配器能力、板侧通信端点、采样能力和恢复能力声明。
- spec authority、版本来源、资源绑定校验和禁止错误设备替代的规则。
- 状态、健康、不可用、占用、probe mismatch、通信失败和未声明能力等错误语义。
- 真实频率源、外部电流、CANopen SDO、board-comm JSON-RPC、下载和 reset 等能力在 HWPOD spec 中的声明边界。
2.3 范围外
- HWPOD CLI/API 的命令形态和输出体验归 PJ2026-010102 HWPOD工具。
- 服务端注册、租约、路由和结果归属归 PJ2026-010103 HWPOD服务。
- 节点侧实际命令执行、JSON-RPC 适配、CANopen 访问和 ioProbe 采样归 PJ2026-010104 AI网关。
- CaseRun 评价、aggregate、回放和训练反馈归 HarnessRL。
3. 术语表
| 术语 | 定义 |
|---|---|
| HWPOD spec | 声明硬件资源身份、绑定关系、能力、状态和操作边界的规格文件或服务端等价声明。 |
| 四要素 | 目标设备、workspace、debug probe 和 io probe 四类 HWPOD 基础资源。 |
| 能力声明 | HWPOD spec 中对 build、download、reset、UART、board-comm、ioProbe、CANopen SDO、电压、电流或频率等能力的声明。 |
| 绑定校验 | 对设备、workspace、probe、node 和通信端点之间关系的一致性校验。 |
| 恢复能力 | HWPOD 对 reset、重新连接、清理输出或回到安全态的受控能力声明。 |
4. 系统边界和接口
本规格把 HWPOD标准作为硬件池的资源语义层看待；本章只描述输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | HWPOD工具、HWPOD服务、AI网关、Agent编排、HarnessRL、客户端和平台管理员。 |
| 外部输入 | 设备清单、workspace 路径、probe UID、io probe 配置、node 标识、通信端点、操作能力、恢复能力和硬件健康事实。 |
| 受控资源 | HWPOD spec、资源身份、能力声明、绑定关系、状态语义、错误语义和验收基线。 |
| 外部输出 | 可引用 HWPOD 身份、能力模型、绑定校验结果、错误分类、状态摘要和下游操作约束。 |
| 用户接口 | HWPOD spec 文件、spec validate/inspect 语义、服务端 registry 中的 spec 摘要。 |
| 系统边界 | HWPOD标准负责定义硬件事实如何被声明和解释；不负责执行命令、管理租约、展示客户端体验或评价 CaseRun 结果。 |
5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-01010101 | 资源身份 | 本规格 6.1 | hwpod-id、目标设备、workspace、probe 和 node 的身份关系 |
L1 硬件池 | HWPOD工具、HWPOD服务、AI网关 |
| PJ2026-01010102 | 能力声明 | 本规格 6.2 | 操作能力、适配器能力、采样能力和恢复能力声明 | 资源身份、设备事实 | 工具入口、服务路由、节点执行 |
| PJ2026-01010103 | 绑定校验 | 本规格 6.3 | workspace、probe、io probe、node 和通信端点的一致性校验 | 能力声明、平台配置 | 安全执行、错误分类 |
| PJ2026-01010104 | 状态错误 | 本规格 6.4 | 健康、占用、不可用、未声明能力和通信失败语义 | 绑定校验、节点事实 | 客户端、HarnessRL、Agent编排 |
6. 原子需求
6.1 HWPOD-STD-REQ-001 资源身份
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-STD-REQ-001 | 资源身份 | PJ2026-01010101 资源身份 | PJ2026-010103 HWPOD服务、PJ2026-010102 HWPOD工具 |
HWPOD标准应为每个可执行真实硬件资源定义稳定身份，使目标设备、workspace、debug probe、io probe 和 HWPOD node 能被同一 hwpod-id 一致引用。
资源身份必须禁止静默替代。一个任务请求某个真实设备时，工具、服务和节点不得用另一个设备、另一个 probe 或另一个 workspace 代替成功结果。
6.2 HWPOD-STD-REQ-002 能力声明
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-STD-REQ-002 | 能力声明 | PJ2026-01010102 能力声明 | PJ2026-010104 AI网关、PJ2026-010102 HWPOD工具 |
HWPOD标准应声明每个资源支持的操作能力和恢复能力，使 build、download、reset、UART、board-comm、ioProbe、CANopen SDO、电压、电流和频率等动作在执行前具备明确边界。
未声明能力不得被工具或节点临时猜测。涉及真实频率源、外部电流或板侧写入的操作必须在 spec 中明确端点、单位、方向、读写属性和安全恢复能力。
6.3 HWPOD-STD-REQ-003 绑定校验
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-STD-REQ-003 | 绑定校验 | PJ2026-01010103 绑定校验 | PJ2026-010104 AI网关、平台运维 |
HWPOD标准应定义绑定校验规则，使 workspace、debug probe UID、io probe 标识、HWPOD node 和板侧通信端点在写操作前能够被一致检查。
绑定校验必须把缺失 spec、probe mismatch、node 不匹配、通信端点不可用和恢复入口缺失区分为不同错误。无法确认目标设备身份时，系统必须停在只读诊断或人工恢复边界，不能继续写入硬件。
6.4 HWPOD-STD-REQ-004 状态与错误语义
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-STD-REQ-004 | 状态错误 | PJ2026-01010104 状态错误 | PJ2026-010103 HWPOD服务、客户端、HarnessRL |
HWPOD标准应定义硬件池状态和错误语义，使健康、占用、不可用、未声明能力、路由失败、节点失败、板侧复位和协议失败能被下游一致解释。
状态和错误语义必须服务执行决策。客户端可以展示错误，HarnessRL 可以引用错误分类，Agent编排可以据此暂停或恢复任务，但不能在各自模块重新定义硬件事实。