mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: 收敛 PaC 自动交付提示

Browse Source
This commit is contained in:
Codex
2026-07-11 11:42:16 +02:00
parent b12dd85375
commit b607c3a996
55 changed files with 2953 additions and 1472 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/agentrun.md
+11 -18
View File
@@ -42,7 +42,7 @@ NC01:/root/agentrun-v02/.worktree/{pr_branch}
## 文档落库规则
AgentRun 仓库内长期参考、`spec-v01-*` 和 `architecture.md` 交叉引用 stub 变更不创建 PR。完成本地审查后，必须直接提交并推送到对应目标分支，例如 `origin/v0.2`。需求规格正文变更落到 UniDesk OA 的 `project-management/PJ2026-01/specs/`，不要在 AgentRun repo 另维护一份正文。过程计划、阶段证据、验收结果和阻塞点写入对应 GitHub issue 评论区，不能用文档 PR 代替直接落库。
AgentRun 源码仓目标 branch 的任何变更都必须通过 GitHub PR 合并，包括长期参考、`spec-v01-*` 与 `architecture.md` 交叉引用 stub。不得以“仅文档”为由直接 push 目标 branch，因为目标 branch 的 PR merge 是 migrated source delivery 的唯一正式触发。若确有不触发交付的文档专用 branch，必须由 owning YAML 与 delivery authority 显式声明，不能把它当作默认例外。需求规格正文变更落到 UniDesk OA 的 `project-management/PJ2026-01/specs/`，不要在 AgentRun repo 另维护一份正文。过程计划、阶段证据、验收结果和阻塞点写入对应 GitHub issue 评论区，不能用文档提交替代正式 issue 证据。
## 部署目标
@@ -62,14 +62,12 @@ trans NC01:k3s kubectl get pods -n agentrun-v02
## 受控 CI/CD 入口
AgentRun 控制面写操作必须通过 UniDesk 高层 CLI 执行。无 `--node/--lane` 的控制面命令解析 `config/agentrun.yaml.controlPlane.default`，当前固定为 `NC01/nc01-v02`；显式 `--node <node> --lane <lane>` 也只应选择 NC01 lane。新增或迁移 lane 必须从 `config/agentrun.yaml` 解析目标，不得从 AgentRun service repo 的 `deploy.json` 读取部署真相。
AgentRun 目标必须从 `config/agentrun.yaml` 解析，不得从 service repo 的 `deploy.json` 或 URL 片段推断。Delivery authority 还必须与 `config/platform-infra/gitea.yaml`、`config/platform-infra/pipelines-as-code.yaml` 的 consumer/repository 组合校验。当前默认 `NC01/nc01-v02` 是 PaC migrated consumer；目标 source branch 的 GitHub PR merge 是唯一正式交付触发。
```bash
bun scripts/cli.ts agentrun control-plane status
bun scripts/cli.ts agentrun control-plane trigger-current --dry-run
bun scripts/cli.ts agentrun control-plane trigger-current --confirm
bun scripts/cli.ts agentrun control-plane refresh --dry-run
bun scripts/cli.ts agentrun control-plane refresh --confirm
bun scripts/cli.ts platform-infra pipelines-as-code status --target NC01 --consumer agentrun-nc01-v02
bun scripts/cli.ts platform-infra pipelines-as-code history --target NC01 --consumer agentrun-nc01-v02 --limit 10
bun scripts/cli.ts agentrun control-plane cleanup-runners --node NC01 --lane nc01-v02 --dry-run
bun scripts/cli.ts agentrun control-plane cleanup-runners --node NC01 --lane nc01-v02 --confirm
bun scripts/cli.ts agentrun control-plane cleanup-runs --min-age-minutes 30 --limit 200 --dry-run
@@ -78,7 +76,7 @@ bun scripts/cli.ts agentrun control-plane cleanup-released-pvs --limit 200 --dry
bun scripts/cli.ts agentrun control-plane cleanup-released-pvs --limit 200 --confirm
```
YAML-only lane 的标准入口是：
平台配置维护与 source delivery 是独立职责。`apply`、`secret-sync` 和 `restart` 只用于 YAML 声明的控制面、Secret 或配置维护，不得作为 PR 合并后的交付恢复：
```bash
bun scripts/cli.ts agentrun control-plane plan --node NC01 --lane nc01-v02
@@ -88,24 +86,19 @@ bun scripts/cli.ts agentrun control-plane secret-sync --node NC01 --lane nc01-v0
bun scripts/cli.ts agentrun control-plane secret-sync --node NC01 --lane nc01-v02 --confirm
bun scripts/cli.ts agentrun control-plane restart --node NC01 --lane nc01-v02 --dry-run
bun scripts/cli.ts agentrun control-plane restart --node NC01 --lane nc01-v02 --confirm
bun scripts/cli.ts agentrun control-plane trigger-current --node NC01 --lane nc01-v02 --dry-run
bun scripts/cli.ts agentrun control-plane trigger-current --node NC01 --lane nc01-v02 --confirm
bun scripts/cli.ts agentrun control-plane status --node NC01 --lane nc01-v02 --full
bun scripts/cli.ts platform-infra gitea mirror status --target NC01
bun scripts/cli.ts platform-infra pipelines-as-code status --target NC01
bun scripts/cli.ts agentrun control-plane platform-maintenance --help
```
`status` 只读观察 YAML 选中 lane 的 source authority、对应 PipelineRun、GitOps latest、Argo Application、runtime workload、manager source commit 和 git mirror/Gitea 摘要，并报告 Argo revision 是否对齐该 lane 的 GitOps latest。未迁移的 legacy `v0.2` lane source authority 只来自 k8s git-mirror snapshot：受控 sync 先为 branch tip 创建 `refs/unidesk/snapshots/agentrun-yaml-lane/<branch>/<commit>`，`status` / `trigger-current` / build 只读取该 snapshot 和 `sourceStageRef`，不得把 host source workspace、本地 fetch/pull、可变 branch ref 或 Pipeline 直连 GitHub 当 authoritative source。默认输出是 compact commander 视图：`target` 只保留 node/lane/source/runtime/CI/GitOps/git-mirror/database 摘要，关键结论在 `summary` 和 `alignment`，成功 probe 的 stdout/stderr tail、完整 YAML target、原始 `source`、`runtime`、`gitMirror` payload 默认省略；需要完整展开时使用返回的 `disclosure.fullCommand` 或显式加 `--full`，需要原始调试视图时加 `--raw`。`status` 额外支持 `--pipeline-run <name>` 与 `--source-commit <sha>` 定点查询；`--pipeline-run` 会读取 PipelineRun `revision` 参数作为 pinned source commit，并在 `alignment.branchDrift` / `summary.branchDrift` 中同时披露当前 snapshot tip、目标 source commit、PipelineRun source commit、是否已被当前 snapshot supersede 以及 `triggerLatest` 下一步。`status` 会向 stderr 输出 `agentrun.control-plane.status.progress` 阶段事件，覆盖 `source`、`runtime` 和 `git-mirror`，避免长时间聚合时无可见进展。legacy `trigger-current` 会先执行 k8s git-mirror sync 并以 snapshot commit 创建 commit-pinned PipelineRun；同名 PipelineRun 正在运行或已经成功时必须拒绝重复触发，只允许在失败态或不存在时创建。该命令只提交 CI/CD 工作，不等待完整 PipelineRun 或 rollout 完成，后续用 `job status` 和 `status --pipeline-run <name>` 轮询。`refresh` 只对 YAML 声明的 Argo Application 执行 hard refresh，用于 GitOps promotion 已完成但 Argo 仍停留旧 revision 时的受控同步入口；它不直接 patch runtime workload。
`status` 只读观察 YAML 选中 lane 的 authority、PipelineRun、GitOps、Argo、runtime、manager source commit 与 Gitea 摘要。默认输出是 compact commander 视图，完整 target 和原始 probe payload 只在 `--full|--raw` 展开。PaC consumer 的正常、失败和超时状态都只能给 `status`、`history` 与只读下钻；不得返回 `trigger-current`、`refresh`、mirror `sync|flush` 或人工 PipelineRun。authority 零匹配、多匹配或配置错误必须返回 `unknown`、`mutation=false` 并 fail-closed。
NC01 `agentrun-nc01-v02` PaC lane 的正式触发链路是：GitHub PR 合并到 `pikasTech/agentrun@v0.2` -> GitHub webhook bridge 同步到 Gitea controlled mirror 和 immutable snapshot refs -> Gitea repository push webhook 触发 Pipelines-as-Code -> Tekton PipelineRun -> GitOps/Argo -> k8s runtime。该 lane 不再使用 branch-follower、Gitea Actions、act_runner 或自维护 `trigger-current` 作为正式 CI 触发器；对应 source authority、repo visibility、public exposure 和 mirror credentials 属于 `config/platform-infra/gitea.yaml`，PaC controller/Repository/webhook/Tekton 参数属于 `config/platform-infra/pipelines-as-code.yaml`。Gitea 的公开 Web UI 是 `https://gitea.pikapython.com`，但 CI、Argo 和 runtime 内部读取必须使用 `gitea-http.devops-infra.svc.cluster.local:3000` 的 ClusterIP URL，避免公网回环和 legacy git-mirror commit 缺失。
NC01 `agentrun-nc01-v02` PaC lane 的正式链路是：GitHub PR merge -> GitHub webhook -> Gitea controlled mirror -> immutable snapshot -> Gitea webhook -> Pipelines-as-Code -> Tekton -> GitOps/Argo -> k8s runtime。该 lane 不使用 branch-follower、Gitea Actions、act_runner 或自维护 trigger fallback。Gitea authority 属于 `config/platform-infra/gitea.yaml`，PaC consumer 属于 `config/platform-infra/pipelines-as-code.yaml`；CI、Argo 和 runtime 内部读取必须使用 YAML 声明的 ClusterIP URL。
AgentRun PaC lane 的 closeout 以 `bun scripts/cli.ts cicd status --node <NODE>` 或 `bun scripts/cli.ts platform-infra pipelines-as-code status --target <NODE> --consumer agentrun-<node>-v02` 为首选状态入口。默认输出必须能直接看到 webhook 是否存在、最新 PipelineRun/TaskRun duration、image status、env identity、digest、GitOps commit、Argo revision/health、manager Deployment readiness 和 runtime source/env annotation。env reuse 的通过证据是 `IMAGE_STATUS=reused`、同一 env identity 和稳定 digest；首次 cache miss 可以作为冷启动事实记录，但不能替代后续 env-reuse 秒级收口。若 GitHub PR 已合并但没有新 PipelineRun，应先排查 `platform-infra gitea mirror webhook status|test` 与 `platform-infra pipelines-as-code history`，不得改用 `trigger-current`、直接创建 PipelineRun、手工 push Gitea 或裸 `kubectl` 作为正式补触发。若 webhook delivery 返回成功但 GitHub head、Gitea branch、snapshot 或 latest PipelineRun source 不一致，先用 `platform-infra gitea mirror webhook status --target <NODE>` 披露差异，再用受控 `platform-infra gitea mirror sync --target <NODE> --confirm` 修复 mirror/snapshot，并把自动跟进缺口归并到 pikasTech/unidesk#1622；不要重复触发旧 `trigger-current` 掩盖 source authority 分叉。
AgentRun PaC lane 的默认观察入口是 `bun scripts/cli.ts cicd status --node <NODE>` 与 `bun scripts/cli.ts platform-infra pipelines-as-code status|history --target <NODE> --consumer agentrun-<node>-v02`。输出应显示 webhook、PipelineRun/TaskRun duration、image、env identity、digest、GitOps、Argo 和 runtime provenance。GitHub PR 合并后没有新 PipelineRun，或 GitHub head、Gitea branch、snapshot 与 PipelineRun source 不一致时，只用 webhook status 与 PaC history 定位，然后修 owning YAML、bridge/controller 或源码；禁止 mirror sync、直接 Gitea push、人工 PipelineRun 或旧 trigger fallback 补齐当前交付。
YAML-only lane 的 `trigger-current --confirm` 是受控长流程入口；k8s git-mirror snapshot sync、image build、GitOps publish、git-mirror flush 和 PipelineRun 创建必须拆成短提交与状态轮询，不得把 clone、build、push 或长时间 polling 放进一个顶层 `trans` 长连接。`trigger-current` 返回异步 job 时，先用 `bun scripts/cli.ts job status <jobId> --tail-bytes 12000` 观察 `agentrun-yaml-lane-trigger` progress，再用 `agentrun control-plane status --node <node> --lane <lane> --pipeline-run <name>` 观察 Tekton、GitOps 和 Argo 对齐。后台步骤的 `status` 与 `ok` 必须共同判定，`status=succeeded` 但 `ok=false` 是终态失败，不能继续轮询到超时。GitOps publish 必须使用隔离临时 clone/worktree，不能切换或污染任何固定 source workspace；`v0.2` 历史失败 publish 若留下 dirty/detached/GitOps branch 状态，不得通过 host workspace repair 恢复 source authority，只清理已知发布残留并从 git-mirror snapshot 重新触发。
只有 owning YAML 明确解析为 `legacy-manual` 的 lane 才能进入旧 trigger/mirror 实现，且命令只在 `agentrun control-plane legacy-cicd --help` 与 `agentrun git-mirror legacy-ops --help` 中可发现。Legacy 长流程必须拆成短提交与状态轮询，不得把 clone、build、push 或长 polling 放入一个顶层 `trans`。PaC 或 `unknown` authority 在任何远端调用或异步 job 创建前都必须结构化拒绝，`mutation=false`。
AgentRun YAML-only lane 发布收口必须以当前 k8s git-mirror snapshot tip 为准。`trigger-current` 期间若 lane source branch 被并行 PR 推进，`status --pipeline-run <name>` 会通过 `branchDrift.sourceBranchAdvanced=true` / `targetSupersededByCurrentBranch=true` 标记该 PipelineRun 已不是当前 snapshot tip；closeout 必须确认最新 snapshot commit 包含本次修复，再按最新 snapshot 重新 `trigger-current`，最后用最新 PipelineRun 的 `status` 证明 `aligned=true`、`blockers=[]`、`argoSyncedToGitops=true` 和 `managerSourceMatchesExpected=true`。不要用已经被更新 source supersede 的中间 PipelineRun 作为最终 closeout。
YAML-only lane 的 `trigger-current` 会先确保目标 branch 已同步到 k8s git-mirror snapshot，再从 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.2` branch 中历史文件只作为迁移前遗留产物存在，不能作为新 lane 的事实来源。Secret export 格式或外部数据库连接参数变化时，先用 `platform-db postgres export-secrets --confirm` 物化本地 Secret source，再用 `agentrun control-plane secret-sync --node <node> --lane <lane> --confirm` 下发，最后用 `agentrun control-plane restart --node <node> --lane <lane> --confirm` 让 manager Deployment 通过 rollout 读取新 Secret；不要手工删除 Pod 或直接 patch Secret。
平台 Secret/config 维护继续使用 YAML `sourceRef`、`secret-sync` 与 `restart`，并允许独立于 delivery authority 执行；它们不得创建 PipelineRun，也不得被描述成 source delivery recovery。不要手工删除 Pod 或直接 patch Secret。
Provider credential Secret 的 `auth.json` 和 `config.toml` 也必须按 NC01 lane 的 YAML `sourceRef` 下发，不能把指挥机全局 Codex 配置当成运行真相。lane 的模型、provider、endpoint 和 Codex runtime options 需要由 UniDesk YAML 拥有时，使用 `sourceMode: codex-config` 和同一 Secret spec 下的 `codexConfig` 渲染 `config.toml`；不要通过修改 `/root/.codex/config.toml` 或 `~/.codex/config.toml` 来改变 HWLAB/AgentRun 运行面模型。