# PJ2026-01 HWLAB 总规格

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |
| v0.4 | b5d8cee438a3bd66ca440a25bf5a16d9081d9efa | 2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 |
| v0.3 | b0cbe9b721b50e9fff4d350ee50ed2af03cf0405 | 2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 |
| v0.2 | b40a37ce771811cc97d74ef0909a7ce441161c6b | 2026-06-14 | 移除项目管理目录中的 evidence 文件，长证据保留在 GitHub issue。 |
| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从迁移来源 pikasTech/HWLAB#1194 迁移到 UniDesk 项目管理目录。 |

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

## 正文

## PJ2026-01 HWLAB 总项目需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-01 |
| 短名 | HWLAB |
| 层级 | L0 总项目 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) 的 HWLAB 裁剪版：正文只保留稳定使命、范围、术语、系统边界、内部模块分工、全局原子需求和必要过程控制。

## 2. 目的和范围

### 2.1 项目使命

HWLAB 的中心目标是把真实硬件资源、Agent 执行、Harness/RL 验收反馈、多客户端入口、多用户运营和平台自动化运维收敛为一个云端硬件研发平台。平台必须服务真实硬件研发闭环：用户或训练任务通过客户端/API 提出需求，Agent 在受控 workspace 中执行，通过硬件池触达真实设备，由 HarnessRL 形成可审计执行事实，并把成功路径、失败分类和训练反馈回流为可复用能力。

### 2.2 范围内

- 真实硬件资源池：板卡、probe、HWPOD 节点、设备注册、占用、健康、可用性和原始硬件事实。
- Agent 执行编排：Code Agent、AgentRun、workspace、session、provider profile、任务生命周期和任务恢复。
- Harness/RL 验收闭环：harness、CaseRun、HWPOD 观测引用、执行事实、评估、回放、训练反馈和 RL 闭环。
- 用户入口：Web、CLI、HTTP API、兼容性、任务入口、状态查看和结果获取。
- 用户与运营管理：用户、组织、组织项目、组织工作台、注册登录、权限、API key、credit、usage、billing、admin 和租户隔离。
- 系统可用性与服务保障：入口可访问、任务可恢复、资源使用可控、运行状态可观察和故障可处理。

### 2.3 范围外

- 无 L1 主责归属的孤立工具美化、旧门禁修补或无原入口验收的观测增强。
- 单个 PR、一次 CaseRun、一次 smoke、一次部署或阶段报告流水；这些属于 L3/L4 或报告，不属于 L0 需求规格正文。
- 具体实现设计、代码结构、临时运行面调试路径、原始日志堆叠和每日进展统计。
- 编号、回写、偏离和管理流程全文；这些由 [规格治理](spec-governance.md) 承载。
- 当前阶段优先级和阶段主线全文；这些属于阶段计划，不属于 L0 需求规格正文。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| HWLAB | 面向真实硬件研发的云端平台，覆盖硬件资源、Agent 执行、Harness/RL 验收、客户端入口、用户运营和平台运维。 |
| HWPOD | 对真实硬件研发资源的标准化抽象，至少关联目标设备、workspace、debug probe 和 io probe，并提供可被服务端和工具引用的资源身份。 |
| 硬件池 | 管理真实硬件资源身份、能力声明、占用释放、健康状态和原始硬件事实的内部模块。 |
| Agent编排 | 管理 Code Agent、AgentRun、workspace、session、provider profile、任务生命周期和任务恢复的内部模块。 |
| HarnessRL | 将硬件执行结果转化为执行事实、aggregate、评估、回放和训练反馈的内部模块。 |
| 客户端 | 面向用户的 Web、CLI 和 HTTP API 入口。 |
| 用户管理 | 管理用户身份、组织协同、权限、API key、credit、usage、billing、admin 和租户隔离的内部模块。 |
| 平台运维 | 管理 CI/CD、git mirror、YAML-first 配置、Secret 下发、rollout、observability、GC 和平台发布的内部模块。 |
| 执行事实 | 可审计、可复验的硬件执行材料，包括硬件事实、执行 trace、ioProbe 数据、case registry、评估结果和必要日志摘要。 |
| 原入口验收 | 通过用户真实使用入口或该能力的原始执行入口完成验收，例如 Web、CLI、API、CaseRun、AgentRun 或 HWPOD 工具。 |
| 运行面 | 承载任务执行或服务运行的实际环境，例如目标 lane、namespace、workspace、node、pod 或外部硬件节点。 |

