pikastech
11 KiB
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 需求规格模板 |
| 上级规格 | PJ2026-0101 硬件池 |
| 规格治理索引 | 规格治理 |
本文采用 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标准。
- 服务端 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 或等价结构，包含状态、错误分类、目标身份和必要结果。 |
| 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 CRUD、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 摘要，但工具不得用服务端缺省值静默补齐未声明的危险写操作能力。
Spec CRUD 必须在 L0-L3 使用同一 PostgreSQL repository 合同：
- L0 由
hwpod spec list|get|create|update|delete --local直接调用 native function， 并从 owning YAML 的 Secret sourceRef 连接 development host PostgreSQL； - L1 由同一命令加
--over-api调用 owning YAML 固定端口上的 HWPOD API， API 与 L0 连接同一个 development database； - L2 的 development API 与 L0/L1 使用同一个 development database， L3 使用 production owning YAML 声明的 production database；
- database、role、endpoint、Secret sourceRef、连接 key 和 schema/table identity 必须来自 owning YAML，不得由命令行参数、进程目录或代码默认值补齐；
- create 和 update 接收完整 spec document，并在写入前执行与 validate 相同的校验；
- list 默认返回有界摘要，get 返回单个完整 document；
- create、update 和 delete 必须输出 authority、mutable、frozen、hwpodId 和 mutation；
- YAML-first 内置 spec 的 update 和 delete 必须返回
hwpod_spec_frozen，不得复制为 runtime spec、写入覆盖层或修改 owning YAML； - runtime spec 与内置 spec 同名时，create 必须返回
hwpod_spec_frozen，不得形成遮蔽或优先级覆盖。 - filesystem JSON registry、
--runtime-spec-dir和 runtime directory env 属于legacy-retire，不得作为 fallback、双写、迁移后 overlay 或第二 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 绑定时，工具应停止在可理解错误上，而不是继续执行低层命令。
工作区浏览必须复用 workspace.ls、workspace.cat 和已有的有界文件操作语义：
workspace.ls返回相对路径、条目类型、名称和有界元数据，目录按需展开， 不把 Windows 绝对路径或节点文件系统暴露为浏览器路由；workspace.cat只读取 workspace policy 允许范围内的单个文件，返回内容类型、 字节数、文本内容或不可预览原因，并对大文件和二进制文件保持有界；- CLI、Web、Agent 和 CaseRun 必须调用同一 compiler、operation plan 和节点路由， 不得为 Web 增加文件直连、共享目录、SSH reader 或第二套执行器。
Web 触发 build、download、UART 和 workspace 操作时必须提交与 CLI 等价的 HWPOD operation，并通过 operationId 查询 accepted、running 和 terminal result。download、reset、 串口发送等写操作必须在服务端重新校验能力和目标，浏览器本地按钮状态不得作为授权或 安全边界。执行结果必须包含 operation、目标、节点、returnCode、artifact 或串口摘要、 结构化 blocker 和脱敏诊断，不得要求前端解析未结构化 stdout。
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网关、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 修复。
Web CaseRun 的工具诊断必须能进入云端日志和用户可见 blocker。路径不存在、Git/PATH/Keil 不可用、probe mismatch、download verify failure、UART/serial-monitor 不可用、capability mismatch 和节点协议异常都应有稳定错误分类和建议下一步；不能只打印到本地黑框或 GUI 日志后让 Cloud Web 显示通用失败。