pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md

PJ2026-01 HWLAB 总规格

修改历史

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

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

正文

PJ2026-01 HWLAB 总项目需求规格

1. 文档控制

字段	内容
编号	PJ2026-01
短名	HWLAB
层级	L0 总项目
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板 的 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 需求规格正文。
• 具体实现设计、代码结构、临时运行面调试路径、原始日志堆叠和每日进展统计。
• 编号、回写、偏离和管理流程全文；这些由 规格治理 承载。
• 当前阶段优先级和阶段主线全文；这些属于阶段计划，不属于 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 硬件池	板卡、探针、HWPOD node、设备注册、资源占用、设备健康、可用性	平台运维	Agent编排、HarnessRL、客户端
PJ2026-0102	Agent编排	PJ2026-0102 Agent编排	Code Agent、AgentRun、workspace、session、provider profile、任务生命周期、任务恢复	硬件池、平台运维、用户管理	HarnessRL、客户端
PJ2026-0103	HarnessRL	PJ2026-0103 HarnessRL	harness、CaseRun、HWPOD 观测引用、执行事实、评估、回放、训练反馈、RL 闭环	硬件池、Agent编排、平台运维	客户端、用户管理
PJ2026-0104	客户端	PJ2026-0104 客户端	Web、CLI、HTTP API、兼容性、用户任务入口与结果获取	用户管理、Agent编排、硬件池、HarnessRL、平台运维	用户入口
PJ2026-0105	用户管理	PJ2026-0105 用户管理	用户、组织、组织项目、组织工作台、权限、API key、credit、usage、billing、admin、租户隔离	客户端、Agent编排、HarnessRL、平台运维	客户端、Agent编排、硬件池、HarnessRL
PJ2026-0106	平台运维	PJ2026-0106 平台运维	CI/CD、git mirror、YAML-first 自动化分布式运维、rollout、Prometheus 运维监控、平台发布	全部 L1 的发布、配置和监控需求	硬件池、Agent编排、HarnessRL、客户端、用户管理

6. 全局原子需求

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

编号	短名	主责模块	关联模块
HWLAB-L0-REQ-001	硬件资源池	PJ2026-0101 硬件池	平台运维、Agent编排、HarnessRL、客户端

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编排	硬件池、用户管理、平台运维、HarnessRL、客户端

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	硬件池、Agent编排、平台运维、客户端、用户管理

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

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

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

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

编号	短名	主责模块	关联模块
HWLAB-L0-REQ-004	统一客户端入口	PJ2026-0104 客户端	用户管理、Agent编排、硬件池、HarnessRL、平台运维

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 用户管理	客户端、Agent编排、硬件池、HarnessRL

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 平台运维	客户端、Agent编排、硬件池、HarnessRL、用户管理

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

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

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

7. 过程控制

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

7.1 阶段验证与反馈入口

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

7.2 测试大纲与手测入口

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