# UniDesk OA 项目规划

## 目的

HWLAB Cloud M1 需要一个项目控制结构，避免局部 issue/PR 工作偏离中心。使用接近科研项目的层级：

- 重大项目：总体使命、产品目标、交付边界，例如 HWLAB 的 `PJ2026-01`。
- 方向：重大项目下的稳定能力域，直接服务 L0 使命，例如 `PJ2026-0101`、`PJ2026-0102`。
- 课题：某个方向内的具体工作计划，例如 `PJ2026-010102` 表示 HWLAB L1 第 1 个方向下的第 2 个 L2 课题。
- 子课题：具有明确验收标准的有界验证切片，继续追加两位编号。
- 执行任务：issue、PR、CaseRun、smoke、部署或文档收口；需要长期管理编号时继续追加两位。

## 文档和 issue 分工

用文档承载长期真相：

- 总规格。
- 方向实施方案。
- 测试/验收规格。
- 决策依据。
- 稳定验收标准。

SPEC 只承载预期终态：

- 目标能力和稳定责任边界。
- 目标架构、数据流、接口和原子需求。
- 可重复执行的验收契约。
- 规格生命周期状态可以记录已生效、未生效或已废弃，但不等于实现进度。

SPEC 不承载执行态：

- 当前实现状态、阶段基线和本轮差距。
- 已完成、未完成、当前阻塞和临时运行面。
- 源码路径、commit、PR、作业、日志、截图、样片或一次性验收证据。

用 issue 承载执行状态：

- 当前负责人和状态。
- 讨论和证据。
- 跨仓引用。
- PR 和 commit 链接。
- 运行 trace、session、job ID。
- 收口评论。
- 长证据索引、CaseRun registry、运行日志、历史 issue 摘要。

阶段报告、任务报告和偏离记录承载跨 issue 的状态汇总。不得为了保存执行进度，把这些内容回填到 SPEC 规范性正文。

不要把稳定需求的唯一副本放在 issue 评论里。长期有效的需求必须蒸馏到对应 `project-management/PJ*/` 项目编号目录，再从 issue 链接过去。
不要把长证据正文放进项目管理目录。项目管理目录只承载规格、治理和阶段中心；长证据保留在 GitHub issue。
规格文件和 GitHub issue 的引用规则分开处理：

- 规格文件不保留单独的迁移来源块：
  - 范围是 `project-management/PJ*/specs/*.md`；
  - 历史来源只写在修改历史 `v0.1` 变更说明中；
  - 格式为 `迁移来源 <owner>/<repo>#<number>`。
- 规格文件引用其他规格时，使用同目录相对路径 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。

## 重大规划型 issue 的 P0 SPEC-first 规则

涉及新能力、跨模块架构、用户可见工作流、长期 API/数据模型、平台运维能力或多阶段实施的大规划型 issue，P0 必须先维护对应 SPEC，再继续实现。issue 只能记录执行状态、讨论和证据，不能成为稳定需求、架构、数据流、时序或验收口径的唯一正文。

P0 SPEC 必须完成：

- 分配或确认 SPEC 编号、短名、层级、主责 L1/L2、上级规格和关联规格。
- 按模板写清文档控制、目的和范围、术语表、系统边界、内部分工、原子需求和过程控制。
- 为涉及实现架构的数据面补齐目标架构图、数据流图和关键时序图；图形优先使用 Markdown 内嵌 `mermaid`。
- 在 SPEC 中写明后续代码文件头部应标注的 SPEC 编号、短名和实现引用版本。
- 把正文写成预期终态，不以当前实现、阶段基线或未完成清单解释目标。

后续代码阶段只能在 P0 SPEC 明确后开始。后续讨论改变稳定需求、数据流、接口或验收口径时，先更新 SPEC，再更新 issue 计划。该规划型 issue 范围内新增或修改的源码文件，文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本；自动生成文件、第三方 vendored 文件、纯配置、锁文件和不能承载注释头的二进制产物可例外，但对应生成器、渲染器或配置入口必须能追溯到 SPEC。

## 当前 HWLAB issue 锚点

- L0 总规格：`project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md`。该规格文档本身承担索引职责；历史 issue 为 `[#1194](https://github.com/pikasTech/HWLAB/issues/1194)`。
- 长期面板/导航：`[#645](https://github.com/pikasTech/HWLAB/issues/645)`（`HWLAB 长期总面板`）。不要把它当成规格书。
- Cloud M1 阶段规格：`project-management/PJ2026-01/specs/stage-cloud-spec-20260601.md`。这是阶段规格，不是 L1 方向；历史 issue 为 `[#644](https://github.com/pikasTech/HWLAB/issues/644)`。
- 新建或更新方向/课题/执行 issue 时，除非用户明确限定在 HWLAB Cloud M1 之外，否则正文应包含 `上级总项目: [#1194](https://github.com/pikasTech/HWLAB/issues/1194)`。