## 4. 系统边界和接口

本规格把 HWLAB 作为一个完整系统看待；本章只描述外部输入、外部输出和系统边界，不描述内部治理流程。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 硬件研发用户、训练任务、平台管理员。 |
| 外部输入 | 硬件研发任务、源码或工程 workspace、目标设备或 HWPOD 选择、构建/下载/调试/采样指令、用户身份凭据、API key、额度和资源约束。 |
| 受控资源 | 真实板卡、debug probe、io probe、HWPOD node、Agent 执行环境、provider profile、用户账号、额度和任务产物存储。 |
| 外部输出 | 任务状态、执行结果、构建/下载/调试产物、硬件采样数据、评估摘要、错误语义、usage/credit 记录和可复验运行记录。 |
| 用户接口 | Web、CLI、HTTP API。 |
| 硬件接口 | HWPOD spec、HWPOD 工具、HWPOD 服务、AI 网关、debug probe、UART、board-comm、ioProbe。 |
| 系统边界 | HWLAB 负责把用户任务连接到受控 Agent 和真实硬件，并返回可理解、可审计、可复用的结果；不替代用户对硬件设计目标、工程代码正确性和业务取舍的判断。 |

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

L1 划分保持现有六个内部能力模块；本章同时作为内部模块分工和方向规格索引。

| 编号 | 内部模块 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-0101 | 硬件池 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) | 板卡、探针、HWPOD node、设备注册、资源占用、设备健康、可用性 | [平台运维](PJ2026-0106-platform-ops.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) |
| PJ2026-0102 | Agent编排 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | Code Agent、AgentRun、workspace、session、provider profile、任务生命周期、任务恢复 | [硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md)、[用户管理](PJ2026-0105-user-management.md) | [HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) |
| PJ2026-0103 | HarnessRL | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | harness、CaseRun、HWPOD 观测引用、执行事实、评估、回放、训练反馈、RL 闭环 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |
| PJ2026-0104 | 客户端 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | Web、CLI、HTTP API、兼容性、用户任务入口与结果获取 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) | 用户入口 |
| PJ2026-0105 | 用户管理 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | 用户、组织、组织项目、组织工作台、权限、API key、credit、usage、billing、admin、租户隔离 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
| PJ2026-0106 | 平台运维 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | CI/CD、git mirror、YAML-first 自动化分布式运维、rollout、Prometheus 运维监控、平台发布 | 全部 L1 的发布、配置和监控需求 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |

## 6. 全局原子需求

### 6.1 HWLAB-L0-REQ-001 硬件资源池

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-001 | 硬件资源池 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) | [平台运维](PJ2026-0106-platform-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) |

HWLAB 应提供真实硬件资源池，使任务能发现、分配、占用、释放并验证真实设备、probe、HWPOD node 和健康状态。

硬件资源池是 HWLAB 的物理事实源。它把板卡、probe、HWPOD node 和设备健康状态整理为稳定、可引用、可审计的资源模型，并确保上层任务拿到的是可执行的真实硬件，而不是临时脚本输出或不可复验的运行副本。

硬件池负责设备身份、能力声明、占用释放、健康和原始硬件事实。平台运维只提供运行与发布支撑；Agent编排、HarnessRL 和客户端消费硬件池输出，不重新定义硬件事实。

### 6.2 HWLAB-L0-REQ-002 Agent 执行编排

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-002 | Agent 执行编排 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) |

HWLAB 应提供 Agent 执行编排，使用户任务能进入受控 workspace/session/provider/runtime，并能跟踪、恢复、取消和归档结果。

Agent 执行编排负责把用户意图转化为可追踪的受控执行。它必须明确任务状态、运行上下文、执行凭据、结果位置和异常收口，避免用户任务只存在于一次性进程、临时容器或无法恢复的日志片段中。

Agent编排负责任务生命周期、workspace、session、provider profile、恢复和归档。硬件池提供可执行资源，用户管理提供身份与权限，平台运维提供运行支撑，HarnessRL 和客户端消费任务状态与结果指针。

### 6.3 HWLAB-L0-REQ-003 HarnessRL 验收闭环

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-003 | HarnessRL 验收闭环 | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |

HWLAB 应提供 Harness/RL 验收闭环，使真实硬件任务产出可审计执行事实、aggregate、评估、回放和训练反馈。

