Codex
9.8 KiB
9.8 KiB
UniDesk OA 模板
L0 总规格骨架
# PJ2026-01 HWLAB 总规格
## 修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |
| v0.1 | <commit> | <YYYY-MM-DD> | 创建需求规格；如来自历史 issue，只在这里写迁移来源 <owner>/<repo>#<number>。 |
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
## 正文
## PJ2026-01 HWLAB 总项目需求规格
## 1. 文档控制
| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-01 |
| 短名 | HWLAB |
| 层级 | L0 总项目 |
| 状态 | 已生效、已废弃或未生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
## 2. 目的和范围
### 2.1 项目使命
<用一段话描述对外系统目标和用户价值。>
### 2.2 范围内
- <系统能力范围>
### 2.3 范围外
- <不属于本规格的对象>
## 3. 术语表
| 术语 | 定义 |
| --- | --- |
| <术语> | <稳定定义> |
## 4. 系统边界和接口
本规格把 HWLAB 作为一个完整系统看待；本章只描述外部输入、外部输出和系统边界，不描述内部治理流程。
| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | <用户、管理员或自动化任务> |
| 外部输入 | <用户请求、业务对象、资源约束、身份凭据、文件或硬件选择> |
| 受控资源 | <系统管理的设备、数据、运行环境或外部资源> |
| 外部输出 | <用户可获得的状态、结果、产物、通知、报告或记录> |
| 用户接口 | <Web、CLI、HTTP API 等> |
| 系统边界 | <系统负责什么；明确不替代用户、管理员或运行环境负责什么> |
## 5. 内部模块分工与规格索引
| 编号 | 内部模块 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-0101 | 硬件池 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) | <主责> | <依赖> | <支撑对象> |
## 6. 全局原子需求
### 6.1 HWLAB-L0-REQ-001 <需求短名>
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| HWLAB-L0-REQ-001 | <需求短名> | [PJ2026-0101 <主责模块>](<相对路径>) | [<关联模块>](<相对路径>) |
<正文第一段写完整需求定义。主责模块必须写下一层主责单元：L0 写 L1，L1 写 L2，L2 写 L3，不重复当前规格本级。正文后续段落写主责职责、关联模块职责、意图、范围和边界。不要把需求句、职责划分、类型、验证方法、验证入口、必需证据或接受标准塞进表格。不要为了凑条目自动添加证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包或结果收集类次要需求。>
L0 issue 正文
目标合并分支: 不适用
原因: 本 issue 是 HWLAB Cloud M1 总项目管理锚点，代码变更由下级 issue/PR 承载。
编号: PJ2026-01
短名: HWLAB
上级面板: [#645](https://github.com/pikasTech/HWLAB/issues/645)
当前 L0 总规格: [#1194](https://github.com/pikasTech/HWLAB/issues/1194)
总规格文档: project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md
## 项目中心
- 当前主线:
- 当前非主线但保留:
- 暂停/等待:
## L1 方向
- [ ] PJ2026-0101 [#<issue-number>](https://github.com/pikasTech/HWLAB/issues/<issue-number>) 硬件池:
- [ ] PJ2026-0102 [#<issue-number>](https://github.com/pikasTech/HWLAB/issues/<issue-number>) Agent编排:
- [ ] PJ2026-0103 [#<issue-number>](https://github.com/pikasTech/HWLAB/issues/<issue-number>) HarnessRL:
- [ ] PJ2026-0104 [#<issue-number>](https://github.com/pikasTech/HWLAB/issues/<issue-number>) 客户端:
- [ ] PJ2026-0105 [#<issue-number>](https://github.com/pikasTech/HWLAB/issues/<issue-number>) 用户管理:
- [ ] PJ2026-0106 [#<issue-number>](https://github.com/pikasTech/HWLAB/issues/<issue-number>) 平台运维:
方向判定: L1 必须是直接服务 L0 的能力域；文档整理、项目管理、看板维护、技能维护、仓库名、工具名和临时执行路径不得作为 L1。
编号规则: 项目编号格式为 PJ<立项年份>-<层级路径>；PJ 表示项目，HWLAB L0 为 PJ2026-01；L1 为 PJ2026-0101；L2 继续追加两位，例如 PJ2026-010102 表示 HWLAB L1 第 1 个方向下的第 2 个 L2 课题；更深层级继续每级追加两位。短名一般控制在 8 个中文汉字以内，解释写入正文说明。
## 职责边界
| 层级 | 负责定义 | 不负责 | 回写对象 |
| --- | --- | --- | --- |
| L0 | 项目使命、范围、系统边界、内部模块分工、全局原子需求 | PR 细节、CaseRun 日志、日报流水、内部治理规则 | L0 规格文件、L1 issue |
| L1 | 能力域范围、成功标准、L2 课题清单、原入口验收类型 | 单个 PR、一次 smoke、仓库/工具/运行面名称、项目管理动作 | L0 规格文件、对应 L1 规格文件 |
| L2 | 单个方向内的具体课题、交付物、阻塞、验收计划 | 总方向定义、实现细节流水 | L1 issue，重大移动再回写 L0 |
| L3 | 一个有界验收切片和单一验收路径 | 路线图、跨课题计划、父级范围变化 | L2/L1 issue |
| L4 | PR、CaseRun、smoke、部署、文档收口等执行和证据 | 新需求、新方向、验收规则变化 | 最近的 L3/L2/L1 |
## 全局验收
- ...
## 偏离判定
- 无上级方向的任务不得直接作为实现任务推进。
- 无原入口验收的任务不得关闭。
- 日报/阶段报告只总结，不替代总规格。
## 回写规则
- 下级 issue 关闭时必须评论回写到对应 L1。
- L1 阶段完成时必须回写本 issue，并更新 `project-management/PJ2026-01` 中的对应规格文件。
L1 方向 issue 正文
目标合并分支: 不适用
原因: 本 issue 是方向级项目管理锚点，代码变更由下级课题/子课题 issue 承载。
编号: PJ2026-010N
短名: <8字以内>
上级总项目: [#1194](https://github.com/pikasTech/HWLAB/issues/1194)
总规格文档: project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md
## 主责边界
- 主责对象:
- 不负责:
- 交接方向:
## 交叉引用
- 上游依赖:
- 下游支撑:
- 接口/证据边界:
- 需同步回写:
## 方向目标
...
## 边界
- 范围内:
- 范围外:
## L2 课题
- [ ] [#<issue-number>](https://github.com/pikasTech/HWLAB/issues/<issue-number>)
## 验收标准
- 原入口:
- 运行入口/lane:
- 证据:
## 当前阻塞
- ...
## 回写规则
- 下级 L2/L3 完成后评论回写本 issue。
- 方向状态变化后更新 L0 规格和对应 L1 规格文件。
L2/L3 执行 issue 头部
目标合并分支: <仓库分支/lane>
编号: PJ2026-010N0M
短名: <8字以内>
上级总项目: [#1194](https://github.com/pikasTech/HWLAB/issues/1194)
主责方向: PJ2026-010N <短名>
关联方向: <可空；只列交接方向，不替代主责>
所属方向: [#<issue-number>](https://github.com/pikasTech/HWLAB/issues/<issue-number>)
所属课题: [#<issue-number>](https://github.com/pikasTech/HWLAB/issues/<issue-number>)
规格文档: project-management/PJ2026-01/specs/<对应规格文件>.md
## 目标
...
## 验收入口
- CLI/Web/CaseRun:
- 目标 lane/node:
- 必需证据:
## 完成后回写
- [ ] 评论回写所属课题
- [ ] 评论回写所属方向
- [ ] 如稳定规则变化，更新 `project-management/PJ2026-01` 中的对应规格文件
重大规划型 issue P0 SPEC 先行块
## P0 SPEC 先行
- SPEC 编号: PJ2026-010N0M
- SPEC 文档: project-management/PJ2026-01/specs/<对应规格文件>.md
- 上级规格: project-management/PJ2026-01/specs/<父级规格>.md
- 关联规格: <Web/API/AgentRun/平台运维等相关 SPEC>
- 实现引用版本: draft-YYYY-MM-DD-p0
- 目标图:
- [ ] 架构图已写入 SPEC
- [ ] 数据流图已写入 SPEC
- [ ] 关键时序图已写入 SPEC
- 代码引用规则:
- [ ] 本 issue 范围内新增或修改源码文件头部必须标注 `SPEC: <编号> <短名> <实现引用版本>`
- [ ] 自动生成、vendored、纯配置、锁文件或二进制产物如不能加头部，必须能从生成器/渲染器/配置入口追溯到 SPEC
后续实现只能在 P0 SPEC 编号、目标图和代码引用规则确认后开始。若后续讨论改变稳定需求、数据流、接口或验收口径，先更新 SPEC，再更新本 issue 计划。
SPEC 图与代码引用章节片段
### 5.1 目标架构图
```mermaid
flowchart LR
A[入口] --> B[服务边界]
B --> C[持久化或运行事实]
C --> D[用户/运维可见输出]
```
### 5.2 目标数据流图
```mermaid
flowchart TD
A[外部输入] --> B[校验/归一化]
B --> C[权威状态]
C --> D[投影/查询]
D --> E[外部输出]
```
### 5.3 关键时序图
```mermaid
sequenceDiagram
participant U as 用户或调用方
participant C as 客户端
participant S as 服务端
participant R as 运行事实
U->>C: 发起动作
C->>S: 受控请求
S->>R: 读取或写入事实
R-->>S: 事实结果
S-->>C: 稳定响应
C-->>U: 用户可见结果
```
### 6.N <REQ> SPEC-first 与代码引用
本能力的实现必须先引用本规格，再进入代码变更。该规划型 issue 范围内新增或修改的源码文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如 `SPEC: PJ2026-010N0M <短名> draft-YYYY-MM-DD-p0`，并用一句话说明文件职责。实现文件不得只写 issue 编号、`latest` 或 `current` 作为规格引用。
阶段报告章节
## YYYY年M月D日阶段报告（北京时间）
- 统计口径
- 时间窗口:
- 核对仓库:
- issue/PR 范围:
- 对总目标的移动
- ...
- 已完成验收
- ...
- 未完成/跨日
- ...
- 偏离评估
- ...
- 下一阶段目标
- ...