## 编号规则

- HWLAB L0 项目编号是 `PJ2026-01`：`PJ` 表示项目，`2026` 是立项年份，`01` 是 HWLAB L0 序号。
- L1 方向编号为 `PJ2026-0101`、`PJ2026-0102`、`PJ2026-0103` 等。
- L2 课题编号在 L1 编号后继续追加两位，例如 `PJ2026-010101`、`PJ2026-010102`、`PJ2026-010201`。
- L3/L4 长期管理编号继续每级追加两位，例如 `PJ2026-01010203` 表示 HWLAB L1 第 01 个 / L2 第 02 个 / L3 第 03 个。
- 不要因为优先级变化而重编号。新稳定节点追加新后缀；执行型 PR 或一次性 smoke 可以引用最近的稳定编号，不一定单独编号。
- 稳定节点短名通常不超过 8 个中文汉字。issue 标题应以编号和短名开头，例如 `PJ2026-010102 频源造模`；详细解释写在正文。

## 建议的 UniDesk 项目管理结构

HWLAB Cloud M1 的长期文档放在 UniDesk 仓库内，并使用项目编号命名目录：

```text
/root/unidesk/project-management/PJ2026-01/
```

推荐文件：

```text
specs/PJ2026-01-HWLAB.md                 # L0 总规格，同时作为项目索引
specs/stage-cloud-spec-20260601.md       # 既有阶段材料，同时承载阶段中心和非中心边界
specs/PJ2026-010N-*.md                   # L1 方向规格
specs/spec-governance.md                 # 编号、层级、回写与偏离规则
```

优先维护 L0 总规格作为入口索引。只有当某个部分具有独立生命周期和评审需要时才拆分到 L1、治理或阶段文件。
禁止在本目录新增 `evidence/` 或其他长证据目录；证据入口在 L0/L1 规格中引用 GitHub issue。
禁止在规格文件正文链接证据 issue；只写“长证据保留在对应 GitHub 证据 issue”这类归属说明。证据 issue 的完整链接保留在 GitHub issue 正文或评论里。

每个长期规格文件最前面必须有修改历史表格，字段固定为：

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |

版本号随稳定规格变更递增；对应 commit id 写入承载该版本内容的 Git commit；变更说明用一句话概括。

## L0-L4 规则

### 职责边界

使用层级做职责拆分，而不只是编号：

| 层级 | 负责 | 不负责 | 回写到 |
| --- | --- | --- | --- |
| L0 | 使命、非目标、预期终态、方向树、全局验收 | 当前中心、PR/CaseRun/日报与实现设计 | L0 规格和 L1 issue |
| L1 | 能力域范围、成功标准、L2 课题清单、原始验收类型 | 单个 PR、一次性 smoke、仓库/工具/运行面名称、项目管理动作 | L0 规格和对应 L1 规格文件 |
| L2 | 一个 L1 内的具体课题、目标交付物和验证计划 | 当前阻塞、宽泛能力域或实现细节流水 | L1 issue，重大移动再回写 L0 |
| L3 | 一个有界验收切片和单一验收路径 | 路线图、多课题计划、父级范围变化 | L2/L1 issue 并带证据 |
| L4 | 具体执行：PR、CaseRun、smoke、部署、文档收口 | 新需求、新方向、验收规则变化 | 最近的 L3/L2/L1，并带原入口证据 |

分类规则：

- 改变使命、预期终态、L1 列表或全局验收的，属于 L0。
- 定义可以容纳多个课题的稳定能力域的，属于 L1。
- 在一个方向内规划具体工作计划的，属于 L2。
- 可以通过一个有界路径验收的，属于 L3。
- 一个 PR、一个 CaseRun、一次 smoke、一次部署或一次文档收口，属于 L4。

### L0 重大项目

L0 定义：

- 使命和非目标。
- 预期终态。
- 产品入口。
- 方向列表。
- 全局验收标准。
- 跨仓真相源。
- issue 层级索引。
- 偏离指标。

通常应该有一个 L0 GitHub issue 和一个 L0 总规格文档。对 HWLAB 来说，标准 L0 编号是 `PJ2026-01`，标准 L0 issue 是 `[#1194](https://github.com/pikasTech/HWLAB/issues/1194)`；`[#645](https://github.com/pikasTech/HWLAB/issues/645)` 只作为长期面板/导航入口。

### L1 方向

L1 方向是直接服务 L0 使命的顶层能力域，不是项目管理工件。

每个方向必须回答：

- 它服务 L0 目标的哪一部分。
- 什么终态算完成。
- 涉及哪些仓库、分支、lane。
- 哪个原始用户/运行面入口可以验收它。
- 目标 L2 课题有哪些。

以下内容不能作为 L1 方向：

