docs: 补充硬件池 L2 规格

2026-06-14 20:34:43 +00:00
parent f8521d2e25
commit 21a2ee72a8
6 changed files with 503 additions and 10 deletions
@@ -78,10 +78,10 @@

 | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
 | --- | --- | --- | --- | --- | --- |
-| PJ2026-010101 | HWPOD标准 | 本规格 6.1 | HWPOD 身份、四要素、能力声明、状态和错误语义 | L0 总规格、阶段 HWPOD 口径 | HWPOD工具、HWPOD服务、AI网关、客户端 |
-| PJ2026-010102 | HWPOD工具 | 本规格 6.2 | 用户和 Agent workspace 内的硬件池操作入口 | HWPOD标准、平台运行入口 | Agent编排、HarnessRL、客户端 |
-| PJ2026-010103 | HWPOD服务 | 本规格 6.3 | 服务端资源注册、健康、租约、占用释放和路由 | HWPOD标准、用户权限、平台运行面 | Agent编排、HarnessRL、客户端 |
-| PJ2026-010104 | AI网关 | 本规格 6.4 | HWPOD node / 网关侧真实硬件动作执行和原始事实回传 | HWPOD标准、平台连接能力 | HWPOD服务、HarnessRL、Agent编排 |
+| PJ2026-010101 | HWPOD标准 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md) | HWPOD 身份、四要素、能力声明、状态和错误语义 | L0 总规格、阶段 HWPOD 口径 | HWPOD工具、HWPOD服务、AI网关、客户端 |
+| PJ2026-010102 | HWPOD工具 | [PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md) | 用户和 Agent workspace 内的硬件池操作入口 | HWPOD标准、平台运行入口 | Agent编排、HarnessRL、客户端 |
+| PJ2026-010103 | HWPOD服务 | [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) | 服务端资源注册、健康、租约、占用释放和路由 | HWPOD标准、用户权限、平台运行面 | Agent编排、HarnessRL、客户端 |
+| PJ2026-010104 | AI网关 | [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md) | HWPOD node / 网关侧真实硬件动作执行和原始事实回传 | HWPOD标准、平台连接能力 | HWPOD服务、HarnessRL、Agent编排 |

 ## 6. 原子需求

@@ -89,7 +89,7 @@

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| HWPOD-L1-REQ-001 | HWPOD 标准 | PJ2026-010101 HWPOD标准 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
+| HWPOD-L1-REQ-001 | HWPOD 标准 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

 硬件池应定义并维护 HWPOD 标准，使每个真实硬件资源都有稳定的身份、四要素组成、能力声明、状态语义和错误语义。

