@@ -2,7 +2,7 @@
name: unidesk-cicd
description: >-
UniDesk CI/CD 控制面，覆盖 PaC consumer 首发 bootstrap、Tekton/Argo、GitOps、
git-mirror、PR 自动交付 、Secret、observability、CI tools image、PipelineRun 清理、
git-mirror、L2/L3 手动计划发布 、Secret、observability、CI tools image、PipelineRun 清理、
Tekton 大对象与 Kine/SQLite 控制面退化、AgentRun 与 HWLAB 部署，
以及 branch-follower 退役只读诊断。
用户提到 CI/CD、deploy、rollout、PipelineRun、PaC、bootstrap、GitOps、Tekton、
@@ -17,9 +17,9 @@ description: >-
HWLAB G14 和 AgentRun CI/CD 的受控入口。任何 PR 监控、Tekton/Argo、git-mirror、Secret、observability、CI tools image、PipelineRun 清理或 AgentRun 部署都必须走 `bun scripts/cli.ts` 。
- `$unidesk-devlevel` 用 L2 Development 和 L3 Production 描述两种集群部署方式：
- 本 skill 负责这两种方式的自动交付 、运行面操作和事故处理；
- 本 skill 负责这两种方式的手动计划发布 、运行面操作和事故处理；
- L0 Function 与 L1 Native 不使用 CI/CD。
- 能在 L0/L1 复现和修复的问题，不用反复 L2/L3 rollout 代替快速小回环；修复后再通过正常自动链回归 对应集群方式。
- 能在 L0/L1 复现和修复的问题，不用反复 L2/L3 rollout 代替快速小回环；需要集群回归时必须先 plan，再手动触发 对应集群方式。
- L2 可由代理按任务需要自行判断。
- L3 必须先完成对应 L2 回归，L2 通过后才请求用户当次明确授权，获授权后再滚动到生产。
@@ -47,6 +47,8 @@ bun scripts/cli.ts platform-infra gitea mirror status --target JD01
bun scripts/cli.ts platform-infra gitea mirror webhook status --target JD01
bun scripts/cli.ts platform-infra pipelines-as-code bootstrap --target NC01 --consumer <consumer> --dry-run
bun scripts/cli.ts platform-infra pipelines-as-code bootstrap --target NC01 --consumer <consumer> --confirm
bun scripts/cli.ts platform-infra pipelines-as-code release plan --target NC01 --consumer <consumer> --source-commit <full-sha> [ --base-commit <full-sha>]
bun scripts/cli.ts platform-infra pipelines-as-code release trigger --target NC01 --consumer <consumer> --source-commit <full-sha> [ --base-commit <full-sha>] --confirm
bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01
bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01 --consumer hwlab-jd01-v03
bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --limit 10
@@ -63,6 +65,16 @@ bun scripts/cli.ts agentrun control-plane legacy-cicd --help
bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
```
- L2/L3 发布触发：
- PR merge、push 和 branch update 只更新 source authority，不创建 PipelineRun；
- 先运行 `release plan` ，检查本次请求范围、累计有效范围、env reuse、待构建镜像数量与列表、rollout 范围和全部受影响服务；
- 当前 GitOps catalog 落后 source 时，plan 必须把累计发布欠账与本次 base 到 source 的请求范围分开显示；
- 有效范围大于请求范围时标记 `expanded` ， `release trigger` 必须在发送 webhook 前拒绝；
- 计划范围扩大时先修复 source range、源码、YAML 或项目 planner，再重新 plan；
- 审阅通过后运行 `release trigger --confirm` ；该命令只向 PaC 发送 webhook，由 PaC 创建 PipelineRun；
- 禁止裸创建 PipelineRun、由 CLI 直建 PipelineRun，或恢复 Gitea 自动 hook；
- L3 继续要求对应 L2 已通过和用户对当次生产发布的明确授权。
- 节点级只读状态：
- 优先用 `cicd status --node <NODE>` ；
- 该入口在目标侧一次批量读取 PipelineRun、Argo Application 与 Deployment，再按 owning YAML consumer 投影，禁止为每个 consumer 并发启动完整 `status` ；
@@ -125,7 +137,7 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
- 确认后把同一命令改为 `--confirm` ；
- 入口从 Gitea 与 PaC owning YAML 精确解析仓库；
- 入口只初始化空 Gitea 仓库和 PaC/Tekton/GitOps 控制面；
- 随后合并 source PR， 作为唯一交付触发 ；
- 随后合并 source PR， 再通过 `release plan` 和 `release trigger --confirm` 手动发布 ；
- 详细最短路径见 [references/gitea-pac.md ](references/gitea-pac.md )。
按职责读取拆分后的 reference：
@@ -208,7 +220,7 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
- 当前业务问题域内的 CI/CD 故障必须直接闭环：
- 用户要求修复、发布或回归某个业务时，选中 consumer 自有的 owning YAML 配置片段、独立 namespace/lane、独立 source artifact、消费仓 `.tekton` 制品和该业务运行配置均属于主任务授权范围；
- 确认故障位于上述范围后，直接完成根因修复、正常 PR 自动交付 和原业务入口回归，不得只登记 issue 后停工；
- 确认故障位于上述范围后，直接完成根因修复、PR 合并、手动 plan/trigger 发布 和原业务入口回归，不得只登记 issue 后停工；
- 修复仍须保持最小影响面，并按 L0、L1、L2 的适用层级逐级回归；不得借域内授权修改共享控制面或其他 consumer；
- 只有致因落入下述公共服务面，或修复必须改变跨 consumer 共享对象时，才转为公共服务面授权判定。
- 未经用户明确授权，不得修改 CI/CD 公共服务面：
@@ -220,12 +232,12 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
- 用户只说“修复某个 consumer 的 CI/CD”不等于授权修改公共服务面；授权必须明确指向共享 PaC、Gitea、git-mirror、Tekton/Argo bootstrap 或其他公共组件；
- consumer 私有修复不得夹带公共服务重构、其他 consumer 配置、共享模板清理或无关 PR；无法在私有边界内修复时按阻塞处理，不得扩大作用域。
- 生产 CI/CD 事故必须优先回退：
- 把自动 链连续失败、多个 consumer 同时失败、生产发布停摆、错误变更持续扩散或需要人工 补链才能交付，按生产事故处理；
- 把共享发布 链连续失败、多个 consumer 同时失败、生产发布停摆、错误变更持续扩散或需要受控入口之外 补链才能交付，按生产事故处理；
- 立即停止与恢复无关的合并、bootstrap、apply、手工同步、补跑和并行架构改造，只保留只读取证与回退动作；
- 先锁定首个失败事件、最后一个成功事件、共同失败指纹和两者之间的变更集，优先证明“哪一个变更导致失败”，禁止从最新错误状态直接开始连续试修；
- 最近变更与失败强相关且回退不会造成不可逆数据损坏时，必须先回退该变更，恢复最后已知健康基线；不得以“顺手完善”“已经改了一半”或“继续修可能更快”为由保留错误基础；
- 回退也必须通过最小单一职责 PR 和正常自动事件 交付，禁止用直接 Gitea push、人工 PipelineRun、Argo sync 或运行面热补伪造恢复；
- 只有回退后的正常事件 已经证明自动 链恢复，才允许从健康基线重新设计前向修复；前向修复必须拆成可独立验证、可独立回退的最小变更；
- 回退也必须通过最小单一职责 PR、 `release plan` 审阅和受控手动 webhook 交付，禁止用直接 Gitea push、裸建 PipelineRun、Argo sync 或运行面热补伪造恢复；
- 只有回退后的受控发布 已经证明链路 恢复，才允许从健康基线重新设计前向修复；前向修复必须拆成可独立验证、可独立回退的最小变更；
- 回退存在不可逆 schema、数据迁移或外部状态风险时，先停止继续发布并保全证据，再选择已有受控恢复路径；不得在没有恢复边界的情况下继续叠加代码修复。
- PaC 公共 status renderer 故障必须先区分交付失败与观察失败：
- 先用 PipelineRun、Argo 与 runtime 独立事实确认自动交付是否成功，不得把 `parse-failure` 或 status timeout 直接表述为交付链失败；
@@ -235,25 +247,25 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
- PK01 的 CI/CD 默认只允许只读诊断：
- 普通 PR merge、自动滚动、环境恢复或跨服务交付不构成 PK01 变更授权；
- 只有用户在当前请求中明确要求修改 PK01，才允许提交或推广会改变 PK01 版本、配置、Secret 绑定、边缘路由、容器或运行面状态的 source 变更。
- PaC migrated consumer 的唯一正式 CI/CD 触发是目标 source branch 的 GitHub PR merge。合并后由 GitHub webhook -> Gitea controlled mirror + immutable snapshot ref -> Gitea web hook -> PaC -> Tekton -> GitOps/Argo -> runtime 自动滚动；不得要求主代理、子代理或操作者再执行 apply、closeout、trigger、sync、flush 或 补跑。
- PaC migrated consumer 的唯一正式 CI/CD 触发是 `release plan` 审阅后由 CLI 手动发送 PaC webhook。GitHub PR merge 只更新 Gitea controlled mirror 与 immutable snapshot ref，不创建 PipelineRun；禁止恢复 Gitea 自动 hook、直接 Gitea push、裸建 PipelineRun、Argo sync 或受控入口之外的 补跑。
- PaC consumer 首次引导必须满足以下约束：
- 默认使用 `pipelines-as-code bootstrap --dry-run|--confirm` ，不再人工串联 Gitea bootstrap 与 PaC apply；
- `apply` 必须在任何 release、RBAC、Secret、Repository CR、Argo 或 webhook 写入前确认 YAML 匹配的 Gitea 仓库已存在；
- source PR 合并后不得再次调用 bootstrap 或 apply； 正常验收不串联 mirror/status/history，只有失败归因才逐层下钻 。
- 自动 链路不通时必须修复自动 链自身，并通过修复 PR 合并产生的新正常事件 验收：
- source PR 合并后不得再次调用 bootstrap 或 apply； 先执行 `release plan` ，范围准确后才执行 `release trigger --confirm`
- 发布 链路不通时必须修复链路 自身，并通过修复 PR 对应的手动 plan/trigger 验收：
- 已发生错误或首次部署尚未跑通时，允许使用 YAML 已声明的受控单步入口调试具体阶段；
- 单步调试必须限定目标、输入和阶段，保留结构化结果，并且不得改写 source/ref authority、伪造成功状态或替代完整交付；
- 单步确认的修复必须回写 owning YAML、renderer 或源码，再由正常 source PR 合并事件跑通自动 CI/CD 链；
- 只有自动链从 source event、artifact、GitOps/Argo 到 runtime 原入口全部收敛，才能把首次部署或故障修复判为完成；
- 单步确认的修复必须回写 owning YAML、renderer 或源码，再由正常 source PR 合并、plan 和手动 webhook 跑通 CI/CD 链；
- 只有发布链从手动 source event、artifact、GitOps/Argo 到 runtime 原入口全部收敛，才能把首次部署或故障修复判为完成；
- 禁止人工 mirror sync、直接 Gitea push、人工 PipelineRun、`trigger-current`
或其他手段补齐当前交付；
- 调试或临时恢复确需改变运行面时，允许按 `$unidesk-daddev` P2 实施最小、可逆 patch，
但不得修改 source/ref authority、伪造交付成功或作为最终验收；
- P2 结论必须收敛到 owning YAML、controller 或源码，
再由修复 PR 的正常自动事件 交付；临时 patch 必须撤销或被声明式交付覆盖；
再由修复 PR 的手动 plan/trigger 交付；临时 patch 必须撤销或被声明式交付覆盖；
- 只读 status/history/events/logs/debug-step 仍是默认定位入口，
`closeout` 只属于显式 compatibility diagnostics，不得进入默认观察或恢复路径。
- CI/CD、GitOps、rollout、PipelineRun、Argo、git-mirror 和 AgentRun 的观察、诊断与 legacy 控制必须走受控 CLI；不要用裸 `kubectl` 、`argo` 、`tkn` 、`curl` 当正式控制入口。PaC migrated consumer 仍只由 GitHub PR merge 触发，不得因“必须走 CLI”而额外调用写命令 。
- CI/CD、GitOps、rollout、PipelineRun、Argo、git-mirror 和 AgentRun 的观察、诊断与控制必须走受控 CLI；不要用裸 `kubectl` 、`argo` 、`tkn` 、`curl` 当正式控制入口。PaC migrated consumer 只允许 `release plan` 后由 `release trigger --confirm` 发送 webhook 。
- CI/CD 校验默认不得阻塞交付：
- 除非用户明确要求某项校验成为门禁，禁止新增会让 Pipeline、artifact、GitOps promote、Argo reconcile、runtime rollout 或 `/health` closeout 失败的配置一致性、版本、契约、schema、preflight 或跨对象校验；
- 全局配置、非选中 target/consumer、跨 consumer 一致性和版本/契约漂移只输出结构化 typed warning，并固定 `blocking=false` ；
@@ -262,11 +274,11 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
- 当前选中对象缺少渲染必需输入、Secret/权限不成立、目标无法唯一解析或 mutation target 不安全时，仍在 mutation 前 fail-closed；这类损害预防不得扩展成全局配置一致性门禁。
- CI/CD source authority 只能来自 YAML 声明的 Kubernetes 托管 source authority：
- legacy lane 由受控命令在 k8s 内同步并创建不可变 `refs/unidesk/snapshots/.../<commit>` stage ref；
- Gitea/PaC migrated lane 由 GitHub PR merge 自动驱动 GitHub webhook bridge、Gitea controlled mirror 与 immutable snapshot ref，禁止合并后人工同步或创建 snapshot；
- Gitea/PaC migrated lane 由 GitHub PR merge 更新 GitHub webhook bridge、Gitea controlled mirror 与 immutable snapshot ref，禁止合并后人工同步或创建 snapshot；该 source 更新不触发 PipelineRun；
- build/status/publish 只消费对应 snapshot， `git fetch/pull` 、可变 branch ref 或 Pipeline 内直连 GitHub 都不能作为 authoritative source。
- CLI 必须组合 `config/platform-infra/gitea.yaml` 与 `config/platform-infra/pipelines-as-code.yaml` ，按 consumer、node、lane、upstream repository、branch 和 Gitea repository 精确解析 delivery authority。不得用 URL 片段或 repo 专属条件判断迁移；当前选中对象零匹配或多匹配时返回 `unknown` 、`mutation=false` 并在 mutation 前 fail-closed，非选中对象和全局一致性错误只进入 `blocking=false` warning。
- PaC 与 `unknown` authority 的 help、plan、status、失败态 `Next` 、`REPAIR` 和实际执行 guard 都不得包含或执行 mutation command。`trigger-current|refresh|sync|flush` 只在 YAML 精确解析为 `legacy-manual` 后进入旧实现，且只从 `legacy-cicd` / `legacy-ops` scoped help 发现；平台 bootstrap、Secret 与配置维护使用独立 scoped help，不得充当 source delivery recovery。
- JD01/NC01 `agentrun-<node>-v02` 、`sentinel-<node>-v03` 、`hwlab-<node>-v03` 的交付收口由自动链自行完成 并写入状态。仅在显式调查自动 链故障时读取 `cicd status --node <NODE>` 或 `platform-infra pipelines-as-code status|history --target <NODE> --consumer <id>` ； 主代理与子代理不得把 `closeout` 当作 PR 合并后的人工步骤。 `cicd branch-follower` 和 `cicd gitea-actions-poc` 对这些 consumer 只保留历史/迁移只读用途。
- JD01/NC01 `agentrun-<node>-v02` 、`sentinel-<node>-v03` 、`hwlab-<node>-v03` 在手动 webhook 后由 PaC/Tekton/GitOps 自动收敛 并写入状态。仅在显式调查发布 链故障时读取 `cicd status --node <NODE>` 或 `platform-infra pipelines-as-code status|history --target <NODE> --consumer <id>` ； `cicd branch-follower` 和 `cicd gitea-actions-poc` 只保留历史/迁移只读用途。
- PaC `.tekton` 文件必须用 Repository CR 的 target/node 参数隔离 JD01/NC01，避免同一个 Gitea push 在一个 target cluster 内额外创建另一个 target 的 PipelineRun。`history --id` 必须按运行面 provenance 和实际 PipelineRun prefix 唯一归属 consumer；零匹配、多匹配或显式 consumer 不一致均 fail-closed，不得回退到默认 consumer 或默认 node。
- PaC source artifact 必须遵循以下边界：
- 由 `config/platform-infra/pipelines-as-code.yaml#consumers[].sourceArtifact` 显式声明；
@@ -326,7 +338,7 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
- 只有同一 deliveryId 的 exact-after immutable snapshot 与 authority branch 经 atomic push 后重新读取 refs 证明一致，才能进入 `committed` ；
- 同 deliveryId 与同 payload 必须幂等，异 payload 必须返回 `409` ； `503` 并使 readiness=false；
- inbox worker 使用 YAML 声明的有界 backoff 自动重试，重启后恢复 `accepted` / `processing` ；Caddy 只可在请求尚未持久化时做小于 10 秒的 body-safe 有界重试。
- Durable inbox 只是 webhook delivery 的持久接收与重试 journal，不是业务 source/ref 的第二份真相，也不得被 PaC、Tekton、GitOps、Argo 或 runtime 当作源码/read model。最终 source authority 仍只有 Gitea authority branch 与 immutable snapshot。默认只使用 `platform-infra gitea mirror webhook status` 观察 accepted -> committed 分层。会 POST hook test 的 mutation 测试入口已经删除；连通性只能通过真正只读的 status、GET 与 readiness 观察，不能制造伪 push 。平台 bootstrap 必须先落入 Git-backed YAML/controller/source，并由正常 PR merge 的自动事件 验收；禁止 Gitea -> GitHub 回写、轮询/read-model fallback、Gitea Actions/act_runner fallback 或第二 source authority。
- Durable inbox 只是 webhook delivery 的持久接收与重试 journal，不是业务 source/ref 的第二份真相，也不得被 PaC、Tekton、GitOps、Argo 或 runtime 当作源码/read model。最终 source authority 仍只有 Gitea authority branch 与 immutable snapshot。默认只使用 `platform-infra gitea mirror webhook status` 观察 accepted -> committed 分层。会 POST hook test 的 mutation 测试入口已经删除；连通性只能通过真正只读的 status、GET 与 readiness 观察。平台 bootstrap 必须先落入 Git-backed YAML/controller/source，并由 PR 合并后的 source authority 状态、手动 plan 和手动 webhook 验收；禁止 Gitea -> GitHub 回写、轮询/read-model fallback、Gitea Actions/act_runner fallback 或第二 source authority。
- Gitea webhook/public-edge 自动链变更的 closeout：
- 必须观察修复 PR 合并后的真实 delivery、rollout 和只读 status/GET/readiness 证据；
- Secret、ConfigMap 或 public-edge 候选已生成不等于 connector Pod 与公网 route 已加载新配置；
@@ -336,8 +348,8 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
- `cicd branch-follower` 对当前 PaC consumer 已退役，只保留 `status|events|logs` 与只读 `debug-step` 历史诊断。默认入口、任意 `--config` 和混合/未知 authority 都不能恢复 `apply|run-once|state-write` 等写能力，也不能猜测默认 node。
- k8s 运行面从拉取已构建镜像开始必须 0 Docker；CI 构建面可以使用 YAML 声明的原生构建工具，但不得把 Docker socket、Docker daemon 或 host Docker 带入运行面。
- 正式 CI/CD、publish、image build 和 rollout 必须走 Tekton Task/Pipeline/PipelineRun 承担 CI，并通过 GitOps/Argo 承担部署收敛；普通 Kubernetes Job 只允许用于 bounded helper、source sync、diagnostic、cleanup 或 bootstrap，不得作为正式发布、镜像构建或 rollout 入口。
- 未迁移的 legacy CI/CD 若仍保留人工入口，必须由单一受控命令完成 source sync、构建、发布、GitOps/Argo 收敛、runtime provenance 校验和 `/health` 端点验证。PaC migrated consumer 不得使用该人工入口，其唯一交付触发是 GitHub PR merge 。
- CI/CD 端到端 wall-clock 目标及预算只由 owning YAML 声明；PaC migrated consumer 从 GitHub PR merge 事件计时，legacy lane 才 从操作者触发受控命令计时，均到 runtime ready 且 `/health` 端点验证完成为止。
- 未迁移的 legacy CI/CD 若仍保留人工入口，必须由单一受控命令完成 source sync、构建、发布、GitOps/Argo 收敛、runtime provenance 校验和 `/health` 端点验证。PaC migrated consumer 不得使用该 legacy 入口，只允许 `release plan` 后执行 `release trigger --confirm`
- CI/CD 端到端 wall-clock 目标及预算只由 owning YAML 声明；PaC migrated consumer 从 CLI 手动 webhook 事件计时，legacy lane 从操作者触发受控命令计时，均到 runtime ready 且 `/health` 端点验证完成为止。
- CI/CD validation 阶段只能验证部署对象的 `/health` 端点和必要 provenance；禁止在 CI/CD gate 中运行 web-probe、Playwright、远程浏览器截图、用户路径 E2E 或等价重型业务探针。业务/用户入口验证只能作为发布后的独立 post-deploy validation 证据，不得阻塞 CI/CD 一键交付。
- 产品功能配置 schema 的 CI/CD 合同：
- repo 内唯一约定路径固定为 `config/feature-config.schema.json` ；
@@ -366,9 +378,9 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
- 指定 `--consumer` 或可唯一归属的 `--id` 时只读取单 consumer 快路径；
- 输出 `config.scope=target-summary|single-consumer` ，不得静默退回默认 consumer。
- 退役 branch-follower 排障只允许使用 `state-read|controller-source|status-read|decide` 、`status|events|logs` 等只读边界；`state-write` 、gate、`run-once` 和自动 loop 不再是当前 PaC consumer 的修复或验收入口。
- 自动 链单步测不通时，应在 Git-backed YAML、controller 或源码中修复根因，并由修复 PR 合并产生的新正常 webhook/PaC 事件复测；不得用 branch-follower 写状态或补跑当前交付。
- 发布 链单步测不通时，应在 Git-backed YAML、planner、 controller 或源码中修复根因，并由修复 PR 合并后的新 plan 和手动 webhook/PaC 事件复测；不得用 branch-follower 写状态或补跑当前交付。
- CI/CD 排障中再次踩到已暴露的运行面坑、工具误用、镜像假设或状态可见性缺口时，必须先把长期规则写入本 skill/reference，再继续只读定位。
- CI/CD 运行面验收必须在目标 NODE/k8s 内计算短摘要；本机只用于源码阅读、编辑和静态合同测试，不能替代正常 PR merge 自动事件 产生的目标运行面证据。
- CI/CD 运行面验收必须在目标 NODE/k8s 内计算短摘要；本机只用于源码阅读、编辑和静态合同测试，不能替代受控手动 webhook 产生的目标运行面证据。
- CI tools image 默认必须包含 `kubectl` ：
- `kubectl` 与其他构建工具统一由 owning YAML 的 tools image Dockerfile 声明并随镜像交付；
- 镜像构建必须执行 `kubectl version --client` 自检；
pikastech