- 文档整理、阶段报告、issue/body 维护。
- 项目管理机制、看板维护、技能维护或 OA 流程工作。
- 仓库名、工具名、CLI 名、服务名、运行面 lane 或临时执行路径。
- 单个 PR、一个 CaseRun、一次 smoke、一个 bug 或一个迁移步骤。

主责 L1 规则：

- L1 是验收主责，不是宽泛标签。每个非平凡 L2/L3/L4 issue 必须且只能有一个主责 L1。
- 可以列相关 L1 做交接，但主责 L1 是定义完成标准的方向。
- 主责不清楚时，问“什么证据能关闭这个 issue”：硬件资源就绪、Agent 执行生命周期、Harness/RL 证据、客户端/API 行为、用户/管理策略，还是平台交付/运维。
- 先按完成标准判断主责，再看实现表面。CLI、Web 页面、HTTP API、hwpod 工具或服务路由不会自动归入 `客户端`；它们主归属定义正确性的领域。只有当完成标准是 Web、CLI、HTTP API 的入口行为、用户交互、兼容性或输出格式时，`客户端` 才是主责 L1。

HWLAB Cloud M1 L1 职责矩阵：

| 编号 | 短名 | 主责 | 不负责 | 交接示例 |
| --- | --- | --- | --- | --- |
| `PJ2026-0101` | 硬件池 | 硬件资源池：板卡、probe、HWPOD 节点、设备注册、占用、健康、可用性 | CaseRun pass/fail 标准、Agent 调度、UI/API 展示、CI/CD | 把 Harness 证据交给 HarnessRL；把资源分配 hook 交给 Agent编排 |
| `PJ2026-0102` | Agent编排 | Agent 执行生命周期：Code Agent、AgentRun、工作区、session、provider profile、任务恢复 | 硬件 inventory、Harness 评分、客户端 UX/API 契约、CI/CD | 从 硬件池 获取设备分配；向 HarnessRL 提供证据；向 客户端 提供状态 |
| `PJ2026-0103` | HarnessRL | Harness/RL 闭环：harness、CaseRun、ioProbe、证据、evaluation、replay、训练反馈、RL 收敛 | 硬件容量、Agent 调度、用户账户、rollout pipeline | 从 硬件池 获取设备事实；从 Agent编排 获取运行生命周期 |
| `PJ2026-0104` | 客户端 | 用户入口：Web、CLI、HTTP API、兼容性、任务入口和结果获取 | 用户/账本真相、Agent 调度内部、硬件 inventory、CI/CD | 向 用户管理 交接 auth/account 策略；从 Agent编排 获取运行状态 |
| `PJ2026-0105` | 用户管理 | 用户和管理域：账户、注册/登录、权限、API key、credit、usage、billing、admin、tenant isolation | 客户端 UX、Agent 执行、硬件证据、部署机制 | 把用户入口交给 客户端；从 Agent编排/HarnessRL 获取 usage 来源 |
| `PJ2026-0106` | 平台运维 | 平台交付和运维：CI/CD、git mirror、YAML-first、Secret sync、rollout、observability、GC、platform release | 产品行为、用户策略、Agent 语义、硬件验收标准 | 承接所有 L1 的部署需求；把健康信号回传给负责人 |

### L2 课题

课题必须足够具体，可以规划和关闭。例如：

- PLC 71-FREQ CaseRun 生产闭环。
- ARM2D 上游集成。
- D601 v0.3 用户账单和使用摘要。
- React 到 Vue 对齐收口。
- Sub2API Codex pool failover 稳定性。

制定 L2 时：

- 从 L1 完成标准出发，再把工作聚合成有交付物和验证计划的稳定课题。
- 不要只按仓库、CLI 命令、UI 页面、实现模块或临时运行面 lane 拆 L2。
- L2 短名通常控制在 8 个中文汉字以内。优先使用能力名；只有当标准/协议本身是交付物并约束后续实现时，才用“标准”类名称。
- 安全、诊断、占用、日志默认合并到拥有相关行为的 L2；除非它们本身成为中心交付物，否则不要单列。
- 一个课题触及多个 L1 时，仍保留一个主责 L1，并列出关联 L1。用交叉引用表达支撑关系，不要在多个方向下重复建同一棵 issue 层级树。

### 硬件池 L2 标准

`PJ2026-0101 硬件池` L2 拆分为：