@@ -99,7 +99,7 @@

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| HWPOD-L1-REQ-002 | HWPOD 工具 | PJ2026-010102 HWPOD工具 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
+| HWPOD-L1-REQ-002 | HWPOD 工具 | [PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

 硬件池应提供 HWPOD 工具入口，使用户、Agent 或 CaseRun 能按同一 HWPOD 语义执行 spec validate、inspect、build、download、UART、board-comm 和 ioProbe 操作。

@@ -109,7 +109,7 @@

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| HWPOD-L1-REQ-003 | HWPOD 服务 | PJ2026-010103 HWPOD服务 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+| HWPOD-L1-REQ-003 | HWPOD 服务 | [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |

 硬件池应提供服务端资源管理能力，使真实设备能被注册、发现、查询健康、占用、释放、冲突处理并路由到正确的 HWPOD node。

@@ -119,7 +119,7 @@

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| HWPOD-L1-REQ-004 | HWPOD node | PJ2026-010104 AI网关 | [HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
+| HWPOD-L1-REQ-004 | HWPOD node | [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md) | [HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

 硬件池应通过 HWPOD node 或 AI 网关触达真实硬件，使下载、调试、UART、board-comm、ioProbe 和其他硬件动作在靠近设备的执行节点上受控执行。

@@ -0,0 +1,123 @@
+# PJ2026-010101 HWPOD标准
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010101 HWPOD标准需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010101 |
+| 短名 | HWPOD标准 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [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 能围绕同一硬件事实执行。
+
+当前实现已经能表达部分 HWPOD 资源、工具入口和 ioProbe 观测，但仍存在未声明资源、probe 绑定不完整和恢复能力不明确时无法安全执行写操作的情况。本课题的预期状态是：任何可被 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-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、重新连接、清理输出或回到安全态的受控能力声明。 |
+
+## 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 代替成功结果。
+
+### 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 中明确端点、单位、方向、读写属性和安全恢复能力。
+
+### 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编排可以据此暂停或恢复任务，但不能在各自模块重新定义硬件事实。
@@ -0,0 +1,123 @@
+# PJ2026-010102 HWPOD工具
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010102 HWPOD工具需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010102 |
+| 短名 | HWPOD工具 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [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 和恢复动作都按同一硬件语义执行。
+
+当前实现已经具备部分 CLI/API 入口和 board-comm/ioProbe 调用链，但仍需要把缺失 spec、错误 probe、服务路由失败、节点协议失败和板侧 JSON-RPC 异常清楚分开。本课题的预期状态是：工具入口不静默切换目标，不把低层连接错误包装成成功，并能为上层 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标准](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 或等价结构，包含状态、错误分类、目标身份和必要结果。 |
+
+## 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 绑定时，工具应停止在可理解错误上，而不是继续执行低层命令。
+
+### 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 修复。
@@ -0,0 +1,123 @@
+# PJ2026-010103 HWPOD服务
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010103 HWPOD服务需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010103 |
+| 短名 | HWPOD服务 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [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 工具和上层任务能通过服务端 authority 访问真实硬件资源。
+
+当前实现已经具备部分 HWPOD runtime API、registry 查询和节点转发路径，但仍需要把缺失资源声明、错误 HWPOD 复用、节点路由失败和板侧协议失败清晰暴露。本课题的预期状态是：服务端只路由已声明、可用、已授权且租约一致的资源，并把每次操作结果归属到明确 HWPOD、node、租约和调用方。
+
+### 2.2 范围内
+
+- HWPOD registry、资源注册、spec 摘要、authority 和版本来源。
+- HWPOD node 心跳接入、健康状态、可用性、能力摘要和路由状态。
+- 租约、占用、释放、冲突处理、超时释放和写操作保护。
+- 工具/API 请求接收、目标解析、节点路由、超时和错误分类。
+- operation result 的归属、查询、摘要和对 HarnessRL/Agent编排/客户端的交接。
+
+### 2.3 范围外
+
+- HWPOD spec 字段和能力模型归 [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)。
+- CLI 命令形态、工具输出和 workspace 内调用归 [PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md)。
+- 节点侧适配器执行和原始硬件事实生产归 [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)。
+- 用户身份、API key、额度和租户策略归 [用户管理](PJ2026-0105-user-management.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| registry | 服务端维护的 HWPOD 资源目录，包含身份、spec 摘要、状态和路由信息。 |
+| authority | 对 HWPOD 资源事实具有当前解释权的服务端或配置来源。 |
+| 租约 | 一次资源占用关系，约束调用方、HWPOD、操作类型、超时和释放。 |
+| 路由 | 服务端把 HWPOD 操作请求转发到正确 HWPOD node 或 AI 网关的过程。 |
+| operation result | 服务端接收并归属的一次硬件操作结果。 |
+
+## 4. 系统边界和接口
+
+本规格把 HWPOD服务作为硬件池的服务端资源管理层看待；本章只描述输入、输出和责任边界。
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | HWPOD工具、Agent编排、HarnessRL、客户端、用户管理、平台管理员。 |
+| 外部输入 | HWPOD spec、node 心跳、能力上报、租约请求、操作请求、用户/任务上下文、释放请求和节点结果。 |
+| 受控资源 | registry、资源状态、租约、路由表、操作请求、operation result 和错误分类。 |
+| 外部输出 | 资源列表、健康状态、租约状态、路由结果、操作结果、错误语义和结果查询摘要。 |
+| 用户接口 | HWLAB runtime API、HWPOD 服务端接口、工具调用接口和 CaseRun/Agent 消费接口。 |
+| 系统边界 | HWPOD服务负责服务端硬件资源真相和路由归属；不定义 spec 字段、命令行体验、节点适配器内部实现或 Harness 评价。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01010301 | 资源注册 | 本规格 6.1 | registry、spec 摘要、authority 和资源状态 | HWPOD标准、平台配置 | 工具、客户端、Agent编排 |
+| PJ2026-01010302 | 租约占用 | 本规格 6.2 | 租约、占用、释放、冲突处理和写操作保护 | 用户管理、资源注册 | Agent编排、CaseRun |
+| PJ2026-01010303 | 节点路由 | 本规格 6.3 | 请求接收、目标解析、node 路由、超时和错误分类 | AI网关、租约占用 | HWPOD工具、HarnessRL |
+| PJ2026-01010304 | 结果归属 | 本规格 6.4 | operation result 归属、查询和摘要交接 | 节点路由、Agent上下文 | HarnessRL、客户端、用户管理 |
+
+## 6. 原子需求
+
+### 6.1 HWPOD-SVC-REQ-001 资源注册
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-SVC-REQ-001 | 资源注册 | PJ2026-01010301 资源注册 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)、[客户端](PJ2026-0104-client.md) |
+
+HWPOD服务应维护 HWPOD registry，使已声明资源、spec 摘要、authority、状态、能力和路由信息能够被工具、客户端和上层任务查询。
+
+Registry 必须以 HWPOD 标准解释资源事实。缺失 HWPOD spec 的真实设备不能被服务端当作可写资源暴露；客户端可以展示不可用或待配置状态，但不能把临时端点当作资源真相。
+
+### 6.2 HWPOD-SVC-REQ-002 租约与占用
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-SVC-REQ-002 | 租约占用 | PJ2026-01010302 租约占用 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
+
+HWPOD服务应提供租约、占用、释放、冲突处理和超时恢复能力，使真实硬件写操作不会被多个任务并发破坏。
+
+租约只定义硬件资源占用事实。用户管理提供调用主体和权限约束，Agent编排提供任务上下文，HWPOD服务负责把这些约束落实到资源可用性和写操作保护。
+
+### 6.3 HWPOD-SVC-REQ-003 节点路由
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-SVC-REQ-003 | 节点路由 | PJ2026-01010303 节点路由 | [PJ2026-010104 AI网关](PJ2026-010104-ai-gateway.md)、[PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md) |
+
+HWPOD服务应把已授权且租约一致的操作请求路由到正确 HWPOD node，并把目标不存在、node 离线、路由超时、协议连接失败和节点返回失败区分输出。
+
+节点路由必须禁止错误 HWPOD 复用。工具请求某个 `hwpod-id` 时，服务端只能使用该资源声明绑定的 node 和能力；无法找到声明或路由时必须返回明确失败。
+
+### 6.4 HWPOD-SVC-REQ-004 结果归属
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-SVC-REQ-004 | 结果归属 | PJ2026-01010304 结果归属 | [HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |
+
+HWPOD服务应把每次 operation result 归属到明确的 HWPOD、node、租约、调用方、操作类型和时间上下文，使 HarnessRL、客户端和账务统计能消费同一结果事实。
+
+结果归属不是长证据归档。服务端只负责保存和交接必要操作结果、摘要和查询指针；CaseRun 评价、回放、训练反馈和用户展示由对应模块在此事实上继续处理。
@@ -0,0 +1,124 @@
+# PJ2026-010104 AI网关
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010104 AI网关需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010104 |
+| 短名 | AI网关 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [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 需求规格模板的项目裁剪版：正文只保留 AI 网关的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+AI网关负责靠近真实硬件执行受控动作并回传原始硬件事实，使 HWPOD 服务能够触达 PC 侧工具、debug probe、board-comm、ioProbe、UART、CANopen、电压、电流和频率等实际设备能力。
+
+当前实现已经能通过节点侧工具触达部分真实板卡和观测链路，但仍存在部分目标 TCP 可达后 JSON-RPC 请求被板侧复位、缺少独立 HWPOD spec/reset/debugProbe 绑定、以及真实频率源写入链路未闭合的情况。本课题的预期状态是：节点能先完成只读连通与身份确认，再按声明能力执行写操作，并在失败时返回可区分的节点、协议、板侧处理或安全恢复错误。
+
+### 2.2 范围内
+
+- HWPOD node / AI 网关进程、心跳、能力上报、健康和可用性。
+- PC 客户端形态、硬件网关盒子形态和靠近设备的 adapter 执行。
+- debug probe 下载、reset、UART、board-comm JSON-RPC、CANopen SDO、ioProbe、电压、电流和频率适配器。
+- 只读诊断、写操作前置身份确认、安全态恢复和恢复失败分类。
+- 原始硬件事实回传，包括板内 echo、板外采样、协议响应、适配器日志摘要和错误语义。
+
+### 2.3 范围外
+
+- HWPOD spec 字段、资源身份和能力声明归 [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)。
+- CLI/API 命令形态和结构化输出归 [PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md)。
+- 服务端 registry、租约、路由和结果归属归 [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md)。
+- CaseRun 评价、aggregate 和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| AI 网关 | 靠近真实硬件的节点侧执行能力，包含 PC 客户端、硬件网关盒子或等价 HWPOD node。 |
+| adapter | 网关侧执行某类硬件动作的适配器，例如 debug probe、UART、board-comm、ioProbe 或 CANopen。 |
+| board-comm | 通过板侧通信协议访问目标固件接口的能力，当前包含 JSON-RPC over TCP 等形态。 |
+| CANopen SDO | 通过 CANopen Service Data Object 读写设备对象字典的协议动作。 |
+| 安全恢复 | 在写操作前后把真实设备恢复到可继续使用状态的 reset、重新连接或清理输出能力。 |
+| 原始硬件事实 | 由节点直接观测或执行得到的协议响应、板外读数、probe 结果和错误语义。 |
+
+## 4. 系统边界和接口
+
+本规格把 AI网关作为硬件池的节点侧执行层看待；本章只描述输入、输出和责任边界。
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | HWPOD服务、HWPOD工具、Agent编排、HarnessRL、平台管理员。 |
+| 外部输入 | 服务端路由请求、HWPOD spec 摘要、租约上下文、adapter 参数、workspace 路径、probe UID、通信端点和超时。 |
+| 受控资源 | HWPOD node、adapter、debug probe、UART、board-comm 连接、ioProbe、CANopen 通道、电压/电流/频率通道和节点日志摘要。 |
+| 外部输出 | 心跳、能力上报、健康状态、adapter 结果、原始硬件事实、恢复结果和错误分类。 |
+| 用户接口 | HWPOD node 协议、网关执行 API、节点侧工具适配器、board-comm/ioProbe 原始接口。 |
+| 系统边界 | AI网关负责真实硬件动作执行和原始事实生产；不拥有服务端资源真相、用户权限、客户端体验或 Harness 评价语义。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01010401 | 节点健康 | 本规格 6.1 | 心跳、能力、健康、可用性和节点运行形态 | HWPOD服务、平台运行面 | 工具、客户端、Agent编排 |
+| PJ2026-01010402 | 适配执行 | 本规格 6.2 | debug、UART、board-comm、ioProbe、CANopen、电压、电流和频率适配器 | HWPOD标准、节点健康 | HWPOD服务、HarnessRL |
+| PJ2026-01010403 | 安全恢复 | 本规格 6.3 | 只读诊断、写前身份确认、reset 和恢复失败分类 | HWPOD标准、适配执行 | Agent编排、CaseRun |
+| PJ2026-01010404 | 原始事实 | 本规格 6.4 | 协议响应、板外读数、adapter 摘要和错误语义回传 | 适配执行、安全恢复 | HarnessRL、客户端 |
+
+## 6. 原子需求
+
+### 6.1 HWPOD-GW-REQ-001 节点健康
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-GW-REQ-001 | 节点健康 | PJ2026-01010401 节点健康 | [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+
+AI网关应上报节点心跳、能力、健康、可用性和运行形态，使 HWPOD 服务能判断某个资源是否可以被路由到真实执行节点。
+
+节点健康必须覆盖 adapter 可用性，而不只是进程在线。debug probe、board-comm 端点、ioProbe、CANopen 通道或恢复能力不可用时，应以能力级状态暴露给服务端。
+
+### 6.2 HWPOD-GW-REQ-002 适配器执行
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-GW-REQ-002 | 适配执行 | PJ2026-01010402 适配执行 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)、[PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) |
+
+AI网关应按 HWPOD spec 声明执行 debug、download、reset、UART、board-comm、ioProbe、CANopen SDO、电压、电流和频率等适配器动作。
+
+适配器执行必须先确认目标身份和声明能力。对于真实频率源链路，网关应能把控制侧写入、板侧读回和外部电流/频率观测区分为不同事实来源。
+
+### 6.3 HWPOD-GW-REQ-003 安全恢复
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-GW-REQ-003 | 安全恢复 | PJ2026-01010403 安全恢复 | [PJ2026-010101 HWPOD标准](PJ2026-010101-hwpod-standard.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
+
+AI网关应在写操作前后提供只读诊断、身份确认、reset 和安全恢复能力，使真实硬件不会在目标不明或恢复入口缺失时被继续写入。
+
+安全恢复必须绑定明确 debug probe、设备和 reset 能力。无法确认 probe 属于目标设备、板侧通信在接收请求后复位、或恢复命令只是空实现时，网关应返回受控失败并停止后续写操作。
+
+### 6.4 HWPOD-GW-REQ-004 原始硬件事实回传
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| HWPOD-GW-REQ-004 | 原始事实 | PJ2026-01010404 原始事实 | [HarnessRL](PJ2026-0103-harness-rl.md)、[PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md) |
+
+AI网关应回传原始硬件事实，使板内协议响应、板外 ioProbe 读数、adapter 摘要、连接失败、协议失败和板侧处理失败能被 HWPOD 工具与 HarnessRL 一致消费。
+
+原始硬件事实必须区分板内 echo、板外真实读数和节点适配器状态。网关不能把 TCP 端口可达、进程在线或命令已发出等中间状态当作硬件动作成功。
@@ -79,7 +79,7 @@ HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较
 | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
 | --- | --- | --- | --- | --- | --- |
 | PJ2026-010301 | CaseRun规格 | 本规格 6.1 | case definition、stage model、postValidation、registry 语义 | Agent编排、硬件池、平台运维 | 客户端、用户管理 |
-| PJ2026-010302 | 观测引用 | 本规格 6.2 | CaseRun 中引用 HWPOD 服务返回的外部观测、单位、采样、统计和硬件动作关联 | [硬件池](PJ2026-0101-hardware-pool.md) 的 PJ2026-010103 HWPOD服务 | CaseRun、评价回放 |
+| PJ2026-010302 | 观测引用 | 本规格 6.2 | CaseRun 中引用 HWPOD 服务返回的外部观测、单位、采样、统计和硬件动作关联 | [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) | CaseRun、评价回放 |
 | PJ2026-010303 | 评估回放 | 本规格 6.3 | aggregate、baseline、judge、replay 和失败分类 | CaseRun、Agent编排、硬件池 | 客户端、训练反馈 |
 | PJ2026-010304 | 训练反馈 | 本规格 6.4 | reward、失败标签、prompt/skill/case 改进样本 | 评估回放、Agent编排 | Agent编排、用户管理 |

@@ -103,7 +103,7 @@ CaseRun 语义必须引用 Agent 执行上下文和硬件事实，但不接管

 HarnessRL 应在 CaseRun 语义中引用 HWPOD 服务提供的外部观测结果，使外部读数能够与 case stage、硬件动作、评价和回放关系稳定关联。

-ioProbe 只是 HWPOD 观测输入的一种。probe 能力、probe 绑定、物理采样、HWPOD node 路由和原始硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md) 的 PJ2026-010103 HWPOD服务负责；HarnessRL 不自建 ioProbe 硬件模型，也不绕过 HWPOD 服务直接管理 probe。
+ioProbe 只是 HWPOD 观测输入的一种。probe 能力、probe 绑定、物理采样、HWPOD node 路由和原始硬件事实归 [PJ2026-010103 HWPOD服务](PJ2026-010103-hwpod-service.md) 负责；HarnessRL 不自建 ioProbe 硬件模型，也不绕过 HWPOD 服务直接管理 probe。

 HarnessRL 只负责把 HWPOD 服务返回的观测事实纳入 CaseRun stage、postValidation、评估和回放关系，并区分板内 echo、日志输出和板外真实读数。客户端只负责展示这些结果，不重新定义观测来源。