pikasTech-unidesk/.agents/skills/unidesk-oa/references/full.md

name, description

name	description
unidesk-oa	UniDesk 项目管理运行技能。用户提到 UniDesk 项目管理目录、HWLAB OA、总项目规格、总规划、重大项目/方向/课题/子课题层级、任务书、实施方案、测试规格、阶段报告、项目偏离，或通过 project-management 与 GitHub issue 管理 HWLAB Cloud M1 / UniDesk / AgentRun 跨仓项目治理时使用。

UniDesk OA

使用本技能时，把 HWLAB Cloud M1 的项目管理稳定地锚定在 UniDesk 仓库内的项目编号目录和相互链接的 GitHub issue 执行记录上。

仓库

• UniDesk 项目管理真相源：/root/unidesk/project-management/PJ2026-01，其中 specs/PJ2026-01-HWLAB.md 是 L0 总规格和项目索引，随 pikasTech/unidesk 的 master 分支版本化。AgentRun 作为 HWLAB Agent编排的执行基础设施归入 PJ2026-0102 及其平台运维支撑规格，不单独创建新的 L0 项目。
• 迁移前 HWLabOA 仓库：/root/HWLabOA 只作为历史材料和对照来源，不再作为 HWLAB Cloud M1 规格真相源。
• 使用 UniDesk GitHub CLI、修改本技能或修改项目管理文档前，必须在 /root/unidesk 执行 git status --short --branch 和 git pull --ff-only origin master。

运行模型

