mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: govern HWLAB requirements specs

Browse Source
This commit is contained in:
Codex
2026-06-14 15:33:10 +00:00
parent fc14b28008
commit b8529abed1
4 changed files with 291 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/unidesk-oa/references/project-planning.md
+7 -3
View File
@@ -32,7 +32,11 @@ HWLAB Cloud M1 需要一个项目控制结构，避免局部 issue/PR 工作偏
不要把稳定需求的唯一副本放在 issue 评论里。长期有效的需求必须蒸馏到 `project-management/PJ2026-01`，再从 issue 链接过去。
不要把长证据正文放进项目管理目录。项目管理目录只承载规格、治理和阶段中心；长证据保留在 GitHub issue。
所有 Markdown 正文、issue/PR 正文和评论中的 issue/PR 引用都必须写成 `[#<number>](https://github.com/<owner>/<repo>/issues/<number>)` 或 `[#<number>](https://github.com/<owner>/<repo>/pull/<number>)`，显示短号、链接目标保留完整 URL；不要显示裸长链接、裸井号编号或 `owner/repo` 加井号编号。`owner/repo#number` 只允许作为 CLI 命令参数 shorthand。
规格文件和 GitHub issue 的引用规则分开处理：
- `project-management/PJ2026-01/specs/*.md` 中，每个规格文件最多保留一个 GitHub issue 链接，即迁移来源表里的自身原 issue。
- 规格文件引用其他规格时，使用同目录相对路径 Markdown 链接，例如 `[PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md)`；不要引用其他规格的 GitHub issue、证据 issue、PR 或裸 `#<number>`。
- GitHub issue/PR 正文和评论中的 issue/PR 引用必须写成 `[#<number>](https://github.com/<owner>/<repo>/issues/<number>)` 或 `[#<number>](https://github.com/<owner>/<repo>/pull/<number>)`，显示短号、链接目标保留完整 URL；不要显示裸长链接、裸井号编号或 `owner/repo` 加井号编号。`owner/repo#number` 只允许作为 CLI 命令参数 shorthand。
## 当前 HWLAB issue 锚点
@@ -62,14 +66,14 @@ HWLAB Cloud M1 的长期文档放在 UniDesk 仓库内，并使用项目编号
```text
specs/PJ2026-01-HWLAB.md # L0 总规格，同时作为项目索引
specs/stage-cloud-spec-20260601.md # 既有阶段材料
specs/stage-cloud-spec-20260601.md # 既有阶段材料，同时承载阶段中心和非中心边界
specs/PJ2026-010N-*.md # L1 方向规格
specs/spec-governance.md # 编号、层级、回写与偏离规则
specs/current-center.md # 当前中心和非中心边界
```
优先维护 L0 总规格作为入口索引。只有当某个部分具有独立生命周期和评审需要时才拆分到 L1、治理或阶段文件。
禁止在本目录新增 `evidence/` 或其他长证据目录；证据入口在 L0/L1 规格中引用 GitHub issue。
禁止在规格文件正文链接证据 issue；只写“长证据保留在对应 GitHub 证据 issue”这类归属说明。证据 issue 的完整链接保留在 GitHub issue 正文或评论里。
每个长期规格文件最前面必须有修改历史表格，字段固定为：
project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md
+160 -77
View File
@@ -4,10 +4,14 @@
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |
| v0.8 | 待提交 | 2026-06-14 | 引用 ISO/IEC/IEEE 29148 需求规格模板。 |
| v0.7 | 待提交 | 2026-06-14 | 合并内部模块分工与规格索引，拆分全局原子需求并移除重复追踪章节。 |
| v0.6 | 待提交 | 2026-06-14 | 删除当前中心拆分文档，阶段中心口径统一回阶段规格。 |
| v0.5 | 待提交 | 2026-06-14 | 移除规格正文中的跨 issue 引用，跨规格关系改用相对路径链接。 |
| 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 | 从 [#1194](https://github.com/pikasTech/HWLAB/issues/1194) 迁移到 UniDesk 项目管理目录。 |
| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从原迁移 issue 迁移到 UniDesk 项目管理目录。 |
## 迁移来源
@@ -15,27 +19,11 @@
| --- | --- |
| 原 issue | [#1194](https://github.com/pikasTech/HWLAB/issues/1194) |
| 原标题 | PJ2026-01 HWLAB 总规格 |
| 原 URL | [#1194](https://github.com/pikasTech/HWLAB/issues/1194) |
| 原状态 | open |
| 原更新时间 | 2026-06-14T12:53:55Z |
| 原 body SHA | 4868729f6e33eec813713e810700b510847164d799373edf01c8ff50126a04b6 |
## 项目规格索引
| 层级 | 文件 | 历史 issue |
| --- | --- | --- |
| 阶段规格 | [stage-cloud-spec-20260601.md](stage-cloud-spec-20260601.md) | [#644](https://github.com/pikasTech/HWLAB/issues/644) |
| L0 总规格 | [PJ2026-01-HWLAB.md](PJ2026-01-HWLAB.md) | [#1194](https://github.com/pikasTech/HWLAB/issues/1194) |
| L1 硬件池 | [PJ2026-0101-hardware-pool.md](PJ2026-0101-hardware-pool.md) | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) |
| L1 Agent编排 | [PJ2026-0102-agent-orchestration.md](PJ2026-0102-agent-orchestration.md) | [#1204](https://github.com/pikasTech/HWLAB/issues/1204) |
| L1 HarnessRL | [PJ2026-0103-harness-rl.md](PJ2026-0103-harness-rl.md) | [#1205](https://github.com/pikasTech/HWLAB/issues/1205) |
| L1 客户端 | [PJ2026-0104-client.md](PJ2026-0104-client.md) | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) |
| L1 用户管理 | [PJ2026-0105-user-management.md](PJ2026-0105-user-management.md) | [#1207](https://github.com/pikasTech/HWLAB/issues/1207) |
| L1 平台运维 | [PJ2026-0106-platform-ops.md](PJ2026-0106-platform-ops.md) | [#1208](https://github.com/pikasTech/HWLAB/issues/1208) |
| 治理规则 | [spec-governance.md](spec-governance.md) | [#1217](https://github.com/pikasTech/HWLAB/issues/1217) |
| 当前中心 | [current-center.md](current-center.md) | [#1218](https://github.com/pikasTech/HWLAB/issues/1218) |
长证据不进入项目管理目录。硬件池证据保留在 [#1216](https://github.com/pikasTech/HWLAB/issues/1216)，Agent编排证据保留在 [#1223](https://github.com/pikasTech/HWLAB/issues/1223)；规格文件只引用证据 issue，不复制证据正文。
长证据不进入项目管理目录。硬件池和 Agent编排 的长证据保留在各自的 GitHub 证据 issue；规格文件只描述证据归属，不复制证据正文，也不链接其他规格的 issue。
## 正文
@@ -49,14 +37,14 @@
| 短名 | HWLAB |
| 层级 | L0 总项目 |
| 状态 | active / L0 需求规格锚点 |
| 长期面板 | [#645](https://github.com/pikasTech/HWLAB/issues/645) HWLAB 长期总面板 |
| 阶段规格 | [#644](https://github.com/pikasTech/HWLAB/issues/644) HWLAB Cloud SPEC / 云平台开发目标 20260601 |
| 阶段中心索引 | [#1218](https://github.com/pikasTech/HWLAB/issues/1218) HWLAB 当前中心索引：阶段主线与非中心边界 |
| 规格治理索引 | [#1217](https://github.com/pikasTech/HWLAB/issues/1217) HWLAB 规格治理索引：编号、层级、回写与偏离规则 |
| L1 划分 | 保持现有六方向：[#1203](https://github.com/pikasTech/HWLAB/issues/1203)、[#1204](https://github.com/pikasTech/HWLAB/issues/1204)、[#1205](https://github.com/pikasTech/HWLAB/issues/1205)、[#1206](https://github.com/pikasTech/HWLAB/issues/1206)、[#1207](https://github.com/pikasTech/HWLAB/issues/1207)、[#1208](https://github.com/pikasTech/HWLAB/issues/1208) |
| 长期面板 | HWLAB 长期总面板，仅作为 GitHub 导航面板，不作为规格正文来源 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 阶段规格 | [HWLAB Cloud SPEC / 云平台开发目标 20260601](stage-cloud-spec-20260601.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
| 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)、[平台运维](PJ2026-0106-platform-ops.md) |
| 规格来源 | `project-management/PJ2026-01` 与迁移前 HWLabOA 阶段材料 |
本文采用中文 L0 需求规格模板：正文只保留稳定使命、范围、运行概念、系统边界、L1 分配、全局原子需求、验证矩阵和追踪关系。编号规则、层级职责、回写、偏离判定和交叉引用治理迁入 [#1217](https://github.com/pikasTech/HWLAB/issues/1217)；阶段主线和非中心边界迁入 [#1218](https://github.com/pikasTech/HWLAB/issues/1218)。
本文采用 [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) 的 HWLAB 裁剪版：正文只保留稳定使命、范围、运行概念、系统边界、内部模块分工和全局原子需求。编号规则、层级职责、回写、偏离判定和交叉引用治理迁入 [规格治理](spec-governance.md)；阶段目标和阶段优先级由 [HWLAB Cloud SPEC](stage-cloud-spec-20260601.md) 承载。
## 2. 目的和范围
@@ -78,8 +66,8 @@ HWLAB 的中心目标是把真实硬件资源、Agent 执行、Harness/RL 验收
- 无 L1 主责归属的孤立工具美化、旧门禁修补或无原入口验收的观测增强。
- 单个 PR、一次 CaseRun、一次 smoke、一次部署或阶段报告流水；这些属于 L3/L4 或报告，不属于 L0 需求规格正文。
- 具体实现设计、代码结构、临时运行面调试路径、原始日志堆叠和每日进展统计。
- 编号、回写、偏离和管理流程全文；这些由 [#1217](https://github.com/pikasTech/HWLAB/issues/1217) 承载。
- 当前阶段优先级和阶段主线全文；这些由 [#1218](https://github.com/pikasTech/HWLAB/issues/1218) 和 [#644](https://github.com/pikasTech/HWLAB/issues/644) 承载。
- 编号、回写、偏离和管理流程全文；这些由 [规格治理](spec-governance.md) 承载。
- 当前阶段优先级和阶段主线全文；这些由 [HWLAB Cloud SPEC](stage-cloud-spec-20260601.md) 承载。
## 3. 运行概念
@@ -104,66 +92,161 @@ HWLAB 的中心目标是把真实硬件资源、Agent 执行、Harness/RL 验收
| 长期文档 | `project-management/PJ2026-01` 规格、实施方案、测试规格、阶段报告 |
| 执行控制面 | HWLAB GitHub issue 树、PR、trace/session/job/run/case registry 证据 |
## 5. L1 方向树
## 5. 内部模块分工与规格索引
L1 划分保持现有六方向；本次整理不新增、不删除、不重命名 L1。
L1 划分保持现有六个内部能力模块；本章同时作为内部模块分工和方向规格索引。
| 编号 | 短名 | L1 规格 issue | 主责 | 上游依赖 | 下游支撑 |
| 编号 | 内部模块 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-0101 | 硬件池 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) | 板卡、探针、HWPOD node、设备注册、资源占用、设备健康、可用性 | [#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维 | [#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL、[#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端 |
| PJ2026-0102 | Agent编排 | [#1204](https://github.com/pikasTech/HWLAB/issues/1204) | Code Agent、AgentRun、workspace、session、provider profile、任务生命周期、任务恢复 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池、[#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维、[#1207](https://github.com/pikasTech/HWLAB/issues/1207) 用户管理 | [#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL、[#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端 |
| PJ2026-0103 | HarnessRL | [#1205](https://github.com/pikasTech/HWLAB/issues/1205) | harness、CaseRun、ioProbe、evidence、评估、回放、训练反馈、RL 闭环 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池、[#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端、[#1207](https://github.com/pikasTech/HWLAB/issues/1207) 用户管理 |
| PJ2026-0104 | 客户端 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) | Web、CLI、HTTP API、SDK/IDE 插件、webhook、公开文档、兼容性、用户任务入口与结果获取 | [#1207](https://github.com/pikasTech/HWLAB/issues/1207) 用户管理、[#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池、[#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL、[#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维 | 用户入口和集成调用 |
| PJ2026-0105 | 用户管理 | [#1207](https://github.com/pikasTech/HWLAB/issues/1207) | 用户、注册登录、权限、API key、credit、usage、billing、admin、租户隔离 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端、[#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL、[#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端、[#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池、[#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL |
| PJ2026-0106 | 平台运维 | [#1208](https://github.com/pikasTech/HWLAB/issues/1208) | CI/CD、git mirror、YAML-first、Secret 下发、rollout、observability、GC、平台发布 | 全部 L1 的发布/配置/观测需求 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池、[#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL、[#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端、[#1207](https://github.com/pikasTech/HWLAB/issues/1207) 用户管理 |
| 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、ioProbe、evidence、评估、回放、训练反馈、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、SDK/IDE 插件、webhook、公开文档、兼容性、用户任务入口与结果获取 | [用户管理](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、Secret 下发、rollout、observability、GC、平台发布 | 全部 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. 全局原子需求
| ID | 需求 | 类型 | 主责 L1 | 验证方法 |
| --- | --- | --- | --- | --- |
| HWLAB-L0-REQ-001 | HWLAB 应提供真实硬件资源池，使任务能发现、分配、占用、释放并验证真实设备、probe、HWPOD node 和健康状态。 | 功能 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池 | 测试、演示 |
| HWLAB-L0-REQ-002 | HWLAB 应提供 Agent 执行编排，使用户任务能进入受控 workspace/session/provider/runtime，并能跟踪、恢复、取消和归档结果。 | 功能 | [#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排 | 测试、演示 |
| HWLAB-L0-REQ-003 | HWLAB 应提供 Harness/RL 验收闭环，使真实硬件任务产出可审计 evidence、aggregate、评估、回放和训练反馈。 | 功能 | [#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL | 测试、检查 |
| HWLAB-L0-REQ-004 | HWLAB 应提供统一客户端入口，使 Web、CLI、API、SDK/IDE plugin 和 Webhook 围绕同一任务模型、权限模型和结果模型协同演进。 | 功能 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端 | 测试、演示 |
| HWLAB-L0-REQ-005 | HWLAB 应提供多用户与运营管理，使身份、权限、API key、credit、usage、billing、admin 和租户隔离具有统一真相。 | 功能 | [#1207](https://github.com/pikasTech/HWLAB/issues/1207) 用户管理 | 测试、检查 |
| HWLAB-L0-REQ-006 | HWLAB 应提供平台交付与运维能力，使代码、配置、密钥、发布、入口、观测和清理通过受控入口维护。 | 支撑 | [#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维 | 检查、演示 |
| HWLAB-L0-REQ-007 | HWLAB 的用户可见能力关闭前必须经过真实入口验收；源码检查、PR 合并或构建通过不能单独作为关闭依据。 | 约束 | 全部 L1 | 检查 |
| HWLAB-L0-REQ-008 | HWLAB 的下级工作必须且只能有一个主责 L1；跨方向支撑通过关联方向和回写表达，不重复建树。 | 约束 | 全部 L1 | 检查 |
| HWLAB-L0-REQ-009 | HWLAB 的稳定需求、验证标准和长期结论应沉淀到 `project-management/PJ2026-01` 的对应规格文件；阶段报告和执行流水不得替代规格。 | 约束 | 全部 L1 | 检查 |
### 6.1 HWLAB-L0-REQ-001 硬件资源池
## 7. 全局验证矩阵
| 字段 | 内容 |
| --- | --- |
| ID | HWLAB-L0-REQ-001 |
| 需求 | HWLAB 应提供真实硬件资源池，使任务能发现、分配、占用、释放并验证真实设备、probe、HWPOD node 和健康状态。 |
| 类型 | 功能 |
| 主责模块 | [硬件池](PJ2026-0101-hardware-pool.md) |
| 职责划分 | 硬件池负责设备身份、能力声明、占用释放、健康和原始硬件事实；平台运维提供运行与发布支撑；Agent编排、HarnessRL 和客户端消费硬件池输出。 |
| 验证方法 | 测试、演示 |
| 验证入口 | HWPOD 工具、HWPOD 服务、AI 网关、CaseRun |
| 必需证据 | hwpod-id、spec、node health、probe、lease、raw hardware evidence |
| 接受标准 | 真实设备可被发现、绑定、执行、释放和审计。 |
| 需求 ID | 方法 | 原入口 | 必需证据 | 接受标准 |
| --- | --- | --- | --- | --- |
| HWLAB-L0-REQ-001 | 测试/演示 | HWPOD 工具、HWPOD 服务、AI 网关、CaseRun | hwpod-id、spec、node health、probe、lease、raw hardware evidence | 真实设备可被发现、绑定、执行、释放和审计。 |
| HWLAB-L0-REQ-002 | 测试/演示 | Web/CLI/API 提交 Agent 任务、AgentRun trace/result | runId、sessionId、workspace、provider profile、trace、artifact/result pointer | 任务生命周期可跟踪，异常可恢复或明确失败。 |
| HWLAB-L0-REQ-003 | 测试/检查 | CaseRun/Harness/ioProbe/replay | caseId、runId、traceId、aggregate、ioProbe samples/stats、evaluation/replay 输出 | evidence 可审计、可复验、可用于训练反馈。 |
| HWLAB-L0-REQ-004 | 测试/演示 | Cloud Web、hwlab-cli、HTTP API、SDK/Webhook sample | Web smoke、CLI smoke、API response、SDK/Webhook 示例 | 多客户端行为和错误语义一致。 |
| HWLAB-L0-REQ-005 | 测试/检查 | user-billing / auth / API key / usage / admin API | session、API key 摘要、preflight、usage record、credit ledger、admin 操作记录 | 用户和运营真相统一且可审计。 |
| HWLAB-L0-REQ-006 | 检查/演示 | CI/CD、git mirror、YAML render、Secret sync、rollout、observability、GC | PipelineRun、source commit、render、fingerprint、public health、logs/trace、GC summary | 平台发布和运行状态可控、可见、可恢复。 |
| HWLAB-L0-REQ-007 | 检查 | L1/L2/L3/L4 收口评论 | 原入口命令、lane/node、trace/session/job/run/URL、结果摘要 | 关闭证据来自真实入口。 |
| HWLAB-L0-REQ-008 | 检查 | issue 正文和回写评论 | 主责方向、关联方向、回写对象 | 每个非平凡工作只有一个主责 L1。 |
| HWLAB-L0-REQ-009 | 检查 | 项目管理规格文件、历史 issue、阶段报告链接 | 长期规格链接、报告链接、issue 引用 | 稳定需求不只存在于评论或日报中。 |
硬件资源池是 HWLAB 的物理事实源。该能力必须把板卡、probe、HWPOD node 和设备健康状态整理为稳定、可引用、可审计的资源模型，并确保上层任务拿到的是可执行的真实硬件，而不是临时脚本输出或不可复验的运行副本。
## 8. 追踪关系
### 6.2 HWLAB-L0-REQ-002 Agent 执行编排
| L0 需求 | 主责 L1 | 关联 L1 | 规格 issue |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-001 | PJ2026-0101 硬件池 | Agent编排、HarnessRL、客户端、平台运维 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) |
| HWLAB-L0-REQ-002 | PJ2026-0102 Agent编排 | 硬件池、HarnessRL、客户端、用户管理、平台运维 | [#1204](https://github.com/pikasTech/HWLAB/issues/1204) |
| HWLAB-L0-REQ-003 | PJ2026-0103 HarnessRL | 硬件池、Agent编排、客户端、用户管理、平台运维 | [#1205](https://github.com/pikasTech/HWLAB/issues/1205) |
| HWLAB-L0-REQ-004 | PJ2026-0104 客户端 | 用户管理、Agent编排、硬件池、HarnessRL、平台运维 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) |
| HWLAB-L0-REQ-005 | PJ2026-0105 用户管理 | 客户端、Agent编排、HarnessRL、硬件池、平台运维 | [#1207](https://github.com/pikasTech/HWLAB/issues/1207) |
| HWLAB-L0-REQ-006 | PJ2026-0106 平台运维 | 全部 L1 | [#1208](https://github.com/pikasTech/HWLAB/issues/1208) |
| HWLAB-L0-REQ-007 | 全部 L1 | [#1217](https://github.com/pikasTech/HWLAB/issues/1217) 治理索引 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) - [#1208](https://github.com/pikasTech/HWLAB/issues/1208) |
| HWLAB-L0-REQ-008 | 全部 L1 | [#1217](https://github.com/pikasTech/HWLAB/issues/1217) 治理索引 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) - [#1208](https://github.com/pikasTech/HWLAB/issues/1208) |
| HWLAB-L0-REQ-009 | 全部 L1 | 项目管理规格文件、[#1217](https://github.com/pikasTech/HWLAB/issues/1217)、[#1218](https://github.com/pikasTech/HWLAB/issues/1218)、[#644](https://github.com/pikasTech/HWLAB/issues/644)、[#645](https://github.com/pikasTech/HWLAB/issues/645) | [#1194](https://github.com/pikasTech/HWLAB/issues/1194)、[#1203](https://github.com/pikasTech/HWLAB/issues/1203) - [#1208](https://github.com/pikasTech/HWLAB/issues/1208) |
| 字段 | 内容 |
| --- | --- |
| ID | HWLAB-L0-REQ-002 |
| 需求 | HWLAB 应提供 Agent 执行编排，使用户任务能进入受控 workspace/session/provider/runtime，并能跟踪、恢复、取消和归档结果。 |
| 类型 | 功能 |
| 主责模块 | [Agent编排](PJ2026-0102-agent-orchestration.md) |
| 职责划分 | Agent编排负责任务生命周期、workspace、session、provider profile、恢复和归档；硬件池提供可执行资源；用户管理提供身份与权限；平台运维提供运行支撑。 |
| 验证方法 | 测试、演示 |
| 验证入口 | Web/CLI/API 提交 Agent 任务、AgentRun trace/result |
| 必需证据 | runId、sessionId、workspace、provider profile、trace、artifact/result pointer |
| 接受标准 | 任务生命周期可跟踪，异常可恢复或明确失败。 |
## 9. 引用和变更规则
Agent 执行编排负责把用户意图转化为可追踪的受控执行。它必须明确任务状态、运行上下文、执行凭据、结果位置和异常收口，避免用户任务只存在于一次性进程、临时容器或无法恢复的日志片段中。
- L1 划分变化必须更新本文档；本次整理未改变 L1 划分。
- 编号、层级、主责、回写、偏离和交叉引用治理规则见 [#1217](https://github.com/pikasTech/HWLAB/issues/1217)。
- 当前阶段主线、非中心边界和阶段计划见 [#1218](https://github.com/pikasTech/HWLAB/issues/1218) 与 [#644](https://github.com/pikasTech/HWLAB/issues/644)。
- 长期导航见 [#645](https://github.com/pikasTech/HWLAB/issues/645)；[#645](https://github.com/pikasTech/HWLAB/issues/645) 不替代本规格。
- 单次执行证据、CaseRun 日志、PR 流水和阶段报告不得堆入本规格正文，应写入对应 L1/L2/L3/L4 issue、证据索引或项目管理阶段报告。
- 稳定规格最终应沉淀到 `project-management/PJ2026-01`；issue 保留执行状态、讨论、证据链接和交叉引用。
### 6.3 HWLAB-L0-REQ-003 HarnessRL 验收闭环
| 字段 | 内容 |
| --- | --- |
| ID | HWLAB-L0-REQ-003 |
| 需求 | HWLAB 应提供 Harness/RL 验收闭环，使真实硬件任务产出可审计 evidence、aggregate、评估、回放和训练反馈。 |
| 类型 | 功能 |
| 主责模块 | [HarnessRL](PJ2026-0103-harness-rl.md) |
| 职责划分 | HarnessRL 负责 evidence、aggregate、评估、回放和训练反馈；硬件池提供原始硬件事实；Agent编排提供执行上下文；平台运维提供可观测和归档支撑。 |
| 验证方法 | 测试、检查 |
| 验证入口 | CaseRun、Harness、ioProbe、replay |
| 必需证据 | caseId、runId、traceId、aggregate、ioProbe samples/stats、evaluation/replay 输出 |
| 接受标准 | evidence 可审计、可复验、可用于训练反馈。 |
HarnessRL 把一次硬件执行转化为可复验的验证与训练材料。它不得只记录 pass/fail，而要保留可解释的硬件输入、执行过程、采样数据、评估结论和回放入口，使失败分类和成功路径能够进入后续改进闭环。
### 6.4 HWLAB-L0-REQ-004 统一客户端入口
| 字段 | 内容 |
| --- | --- |
| ID | HWLAB-L0-REQ-004 |
| 需求 | HWLAB 应提供统一客户端入口，使 Web、CLI、API、SDK/IDE plugin 和 Webhook 围绕同一任务模型、权限模型和结果模型协同演进。 |
| 类型 | 功能 |
| 主责模块 | [客户端](PJ2026-0104-client.md) |
| 职责划分 | 客户端负责 Web、CLI、HTTP API、SDK/IDE 插件、webhook 和公开文档的一致入口；用户管理提供身份权限；Agent编排、硬件池、HarnessRL 和平台运维提供后端能力。 |
| 验证方法 | 测试、演示 |
| 验证入口 | Cloud Web、hwlab-cli、HTTP API、SDK/Webhook sample |
| 必需证据 | Web smoke、CLI smoke、API response、SDK/Webhook 示例 |
| 接受标准 | 多客户端行为和错误语义一致。 |
统一客户端入口要求不同用户界面共享同一任务、权限、错误和结果语义。Web、CLI、API 和 SDK 可以有不同交互形态，但不能各自定义一套状态机、错误口径或结果读取路径。
### 6.5 HWLAB-L0-REQ-005 用户与运营管理
| 字段 | 内容 |
| --- | --- |
| ID | HWLAB-L0-REQ-005 |
| 需求 | HWLAB 应提供多用户与运营管理，使身份、权限、API key、credit、usage、billing、admin 和租户隔离具有统一真相。 |
| 类型 | 功能 |
| 主责模块 | [用户管理](PJ2026-0105-user-management.md) |
| 职责划分 | 用户管理负责身份、权限、API key、credit、usage、billing、admin 和租户隔离；客户端负责呈现入口；Agent编排、硬件池和 HarnessRL 消费用户与额度约束。 |
| 验证方法 | 测试、检查 |
| 验证入口 | user-billing、auth、API key、usage、admin API |
| 必需证据 | session、API key 摘要、preflight、usage record、credit ledger、admin 操作记录 |
| 接受标准 | 用户和运营真相统一且可审计。 |
用户与运营管理定义平台多用户运行的业务事实。它必须保证用户身份、权限、额度、计量、账务和管理操作可以被统一查询和审计，避免同一用户或同一资源消费在不同入口出现不同真相。
### 6.6 HWLAB-L0-REQ-006 平台交付与运维
| 字段 | 内容 |
| --- | --- |
| ID | HWLAB-L0-REQ-006 |
| 需求 | HWLAB 应提供平台交付与运维能力，使代码、配置、密钥、发布、入口、观测和清理通过受控入口维护。 |
| 类型 | 支撑 |
| 主责模块 | [平台运维](PJ2026-0106-platform-ops.md) |
| 职责划分 | 平台运维负责 CI/CD、git mirror、YAML-first、Secret 下发、rollout、observability、GC 和平台发布；其他模块提供发布、配置和观测需求。 |
| 验证方法 | 检查、演示 |
| 验证入口 | CI/CD、git mirror、YAML render、Secret sync、rollout、observability、GC |
| 必需证据 | PipelineRun、source commit、render、fingerprint、public health、logs/trace、GC summary |
| 接受标准 | 平台发布和运行状态可控、可见、可恢复。 |
平台交付与运维是所有内部模块持续运行的基础能力。它必须让源码、配置、密钥、部署、公开入口、运行观测和资源清理都有受控入口和可追踪证据，不能依赖手工热修、运行面反推或不可复现的命令序列。
### 6.7 HWLAB-L0-REQ-007 用户可见能力关闭验收
| 字段 | 内容 |
| --- | --- |
| ID | HWLAB-L0-REQ-007 |
| 需求 | HWLAB 的用户可见能力关闭前必须经过真实入口验收；源码检查、PR 合并或构建通过不能单独作为关闭依据。 |
| 类型 | 约束 |
| 主责模块 | 全部内部模块 |
| 职责划分 | 定义完成标准的主责模块负责原入口验收；关联模块提供必要上下游证据；执行 issue 负责记录命令、目标 lane/node 和结果摘要。 |
| 验证方法 | 检查 |
| 验证入口 | L1/L2/L3/L4 收口评论 |
| 必需证据 | 原入口命令、lane/node、trace/session/job/run/URL、结果摘要 |
| 接受标准 | 关闭证据来自真实入口。 |
用户可见能力必须以用户真实入口或原始验收入口为关闭依据。代码层证据可以作为辅助材料，但不能替代 Web、CLI、API、CaseRun、AgentRun 或运行面入口的实际结果。
### 6.8 HWLAB-L0-REQ-008 单一主责 L1
| 字段 | 内容 |
| --- | --- |
| ID | HWLAB-L0-REQ-008 |
| 需求 | HWLAB 的下级工作必须且只能有一个主责 L1；跨方向支撑通过关联方向和回写表达，不重复建树。 |
| 类型 | 约束 |
| 主责模块 | 全部内部模块 |
| 职责划分 | 下级工作由定义完成标准的模块承担主责；其他模块只作为关联方向、上游依赖、下游支撑或回写对象出现。 |
| 验证方法 | 检查 |
| 验证入口 | issue 正文和回写评论 |
| 必需证据 | 主责方向、关联方向、回写对象 |
| 接受标准 | 每个非平凡工作只有一个主责 L1。 |
单一主责规则用于防止同一工作在多个方向重复建树。跨模块协作通过依赖、支撑和回写表达，但验收标准和关闭责任只能落到一个主责模块。
### 6.9 HWLAB-L0-REQ-009 长期规格沉淀
| 字段 | 内容 |
| --- | --- |
| ID | HWLAB-L0-REQ-009 |
| 需求 | HWLAB 的稳定需求、验证标准和长期结论应沉淀到 `project-management/PJ2026-01` 的对应规格文件；阶段报告和执行流水不得替代规格。 |
| 类型 | 约束 |
| 主责模块 | 全部内部模块 |
| 职责划分 | L0 负责总使命、范围和全局约束；L1 负责对应模块的稳定需求和验收边界；L2/L3/L4 issue 保留执行状态、讨论、证据链接和关闭回写。 |
| 验证方法 | 检查 |
| 验证入口 | 项目管理规格文件、历史 issue、阶段报告链接 |
| 必需证据 | 长期规格链接、报告链接、issue 引用 |
| 接受标准 | 稳定需求不只存在于评论或日报中。 |
长期规格沉淀要求把稳定要求、验收标准和可复用结论写回项目管理规格文件。阶段报告只描述阶段移动，GitHub issue 只承担执行控制面和证据锚点，不能成为长期规格正文的唯一来源。
project-management/PJ2026-01/specs/current-center.md
-58
View File
@@ -1,58 +0,0 @@
# HWLAB 当前中心索引：阶段主线与非中心边界
## 修改历史
| 版本 | 对应 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 | 从 [#1218](https://github.com/pikasTech/HWLAB/issues/1218) 迁移到 UniDesk 项目管理目录。 |
## 迁移来源
| 字段 | 内容 |
| --- | --- |
| 原 issue | [#1218](https://github.com/pikasTech/HWLAB/issues/1218) |
| 原标题 | HWLAB 当前中心索引：阶段主线与非中心边界 |
| 原 URL | [#1218](https://github.com/pikasTech/HWLAB/issues/1218) |
| 原状态 | open |
| 原更新时间 | 2026-06-14T12:52:18Z |
| 原 body SHA | 1818977dd433ec0ae8390773aed02967f61d1bb90ab30810af2c1337fc3ce5a8 |
## 正文
上级总项目: [#1194](https://github.com/pikasTech/HWLAB/issues/1194)
关联阶段规格: [#644](https://github.com/pikasTech/HWLAB/issues/644)
关联面板: [#645](https://github.com/pikasTech/HWLAB/issues/645)
性质: 阶段中心索引，不是 L1 方向，不是 L2 课题，不重新定义 L1 划分。
迁出来源: [#1194](https://github.com/pikasTech/HWLAB/issues/1194) 旧版“当前中心”章节
迁出时间: 2026-06-14（北京时间）
## 使用规则
- 本文档 保存阶段性主线、非中心边界和计划口径。
- L0 规格只引用本文档，不在规格正文中展开阶段计划。
- 阶段中心变化不等于 L1 划分变化；如确需改变 L1 方向树，必须先回到 [#1194](https://github.com/pikasTech/HWLAB/issues/1194) 按规格变更处理。
- 阶段报告和当天进展不得写入 [#1194](https://github.com/pikasTech/HWLAB/issues/1194) 正文，应写到本文档 评论、[#644](https://github.com/pikasTech/HWLAB/issues/644) 或阶段报告中。
## 当前中心
- 当前主线一：硬件池优先，先保证真实板卡、探针、HWPOD node、设备注册、占用、健康和可用性可被下游稳定引用。
- 当前主线二：Agent编排连接用户任务、workspace、session、provider profile、任务恢复和硬件池资源。
- 当前主线三：HarnessRL 在真实硬件和 Agent 编排之上形成 CaseRun、ioProbe、evidence、评估、回放、训练反馈闭环。
- 当前主线四：客户端和用户管理把平台能力对外开放为 Web/CLI/API/SDK、身份、权限、额度、计量和 admin 能力。
- 当前支撑主线：平台运维通过 CI/CD、git mirror、YAML-first、Secret、rollout、observability 和 GC 保证各方向可持续交付。
## 当前非中心
- 无硬件池、Agent编排、HarnessRL、客户端、用户管理或平台运维归属的孤立工具美化。
- 不解除明确 blocker 的旧门禁修补。
- 无原入口验收的观测增强。
- 只统计 issue/PR 数量、但不能说明对 L1 验收移动的阶段报告。
## 回写规则
- 阶段中心变化时更新本文档，并在 [#1194](https://github.com/pikasTech/HWLAB/issues/1194) 保持引用。
- 如果阶段中心变化影响 L0 使命、范围、L1 方向树或全局需求，必须同步更新 [#1194](https://github.com/pikasTech/HWLAB/issues/1194)。
- 具体执行进展只写入对应 L1/L2/L3/L4 issue 或本文档 评论，不写入 L0 规格正文。
project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md
+124
View File
@@ -0,0 +1,124 @@
# ISO/IEC/IEEE 29148 需求规格模板
## 来源和定位
本模板用于 UniDesk `project-management/` 下的 L0、L1、L2 需求规格文档。模板基线采用 ISO/IEC/IEEE 29148:2018 的需求工程分层思路，并结合 HWLAB 项目管理约束做轻量裁剪。
参考来源：
- ISO/IEC/IEEE 29148:2018：<https://www.iso.org/standard/72089.html>
- IEEE 830-1998 已被替代的官方说明：<https://standards.ieee.org/ieee/830/1222/>
- ReqView 对 29148 模板族的说明：<https://www.reqview.com/doc/iso-iec-ieee-29148-templates/>
- ReqView 的 29148 软件需求规格示例：<https://www.reqview.com/doc/iso-iec-ieee-29148-srs-example/>
使用原则：
- 业务需求规格用于使命和商业目标，利益相关方需求规格用于用户和运营方诉求，系统需求规格用于跨硬件、软件、人员和流程的系统级要求，软件需求规格用于软件能力要求，运行概念文档用于描述主要运行场景。
- HWLAB 的 L0、L1、L2 规格共用同一骨架，但粒度不同：L0 写使命、边界和全局需求；L1 写内部模块职责和验收边界；L2 写具体课题的交付物、阻塞项和验证计划。
- 规格正文只写稳定需求、边界、职责、验证和必要追踪关系；阶段报告、执行流水、长日志、拉取请求过程和一次性证据放到 GitHub 议题、阶段报告或证据索引中。
- 每条原子需求使用独立小节。信息表中必须包含主责、职责划分、验证入口、必需证据和接受标准；正文说明需求意图和边界。
## 文档骨架
```markdown
# <编号> <短名> 需求规格
## 修改历史
| 版本 | 对应提交标识 | 更新日期 | 变更说明 |
| --- | --- | --- | --- |
| v0.1 | 待提交 | <年-月-日> | 创建需求规格。 |
## 迁移来源
| 字段 | 内容 |
| --- | --- |
| 原 GitHub 议题 | [#<编号>](https://github.com/<组织>/<仓库>/issues/<编号>) |
| 原标题 | <标题> |
| 原状态 | <打开或关闭> |
| 原更新时间 | <时间戳> |
| 原正文摘要标识 | <摘要标识> |
## 正文
## <编号> <短名> 需求规格
## 1. 文档控制
| 字段 | 内容 |
| --- | --- |
| 编号 | <项目编号> |
| 短名 | <短名> |
| 层级 | L0、L1 或 L2 |
| 状态 | 有效、草案或归档 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](<相对路径>) |
| 上级规格 | <相对路径链接；L0 可留空> |
| 阶段规格 | <相对路径链接；不适用时留空> |
| 规格治理索引 | <相对路径链接> |
| 规格来源 | <项目管理路径、历史材料或 GitHub 议题> |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留稳定使命、范围、运行概念、系统边界、内部模块或课题分工、原子需求和验证口径。编号、层级职责、回写、偏离判定和交叉引用治理由规格治理文档承载。
## 2. 目的和范围
### 2.1 目的
<用一段话说明该规格服务的项目目标、用户目标或系统目标。>
### 2.2 范围内
- <范围项>
### 2.3 范围外
- <非目标或转交范围>
## 3. 运行概念
1. <关键场景或运行步骤>
## 4. 系统边界和接口
| 类别 | 内容 |
| --- | --- |
| 用户入口 | <网页端、命令行、应用接口、开发工具包等> |
| 上游系统 | <依赖来源> |
| 下游系统 | <输出消费方> |
| 验收入口 | <测试、演示、检查或分析入口> |
| 长期文档 | <规格、计划、测试规格、阶段报告> |
| 执行控制面 | <议题、拉取请求、跟踪记录、会话、任务、运行记录或案例登记> |
## 5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| <项目编号> | <短名> | [<规格名>](<相对路径>) | <主责> | <依赖> | <支撑对象> |
## 6. 原子需求
### 6.1 <需求编号> <需求短名>
| 字段 | 内容 |
| --- | --- |
| 编号 | <需求编号> |
| 需求 | <系统或模块应当具备的能力或约束> |
| 类型 | 功能、约束、支撑、接口或质量 |
| 主责模块 | <相对路径链接或主责编号> |
| 职责划分 | <主责负责什么；关联模块负责什么；哪些内容不属于本需求> |
| 验证方法 | 测试、演示、检查或分析 |
| 验证入口 | <命令行、网页端、应用接口、案例运行、跟踪记录等原入口> |
| 必需证据 | <运行编号、跟踪编号、链接、日志摘要、报告链接等> |
| 接受标准 | <可判定的完成标准> |
<正文说明该原子需求的意图、范围、边界和验收语义。正文不放执行流水和长证据。>
## 7. 假设和风险
- <只写会影响需求或验证的稳定假设和风险。>
## 8. 变更控制
- 稳定需求变化必须更新本文档。
- 阶段计划和执行流水不得替代本文档。
- 下级工作完成后按规格治理文档回写。
```