Codex
7.4 KiB
PJ2026-010102 HWPOD工具
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010102 HWPOD工具需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010102 |
| 短名 | HWPOD工具 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0101 硬件池 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWPOD 工具的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
HWPOD工具负责把 HWPOD 标准和服务能力暴露为用户、Agent 和 CaseRun 可调用的原入口，使 spec 校验、inspect、build、download、UART、board-comm、ioProbe 和恢复动作都按同一硬件语义执行。
本课题的目标状态是：工具入口不静默切换目标，不把低层连接或协议错误包装成成功，并能为上层 CaseRun 提供稳定、低噪声、可判定的命令结果。
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 工具语义的复用。
2.3 范围外
- HWPOD spec 的字段定义和能力模型归 PJ2026-010101 HWPOD标准。
- 服务端 registry、租约、路由和资源归属归 PJ2026-010103 HWPOD服务。
- 节点侧适配器执行、板侧 JSON-RPC、CANopen 访问和 ioProbe 采样归 PJ2026-010104 AI网关。
- Web/CLI/API 的跨产品展示一致性归 客户端。
3. 术语表
| 术语 | 定义 |
|---|---|
| 工具入口 | 用户、Agent 或 CaseRun 调用 HWPOD 能力的 CLI、脚本或 API 包装入口。 |
| 原入口 | 对某项能力最接近真实用户或真实运行路径的验收入口。 |
| 只读诊断 | 不改变硬件状态的 spec、status、api、inventory 或 read 类命令。 |
| 写操作 | download、reset、SDO write、输出刺激、电流/频率设定等会改变设备状态的命令。 |
| 结构化输出 | 可被上层解析的 JSON 或等价结构，包含状态、错误分类、目标身份和必要结果。 |
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-010103 HWPOD服务 |
HWPOD工具应提供 spec 新建、修改、validate 和 inspect 能力，使硬件资源身份、能力声明和绑定关系能在执行前被用户和自动化任务检查。
Spec 工具必须以 HWPOD 标准为准输出校验结果。服务端 registry 可以提供 authority 摘要，但工具不得用服务端缺省值静默补齐未声明的危险写操作能力。
6.2 HWPOD-TOOL-REQ-002 执行动作入口
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-TOOL-REQ-002 | 执行动作 | PJ2026-01010202 执行动作 | PJ2026-010103 HWPOD服务、Agent编排 |
HWPOD工具应提供 build、download、reset、UART、filesystem 和通用硬件动作入口，使用户、Agent 和 CaseRun 能通过同一 HWPOD 语义触发真实硬件操作。
执行动作入口必须在写操作前确认目标身份、租约状态和能力声明。缺少 spec、缺少恢复能力或无法确认 probe 绑定时，工具应停止在可理解错误上，而不是继续执行低层命令。
6.3 HWPOD-TOOL-REQ-003 观测与协议入口
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-TOOL-REQ-003 | 观测工具 | PJ2026-01010203 观测工具 | PJ2026-010104 AI网关、HarnessRL |
HWPOD工具应提供 board-comm、ioProbe、CANopen SDO、频率读写和电流读写等观测与协议入口，使 CaseRun 能把板内协议结果和板外物理读数稳定关联。
观测工具必须保留目标身份、单位、方向、采样来源和命令参数。HarnessRL 可以引用这些结果做评价和回放，但不得绕过 HWPOD 工具直接定义硬件观测模型。
6.4 HWPOD-TOOL-REQ-004 诊断输出
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| HWPOD-TOOL-REQ-004 | 诊断输出 | PJ2026-01010204 诊断输出 | 客户端、PJ2026-010101 HWPOD标准、PJ2026-010104 AI网关 |
HWPOD工具应输出可判定的结构化结果，使成功、未声明资源、目标不匹配、服务路由失败、节点离线、协议连接失败和板侧处理失败能够被上层区分。
诊断输出不得替代能力实现。工具只能把真实失败分类并暴露给用户、Agent、CaseRun 或客户端；缺失的 spec、路由、节点适配器或板侧处理能力仍必须由对应 L2 修复。