• 将 project-management/PJ2026-01 下的 Markdown 视为长期规格真相源。
• 将 GitHub issue 视为执行控制面、历史讨论入口和长证据承载处：状态、讨论、跨仓引用、PR 链接和收口证据可以在 issue 中流转，但规格正文不得只写在 issue 中。
• 长证据、trace、CaseRun registry、运行日志、历史 issue 摘要和证据索引保留在 GitHub issue 或具体执行 issue 中，禁止以 evidence/ 目录或长证据文件形式污染 project-management/PJ2026-01。
• project-management/PJ2026-01/specs/*.md 规格文件不保留单独的迁移来源块；历史来源只写在修改历史 v0.1 的变更说明中，格式为 迁移来源 <owner>/<repo>#<number>。规格文件引用其他规格必须使用同目录相对路径 Markdown 链接，禁止引用其他规格的 GitHub issue、证据 issue、PR 或裸 #<number>；唯一例外是第 7 章过程控制可保留跨 L1 阶段验证 issue 索引，用于内测、灰度和用户反馈分流，不承载问卷正文、参与者资料、原始反馈、长证据或执行流水。
• AgentRun 仓库内 docs/reference/spec-v01-*.md 和 docs/reference/architecture.md 不再承载规格正文；迁移后只保留指向 UniDesk OA 规格的交叉引用 stub，避免 AgentRun repo 与 project-management/PJ2026-01 双份规格漂移。AgentRun 专项内容按职责落到 project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md、project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md、project-management/PJ2026-01/specs/PJ2026-010602-source-sync.md、project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md、project-management/PJ2026-01/specs/PJ2026-010604-public-entry.md 或 project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md 及其 L3，不创建 PJ2026-02。
• HWLAB v0.2/v0.3 仓库内 docs/reference/spec-* 以及 cloud-workbench.md、code-agent-chat-readiness.md、g14-gitops-cicd.md / node-gitops-cicd.md、dev-runtime-boundary.md、gateway-outbound-demo.md、MVP-e2e-acceptance.md、architecture.md 已收编为 UniDesk OA 交叉引用或历史 stub；这些路径只保留链接兼容和运行参考，不能再作为需求规格正文来源。需要变更 Web/CLI/API、Code Agent、runtime boundary、公开入口、测试大纲或 Gateway 主动出站需求时，先更新 project-management/PJ2026-01/specs/ 和相应测试/过程 issue。
• 写入 GitHub issue/PR 正文或评论时，issue/PR 引用必须写成 [#<number>](https://github.com/<owner>/<repo>/issues/<number>) 或 [#<number>](https://github.com/<owner>/<repo>/pull/<number>)，显示短号、链接目标保留完整 URL；不要显示裸长链接、裸井号编号或 owner/repo 加井号编号。CLI 参数中的 owner/repo#number shorthand 只作为命令输入例外。
• 不要让日报或阶段报告成为总规划。阶段报告只总结相对总规格的移动，不能替代中心规划。
• 当任务缺少上级方向、验收标准或原始验证入口时，先归类为规划/调查，不要直接变成实现任务。
• L1 方向必须是直接服务 L0 使命的能力域。文档整理、阶段报告、项目管理机制、看板维护、技能维护、仓库名、工具名和临时执行路径都不能作为 L1 方向。
• L1 是验收主责，不是宽泛标签。跨方向 issue 可以列关联 L1，但必须且只能有一个主责 L1，选择依据是哪个方向定义完成标准。
• 重大规划型 issue 必须 P0 SPEC-first：P0 阶段先在 project-management/PJ2026-01/specs/ 维护对应 SPEC，明确 SPEC 编号、上级/关联规格、架构图、数据流图、关键时序图和代码引用规则，再进入后续实现。issue 正文只能承载执行计划和证据，不能替代 SPEC 正文。

需求规格写作规则

• 需求规格是对外系统能力、边界和职责说明，不写内部治理、issue 关闭规则、长期面板、阶段报告、执行控制面、单次验证流水、PR 过程或证据堆叠。
• 文档控制表只保留规格自身必要字段；状态只能写 已生效、已废弃 或 未生效。不要在文档控制表里写长期面板、阶段规格、L1 划分、规格来源或迁移来源。
• 修改历史只记录已经定稿的版本。用户未明确说“可以定稿”前，不新增 待提交 版本号，也不把每次小编辑拆成一个版本。
• L0、L1、L2 需求规格正文固定使用裁剪后的 1-7 章结构：文档控制、目的和范围、术语表、系统边界和接口、内部分工与规格索引、原子需求、过程控制。第 7 章只索引阶段验证、内测、灰度或用户反馈分流 issue；不要在 SPEC 正文追加假设和风险、变更控制、开放缺口、验收标准或执行过程流水。
• 涉及新能力、跨模块架构、用户可见工作流、长期 API/数据模型、平台运维能力或多阶段实施的 SPEC，必须在正文中包含目标架构图、数据流图和关键时序图；图形优先使用 Markdown 内嵌 mermaid，并和原子需求编号互相对应。
• L0 系统边界必须把 HWLAB 作为完整系统看待，描述外部使用者、外部输入、受控资源、外部输出、用户接口和系统责任边界，不写内部治理材料。
• 稳定概念用术语表表达；不要写没有判定价值的“运行概念”流水。
• L0 的 L1 方向树和项目规格索引合并为内部模块分工与规格索引，用相对路径索引到每个内部模块规格文档。
• 原子需求每条独立成节，信息表使用横向表格且只放短元数据，推荐列为 编号 | 短名 | 主责模块 | 关联模块。主责模块必须写下一层主责单元并带项目编号：L0 原子需求写 L1，L1 原子需求写 L2，L2 原子需求写 L3；禁止在 L1/L2 原子需求里把主责模块写成本规格本级。禁止把需求句、职责划分、验收口径或大段说明塞进表格，正文必须承载需求定义、职责边界、意图和范围。
• 不要为了凑全局原子需求条数自动添加次要派生能力。证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包/结果收集等需求，除非用户明确授意，不得写入 OA 规格或 L0 原子需求。
• 平台运维在 L0 中只能作为支撑后勤职责出现；对外需求应写成系统可用性、可恢复、资源可控等用户可感知能力，不写成“HWLAB 对外提供平台运维能力”。
• 单一主责、关闭验收、规格沉淀、回写和偏离判定是治理规则，不得伪装成 L0 原子需求。
• L2 是稳定能力域，不是仓库文件名或原始 spec 文档一比一搬运目录。单个 L1 下的 L2 通常不超过 6 个；从仓库参考文档迁移过来的大量细项应合并到少量 L2，并把更细的服务、lane、source truth、验证切片放到 L3 或正文分工中。
• 运维交付内容必须按职责归位：通用 CI/CD、发布判定、镜像 promotion 放到平台运维的发布流水；通用 Git mirror、source truth、GitOps branch、artifact catalog 放到源码同步；Secret/YAML/sourceRef/targetKey/fingerprint 放到 YAML运维。只有能抽象到多服务共用的规则才放通用 L2；AgentRun 固定 branch、namespace、Pipeline、GitOps path、真实 provider turn 等专项细节放到这些通用规格下的 AgentRun 专项 L3，PJ2026-0102 Agent编排 只引用这些支撑规格，不把运维后勤 L2 塞进 Agent编排。
• 大规划型 issue 范围内新增或修改的源码文件，文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如 SPEC: PJ2026-01060505 Workbench性能 draft-2026-06-17-p0；不得只写 issue 编号、latest 或 current。自动生成文件、第三方 vendored 文件、纯配置、锁文件和无法承载注释头的二进制产物可例外，但对应生成器、渲染器或配置入口必须可追溯到 SPEC。

HWLAB 标准 issue 锚点

• L0 总规格：project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md，历史 issue [#1194](https://github.com/pikasTech/HWLAB/issues/1194)。
• AgentRun 规格入口：project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md；核心 L2 为 PJ2026-010201 AgentRun核心、PJ2026-010202 Runtime装配、PJ2026-010203 队列会话、PJ2026-010204 后端Profile、PJ2026-010205 HWLAB接入。平台运维支撑入口为 PJ2026-010601 发布流水、PJ2026-010602 源码同步、PJ2026-010603 YAML运维、PJ2026-010604 公开入口和 PJ2026-010605 可观测监控；其中 AgentRun 专项 L3 只承载 AgentRun 固定 lane/source 事实，D601 v0.3 用户入口等跨模块 public entry truth 归 PJ2026-010604。
• 长期导航面板：[#645](https://github.com/pikasTech/HWLAB/issues/645)（HWLAB 长期总面板）。这是面板，不是规格书。
• 当前 Cloud M1 阶段规格：project-management/PJ2026-01/specs/stage-cloud-spec-20260601.md，历史 issue [#644](https://github.com/pikasTech/HWLAB/issues/644)。
• 创建或更新 HWLAB 项目管理 issue 时，非平凡 L1/L2/L3/L4 工作都要链接回 project-management/PJ2026-01 中的对应规格文件，并保持 [#645](https://github.com/pikasTech/HWLAB/issues/645) 只作为导航索引。
• 所有管理 issue 和规格都使用 HWLAB 层级编号：项目编号格式为 PJ<YYYY>-<path>；PJ 表示项目，2026 是立项年份，HWLAB L0 是 PJ2026-01；L1 编号是 PJ2026-0101、PJ2026-0102 等；L2 继续追加两位，例如 PJ2026-010102 表示 HWLAB L1 第 1 个方向下的第 2 个 L2 课题。稳定节点短名通常控制在 8 个中文汉字以内，解释写在正文，不写进名称。

工作流

1. 做规划类问题时，读取 references/project-planning.md。
2. 创建或更新总规格、issue 正文时，读取 references/templates.md。
3. 写入 GitHub issue/PR 评论时，同时使用 unidesk-gh；所有写入必须从 /root/unidesk 通过 bun scripts/cli.ts gh ... 完成。
4. 修改长期项目管理文档时，把稳定规划内容放到 project-management/PJ2026-01 的总规格/规格文件，阶段报告只保留带日期的总结。
5. 修订 L1/L2 层级时，先按完成标准判断主责，再看实现表面。工具、CLI、Web、API 形态可以形成关联 L1，但主责 L1 必须是定义完成标准的能力域。
6. 更新重大规划型 issue 时，先把 P0 SPEC 文件和图维护到位，再用 unidesk-gh 回写 issue；后续代码任务必须在 issue 中引用 SPEC 编号和实现引用版本。

必需层级和职责

除非用户给出更严格的层级，否则使用以下任务树：

• L0：重大项目 / 总规格。负责使命、范围、系统边界、内部模块分工与规格索引、全局原子需求。
• L1：方向。负责一个稳定能力域、范围边界、成功标准、L2 课题清单和子工作验收定义权。
• L2：课题。负责某个 L1 内的具体工作计划，包括交付物、阻塞项和验证计划。
• L3：子课题 / 验收切片。负责一个有界验收路径，例如一条 CaseRun 线、Web 检查、CLI smoke 或部署/控制面验证。
• L4：执行任务 / PR / CaseRun / smoke / 文档收口。负责具体执行和证据收集，不能重新定义父级范围。

每个非平凡 issue 都应写明上级链接、目标分支/lane、验收标准、验证入口和收口回写目标。 重大规划型 issue 还必须把“更新并确认 SPEC”列为 P0，且 P0 未完成前不得推进代码实现。