# PJ2026-010102 HWPOD工具

## 修改历史

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

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

## 正文

## PJ2026-010102 HWPOD工具需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010102 |
| 短名 | 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 标准和服务能力暴露为用户、Agent 和 CaseRun 可调用的原入口，使 spec 校验、inspect、build、download、UART、board-comm、ioProbe 和恢复动作都按同一硬件语义执行。

本课题的目标状态是：工具入口不静默切换目标，不把低层连接或协议错误包装成成功，并能为上层 CaseRun 提供稳定、低噪声、可判定的命令结果。

在 Web CaseRun 场景中，HWPOD 工具语义可以被 Cloud API、AgentRun runner、HWPOD 服务或节点适配器间接调用，但其完成态必须仍然表现为结构化 operation result，而不是只留在本地命令 stdout、Windows 控制台或人工 issue 评论。

### 2.2 范围内

- HWPOD spec 新建、修改、validate、inspect 和资源摘要输出。
- build、download、reset、UART、filesystem、board-comm、ioProbe、CANopen SDO 和频率/电流类硬件动作入口。
- HWPOD runtime API、服务端 authority 和本地 workspace 之间的目标解析。
- 命令返回码、结构化输出、错误分类、read-only 诊断和写操作前置校验。
- Agent workspace、CaseRun 和人工 CLI 对同一 HWPOD 工具语义的复用。
- Web CaseRun 对 HWPOD 工具结果的引用边界，包括 operation result id、日志/证据路径、returnCode、target 摘要和可脱敏 blocker。

### 2.3 范围外

- HWPOD spec 的字段定义和能力模型归 [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)。
- 服务端 registry、租约、路由和资源归属归 [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md)。
- 节点侧适配器执行、板侧 JSON-RPC、CANopen 访问和 ioProbe 采样归 [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)。
- Web/CLI/API 的跨产品展示一致性归 [客户端](PJ2026-0104-client.md)。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| 工具入口 | 用户、Agent 或 CaseRun 调用 HWPOD 能力的 CLI、脚本或 API 包装入口。 |
| 原入口 | 对某项能力最接近真实用户或真实运行路径的验收入口。 |
| 只读诊断 | 不改变硬件状态的 spec、status、api、inventory 或 read 类命令。 |
| 写操作 | download、reset、SDO write、输出刺激、电流/频率设定等会改变设备状态的命令。 |
| 结构化输出 | 可被上层解析的 JSON 或等价结构，包含状态、错误分类、目标身份和必要结果。 |
| CaseRun 工具结果 | 可被 CaseRun artifact manifest 引用的 HWPOD 工具执行摘要，至少包含目标身份、op 类型、结果状态、证据指针和脱敏诊断。 |

## 4. 系统边界和接口

本规格把 HWPOD工具作为硬件池的操作入口层看待；本章只描述输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 硬件研发用户、Agent workspace、CaseRun、客户端、平台管理员。 |
| 外部输入 | `hwpod-id`、spec 路径、workspace、目标操作、操作参数、runtime API 配置、租约上下文和命令超时。 |
| 受控资源 | 工具命令、目标解析、前置校验、调用上下文、结构化输出和错误分类。 |
| 外部输出 | spec 校验结果、inspect 摘要、operation result、board-comm 响应、ioProbe 读数、错误语义和退出状态。 |
| 用户接口 | HWPOD CLI、工具脚本、CaseRun 调用入口、Agent workspace 内命令入口。 |
| 系统边界 | HWPOD工具负责入口语义和调用结果表达；不拥有硬件身份真相、服务端租约真相、节点执行细节或 Harness 评价语义。 |

## 5. 内部分工与规格索引

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-01010201 | Spec工具 | 本规格 6.1 | spec 新建、修改、validate、inspect 和摘要输出 | HWPOD标准 | HWPOD服务、客户端 |
| PJ2026-01010202 | 执行动作 | 本规格 6.2 | build、download、reset、UART、filesystem 和通用硬件动作入口 | HWPOD标准、HWPOD服务 | Agent编排、CaseRun |
| PJ2026-01010203 | 观测工具 | 本规格 6.3 | board-comm、ioProbe、CANopen SDO、频率和电流读写入口 | AI网关、HWPOD服务 | HarnessRL、Agent编排 |
| PJ2026-01010204 | 诊断输出 | 本规格 6.4 | 结构化结果、返回码、错误分类和目标摘要 | HWPOD标准、HWPOD服务、AI网关 | 客户端、CaseRun |

## 6. 原子需求

### 6.1 HWPOD-TOOL-REQ-001 Spec 工具

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-TOOL-REQ-001 | Spec工具 | PJ2026-01010201 Spec工具 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)、[PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) |

HWPOD工具应提供 spec 新建、修改、validate 和 inspect 能力，使硬件资源身份、能力声明和绑定关系能在执行前被用户和自动化任务检查。

Spec 工具必须以 HWPOD 标准为准输出校验结果。服务端 registry 可以提供 authority 摘要，但工具不得用服务端缺省值静默补齐未声明的危险写操作能力。

### 6.2 HWPOD-TOOL-REQ-002 执行动作入口

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-TOOL-REQ-002 | 执行动作 | PJ2026-01010202 执行动作 | [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

HWPOD工具应提供 build、download、reset、UART、filesystem 和通用硬件动作入口，使用户、Agent 和 CaseRun 能通过同一 HWPOD 语义触发真实硬件操作。

执行动作入口必须在写操作前确认目标身份、租约状态和能力声明。缺少 spec、缺少恢复能力或无法确认 probe 绑定时，工具应停止在可理解错误上，而不是继续执行低层命令。

Web CaseRun 所需的 build、download、reset、UART 和 workspace 文件动作应保留 CaseRun 工具结果所需字段，使 HarnessRL 能把工具输出、HWPOD operation result、AgentRun trace 和 aggregate 关联到同一 run。工具入口不得要求 Web、web-probe 或 HarnessRL 解析未结构化 stdout 才能判断关键状态。

### 6.3 HWPOD-TOOL-REQ-003 观测与协议入口

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-TOOL-REQ-003 | 观测工具 | PJ2026-01010203 观测工具 | [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

HWPOD工具应提供 board-comm、ioProbe、CANopen SDO、频率读写和电流读写等观测与协议入口，使 CaseRun 能把板内协议结果和板外物理读数稳定关联。

观测工具必须保留目标身份、单位、方向、采样来源和命令参数。HarnessRL 可以引用这些结果做评价和回放，但不得绕过 HWPOD 工具直接定义硬件观测模型。

### 6.4 HWPOD-TOOL-REQ-004 诊断输出

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWPOD-TOOL-REQ-004 | 诊断输出 | PJ2026-01010204 诊断输出 | [客户端](PJ2026-0104-client.md)、[PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)、[PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md) |

HWPOD工具应输出可判定的结构化结果，使成功、未声明资源、目标不匹配、服务路由失败、节点离线、协议连接失败和板侧处理失败能够被上层区分。

诊断输出不得替代能力实现。工具只能把真实失败分类并暴露给用户、Agent、CaseRun 或客户端；缺失的 spec、路由、节点适配器或板侧处理能力仍必须由对应 L2 修复。

Web CaseRun 的工具诊断必须能进入云端日志和用户可见 blocker。路径不存在、Git/PATH/Keil 不可用、probe mismatch、download verify failure、UART/serial-monitor 不可用、capability mismatch 和节点协议异常都应有稳定错误分类和建议下一步；不能只打印到本地黑框或 GUI 日志后让 Cloud Web 显示通用失败。
