From 9dc277ed169aba35e6600685ffa1dc9731f5bf4d Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 14 Jun 2026 18:10:10 +0000 Subject: [PATCH] docs: close yaml-first governance loop --- .agents/skills/unidesk-ymalops/SKILL.md | 8 ++++---- docs/reference/agentrun.md | 6 ++++-- docs/reference/yaml-first-ops.md | 5 +++++ 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/.agents/skills/unidesk-ymalops/SKILL.md b/.agents/skills/unidesk-ymalops/SKILL.md index 0daddc36..96d79ae4 100644 --- a/.agents/skills/unidesk-ymalops/SKILL.md +++ b/.agents/skills/unidesk-ymalops/SKILL.md @@ -1,6 +1,6 @@ --- name: unidesk-ymalops -description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/YAML-first 正规化、YAML ops、运维配置职责、platform-infra 配置重构、Secret sourceRef、publicExposure、target/lane/node、ops helper 抽取、删除 hardcoded defaults/特例、或 pikasTech/unidesk#390 时使用。 +description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/YAML-first 正规化、YAML ops、运维配置职责、platform-infra 配置重构、Secret sourceRef、publicExposure、target/lane/node、ops helper 抽取、删除 hardcoded defaults/特例，或历史收敛 issue pikasTech/unidesk#390/#398/#401 时使用。 --- # UniDesk YAML Ops @@ -9,7 +9,7 @@ description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/ 本技能用于推进 UniDesk 的 `ymal-first 正规化`：把运维参数、节点/lane/service 归属、公开暴露、Secret 绑定、容量/版本/endpoint 等可调事实收敛到 YAML；代码只负责读取、校验形状、渲染计划、执行薄的 domain CLI。 -当前收敛跟踪 issue 是 `pikasTech/unidesk#390`。#390 是固定 R1-R5 的关闭计划，不是继续追加 Round 的长期队列；只能为固定 R1-R5 创建对应子 issue，不得新增 R6 或“继续 Round”。如果任务持续超过一个工作段，使用 `bun scripts/cli.ts gh issue comment create 390 --repo pikasTech/unidesk --body-stdin` 追加进度、卡点和验收证据。 +历史收敛 issue `pikasTech/unidesk#390`、`#398` 和 `#401` 都是已关闭的阶段性收口记录，不是继续追加 Round 的长期队列。后续 YAML-first 工作必须先基于当前代码重新盘点；如果需要 broad cleanup，重新创建一个边界清晰的总 issue，并在实现前冻结不超过 5 个实际代码/配置功能阶段。测试、证据收集、门禁、issue lifecycle、看板维护或 docs-only 蒸馏不能包装成阶段。 ## Required Reading @@ -30,7 +30,7 @@ description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/ - 受控 CLI 输出只能披露对象名、key 名、sourceRef、targetKey、缺失项、fingerprint、字节数和执行摘要；不得打印 base64 payload、解码值、完整 DSN、API key 或可复制凭据。 - 不做新的全局大 orchestrator。优先保留 domain CLI，把公共能力抽到 ops helper，domain CLI 只表达领域动作。 - 不为了“防回归”新增合同测试、重型 preflight、历史 guard 或 feature flag。旧门禁阻碍最新 ymal-first 目标时，优先拆除。 -- 对已经冻结范围的正规化 issue，新发现事项只能归入 `must-fix-in-current-plan`、`keep-domain-special` 或 `parked-out-of-scope`；不得因为新 grep 命中继续追加阶段。 +- 对已经冻结范围的正规化 issue，新发现事项只能归入 `must-fix-in-current-plan`、`keep-domain-special` 或 `parked-out-of-scope`；不得因为新 grep 命中继续追加阶段，也不得把测试/证据/门禁/issue 维护当成阶段。 ## Workflow @@ -42,7 +42,7 @@ description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/ 6. 抽公共 ops primitives：在增加新 service 分支前，优先复用或扩展公共 helper。 7. 保持 domain CLI 薄：`platform-infra`、`server`、`gc`、`agentrun`、`hwlab` 等入口只组合 YAML、helper 和执行动作，不复制底层 Kubernetes/FRP/Caddy/Secret 逻辑。 8. 验证原入口：CLI/config 改动默认只跑语法、help/命令形态、plan/dry-run 或对应 sync/validate；涉及真实运行面的收口要跑原 CLI 入口，不新增合同测试。 -9. 有限收口：当 issue 已经冻结阶段，完成当前阶段后只更新父 issue 的进展和下一固定阶段；不要把候选扫描结果转成新的 Round。 +9. 有限收口：当 issue 已经冻结阶段，完成当前阶段后只更新父 issue 的进展和下一固定阶段；固定阶段全部完成后关闭总 issue，不把候选扫描结果转成新的 Round。 ## Common Refactor Targets diff --git a/docs/reference/agentrun.md b/docs/reference/agentrun.md index 24a18228..1a3622ad 100644 --- a/docs/reference/agentrun.md +++ b/docs/reference/agentrun.md @@ -63,7 +63,7 @@ trans G14:k3s kubectl get pods -n agentrun-v01 ## 受控 CI/CD 入口 -AgentRun 控制面写操作必须通过 UniDesk 高层 CLI 执行。历史 `v0.1` G14 lane 仍保留无 `--node/--lane` 的兼容入口；新增或迁移 lane 必须使用 `--node --lane ` 从 `config/agentrun.yaml` 解析目标，不得从 AgentRun service repo 的 `deploy.json` 读取部署真相。 +AgentRun 控制面写操作必须通过 UniDesk 高层 CLI 执行。无 `--node/--lane` 的控制面命令不再表示代码里的固定 G14/v0.1 常量，而是解析 `config/agentrun.yaml.controlPlane.default`；显式 `--node --lane ` 仍可选择其他 lane。新增或迁移 lane 必须从 `config/agentrun.yaml` 解析目标，不得从 AgentRun service repo 的 `deploy.json` 读取部署真相。 ```bash bun scripts/cli.ts agentrun control-plane status @@ -92,10 +92,12 @@ bun scripts/cli.ts agentrun control-plane trigger-current --node D601 --lane v02 bun scripts/cli.ts agentrun control-plane status --node D601 --lane v02 --full ``` -`status` 只读观察 `G14:/root/agentrun-v01` 当前 commit、对应 PipelineRun、GitOps latest、Argo Application、`agentrun-v01` workload、manager source commit 和 git mirror 摘要，并报告 Argo revision 是否对齐 `v0.1-gitops` latest。默认输出是 compact commander 视图，只保留 `summary`、阶段耗时、对齐状态和 drill-down 命令；需要远端 stdout/stderr tail 时显式加 `--full`，需要原始 git mirror cache 输出时显式加 `--raw`。`status` 额外支持 `--pipeline-run ` 与 `--source-commit ` 定点查询，返回 `target`、`targetValidation` 和 `next.*` drill-down，便于直接判断某次 run 是成功、历史成功、运行中、缺失还是 source mismatch。`status` 会向 stderr 输出 `agentrun.control-plane.status.progress` 阶段事件，覆盖 `source`、`runtime` 和 `git-mirror`，避免长时间聚合时无可见进展。`trigger-current` 会先把固定 source worktree 快进到 `origin/v0.1`，再以当前 commit 创建 commit-pinned PipelineRun；同名 PipelineRun 正在运行或已经成功时必须拒绝重复触发，只允许在失败态或不存在时创建。该命令只提交 CI/CD 工作，不等待完整 PipelineRun 或 rollout 完成，后续用 `status` 轮询。`refresh` 只对 `argocd/agentrun-g14-v01` 执行 hard refresh，用于 GitOps promotion 已完成但 Argo 仍停留旧 revision 时的受控同步入口；它不直接 patch runtime workload。 +`status` 只读观察 YAML 选中 lane 的 source workspace 当前 commit、对应 PipelineRun、GitOps latest、Argo Application、runtime workload、manager source commit 和 git mirror 摘要，并报告 Argo revision 是否对齐该 lane 的 GitOps latest。默认输出是 compact commander 视图，只保留 `summary`、阶段耗时、对齐状态和 drill-down 命令；需要远端 stdout/stderr tail 时显式加 `--full`，需要原始 git mirror cache 输出时显式加 `--raw`。`status` 额外支持 `--pipeline-run ` 与 `--source-commit ` 定点查询，返回 `target`、`targetValidation` 和 `next.*` drill-down，便于直接判断某次 run 是成功、历史成功、运行中、缺失还是 source mismatch。`status` 会向 stderr 输出 `agentrun.control-plane.status.progress` 阶段事件，覆盖 `source`、`runtime` 和 `git-mirror`，避免长时间聚合时无可见进展。`trigger-current` 会先把 YAML 声明的 source worktree 快进到 lane source branch，再以当前 commit 创建 commit-pinned PipelineRun；同名 PipelineRun 正在运行或已经成功时必须拒绝重复触发，只允许在失败态或不存在时创建。该命令只提交 CI/CD 工作，不等待完整 PipelineRun 或 rollout 完成，后续用 `status` 轮询。`refresh` 只对 YAML 声明的 Argo Application 执行 hard refresh，用于 GitOps promotion 已完成但 Argo 仍停留旧 revision 时的受控同步入口；它不直接 patch runtime workload。 YAML-only lane 的 `trigger-current` 会先确保目标 source workspace/branch 存在，再从 UniDesk YAML 声明的 image build、GitOps branch/path、runtime namespace、Secret、数据库和 manager env 渲染 artifact catalog 与 GitOps desired state。该路径会删除新 lane source branch 中的 `deploy/deploy.json`，因为部署真相已经迁入 UniDesk YAML；旧 `v0.1` branch 中历史文件只作为迁移前遗留产物存在，不能作为新 lane 的事实来源。Secret export 格式或外部数据库连接参数变化时，先用 `platform-db postgres export-secrets --confirm` 物化本地 Secret source，再用 `agentrun control-plane secret-sync --node --lane --confirm` 下发，最后用 `agentrun control-plane restart --node --lane --confirm` 让 manager Deployment 通过 rollout 读取新 Secret；不要手工删除 Pod 或直接 patch Secret。 +AgentRun resource/session client policy 也由 `config/agentrun.yaml` 声明。`client.sessionPolicy` 是 `agentrun send session/...` 和相关 session payload 生成的默认 `tenantId`、`projectId`、`providerId`、`backendProfile`、`workspaceRef` 和 execution policy 来源；lane `secrets[].providerCredential.profile` 声明 provider credential Secret 归属，UniDesk CLI 只按 YAML 聚合 Secret name/key，不再用代码拼接 provider Secret 名称。只读入口 `bun scripts/cli.ts agentrun explain session-policy` 用于查看当前默认 lane、session policy、实际 executionPolicy payload 和 provider credential binding 来源；输出只能包含 Secret metadata、key 名和 `valuesPrinted=false`，不得打印 Secret value。 + `cleanup-runs` 是 AgentRun `v0.1` 完成态 CI workspace retention 入口，只清理 `agentrun-ci` namespace 中超过 `--min-age-minutes` 的 `agentrun-v01-ci-*` PipelineRun，通过 Tekton ownerRef 释放临时 workspace PVC。dry-run 必须披露候选 PipelineRun、owned PVC、active mount 保护、local-path 实际估算 bytes 和 confirm 命令。默认保护最新完成的 PipelineRun，保留当前 CI/CD 状态证据。`cleanup-released-pvs` 是二次回收入口，只处理 `agentrun-ci`、`local-path`、`Delete` reclaim policy 的 `Released` PV；它不触碰 `agentrun-v01` runtime namespace、业务 PVC、Secret、registry storage 或 GitOps desired state。磁盘治理和 G14 safe-stop 规则见 `docs/reference/gc.md`。 涉及 AgentRun runner egress、`transientEnv` 或 Secret 不泄露的 closeout，必须用真实 `create/apply/send` 资源原语触发 `agentrun-v01` runner Job，再通过 `describe runnerjob/...`、`events run/...`、`logs session/...` 或必要的兼容 bridge 检查 runner job response、event/trace 和 Kubernetes Pod spec。通过证据应显示 proxy env 是否存在、`NO_PROXY` 是否包含 `hyueapi.com`/`.hyueapi.com`、短期 `HWLAB_API_KEY` 等 `transientEnv` 是否通过 per-job Secret 的 `valueFrom.secretKeyRef` 注入，以及 response/event 只输出 env name、Secret metadata 和 `valuesPrinted=false`。不得在 issue、trace 或 Pod spec 摘要中输出 Secret value。AgentRun 内部 SecretRef 合同以 AgentRun 仓库 `docs/reference/spec-v01-secret-distribution.md` 和 `docs/reference/spec-v01-runtime-assembly.md` 为权威；UniDesk 只记录验证入口和跨仓库归因。 diff --git a/docs/reference/yaml-first-ops.md b/docs/reference/yaml-first-ops.md index c0f2561b..da031c25 100644 --- a/docs/reference/yaml-first-ops.md +++ b/docs/reference/yaml-first-ops.md @@ -123,6 +123,10 @@ YAML-first cleanup work must not become an open-ended sequence of rounds. Once a A shared helper extraction stops when the repeated mechanism has a stable helper, the remaining differences are true domain behavior, or the remaining candidates are outside the frozen scope. Do not continue extracting only to make every domain file look identical. The final audit should list completed changes, kept domain differences, parked risks and validation evidence, then close the issue instead of opening a follow-up round by default. +Closed governance issues are historical records, not standing queues. A later YAML-first pass must start from a fresh code/config inventory and a new bounded issue instead of reopening or appending phases to an already closed issue. For broad cleanup, the phase list should stay small and fixed before implementation; do not exceed five phases unless the user explicitly requests a different bound. + +Each frozen phase must deliver a concrete code, configuration or user-facing CLI behavior change. Validation commands, evidence gathering, issue comments, merge/preflight work, progress reporting and docs-only distillation are closeout activities; they may be recorded, but they are not phases. When all frozen phases are complete, close the parent issue and classify remaining discoveries as in-scope leftovers already handled, true domain differences, or out-of-scope parked risks. + ## Anti-Patterns Avoid these patterns: @@ -138,6 +142,7 @@ Avoid these patterns: - using contract tests or hidden guards to freeze policy values that should remain YAML-controlled - preserving legacy command branches after the latest YAML-first path supersedes them - extending a frozen cleanup issue by appending new rounds instead of classifying discoveries as in-scope, domain-specific or parked +- treating validation, evidence collection, issue lifecycle work, or docs-only closeout as implementation phases ## Documentation Boundary