Codex
11 KiB
11 KiB
HWLAB 规格治理索引：编号、层级、回写与偏离规则
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|---|---|---|
| v0.3 | b5d8cee438 |
2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 |
| v0.2 | b0cbe9b721 |
2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 |
| v0.1 | 37de91c653 |
2026-06-14 | 从迁移来源 pikasTech/HWLAB#1217 迁移到 UniDesk 项目管理目录。 |
正文
上级总项目: PJ2026-01 HWLAB 总规格 关联面板: HWLAB 长期总面板 性质: 规格治理索引，不是 L1 方向，不是 L2 课题，不定义产品/系统需求。 迁出来源: L0 总规格 旧版“项目编号与命名规则 / L1 方向判定 / 层级职责边界 / 管理入口职责边界 / 交叉引用检查 / 偏离判定 / 回写规则”章节 迁出时间: 2026-06-14（北京时间）
使用规则
- 本文档只保存项目管理和规格治理规则，供 L0 总规格、L1/L2/L3/L4 issue 引用。
- 不在本文档中新增、删除或重排 L1 方向；L1 方向树以 L0 总规格 为准。
- 不在本文档 中记录阶段进展、CaseRun 日志、PR 流水或具体实现方案。
- 治理规则变化需要回写 L0 总规格 的引用关系，并同步更新 UniDesk
$unidesk-oa。
重大规划型 issue 的 P0 SPEC-first 规则
- 涉及新能力、跨模块架构、用户可见工作流、长期 API/数据模型、平台运维能力或多阶段实施的大规划型 issue，P0 阶段必须先维护
project-management/PJ2026-01/specs/中的对应 SPEC；不得只把稳定需求、架构或验收标准写在 issue 正文里。 - P0 SPEC 必须按模板明确编号、短名、层级、状态、上级规格、关联规格、目的和范围、术语表、系统边界、内部分工、原子需求和过程控制。涉及实现架构的数据面必须在 SPEC 中包含架构图、数据流图和关键时序图；图形优先使用 Markdown 内嵌
mermaid。 - issue 正文的 P0 必须链接到对应 SPEC 文件和 SPEC 编号，并声明后续代码工作只有在 SPEC 编号、目标图和代码引用规则确认后才能开始。后续讨论改变稳定需求、数据流、接口或验收口径时，先更新 SPEC，再更新 issue 计划。
- 该规划型 issue 范围内新增或修改的源码文件，文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如
SPEC: PJ2026-01060505 Workbench性能 draft-2026-06-17-p0。自动生成文件、第三方 vendored 文件、纯配置、锁文件和不能承载注释头的二进制产物不要求加源码头部，但对应生成器、渲染器或配置入口必须能追溯到 SPEC。 - PR/issue 收口必须回写实际遵循的 SPEC 编号、实现引用版本、触达源码文件头部标注情况，以及是否需要修订 SPEC。发现代码实现偏离 SPEC 时，先修 SPEC 或修代码，不能用 issue 评论替代长期规格。
编号与命名规则
- 编号格式：
PJ<立项年份>-<层级路径>。 PJ表示项目，2026表示立项年份。- HWLAB L0 总项目编号固定为
PJ2026-01。 - L1 方向编号在 L0 路径后追加两位，例如
PJ2026-0101表示 HWLAB 第 1 个 L1 方向。 - L2 课题编号继续追加两位，例如
PJ2026-010102表示 HWLAB 第 1 个 L1 方向下的第 2 个 L2 课题。 - L3/L4 持久管理节点继续每级追加两位，例如
PJ2026-01010203表示 L1 第 01 个 / L2 第 02 个 / L3 第 03 个。 - 已分配的持久编号不因优先级、阶段或主线变化而重排；新增持久节点只追加新后缀。
- 单个 PR、一次 smoke、一次 CaseRun 等纯执行项可以只引用最近的持久编号，不强制独立编号。
- 持久节点必须有短名，一般控制在 8 个中文汉字以内；必要解释写在说明列或正文里，不塞进名称。
- issue 标题建议格式：
<编号> <短名>；执行 issue 可在短名后追加冒号和具体任务描述。
层级职责边界
| 层级 | 负责定义 | 不负责 | 回写对象 |
|---|---|---|---|
L0 / PJ2026-01 |
项目使命、系统范围、L1 方向树、全局需求、全局验收 | PR 细节、CaseRun 日志、日报流水、具体实现设计 | project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md、L1 issue |
| L1 / 方向 | 能力域范围、成功标准、L2 课题清单、原入口验收类型、交叉引用边界 | 单个 PR、一次 smoke、仓库/工具/runtime 名称、项目管理动作 | L0 总规格；方向范围变化时同步 project-management/PJ2026-01 |
| L2 / 课题 | 单个方向内的具体工作计划、交付物、阻塞、验收计划 | 总方向定义、跨方向路线图、实现细节流水 | 所属 L1；重大移动再回写 L0 总规格 |
| L3 / 验收切片 | 一个有界验收切片和单一验收路径 | 多课题计划、父级范围变化、新能力域定义 | 所属 L2/L1，并附 evidence |
| L4 / 执行任务 | PR、CaseRun、smoke、部署、文档收口等执行和 evidence | 新需求、新方向、验收规则变化 | 最近的 L3/L2/L1，必要时回写 L0 总规格 |
L1 主责判定
L1 方向必须是直接服务 L0 使命的一等产品/系统边界，并能定义下级工作的完成标准。L1 不是松散标签；跨方向任务可以列关联方向，但必须有且只有一个主责 L1。主责 L1 按“谁定义完成标准、谁接收回写 evidence”判定。
合格的 L1 方向应同时满足：
- 直接支撑云端硬件研发平台的产品、技术或运营能力。
- 可以承载多个 L2 课题和验证切片，而不是单个 PR 或单次文档更新。
- 有明确的用户价值、平台能力或真实运行面验收方式。
- 能说明上游依赖、下游支撑、接口/证据边界和需同步回写对象。
管理入口职责边界
| 入口 | 定位 | 能定义 | 不能定义/承载 | 回写要求 |
|---|---|---|---|---|
| PJ2026-01 | L0 总项目需求规格 | 使命、范围、方向树、全局需求、全局验收 | 执行流水、PR 细节、CaseRun 原始日志、治理细则全文 | L1 范围变化和重大验收移动必须回写 |
| HWLAB 长期总面板 | 长期总面板和导航摘要 | L0/L1/L2 入口索引、阶段入口、历史专题导航 | 规格正文、验收标准、方向定义 | 指向 L0 总规格，不替代 L0 总规格 |
| HWLAB Cloud SPEC | Cloud M1 当前阶段规格 | 当前阶段目标、阶段口径、阶段验收重点 | L0 总规格、L1 方向本身、长期编号规则 | 阶段目标变化影响总规格时回写 L0 总规格 |
project-management/PJ2026-01 |
长期文档和阶段报告沉淀 | 稳定规格、实施方案、测试规格、阶段报告 | 日常执行看板、未收敛讨论 | 从 issue 蒸馏稳定结论回文档 |
UniDesk $unidesk-oa |
agent 侧项目治理操作规程 | agent 如何识别锚点、编号、职责、回写 | HWLAB 项目内容本身、L1 能力域 | 治理规则变化后更新 skill，并在 L0 总规格 索引 commit |
交叉引用检查
- L1/L2/L3 issue 只要涉及互相支撑，必须在正文写明“上游依赖、下游支撑、接口/证据边界、需同步回写”。
- 依赖其他 L1 的能力时，规格文件必须用相对路径链接引用对应 L1 规格；执行 issue 必须引用对应 L1 issue 编号；不能只写方向名。
- 如果一个变更影响多个 L1 的接口、证据或验收标准，主责 L1 必须回写受影响 L1，并在 L0 总规格 留下重大移动摘要。
- 下级 issue 关闭前必须检查引用对象是否需要同步更新；引用未回写时不得直接关闭。
- HWLAB 长期总面板只做导航索引，不替代上述交叉引用检查。
偏离判定
出现以下情况时，任务必须先回到 L0 总规格 或对应 L1 issue 重新归类：
- 把文档整理、项目管理、skill 维护、看板维护或阶段报告当成 L1 方向。
- 没有上级 L1 方向，却直接创建实现任务。
- 涉及互相支撑但未引用对应 L1 issue。
- 没有明确原入口验收，却计划关闭用户可见能力 issue。
- 工具、CI、Web parity、观测增强没有解除某个 L1 的明确 blocker。
- 阶段报告只统计 issue/PR 数量，没有说明对 L1 验收的移动。
- 硬件池、Agent编排、HarnessRL、客户端、用户管理、平台运维互相抢主责，但没有说明 primary L1 和交叉引用。
回写规则
- HWLAB 长期总面板只做长期总面板和导航，不承担规格正文。
- L1 方向变化必须回写 L0 总规格 正文。
- L1/L2/L3 持久管理 issue 标题必须以编号和短名开头。
- L1 issue 关闭或阶段完成时，必须评论回写 L0 总项目 issue，并说明验收证据、剩余 blocker 和是否需要更新项目管理规格。
- L2/L3/L4 执行 issue 必须写明编号、短名、上级总项目、主责方向、关联方向、目标 lane/branch、验收入口和完成后回写对象。
- 稳定规则和长期规格最终应沉淀到
project-management/PJ2026-01；issue 保留执行状态、讨论、证据和交叉引用。 - agent 处理 HWLAB OA/总规格/项目漂移/issue 树任务时，应先加载
$unidesk-oa，并以 L0 总规格 和对应 L0 issue 锚点为准。
AgentRun 跨仓规格归位
- AgentRun 是 HWLAB Agent编排 的执行基础设施，不单独创建新的 OA L0 项目。
- AgentRun 仓库内
docs/reference/spec-v01-*.md只保留到 UniDesk OA 规格的交叉引用 stub；规格正文归project-management/PJ2026-01/specs/管理，避免双份规格漂移。 - AgentRun 功能规格按职责落到 AgentRun核心、Runtime装配、队列会话、后端Profile 和 HWLAB接入。
- 通用发布、源码同步和 YAML/Secret 运维仍归平台运维；只有能抽象到多服务共用的规则才放通用 L2。AgentRun 固定 lane、source truth 和真实联调等专项事实只作为 发布流水 与 源码同步 下的 AgentRun L3 管理。
- 迁移仓库内大量 SPEC 时，先合并为少量稳定 L2，再把服务、lane、source truth、验证切片拆到 L3；不要按原始文件一比一制造 L2。