pikasTech-unidesk/.agents/skills/unidesk-oa/references/project-planning.md

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 分工

用文档承载长期真相：

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

用 issue 承载执行状态：

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

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

• project-management/PJ2026-01/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 仓库内，并使用项目编号命名目录：

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

推荐文件：

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	使命、非目标、当前中心、L1 方向树、全局验收、偏离规则	PR 细节、CaseRun 日志、日报流水、实现设计	project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md 和 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 数量当成进展。只报告真正推动方向接近验收标准的变化。