docs: add g14 cicd performance analysis

AGENTS.md

@@ -58,6 +58,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥
 - DEV 运行态、端口、k3s 和 DB DNS 边界：[docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)
 - G14 GitOps 发布、SecretRef preflight、runner/host 边界和镜像发布：[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)
 - G14 GitOps CI/CD、Tekton/Argo CD、集群内 registry 和无锁镜像化发布：[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)
+- G14 CI/CD 性能基线、根因分析和加速收益估算：[docs/reference/g14-cicd-performance.md](docs/reference/g14-cicd-performance.md)
 - Code Agent 对话就绪与真实回复判定：[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md)
 - DEV runtime hotfix runbook 与只读审计：[docs/reference/dev-runtime-hotfix-runbook.md](docs/reference/dev-runtime-hotfix-runbook.md)
 - Gateway 主动出站 demo、poll/result 和本地 smoke：[docs/reference/gateway-outbound-demo.md](docs/reference/gateway-outbound-demo.md)

docs/reference/g14-cicd-performance.md

@@ -0,0 +1,156 @@
+# G14 CI/CD 性能分析
+
+本文是 HWLAB G14 CI/CD 性能优化的长期参考，覆盖 `G14` source branch、Tekton PipelineRun、per-service BuildKit 镜像发布、`G14-gitops` promotion、Argo CD sync 和 DEV runtime health。D601 legacy CI/CD、Code Queue runner 和 host 侧临时构建路径不属于本文范围。
+
+## 性能模型
+
+G14 CI/CD 耗时必须按阶段测量，不能只看一个 PipelineRun 总时长：
+
+1. Source trigger：`G14` source commit 被 `hwlab-g14-branch-poller` 发现。
+2. Source preparation：`prepare-source` clone source、checkout 精确 revision、导入最新 GitOps artifact catalog，并安装必要 npm 依赖。
+3. Primitive validation：`repo-reports-guard`、`g14-contract-check`、`codex-api-forwarder-check` 从准备好的 workspace 并行运行。
+4. Artifact planning：`plan-artifacts` 根据 component input hash 和上一轮 catalog 判断 affected/reused services。
+5. Per-service fan-out：affected services 通过 BuildKit 发布镜像；reused services 复用 catalog identity，不能改变 workload pod template。
+6. Artifact collection：`collect-artifacts` 汇总 per-service results 并验证 publish report。
+7. GitOps promotion：`gitops-promote` 刷新 catalog、render desired state、commit 并 push `G14-gitops`。
+8. Argo rollout：Argo CD 消费 `G14-gitops`，同步 runtime namespace，并让公网 health 对新 desired state 生效。
+
+每次性能报告必须标注运行类型：
+
+- `reuse-only`：没有服务镜像需要重建。
+- `single-component-build`：一个服务镜像重建，其余服务复用。
+- `multi-component-build`：多个但不是全部服务镜像重建。
+- `full-rebuild`：共享输入或 build-system 输入变化导致全部服务镜像重建。
+
+## 当前基线
+
+当前 G14 pipeline 已具备关键架构优化：一分钟 source polling、组件级 lazy build、per-service fan-out、G14 本地 registry、本地 base image、BuildKit-only publish、GitOps/Argo 分离。剩余耗时主要集中在固定开销和镜像构建机制上。
+
+当前滚动基线量级：
+
+| 阶段 | 典型范围 | 说明 |
+| --- | --- | --- |
+| Source trigger | 0-60s | poller 每分钟运行一次；平均等待应接近 30s。 |
+| `prepare-source` | 75-175s | 主要由 fresh clone、GitOps catalog fetch 和 `npm ci` 组成；这是很多单组件运行里的最大固定成本。 |
+| Primitive validation | 每项 5-10s | source 准备后并行运行，目前不是主要瓶颈。 |
+| `plan-artifacts` | 6-10s | 当前可接受，重点是保持只读和确定性。 |
+| Reused service TaskRun | 每项 8-12s | fan-out wall time 接近最慢复用 task，但 unchanged services 仍会启动 build-shaped pod。 |
+| Fast affected service build | 25-35s | 小型 Node 服务且 cache 命中时的常见范围。 |
+| Heavy affected service build | 120-220s | 依赖面宽或重建 Codex 相关层的服务可能达到该范围。 |
+| `collect-artifacts` | 8-10s | 当前可接受，主要是校验和 report assembly。 |
+| `gitops-promote` | 50-105s | 主要由 render/check、GitOps clone/checkout、tree copy、commit、push 构成。 |
+| Argo sync 到 DEV Healthy | 10-220s | 受 repository refresh timing 和 workload 是否真实滚动影响较大。 |
+
+当前端到端预期范围：
+
+| 运行类型 | PipelineRun | source commit 后到 DEV Healthy |
+| --- | --- | --- |
+| `reuse-only` | 3-4.5m | 3.5-6m |
+| `single-component-build` | 3.2-5.5m | 4-7.5m |
+| `full-rebuild` | 6-7m | 6.5-9m |
+
+这些值是性能基线，不是发布 SLO。任何 CI/CD 优化 PR 都应按同一种运行类型做 before/after 对比。
+
+## 根本原因
+
+### Source Preparation 冷启动
+
+`prepare-source` 每次 PipelineRun 都执行 fresh source clone、精确 checkout、GitOps catalog lookup 和 `npm ci`。当前 tools image 已避免运行时安装系统包，但没有消除每轮 npm install 成本。npm 或 GitHub 延迟上升时，后续 validation 和 build task 都会被这个共享 workspace 阻塞。
+
+根因：source preparation 被当成无状态冷启动处理，但实际工作负载反复使用同一个小型依赖图和同一个私有仓库。
+
+### Build Context 过宽且重复处理 Runtime 依赖
+
+服务镜像由 `scripts/artifact-publish.mjs` 生成 Dockerfile。该 Dockerfile 安装 production npm dependencies，然后复制 `internal`、`cmd`、`scripts`、`web`、`tools`、`skills`、`deploy` 等大范围目录。per-service Tekton task 还会先把 prepared source repo 复制到 service work directory，再调用 BuildKit。
+
+根因：BuildKit 接收到 monorepo-shaped context，并重复执行本应预烘或按服务裁剪的 dependency-layer 工作。
+
+### Reuse 路径仍启动 Build-Shaped Pod
+
+组件级 lazy build 已能正确把 unchanged services 标成 reused，但每个服务仍有一个带 BuildKit sidecar wiring 的 `build-*` TaskRun。reused services 会很快写出 Tekton results 并退出，但 Kubernetes 仍要承担 pod scheduling、sidecar setup、entrypoint setup 和 result collection 开销。
+
+根因：Tekton result wiring 绑定在 service task 上，reuse 被实现为 build-shaped task 内部的快速分支，而不是更轻量的 catalog-result 路径。
+
+### GitOps Promotion 做了完整 Workspace 工作
+
+`gitops-promote` 做 source freshness check、artifact catalog refresh、desired state render、render check、GitOps branch clone、generated state copy、commit 和 push。这保证了 release truth 清晰，但当前 repository 和文件树操作比必要量更重。
+
+根因：GitOps promotion 语义正确，但没有针对 shallow/sparse branch operation 或 incremental generated-state update 做优化。
+
+### Argo Repository Discovery 带来变量延迟
+
+`gitops-promote` push `G14-gitops` 后，Argo CD 不一定立刻发现新 revision。对于 reused-image 或小镜像变更，workload rollout 本身可能很快，repository discovery 反而变成端到端耗时里的显著部分。
+
+根因：CI push 和 Argo refresh 是松耦合的；GitOps 仍是真相，但运行态观察会滞后于 push。
+
+### Retention Cleanup 对排障噪声覆盖不足
+
+retention cleaner 会删除超过保留窗口的 completed PipelineRuns，但近期 failed PipelineRuns、failed TaskRuns 和 orphan Error pods 仍可能堆在 `hwlab-ci`。这通常不会给 pipeline 增加分钟级耗时，但会拖慢诊断并制造 API/list 噪声。
+
+根因：retention policy 更偏向长期清理，不是针对已知 bad-run burst 后的近期失败对象治理。
+
+## 改进建议
+
+| 优先级 | 建议 | 预期效果 |
+| --- | --- | --- |
+| P0 | 增加稳定的分段 timing 输出，覆盖 source clone、catalog fetch、`npm ci`、BuildKit context transfer、dependency install、cache import/export、GitOps clone、render、commit、push、Argo refresh、workload ready。 | 直接加速很小，但能让后续优化具备可比数据，避免把网络、npm、BuildKit、Argo 延迟混为一谈。 |
+| P0 | 给 `prepare-source` 使用 npm dependency cache，或在 CI tools image 里预装 repo dependencies，同时保留对 `package-lock.json` 精确性的校验。 | 将 `prepare-source` 从 75-175s 降到约 35-70s。单轮 PipelineRun 预计节省 40-100s。 |
+| P0 | 构建并使用包含 production `node_modules`、Codex package 和平台专用 Codex binary 的 runtime base image。 | 减少服务镜像重复依赖工作。fast build 维持约 20-35s；heavy build 从 120-220s 降到约 45-90s；full rebuild 预计节省 1-3m。 |
+| P0 | 为服务镜像增加生成式 `.dockerignore` 或 pruned BuildKit context，排除 `.git`、prepared `node_modules`、无关 generated files 和可排除的无关 service directories。 | 降低 context transfer 和 cache invalidation。小型 build 预计节省 10-40s，heavy build 预计节省 30-90s，同时降低磁盘压力。 |
+| P1 | 将 unchanged services 从 BuildKit-shaped tasks 拆出。可让 `plan-artifacts` 直接输出 catalog-backed service results，或给 reused service 使用无 sidecar 的轻量 task，changed services 保持 BuildKit。 | reuse-only 和 single-component fan-out 预计节省 10-30s，并显著减少 sidecar/pod 噪声；主要收益是稳定性和可观测性。 |
+| P1 | 优化 `gitops-promote`：对 `G14-gitops` 使用 shallow/sparse checkout，复用已 render 的输出做 check，避免复制或提交未变化的 generated paths。 | 将 `gitops-promote` 从 50-105s 降到约 20-45s。每轮 promotion 预计节省 30-60s。 |
+| P1 | GitOps push 成功后触发 Argo hard refresh，再用短轮询观察 sync。 | 当 workload 本身健康时，CI succeeded 到 DEV Healthy 从 10-220s 降到约 10-60s。 |
+| P1 | 扩展 failed-run retention：给 failed PipelineRuns 和 orphan Error pods 设置明确的短保留窗口，同时禁止删除 active PipelineRuns 和 runtime namespaces。 | 对 pipeline 直接加速有限，但能显著降低 bad-run burst 后的诊断噪声和 API/list 噪声。 |
+| P2 | 保持一分钟 polling，除非 source-trigger wait 成为主瓶颈；在固定开销降低前不要优先引入 GitHub webhook 复杂度。 | 理论平均最多节省约 30s；当前收益低于 `prepare-source`、BuildKit 和 GitOps promotion。 |
+| P2 | 在 context 和 base image 优化落地后，再调 BuildKit CPU/memory requests 与 cache export mode。 | 可能额外提升 build 10-20%，但在 build context 和 dependency layer 仍过宽时过早调资源不可靠。 |
+
+## 高优先级改进后的预期效果
+
+高优先级改进指 P0 项，加上 P1 的 GitOps promotion 优化和 Argo refresh coupling。它不要求改变当前 Tekton/GitOps/Argo truth model，也不需要回退到 shell runner。
+
+预期高优先级优化后范围：
+
+| 运行类型 | PipelineRun | source commit 后到 DEV Healthy |
+| --- | --- | --- |
+| `reuse-only` | 1.8-2.6m | 2.2-3.5m |
+| `single-component-build` | 2.0-3.2m | 2.5-4m |
+| `full-rebuild` | 3.8-5.2m | 4.3-6m |
+
+这是第一阶段务实目标：保持当前发布真相模型，优先消除普通 PR rollout 中占比最高的固定成本。
+
+## 全部建议落地后的预期效果
+
+全部建议包括高优先级项、reuse task 拆分、failed-run retention 改进，以及后续 BuildKit resource tuning。
+
+预期全部优化后范围：
+
+| 运行类型 | PipelineRun | source commit 后到 DEV Healthy |
+| --- | --- | --- |
+| `reuse-only` | 1.2-1.8m | 1.5-2.5m |
+| `single-component-build` | 1.6-2.6m | 2-3.2m |
+| `full-rebuild` | 3-4.5m | 3.5-5m |
+
+剩余下限是真实工作：私有 source 访问、validation、immutable image publication、GitOps truth update、Argo sync 和 live runtime health。不要为了追求亚分钟 full CI/CD 而折叠这些边界。
+
+## 实施顺序
+
+1. 增加低噪声 timing instrumentation。
+2. 为 `prepare-source` 增加 npm/prepared-dependency cache。
+3. 构建包含依赖和 Codex binary 的 production runtime base。
+4. 裁剪 BuildKit context，并增加生成式 `.dockerignore` 保护。
+5. 优化 `gitops-promote` clone/render/copy/push 机制。
+6. GitOps push 后触发 Argo refresh，并测量 CI-success 到 DEV-health 耗时。
+7. 将 reuse path 从 BuildKit-shaped service tasks 中拆出。
+8. 扩展 failed-run retention cleanup。
+9. 在 build graph 变小后再调 BuildKit resources。
+
+## 验收标准
+
+任何优化 PR 只有在给出同运行类型 before/after 数据，并保持以下不变量时，才算可合并：
+
+- Source commit 仍是唯一 artifact identity。
+- 镜像仍使用 commit tag 和 digest 作为发布身份。
+- `G14-gitops` 仍是 Argo CD 消费的 desired-state truth。
+- Unchanged services 不会因为全局 source commit 变化而滚动。
+- Failed/stale PipelineRun cleanup 不触碰 `hwlab-dev`、`hwlab-prod`、Argo runtime state、registry storage 或 active PipelineRuns。
+- Runtime success 仍由 Argo Application revision、workload readiness 和必要公网 health 证明。