# PJ2026-010101 HWPOD标准

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |

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

## 正文

## PJ2026-010101 HWPOD标准需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010101 |
| 短名 | HWPOD标准 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 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 端点、恢复能力和可解释错误语义。

Web CaseRun 使用 HWPOD 时，caseId、hwpodId、nodeId、workspace、probe、能力声明和状态错误必须能被 Cloud Web、API、HWPOD 服务、Python UI node、AgentRun 和 HarnessRL 一致引用。

### 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 中的声明边界。
- Web CaseRun 可用性判断所需的 workspace、Keil build、download、UART、apply-patch、diagnostics 和 node-reported capability 声明边界。

### 2.3 范围外

- HWPOD CLI/API 的命令形态和输出体验归 [PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md)。
- 服务端注册、租约、路由和结果归属归 [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md)。
- 节点侧实际命令执行、JSON-RPC 适配、CANopen 访问和 ioProbe 采样归 [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)。
- CaseRun 评价、aggregate、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。

## 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、重新连接、清理输出或回到安全态的受控能力声明。 |
| node-reported capability | HWPOD node 在心跳或 inventory 中上报的实际能力摘要，用于与 HWPOD spec 声明能力比对。 |

## 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-010103-hwpod-service.md)、[PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md) |

HWPOD标准应为每个可执行真实硬件资源定义稳定身份，使目标设备、workspace、debug probe、io probe 和 HWPOD node 能被同一 `hwpod-id` 一致引用。

资源身份必须禁止静默替代。一个任务请求某个真实设备时，工具、服务和节点不得用另一个设备、另一个 probe 或另一个 workspace 代替成功结果。

Web CaseRun 的资源身份必须至少能稳定关联 caseId、hwpodId、nodeId、workspace authority、目标设备、debug probe、UART binding 和 service authority。Web、web-probe 或 CLI 不得用本地目录名、旧 direct-url、最近连接节点或人工选择文本替代 HWPOD spec 身份。

### 6.2 HWPOD-STD-REQ-002 能力声明

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-STD-REQ-002 | 能力声明 | PJ2026-01010102 能力声明 | [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)、[PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md) |

HWPOD标准应声明每个资源支持的操作能力和恢复能力，使 build、download、reset、UART、board-comm、ioProbe、CANopen SDO、电压、电流和频率等动作在执行前具备明确边界。

未声明能力不得被工具或节点临时猜测。涉及真实频率源、外部电流或板侧写入的操作必须在 spec 中明确端点、单位、方向、读写属性和安全恢复能力。

HWPOD spec 声明能力必须能与 node-reported capability 对齐。CaseRun 所需的 workspace apply-patch、Keil build、download/reset、UART read/write、diagnostics 和日志证据能力若在 spec 或节点任一侧缺失，应形成 capability mismatch，而不是等到 CaseRun 执行阶段以通用失败暴露。

### 6.3 HWPOD-STD-REQ-003 绑定校验

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-STD-REQ-003 | 绑定校验 | PJ2026-01010103 绑定校验 | [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)、[平台运维](PJ2026-0106-platform-ops.md) |

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服务](PJ2026-010103-hwpod-service.md)、[客户端](PJ2026-0104-client.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

HWPOD标准应定义硬件池状态和错误语义，使健康、占用、不可用、未声明能力、路由失败、节点失败、板侧复位和协议失败能被下游一致解释。

状态和错误语义必须服务执行决策。客户端可以展示错误，HarnessRL 可以引用错误分类，Agent编排可以据此暂停或恢复任务，但不能在各自模块重新定义硬件事实。
