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

docs: keep HWLAB requirements focused

Browse Source
This commit is contained in:
Codex
2026-06-14 16:19:08 +00:00
parent 03b47aefff
commit 43b713a553
4 changed files with 45 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/unidesk-oa/SKILL.md
+2 -1
View File
@@ -33,7 +33,8 @@ description: UniDesk 项目管理运行技能。用户提到 UniDesk 项目管
- L0 系统边界必须把 HWLAB 作为完整系统看待，描述外部使用者、外部输入、受控资源、外部输出、用户接口和系统责任边界，不写内部治理材料。
- 稳定概念用术语表表达；不要写没有判定价值的“运行概念”流水。
- L0 的 L1 方向树和项目规格索引合并为内部模块分工与规格索引，用相对路径索引到每个内部模块规格文档。
- 原子需求每条独立成节，信息表使用横向表格 `编号 | 需求 | 主责模块 | 职责划分`。主责模块必须带项目编号和相对路径链接；不写 `类型`、`验证方法`、`验证入口`、`必需证据`、`接受标准`，正文只说明意图和边界，不重复需求句。
- 原子需求每条独立成节，信息表使用横向表格且只放短元数据，推荐列为 `编号 | 短名 | 主责模块 | 关联模块`。主责模块必须带项目编号和相对路径链接；禁止把需求句、职责划分、验收口径或大段说明塞进表格，正文必须承载需求定义、职责边界、意图和范围。
- 不要为了凑全局原子需求条数自动添加次要派生能力。证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包/结果收集等需求，除非用户明确授意，不得写入 OA 规格或 L0 原子需求。
- 平台运维在 L0 中只能作为支撑后勤职责出现；对外需求应写成系统可用性、可恢复、资源可控等用户可感知能力，不写成“HWLAB 对外提供平台运维能力”。
- 单一主责、关闭验收、规格沉淀、回写和偏离判定是治理规则，不得伪装成 L0 原子需求。
.agents/skills/unidesk-oa/references/templates.md
+3 -3
View File
@@ -71,11 +71,11 @@
### 6.1 HWLAB-L0-REQ-001 <需求短名>
| 编号 | 需求 | 主责模块 | 职责划分 |
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-001 | <HWLAB 应提供的对外系统能力> | [PJ2026-0101 <主责模块>](<相对路径>) | <主责负责什么；关联模块负责什么；哪些内容不属于本需求> |
| HWLAB-L0-REQ-001 | <需求短名> | [PJ2026-0101 <主责模块>](<相对路径>) | [<关联模块>](<相对路径>) |
<正文说明该原子需求的意图、范围和边界。正文不重复需求句，不写类型、验证方法、验证入口、必需证据或接受标准。>
<正文第一段写完整需求定义。正文后续段落写主责职责、关联模块职责、意图、范围和边界。不要把需求句、职责划分、类型、验证方法、验证入口、必需证据或接受标准塞进表格。不要为了凑条目自动添加证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包或结果收集类次要需求。>
```
## L0 issue 正文
project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md
+35 -35
View File
@@ -98,72 +98,72 @@ L1 划分保持现有六个内部能力模块；本章同时作为内部模块
### 6.1 HWLAB-L0-REQ-001 硬件资源池
| 编号 | 需求 | 主责模块 | 职责划分 |
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-001 | HWLAB 应提供真实硬件资源池，使任务能发现、分配、占用、释放并验证真实设备、probe、HWPOD node 和健康状态。 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) | 硬件池负责设备身份、能力声明、占用释放、健康和原始硬件事实；平台运维提供运行与发布支撑；Agent编排、HarnessRL 和客户端消费硬件池输出。 |
| 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 | HWLAB 应提供 Agent 执行编排，使用户任务能进入受控 workspace/session/provider/runtime，并能跟踪、恢复、取消和归档结果。 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | Agent编排负责任务生命周期、workspace、session、provider profile、恢复和归档；硬件池提供可执行资源；用户管理提供身份与权限；平台运维提供运行支撑。 |
| 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 | HWLAB 应提供 Harness/RL 验收闭环，使真实硬件任务产出可审计 evidence、aggregate、评估、回放和训练反馈。 | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | HarnessRL 负责 evidence、aggregate、评估、回放和训练反馈；硬件池提供原始硬件事实；Agent编排提供执行上下文；平台运维提供可观测和归档支撑。 |
| 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 验收闭环，使真实硬件任务产出可审计 evidence、aggregate、评估、回放和训练反馈。
HarnessRL 把一次硬件执行转化为可复验的验证与训练材料。它不得只记录 pass/fail，而要保留可解释的硬件输入、执行过程、采样数据、评估结论和回放入口，使失败分类和成功路径能够进入后续改进闭环。
HarnessRL 负责 evidence、aggregate、评估、回放和训练反馈。硬件池提供原始硬件事实，Agent编排提供执行上下文，平台运维提供可观测和归档支撑，客户端和用户管理消费验收结果与统计信息。
### 6.4 HWLAB-L0-REQ-004 统一客户端入口
| 编号 | 需求 | 主责模块 | 职责划分 |
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-004 | HWLAB 应提供统一客户端入口，使 Web、CLI、API、SDK/IDE plugin 和 Webhook 围绕同一任务模型、权限模型和结果模型协同演进。 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | 客户端负责 Web、CLI、HTTP API、SDK/IDE 插件、webhook 和公开文档的一致入口；用户管理提供身份权限；Agent编排、硬件池、HarnessRL 和平台运维提供后端能力。 |
| 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、API、SDK/IDE plugin 和 Webhook 围绕同一任务模型、权限模型和结果模型协同演进。
统一客户端入口要求不同用户界面共享同一任务、权限、错误和结果语义。Web、CLI、API 和 SDK 可以有不同交互形态，但不能各自定义一套状态机、错误口径或结果读取路径。
客户端负责 Web、CLI、HTTP API、SDK/IDE 插件、webhook 和公开文档的一致入口。用户管理提供身份权限，Agent编排、硬件池、HarnessRL 和平台运维提供后端能力；客户端不重新定义这些后端事实。
### 6.5 HWLAB-L0-REQ-005 用户与运营管理
| 编号 | 需求 | 主责模块 | 职责划分 |
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-005 | HWLAB 应提供多用户与运营管理，使身份、权限、API key、credit、usage、billing、admin 和租户隔离具有统一真相。 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | 用户管理负责身份、权限、API key、credit、usage、billing、admin 和租户隔离；客户端负责呈现入口；Agent编排、硬件池和 HarnessRL 消费用户与额度约束。 |
| 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 | HWLAB 应作为云端服务保持可访问、可恢复、资源使用可控，使用户能够稳定提交任务、查看状态和获取结果。 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | 平台运维作为后勤模块负责发布、配置、密钥、观测、资源清理和故障恢复支撑；客户端、Agent编排、硬件池、HarnessRL 和用户管理提供各自服务健康和资源需求。 |
| 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 的基础条件。用户感知到的是入口可访问、任务不中途丢失、故障后有恢复路径、资源不会被失控占用；平台运维只作为后勤职责支撑这些对外结果。
### 6.7 HWLAB-L0-REQ-007 任务状态与结果获取
| 编号 | 需求 | 主责模块 | 职责划分 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-007 | HWLAB 应向用户提供任务全生命周期状态和结果获取能力，使用户能查询任务进展、当前阻塞、最终产物、关键 evidence 摘要和结果位置。 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | 客户端负责统一呈现和查询入口；Agent编排提供任务状态、执行上下文和结果指针；HarnessRL 提供 evidence 摘要；用户管理保证用户只能读取有权限的任务与结果。 |
该需求面向用户对“任务现在到哪里了、产物在哪里、失败卡在哪一步”的基本可见性。不同入口可以有不同呈现方式，但必须围绕同一任务状态和结果模型，避免 Web、CLI、API 看到互相矛盾的进度或结果。
### 6.8 HWLAB-L0-REQ-008 失败诊断与恢复建议
| 编号 | 需求 | 主责模块 | 职责划分 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-008 | HWLAB 应把 Agent 执行、硬件操作、权限额度和平台运行中的失败转化为用户可理解的错误分类、上下文和恢复建议。 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | Agent编排负责把执行失败归入任务生命周期；硬件池提供设备、probe 和 HWPOD 错误语义；HarnessRL 提供 evidence 与评估上下文；客户端负责向用户展示可操作的下一步；平台运维提供平台故障状态。 |
该需求要求失败信息从“底层日志碎片”提升为用户能处理的问题描述。系统应区分权限不足、额度不足、硬件不可用、probe 不匹配、构建失败、下载失败、Agent 执行失败和平台不可用等类别，并给出可执行的下一步处理方向。
### 6.9 HWLAB-L0-REQ-009 结果包与复现线索
| 编号 | 需求 | 主责模块 | 职责划分 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-009 | HWLAB 应为完成的硬件研发任务提供可获取、可引用的结果包，使用户能获得产物、关键 evidence、环境摘要、资源摘要和复现线索。 | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | HarnessRL 负责整理 evidence、评估结果和复现线索；Agent编排提供 workspace、session 和执行上下文；硬件池提供设备和 HWPOD 资源摘要；客户端负责结果包获取入口。 |
结果包是用户离开一次在线任务后仍能理解、复查和继续工作的交付物。它不要求完整复制所有运行日志，但必须保留足以解释结果、定位关键环境和支撑后续复现的摘要信息。
平台运维负责发布、配置、密钥、观测、资源清理和故障恢复支撑。客户端、Agent编排、硬件池、HarnessRL 和用户管理提供各自服务健康和资源需求，并通过平台运维获得运行保障。
project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md
+5 -4
View File
@@ -16,7 +16,8 @@
- 业务需求规格用于使命和商业目标，利益相关方需求规格用于用户和运营方诉求，系统需求规格用于跨硬件、软件、人员和流程的系统级要求，软件需求规格用于软件能力要求。运行流程和一次性执行过程不进入需求规格正文，稳定概念优先沉淀为术语表。
- HWLAB 的 L0、L1、L2 规格共用同一骨架，但粒度不同：L0 写使命、边界和全局需求；L1 写内部模块职责和验收边界；L2 写具体课题的交付物、阻塞项和验证计划。
- 规格正文只写稳定需求、系统边界、外部输入输出、职责和必要追踪关系；内部治理、阶段报告、执行流水、长日志、拉取请求过程和一次性证据不进入需求规格正文。
- 每条原子需求使用独立小节。信息表使用横向表格，必须包含编号、需求、主责模块和职责划分；正文只说明需求意图和边界，不重复需求句。
- 每条原子需求使用独立小节。信息表使用横向表格且只放短元数据，推荐包含编号、短名、主责模块和关联模块；需求定义、职责划分、意图、范围和边界写在正文中，避免表格厚而正文薄。
- 不要为了凑全局需求条目自动添加证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包或结果收集类次要需求；除非用户明确授意，这些内容不进入 OA 规格。
## 文档骨架
@@ -92,11 +93,11 @@
### 6.1 <需求编号> <需求短名>
| 编号 | 需求 | 主责模块 | 职责划分 |
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| <需求编号> | <系统或模块应当具备的能力或约束> | <项目编号 短名，使用相对路径链接> | <主责负责什么；关联模块负责什么；哪些内容不属于本需求> |
| <需求编号> | <需求短名> | <项目编号 短名，使用相对路径链接> | <关联模块，使用相对路径链接> |
<正文说明该原子需求的意图、范围和边界。正文不重复需求句，不放执行流水和长证据。>
<正文第一段写完整需求定义。正文后续段落写主责职责、关联模块职责、意图、范围和边界。正文不放执行流水和长证据。>
## 7. 假设和风险