fix: make branch follower k8s native
This commit is contained in:
Codex
@@ -16,7 +16,6 @@ HWLAB Cloud M1 / UniDesk / AgentRun 跨仓项目治理锚定在 UniDesk 仓库
|
||||
|
||||
## Reference 路由
|
||||
|
||||
- 项目规划、层级职责、issue 锚点和工作流的完整旧规则在 [references/full.md](references/full.md)。
|
||||
- 项目规划细则读 [references/project-planning.md](references/project-planning.md)。
|
||||
- 模板读 [references/templates.md](references/templates.md)。
|
||||
|
||||
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
name: unidesk-oa
|
||||
description: 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 未完成前不得推进代码实现。
|
||||
Reference in New Issue
Block a user