HarnessRL 把一次硬件执行转化为可复验的验证与训练材料。它不得只记录 pass/fail，而要保留可解释的硬件输入、执行过程、采样数据、评估结论和回放入口，使失败分类和成功路径能够进入后续改进闭环。

HarnessRL 负责执行事实、aggregate、评估、回放和训练反馈。硬件池提供原始硬件事实，Agent编排提供执行上下文，平台运维提供运行支撑，客户端和用户管理消费验收结果与统计信息。

### 6.4 HWLAB-L0-REQ-004 统一客户端入口

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-004 | 统一客户端入口 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |

HWLAB 应提供统一客户端入口，使 Web、CLI 和 HTTP API 围绕同一任务模型、权限模型和结果模型协同演进。

统一客户端入口要求不同用户界面共享同一任务、权限、错误和结果语义。Web、CLI 和 HTTP API 可以有不同交互形态，但不能各自定义一套状态机、错误口径或结果读取路径。

客户端负责 Web、CLI 和 HTTP API 的一致入口。用户管理提供身份权限，Agent编排、硬件池、HarnessRL 和平台运维提供后端能力；客户端不重新定义这些后端事实。

### 6.5 HWLAB-L0-REQ-005 用户与运营管理

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-005 | 用户与运营管理 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

HWLAB 应提供多用户与运营管理，使身份、组织、权限、API key、credit、usage、billing、admin 和租户隔离具有统一真相。

用户与运营管理定义平台多用户和组织协同运行的业务事实。它必须保证用户身份、组织成员关系、组织内项目和工作台归属、权限、额度、计量、账务和管理操作可以被统一查询和审计，避免同一用户、同一组织或同一资源消费在不同入口出现不同真相。

用户管理负责身份、组织、权限、API key、credit、usage、billing、admin 和租户隔离。客户端负责呈现入口和组织工作台，Agent编排、硬件池和 HarnessRL 消费用户、组织、租户和额度约束。

### 6.6 HWLAB-L0-REQ-006 系统可用性与服务保障

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-006 | 系统可用性与服务保障 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[用户管理](PJ2026-0105-user-management.md) |

HWLAB 应作为云端服务保持可访问、可恢复、资源使用可控，使用户能够稳定提交任务、查看状态和获取结果。

系统可用性与服务保障不是 HWLAB 对外出售的功能模块，而是用户能够持续使用 HWLAB 的基础条件。用户感知到的是入口可访问、任务不中途丢失、故障后有恢复路径、资源不会被失控占用；平台运维只作为后勤职责支撑这些对外结果。

平台运维负责发布、YAML-first 自动化分布式运维、Prometheus 运维监控和故障恢复支撑。客户端、Agent编排、硬件池、HarnessRL 和用户管理提供各自服务健康指标和运行需求，并通过平台运维获得后勤支撑。

## 7. 过程控制

本章只索引跨 L1 的阶段验证、灰度、内测和用户反馈分流 issue，便于将阶段运行过程回写到现有能力模块；不新增 L1，不替代阶段计划，也不把参与者资料、原始反馈、长证据或执行流水写入 L0 规格正文。

### 7.1 阶段验证与反馈入口

| 阶段 issue | 定位 | 关联 L1 | 回写口径 |
| --- | --- | --- | --- |
| [#1230](https://github.com/pikasTech/HWLAB/issues/1230) 内测一期招募与运行 | HWPOD 云嵌入式开发平台第一期内测；承载招募、运行、反馈分流和阶段结论 | 硬件池、Agent编排、HarnessRL、客户端、用户管理、平台运维 | 反馈先脱敏，再按主责 L1/L2 新建或关联具体 issue；阶段结束只回写稳定需求变化和重大边界移动 |

### 7.2 测试大纲与手测入口

| 测试 issue | 定位 | 覆盖入口 | 回写口径 |
| --- | --- | --- | --- |
| [#1231](https://github.com/pikasTech/HWLAB/issues/1231) 内测一期测试大纲 | 按 `TEST.md` 风格组织需要 HWLAB 实际业务能力支撑的端到端手动测试用例 | 账号/额度、AI 网关、HWPOD 工具、Web、CLI、HTTP API、真实硬件、Agent 任务、构建下载、ioProbe | 测试失败先脱敏，再按硬件池、Agent编排、HarnessRL、客户端、用户管理或平台运维拆分 issue；阶段结论回写 [#1230](https://github.com/pikasTech/HWLAB/issues/1230) |