Codex
127 lines
8.7 KiB
Markdown
127 lines
8.7 KiB
Markdown
# PJ2026-0101 硬件池
|
|
|
|
## 修改历史
|
|
|
|
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|
|
| --- | --- | --- | --- |
|
|
| v0.3 | b5d8cee438a3bd66ca440a25bf5a16d9081d9efa | 2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 |
|
|
| v0.2 | b0cbe9b721b50e9fff4d350ee50ed2af03cf0405 | 2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 |
|
|
| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从迁移来源 pikasTech/HWLAB#1203 迁移到 UniDesk 项目管理目录。 |
|
|
|
|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
|
|
|
|
## 正文
|
|
|
|
## PJ2026-0101 硬件池需求规格
|
|
|
|
## 1. 文档控制
|
|
|
|
| 字段 | 内容 |
|
|
| --- | --- |
|
|
| 编号 | PJ2026-0101 |
|
|
| 短名 | 硬件池 |
|
|
| 层级 | L1 方向 |
|
|
| 状态 | 已生效 |
|
|
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
|
|
| 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) |
|
|
| 规格治理索引 | [规格治理](spec-governance.md) |
|
|
|
|
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留硬件池的稳定使命、范围、术语、系统边界、内部分工和原子需求。
|
|
|
|
## 2. 目的和范围
|
|
|
|
### 2.1 目的
|
|
|
|
硬件池负责把真实板卡、debug probe、io probe、HWPOD node 和设备健康状态组织成可引用、可占用、可释放、可审计的硬件资源池。它是 HWLAB 的物理事实源，必须让上层 Agent、Harness 和客户端拿到真实硬件事实，而不是临时脚本输出或不可复验的运行副本。
|
|
|
|
### 2.2 范围内
|
|
|
|
- HWPOD 资源身份、四要素模型、能力声明、状态和错误语义。
|
|
- `hwpod-id`、HWPOD spec、资源 registry、authority 和版本来源。
|
|
- HWPOD 工具入口，包括 spec validate、inspect、build、download、UART、board-comm 和 ioProbe 操作。
|
|
- HWPOD 服务端注册、健康、inventory、租约、占用释放、冲突处理、路由和结果归属。
|
|
- HWPOD node / AI 网关的心跳、能力上报、受控命令执行、probe 校验和原始硬件事实回传。
|
|
|
|
### 2.3 范围外
|
|
|
|
- Agent run、command、session、provider profile 和 workspace 生命周期归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
|
|
- CaseRun 评价、pass/fail、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。
|
|
- Web、CLI 和 HTTP API 的通用用户入口体验归 [客户端](PJ2026-0104-client.md)。
|
|
- 用户身份、API key、额度、账本和租户策略归 [用户管理](PJ2026-0105-user-management.md)。
|
|
- CI/CD、Git mirror、YAML-first 运维、发布、公开入口和 Prometheus 运维监控归 [平台运维](PJ2026-0106-platform-ops.md)。
|
|
|
|
## 3. 术语表
|
|
|
|
| 术语 | 定义 |
|
|
| --- | --- |
|
|
| HWPOD | 由目标设备、workspace、debug probe 和 io probe 组成的硬件研发执行上下文。 |
|
|
| HWPOD spec | 描述 HWPOD 身份、硬件能力、node 绑定、probe 约束和操作能力的规格声明。 |
|
|
| HWPOD node | 靠近真实硬件的执行节点，负责按受控协议执行硬件操作并回传结构化结果。 |
|
|
| debug probe | 用于下载、调试或访问目标设备的调试探针。 |
|
|
| io probe | 用于采集板外输入输出、电压、电流、频率或其他外部物理状态的观测探针。 |
|
|
| 租约 | 对真实硬件资源的一次占用关系，用于避免多任务冲突并支持超时释放。 |
|
|
|
|
## 4. 系统边界和接口
|
|
|
|
本规格把硬件池作为 HWLAB 内部的硬件资源子系统看待；本章只描述该子系统的输入、输出和责任边界。
|
|
|
|
| 边界项 | 内容 |
|
|
| --- | --- |
|
|
| 外部使用者 | Agent编排、HarnessRL、客户端、平台管理员和需要真实硬件的训练任务。 |
|
|
| 外部输入 | HWPOD spec、`hwpod-id`、workspace、目标设备选择、probe 约束、HWPOD node 状态、硬件操作请求和租约上下文。 |
|
|
| 受控资源 | 真实板卡、debug probe、io probe、HWPOD node、资源 registry、租约和硬件操作记录。 |
|
|
| 外部输出 | 资源身份、能力声明、可用性、健康状态、占用释放状态、operation result、原始硬件事实和硬件错误语义。 |
|
|
| 用户接口 | HWPOD 工具、HWLAB runtime API、HWPOD 服务端接口、HWPOD node / AI 网关协议。 |
|
|
| 系统边界 | 硬件池负责硬件事实和资源占用正确性；不定义 Agent 执行策略、Harness 评分、用户账本、客户端展示或平台发布流程。 |
|
|
|
|
## 5. 内部分工与规格索引
|
|
|
|
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| 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. 原子需求
|
|
|
|
### 6.1 HWPOD-L1-REQ-001 HWPOD 标准与资源身份
|
|
|
|
| 编号 | 短名 | 主责模块 | 关联模块 |
|
|
| --- | --- | --- | --- |
|
|
| 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 标准，使每个真实硬件资源都有稳定的身份、四要素组成、能力声明、状态语义和错误语义。
|
|
|
|
该标准必须让设备、workspace、debug probe、io probe 和 HWPOD node 的关系可以被服务端、工具和上层任务一致解释。客户端可以展示这些事实，Agent编排和 HarnessRL 可以消费这些事实，但不得在各自模块重新发明硬件身份或能力模型。
|
|
|
|
### 6.2 HWPOD-L1-REQ-002 HWPOD 工具入口
|
|
|
|
| 编号 | 短名 | 主责模块 | 关联模块 |
|
|
| --- | --- | --- | --- |
|
|
| 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 操作。
|
|
|
|
工具入口必须以 HWLAB runtime API 和 HWPOD authority 为准解析资源，不能依赖遗留环境变量或一次性脚本静默改写目标。客户端负责命令呈现和多端一致性，硬件池负责命令背后的硬件语义和资源事实。
|
|
|
|
### 6.3 HWPOD-L1-REQ-003 HWPOD 服务与租约
|
|
|
|
| 编号 | 短名 | 主责模块 | 关联模块 |
|
|
| --- | --- | --- | --- |
|
|
| 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。
|
|
|
|
服务端必须把租约、权限约束和资源状态统一到同一硬件池事实中。用户管理提供身份和额度约束，Agent编排消费分配结果，平台运维提供运行支撑；这些关联模块不接管硬件资源真相。
|
|
|
|
### 6.4 HWPOD-L1-REQ-004 HWPOD node 与 AI 网关
|
|
|
|
| 编号 | 短名 | 主责模块 | 关联模块 |
|
|
| --- | --- | --- | --- |
|
|
| 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 和其他硬件动作在靠近设备的执行节点上受控执行。
|
|
|
|
HWPOD node 必须上报心跳、能力和健康状态，并在执行动作时返回结构化原始硬件事实。涉及 probe 绑定、外部 ioProbe 读数和板内 echo 的场景必须能区分物理事实来源，避免把错误设备、错误探针或不可复验输出当作成功硬件结果。
|