From b672dc5db62e1a68b26e3ab2d908133c4b60ee75 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 1 Jul 2026 11:16:42 +0000 Subject: [PATCH] docs: clarify k8s snapshot source authority --- docs/reference/agentrun.md | 10 ++++------ docs/reference/hwlab.md | 9 +++++---- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/reference/agentrun.md b/docs/reference/agentrun.md index 03980d02..956c472c 100644 --- a/docs/reference/agentrun.md +++ b/docs/reference/agentrun.md @@ -94,15 +94,13 @@ 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` 只读观察 YAML 选中 lane 的 source workspace 当前 commit、对应 PipelineRun、GitOps latest、Argo Application、runtime workload、manager source commit 和 git mirror 摘要，并报告 Argo revision 是否对齐该 lane 的 GitOps latest。默认输出是 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 ` 与 `--source-commit ` 定点查询；`--pipeline-run` 会读取 PipelineRun `revision` 参数作为 pinned source commit，并在 `alignment.branchDrift` / `summary.branchDrift` 中同时披露当前 branch tip、目标 source commit、PipelineRun source commit、是否已被当前 branch supersede 以及 `triggerLatest` 下一步。`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 完成，后续用 `job status` 和 `status --pipeline-run ` 轮询。`refresh` 只对 YAML 声明的 Argo Application 执行 hard refresh，用于 GitOps promotion 已完成但 Argo 仍停留旧 revision 时的受控同步入口；它不直接 patch runtime workload。 +`status` 只读观察 YAML 选中 lane 的 source authority、对应 PipelineRun、GitOps latest、Argo Application、runtime workload、manager source commit 和 git mirror 摘要，并报告 Argo revision 是否对齐该 lane 的 GitOps latest。`v0.2` lane 的 source authority 只来自 k8s git-mirror snapshot：受控 sync 先为 branch tip 创建 `refs/unidesk/snapshots/agentrun-yaml-lane//`，`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 ` 与 `--source-commit ` 定点查询；`--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`，避免长时间聚合时无可见进展。`trigger-current` 会先执行 k8s git-mirror sync 并以 snapshot commit 创建 commit-pinned PipelineRun；同名 PipelineRun 正在运行或已经成功时必须拒绝重复触发，只允许在失败态或不存在时创建。该命令只提交 CI/CD 工作，不等待完整 PipelineRun 或 rollout 完成，后续用 `job status` 和 `status --pipeline-run ` 轮询。`refresh` 只对 YAML 声明的 Argo Application 执行 hard refresh，用于 GitOps promotion 已完成但 Argo 仍停留旧 revision 时的受控同步入口；它不直接 patch runtime workload。 -YAML-only lane 的 `trigger-current --confirm` 是受控长流程入口；source bootstrap、image build、GitOps publish、git-mirror sync 和 PipelineRun 创建必须拆成短提交与状态轮询，不得把 clone、build、push 或长时间 polling 放进一个顶层 `trans` 长连接。`trigger-current` 返回异步 job 时，先用 `bun scripts/cli.ts job status --tail-bytes 12000` 观察 `agentrun-yaml-lane-trigger` progress，再用 `agentrun control-plane status --node --lane --pipeline-run ` 观察 Tekton、GitOps 和 Argo 对齐。后台步骤的 `status` 与 `ok` 必须共同判定，`status=succeeded` 但 `ok=false` 是终态失败，不能继续轮询到超时。GitOps publish 必须使用隔离临时 clone/worktree，不能切换或污染 YAML 声明的固定 source workspace；如果历史失败 publish 已让固定 workspace dirty、detached 或停在 GitOps 分支，只清理已知生成产物/失败发布残留并恢复到 lane source branch 后再重试。 +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 --tail-bytes 12000` 观察 `agentrun-yaml-lane-trigger` progress，再用 `agentrun control-plane status --node --lane --pipeline-run ` 观察 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 重新触发。 -AgentRun YAML-only lane 发布收口必须以当前 source branch truth 为准。`trigger-current` 期间若 lane source branch 被并行 PR 推进，`status --pipeline-run ` 会通过 `branchDrift.sourceBranchAdvanced=true` / `targetSupersededByCurrentBranch=true` 标记该 PipelineRun 已不是当前 branch tip；closeout 必须确认最新 tip 包含本次修复，再按最新 tip 重新 `trigger-current`，最后用最新 PipelineRun 的 `status` 证明 `aligned=true`、`blockers=[]`、`argoSyncedToGitops=true` 和 `managerSourceMatchesExpected=true`。不要用已经被更新 source supersede 的中间 PipelineRun 作为最终 closeout。 +AgentRun YAML-only lane 发布收口必须以当前 k8s git-mirror snapshot tip 为准。`trigger-current` 期间若 lane source branch 被并行 PR 推进，`status --pipeline-run ` 会通过 `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。 -`trigger-current` 的 source bootstrap 可能为 commit-pinned 构建短暂检出精确 commit；confirmed `trigger-current` 收尾会尝试把 YAML 声明的固定 source workspace 恢复到 lane source branch，并在返回 JSON 中披露 `sourceWorkspaceRestore`。如果返回 `source-worktree-restore-failed` warning、workspace dirty，或后续 `status` 仍显示 `summary.source.workspaceDetached=true`，先按 `sourceWorkspaceRestore.failureKind` 修复固定 workspace，再继续创建 worktree、触发发布或写 closeout；不要把 detached 固定 workspace 当作下一轮开发或部署的 source truth。 - -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。 +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.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。 Provider credential Secret 的 `auth.json` 和 `config.toml` 也必须按 lane 的 YAML `sourceRef` 下发，不能把指挥机全局 Codex 配置当成所有 lane 的运行真相。HWLAB 通过 D601 `agentrun-v02` 使用 Codex profile 时，`config.toml` 应只携带该 lane 需要的 Codex CLI runtime options，例如 model、reasoning、context window、auto compact、storage 和 network 相关键；除非对应 `auth.json` / API key source 也由同一 lane 明确拥有并已验证，否则不要在 lane config 中覆盖 provider endpoint、`base_url`、`model_provider` 或其他 endpoint 绑定。常见回归有两类：同步到 runner 的 config 缺少 `model_context_window` / `model_auto_compact_token_limit`，导致多轮 tool/webSearch 后报 context-window failure；或者为了补参数误加不匹配的 provider endpoint，导致 provider auth failure。修复必须走 `agentrun control-plane secret-sync --node --lane ` 的 dry-run/confirm，再用 `restart` 生效，并通过 HWLAB `hwlab-cli client agent send|trace|result` 原入口验证；不要从 Kubernetes Secret 反解配置内容或在 issue/trace 中打印 payload。 diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index bf9fb8d8..e8a8a206 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -8,16 +8,17 @@ - HWLAB legacy G14 DEV/PROD 已退役；`G14`/`G14-gitops`、`hwlab-dev`/`hwlab-prod`、17666/17667 和 18666/18667 不再是当前 source/runtime truth。退役状态和执行入口是 `bun scripts/cli.ts hwlab g14 retirement status|plan|execute --confirm`，细则见 `docs/reference/g14.md`。 - HWLAB 指挥侧目标选择必须以 issue 或 CLI 中明确写出的 lane/node 为准；只有没有明确目标时，才读取 `config/hwlab-node-lanes.yaml` 的默认值。`config/hwlab-node-lanes.yaml` 是 node、lane、workspace、CI/CD repo、namespace、GitOps path、公网入口和 Secret sourceRef 的配置真相，长期参考不能把 G14、D601、v0.2 或 v0.3 写成隐藏默认。 - HWLAB node-scoped `git-mirror` 的 GitHub upstream 标准传输使用 SSH，并由 `config/hwlab-node-control-plane.yaml` 的 `targets[].gitMirror.githubTransport.mode: ssh` 声明。D601/v03 固定通过 `GIT_SSH` wrapper 访问 `ssh://git@ssh.github.com:443/...`；node-global HTTP proxy 只作为 SSH CONNECT tunnel，不是 GitHub HTTPS auth/token transport。若运行面或 CLI 输出 `transport=https`、`GITHUB_TOKEN`、`git-mirror-github-token` 或 HTTPS token sourceRef，视为 control-plane drift/配置回归，先修 YAML 并执行 `hwlab nodes control-plane apply --node --lane --confirm`，禁止改走 HTTPS、host workspace repair、fallback 或多来源仲裁。 +- HWLAB v0.3 CI/CD source authority 只来自 k8s git-mirror snapshot：`trigger-current` / `status` / build 先经受控 sync 创建并读取 `refs/unidesk/snapshots/hwlab-node-runtime//`，不得把 host worktree、本地 fetch/pull、可变 branch ref 或 Pipeline 直连 GitHub 当 authoritative source。固定 workspace 只服务源码修改、PR 准备和 repo 内验证；rollout closeout 以 git-mirror snapshot、PipelineRun、GitOps/Argo revision 和 runtime revision 收口。完整操作口径见 `$unidesk-cicd`。 - 进入任何 HWLAB lane 工作前，先解析目标 `--node --lane ` 或 issue 中的“目标分支/目标节点”，再用 YAML 解析出的 route/workspace/sourceBranch/kubeRoute/runtime namespace 做预检、快进和验证。例如 `目标分支: HWLAB v0.3` 且 `目标节点: D601` 时，工作面是 `D601:/home/ubuntu/workspace/hwlab-v03`、source branch 是 `v0.3`、k3s route 是 `D601:k3s`、runtime namespace 是 `hwlab-v03`、公网入口是 `https://hwlab.pikapython.com`。 -- D518 的 HWLAB v0.3 固定主 workspace 是 `D518:/home/ubuntu/workspace/hwlab-v03`，固定跟踪 `github/v0.3`。D518 上的源码修改、PR 准备、运行面修复和 rollout 前 source truth 检查必须在该固定 workspace 下创建任务级 `.worktree/`；master server 本地 `/root/HWLAB`、一次性 clone 或未由 YAML 选中的路径只能做只读对照，不能承担 D518 source truth。 -- JD01 的 HWLAB v0.3 固定主 workspace 是 `JD01:/root/workspace/hwlab-v03`，固定跟踪 `github/v0.3`。JD01 上的源码修改、PR 准备、运行面修复和 rollout 前 source truth 检查必须在该固定 workspace 下创建任务级 `.worktree/`；如果固定目录尚未初始化，先建立该目录的固定 repo，再继续当前任务。 +- D518 的 HWLAB v0.3 固定主 workspace 是 `D518:/home/ubuntu/workspace/hwlab-v03`，固定跟踪 `github/v0.3`。D518 上的源码修改、PR 准备和 repo 内验证必须在该固定 workspace 下创建任务级 `.worktree/`；master server 本地 `/root/HWLAB`、一次性 clone 或未由 YAML 选中的路径只能做只读对照，不能承担 D518 开发 source truth。 +- JD01 的 HWLAB v0.3 固定主 workspace 是 `JD01:/root/workspace/hwlab-v03`，固定跟踪 `github/v0.3`。JD01 上的源码修改、PR 准备和 repo 内验证必须在该固定 workspace 下创建任务级 `.worktree/`；如果固定目录尚未初始化，先建立该目录的固定 repo，再继续当前任务。 - JD01 的出网、依赖拉取、k3s/bootstrap、git-mirror 和 web-probe 浏览器依赖都以 UniDesk YAML 中的 host-route/host-proxy 声明为准：`config/hwlab-node-control-plane.yaml` 的 `nodes.JD01.egressProxy`、`config/platform-infra/host-proxy.yaml#targets.JD01`，以及 `config/hwlab-node-lanes.yaml` 的 JD01 network/download/sourceWorkspace 配置。JD01 的 MDTODO、Cloud Web、web-probe 或 rollout 任务不是 Sub2API 任务；除非 issue/CLI 明确指向 Sub2API runtime、Codex pool 或 platform-infra sub2api target，不要把这类故障默认归因到 Sub2API，也不要把 JD01 egress 临时切到 Sub2API 路径。 - JD01 的 node-local registry 是 k3s workload/PVC，不是 host Docker registry。`hwlab nodes control-plane infra status --node JD01 --lane v03` 应显示 registry workload ready、PVC bound、endpoint ready、`zeroSeeded=true` 和 `seededFromOldRegistry=false`；旧 host Docker `registry` 容器应保持停止。零种子 registry 迁移后，必须通过受控 `runtime-image preload` 和 `infra tools-image build/status` 补齐 BuildKit、runtime/base 和 tools image，再把 HWLAB/AgentRun status 与 web-probe smoke 作为可用性证据。 - HWLAB 项目内长期规则入口仍以目标 repo 的 `AGENTS.md` 为准。进入已解析的目标 workspace 后，必须重新读取该 workspace 的规则文件；不能只凭主 server 的压缩上下文继续操作。 -- 每次开始 node/lane 工作前必须通过 UniDesk SSH 桥检查目标 workspace，例如 `trans : sh -- 'git fetch origin && git pull --ff-only origin && git status --short --branch && git remote -v'`；若不满足目标 lane 预期，先修正 workspace，不能继续开发、render、polling 或部署。 +- 每次开始 node/lane 源码修改、PR 准备或 repo 内验证前必须通过 UniDesk SSH 桥检查目标 workspace，例如 `trans : sh -- 'git fetch origin && git pull --ff-only origin && git status --short --branch && git remote -v'`；若不满足目标 lane 预期，先修正 workspace，不能继续把该 workspace 用作开发工作面。CI/CD trigger、status 和 rollout source closeout 仍以 k8s git-mirror snapshot 为准。 - k3s 操作必须使用 YAML 解析出的 route 语法，例如 `trans D601:k3s ...` 或 `trans G14:k3s ...`。第一个 route token 必须定位分布式目标，后续 token 才是 operation。 - D601 node-scoped runtime（例如 `D601` + `v0.3`）不是 legacy；只要 issue/CLI 明确选择 D601 node/lane，就按 YAML 中的 D601 target 执行。D601 legacy 只指旧 DEV/迁移/回滚对照路径（如 `/home/ubuntu/workspace/hwlab-dev`、16666/16667 或历史 `deploy/deploy.json` wrapper），必须由 issue/CLI 明确写成 legacy/迁移/回滚才使用。 -- `/root/HWLAB`、`/workspace/hwlab`、`/home/ubuntu/hwlab`、`/tmp/hwlab-*`、无关 runner clone、master-server checkout 或未由 YAML 选中的 workspace 都不能作为当前 HWLAB source truth。 +- `/root/HWLAB`、`/workspace/hwlab`、`/home/ubuntu/hwlab`、`/tmp/hwlab-*`、无关 runner clone、master-server checkout 或未由 YAML 选中的 workspace 都不能作为当前 HWLAB 开发 source truth；CI/CD source authority 只看 k8s git-mirror snapshot。 ## 关键 GitHub 入口