| 编号 | 短名 | 主责 | 关联 L1 | 边界 |
| --- | --- | --- | --- | --- |
| `PJ2026-010101` | `HWPOD标准` | 定义 HWPOD-SPEC、硬件资源身份、能力模型、AI 网关接入标准、操作能力标准、状态/错误语义和验收基线。 | 客户端、HarnessRL、Agent编排 | 这是标准/协议型交付，不是单纯文档。它定义 HWPOD 资源和 AI 网关能力声明的正确性规则。 |
| `PJ2026-010102` | `HWPOD工具` | 实现硬件池领域工具侧，包括 `hwpod-ctl`、HWPOD-SPEC 新建/修改/校验，以及 compile、download、filesystem、IO 等操作入口。 | 客户端 | 这不是通用 `客户端` L1。只要完成标准由 HWPOD 语义或真实硬件执行定义，就主归属硬件池。通用 CLI 登录、profile 体验、HTTP API 入口和多客户端一致性归 `客户端`。 |
| `PJ2026-010103` | `HWPOD服务` | 实现服务端 HWPOD 注册、管理、状态、必要的权限/租约、请求接收、路由、结果归档，并把工具侧请求转发到 AI 网关节点。 | 用户管理、Agent编排、平台运维 | 它负责 HWPOD 服务端语义，不负责全局部署机制、用户策略或 Agent 任务调度。 |
| `PJ2026-010104` | `AI网关` | 实现连接真实硬件到服务端的节点侧能力，包括 PC 客户端形态、硬件网关盒子形态、心跳、命令执行、日志/artifact/IO 结果回传和适配器执行。 | HarnessRL、Agent编排、平台运维 | debug probe、UART、board-comm、ioProbe、电压/电流/频率/CANopen 等适配器是网关侧能力切片，通常作为本 L2 下的 L3，除非发展成更大的工作计划。 |

硬件池已吸收概念：

- `资源模型` 并入 `HWPOD标准`；标准同时定义资源模型和网关能力模型。
- `资源占用` 通常并入 `HWPOD服务`，当它涉及租约、权限、路由状态；涉及用户可见操作请求时也会落到 `HWPOD工具`。
- `安全状态` 是 `HWPOD服务` 和 `AI网关` 的横向验收要求；除非安全态恢复本身成为中心课题，否则不要单列 L2。
- `运行诊断` 分散到行为负责人：规格不一致归 `HWPOD标准`，命令/API 诊断归 `HWPOD工具`，路由/状态诊断归 `HWPOD服务`，node/probe/IO 执行诊断归 `AI网关`。
- debug/download/IO/观测通道默认不单列 L2。把它们视为 `AI网关` 下的能力切片，以及 `HWPOD工具` 侧的操作入口。

硬件池跨 L1 示例：

| 工作项 | 主责 L1 | 关联 L1 | 理由 |
| --- | --- | --- | --- |
| 增加 `hwpod-ctl spec validate` 校验 HWPOD-SPEC 正确性 | 硬件池 | 客户端 | 完成标准是 HWPOD 标准正确性，即使表面是 CLI。 |
| 统一所有 HWLAB CLI 的 JSON 输出 schema | 客户端 | 硬件池 | 完成标准是多客户端/用户入口一致性。 |
| 在 Web/API 展示 HWPOD inventory | 客户端 | 硬件池 | 用户入口行为是主责，HWPOD 语义从硬件池引用。 |
| 修复 probe mismatch 被报告为成功 | 硬件池 | HarnessRL | 真实硬件执行/错误语义是主责，HarnessRL 消费结果。 |
| 给 AgentRun 任务分配 HWPOD 资源 | 硬件池 或 Agent编排 | Agent编排 或 硬件池 | 如果完成标准是资源分配正确性，主责硬件池；如果完成标准是任务生命周期调度，主责 Agent编排。 |

### L3 子课题

子课题是验证切片。必须定义单一验收路径：

- 一个带预期 artifact 的 CaseRun。
- 一个指定目标 lane 的 CLI smoke。
- 一个 Web 原入口检查。
- 一个带状态证据的部署/控制面动作。
- 一个带引用的文档决策。

### L4 执行任务

执行任务对应一个 PR、一次运行面验证、一个 CaseRun 或一次收口文档更新。它不应该变成 mini-epic。

## 偏离控制

出现以下情况时，将任务标记为偏离风险：

- 没有 L1/L2 上级。
- 把文档、项目管理、看板维护或技能维护当作父方向。
- 改进工具但没有移除具名阻塞项。
- 改变运行面/控制面但没有原始验证入口。
- 扩展前端对齐但没有绑定到 Code Agent/HWPOD/用户工作流。
- 改善可观测性但没有下游决策依赖新信号。
- 持续打磨 ARM2D/PLC 证据，但没有新的真实上游或板级用例。

发现偏离风险后，要么挂回上级和验收标准，要么重新归类为调查。

## 阶段报告规则

每份阶段报告应包含：

- 时间窗口和时区。
- 来源范围：核对过的 repo、issue、PR。
- 相对 L0/L1 目标的移动。
- 已完成的验证证据。
- 开放阻塞项。
- 偏离评估。
- 下一阶段面向验证的目标。

避免把 issue 数量当成进展。只报告真正推动方向接近验收标准的变化。
