# UniDesk OA 模板

## SPEC 正文边界

- SPEC 只写预期终态、目标能力、稳定边界和验收契约。
- 文档控制中的“状态”只表示规格生命周期，不表示实现进度。
- SPEC 不增加“实现状态”“当前基线”“当前阻塞”或“已完成能力”章节。
- 当前状态、阶段差距和实现证据进入阶段报告、任务报告、偏离记录或 GitHub issue。
- 源码路径、commit、PR、作业、日志、截图和样片清单不得作为 SPEC 规范性正文。

## L0 总规格骨架

```markdown
# 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 正文

```markdown
目标合并分支: 不适用
原因: 本 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 正文

```markdown
目标合并分支: 不适用
原因: 本 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 头部

```markdown
目标合并分支: <仓库分支/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 先行块

```markdown
## 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 图与代码引用章节片段

````markdown
### 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` 作为规格引用。
````

## 阶段报告章节

```markdown
## YYYY年M月D日阶段报告（北京时间）

- 统计口径
  - 时间窗口:
  - 核对仓库:
  - issue/PR 范围:

- 对总目标的移动
  - ...

- 已完成验收
  - ...

- 未完成/跨日
  - ...

- 偏离评估
  - ...

- 下一阶段目标
  - ...
```
