From 71ea48b53d4fa2f21de16dbc22f515870d21692a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 29 Apr 2026 11:39:57 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/ci.md | 278 +++++++++++++++++++--------- docs/zh-CN/reference/RELEASING.md | 289 ++++++++++++++++-------------- 2 files changed, 349 insertions(+), 218 deletions(-) diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 8594d9768..79ac7f6af 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -1,68 +1,68 @@ --- read_when: - - 你需要了解为什么 CI 作业运行了或没有运行 + - 你需要了解某个 CI 作业为什么运行或没有运行 - 你正在调试失败的 GitHub Actions 检查 -summary: CI 作业图、作用域门禁和等效本地命令 +summary: CI 作业图、范围门禁和本地命令对应项 title: CI 流水线 x-i18n: - generated_at: "2026-04-29T10:40:02Z" + generated_at: "2026-04-29T11:37:50Z" model: gpt-5.5 provider: openai - source_hash: 4e4b9dae0e16e5ae701c4dbe5966ac9c4b3d8a3292f1804eef8f595616170e43 + source_hash: f3240aa7058dc4f624c45a400cac7a5b2cbbe442a7e17f3f0e1858cc9a876129 source_path: ci.md workflow: 16 --- -CI 在每次推送到 `main` 以及每个拉取请求时运行。它使用智能作用域，在只有无关区域发生变化时跳过昂贵的作业。手动 `workflow_dispatch` 运行会有意绕过智能作用域，并为发布候选版本或广泛验证展开完整的正常 CI 图；对于独立手动运行，Android 通道通过 `include_android` 选择启用。仅发布用的插件预发布通道位于单独的 `Plugin Prerelease` 工作流中，并且只会从 `Full Release Validation` 或显式手动调度运行。 +CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能范围限定，在只有无关区域变更时跳过昂贵任务。手动 `workflow_dispatch` 运行会有意绕过智能范围限定，并展开完整的常规 CI 图，用于候选发布或广泛验证；对于独立手动运行，Android 轨道通过 `include_android` 选择启用。仅发布用的插件预发布轨道位于单独的 `Plugin Prerelease` 工作流中，并且只从 `Full Release Validation` 或显式手动调度运行。 -`check-dependencies` 分片运行 `pnpm deadcode:dependencies`，这是一个仅依赖项的生产 Knip 检查，固定到该脚本使用的最新 Knip 版本，并且在 `dlx` 安装时禁用 pnpm 的最低发布年龄。它还运行 `pnpm deadcode:unused-files`，将 Knip 的生产未使用文件发现结果与 `scripts/deadcode-unused-files.allowlist.mjs` 进行比较。当 PR 添加新的未审查未使用文件，或在清理后留下过期的允许列表条目时，该保护会失败，同时保留 Knip 无法静态解析的有意动态插件、生成文件、构建、实时测试和包桥接表面。 +`check-dependencies` 分片运行 `pnpm deadcode:dependencies`，这是一个仅针对生产 Knip 依赖项的检查过程，固定到该脚本使用的最新 Knip 版本，并在 `dlx` 安装时禁用 pnpm 的最小发布年龄限制。它还运行 `pnpm deadcode:unused-files`，将 Knip 的生产未使用文件发现与 `scripts/deadcode-unused-files.allowlist.mjs` 进行比较。该保护会在 PR 添加新的未经审查的未使用文件，或在清理后留下过期的 allowlist 条目时失败，同时保留 Knip 无法静态解析的有意动态插件、生成内容、构建、实时测试和软件包桥接表面。 -`Full Release Validation` 是用于“发布前运行所有内容”的手动总控工作流。它接受一个分支、标签或完整提交 SHA，使用该目标调度手动 `CI` 工作流，调度 `Plugin Prerelease` 以提供仅发布用的插件、包、静态和 Docker 证明，并调度 `OpenClaw Release Checks` 以执行安装冒烟、包验收、Docker 发布路径套件、实时/E2E、OpenWebUI、QA Lab 对等性、Matrix 和 Telegram 通道。当提供已发布包规格时，它也可以运行发布后的 `NPM Telegram Beta E2E` 工作流。`release_profile=minimum|stable|full` 控制传递给发布检查的实时/提供商覆盖广度：`minimum` 保留最快的 OpenAI/核心发布关键通道，`stable` 添加稳定的提供商/后端集合，`full` 运行广泛的顾问提供商/媒体矩阵。该总控工作流会记录已调度的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流重新运行后变绿，只需重新运行父级验证器作业，以刷新总控结果和时间摘要。 +`Full Release Validation` 是用于“发布前运行所有内容”的手动总括工作流。它接受分支、标签或完整提交 SHA，使用该目标调度手动 `CI` 工作流，调度 `Plugin Prerelease` 以获取仅发布用的插件/软件包/静态/Docker 证明，并调度 `OpenClaw Release Checks` 以执行安装冒烟、软件包验收、Docker 发布路径套件、实时/E2E、OpenWebUI、QA Lab 奇偶性、Matrix 和 Telegram 轨道。当提供已发布软件包规格时，它还可以运行发布后的 `NPM Telegram Beta E2E` 工作流。`release_profile=minimum|stable|full` 控制传入发布检查的实时/提供商覆盖广度：`minimum` 保留最快的 OpenAI/核心发布关键轨道，`stable` 添加稳定的提供商/后端集合，`full` 运行广泛的建议提供商/媒体矩阵。该总括工作流会记录已调度的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流被重新运行并变为绿色，只重新运行父级验证器作业即可刷新总括结果和时间摘要。 -对于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。对于发布候选版本使用 `all`，仅针对正常完整 CI 子项使用 `ci`，针对每个发布子项使用 `release-checks`，或者在总控工作流上使用更窄的发布组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这样可以在完成聚焦修复后，将失败发布盒子的重新运行范围限制住。 +对于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。对候选发布使用 `all`，仅对常规完整 CI 子项使用 `ci`，对每个发布子项使用 `release-checks`，或在总括工作流上使用更窄的发布组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这样可以在集中修复后将失败发布环境的重新运行限制在边界内。 -发布实时/E2E 子项保留广泛的原生 `pnpm test:live` 覆盖，但它会通过 `scripts/test-live-shard.mjs` 以具名分片运行（`native-live-src-agents`、`native-live-src-gateway-core`、按提供商过滤的 `native-live-src-gateway-profiles` 作业、`native-live-src-gateway-backends`、`native-live-test`、`native-live-extensions-a-k`、`native-live-extensions-l-n`、`native-live-extensions-openai`、`native-live-extensions-o-z-other`、`native-live-extensions-xai`、拆分的媒体音频/视频分片，以及按提供商过滤的音乐分片），而不是一个串行作业。这样在保持相同文件覆盖的同时，使慢速实时提供商故障更容易重新运行和诊断。聚合的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称仍然可用于手动一次性重新运行。 +发布实时/E2E 子项保留广泛的原生 `pnpm test:live` 覆盖，但它通过 `scripts/test-live-shard.mjs` 将其作为具名分片运行（`native-live-src-agents`、`native-live-src-gateway-core`、按提供商过滤的 `native-live-src-gateway-profiles` 作业、`native-live-src-gateway-backends`、`native-live-test`、`native-live-extensions-a-k`、`native-live-extensions-l-n`、`native-live-extensions-openai`、`native-live-extensions-o-z-other`、`native-live-extensions-xai`、拆分的媒体音频/视频分片，以及按提供商过滤的音乐分片），而不是一个串行作业。这样既保持相同的文件覆盖，又让缓慢的实时提供商失败更容易重新运行和诊断。聚合分片名称 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 对手动一次性重新运行仍然有效。 -原生实时媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预安装 `ffmpeg` 和 `ffprobe`；媒体作业只会在设置前验证这些二进制文件。将 Docker 支持的实时套件保留在普通 Blacksmith runner 上，因为容器作业不适合启动嵌套 Docker 测试。 +原生实时媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预装了 `ffmpeg` 和 `ffprobe`；媒体作业只在设置前验证二进制文件。将 Docker 支撑的实时套件保留在常规 Blacksmith runner 上，因为容器作业不适合启动嵌套 Docker 测试。 -Docker 支持的实时模型/后端分片会为每个选定提交使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:` 镜像。实时发布工作流会构建并推送该镜像一次，然后 Docker 实时模型、Gateway 网关、CLI 后端、ACP 绑定和 Codex harness 分片会使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。如果这些分片独立重新构建完整源 Docker 目标，则说明发布运行配置错误，并会在重复镜像构建上浪费墙钟时间。 +Docker 支撑的实时模型/后端分片对每个选定提交使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:` 镜像。实时发布工作流会构建并推送一次该镜像，然后 Docker 实时模型、Gateway 网关、CLI 后端、ACP 绑定和 Codex harness 分片会以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。如果这些分片独立重新构建完整源 Docker 目标，则说明发布运行配置错误，并且会在重复镜像构建上浪费挂钟时间。 -`OpenClaw Release Checks` 使用受信任的工作流引用，将选定引用一次性解析为 `release-package-under-test` tarball，然后将该产物传递给实时/E2E 发布路径 Docker 工作流和包验收分片。这能确保发布盒子之间的包字节保持一致，并避免在多个子作业中重新打包同一个候选版本。 +`OpenClaw Release Checks` 使用受信任的工作流 ref 将选定 ref 一次解析为 `release-package-under-test` tarball，然后将该构件传递给实时/E2E 发布路径 Docker 工作流和软件包验收分片。这会让软件包字节在各个发布环境间保持一致，并避免在多个子作业中重新打包同一个候选项。 -`Package Acceptance` 是用于验证包产物且不阻塞发布工作流的旁路运行工作流。它从已发布的 npm 规格、使用选定 `workflow_ref` harness 构建的受信任 `package_ref`、带 SHA-256 的 HTTPS tarball URL，或来自另一个 GitHub Actions 运行的 tarball 产物中解析一个候选版本，将其上传为 `package-under-test`，然后使用该 tarball 复用 Docker 发布/E2E 调度器，而不是重新打包工作流检出。配置文件覆盖冒烟、包、产品、完整和自定义 Docker 通道选择。`package` 配置文件使用离线插件覆盖，因此已发布包验证不会受实时 ClawHub 可用性限制。可选的 Telegram 通道会在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` 产物，并为独立调度保留已发布 npm 规格路径。 +`Package Acceptance` 是用于验证软件包构件且不阻塞发布工作流的旁路运行工作流。它会从已发布的 npm 规格、使用选定 `workflow_ref` harness 构建的受信任 `package_ref`、带 SHA-256 的 HTTPS tarball URL，或另一个 GitHub Actions 运行中的 tarball 构件解析一个候选项，将其上传为 `package-under-test`，然后使用该 tarball 复用 Docker 发布/E2E 调度器，而不是重新打包工作流检出内容。配置档覆盖冒烟、软件包、产品、完整和自定义 Docker 轨道选择。`package` 配置档使用离线插件覆盖，因此已发布软件包验证不会受实时 ClawHub 可用性阻塞。可选 Telegram 轨道在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` 构件，并保留已发布 npm 规格路径以支持独立调度。 -## 包验收 +## 软件包验收 -当问题是“这个可安装的 OpenClaw 包作为产品是否可用？”时，使用 `Package Acceptance`。它不同于正常 CI：正常 CI 验证源代码树，而包验收会通过用户在安装或更新后实际使用的同一 Docker E2E harness 验证单个 tarball。 +当问题是“这个可安装的 OpenClaw 软件包是否能作为产品工作？”时，使用 `Package Acceptance`。它不同于常规 CI：常规 CI 验证源代码树，而软件包验收通过用户在安装或更新后会执行的同一个 Docker E2E harness 来验证单个 tarball。 该工作流有四个作业： -1. `resolve_package` 检出 `workflow_ref`，解析一个包候选版本，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者作为 `package-under-test` 产物上传，并在 GitHub 步骤摘要中打印来源、工作流引用、包引用、版本、SHA-256 和配置文件。 -2. `docker_acceptance` 调用 `openclaw-live-and-e2e-checks-reusable.yml`，并使用 `ref=workflow_ref` 和 `package_artifact_name=package-under-test`。可复用工作流会下载该产物，验证 tarball 清单，在需要时准备 package-digest Docker 镜像，并针对该包运行选定的 Docker 通道，而不是打包工作流检出。当某个配置文件选择多个目标 `docker_lanes` 时，可复用工作流会准备一次包和共享镜像，然后将这些通道展开为并行目标 Docker 作业，并使用唯一产物。 -3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时运行，并且在 Package Acceptance 已解析某个包时安装同一个 `package-under-test` 产物；独立 Telegram 调度仍然可以安装已发布 npm 规格。 -4. `summary` 会在包解析、Docker 验收或可选 Telegram 通道失败时使工作流失败。 +1. `resolve_package` 检出 `workflow_ref`，解析一个软件包候选项，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将二者上传为 `package-under-test` 构件，并在 GitHub 步骤摘要中打印来源、工作流 ref、软件包 ref、版本、SHA-256 和配置档。 +2. `docker_acceptance` 使用 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 调用 `openclaw-live-and-e2e-checks-reusable.yml`。可复用工作流会下载该构件，验证 tarball 清单，在需要时准备软件包摘要 Docker 镜像，并针对该软件包运行选定的 Docker 轨道，而不是打包工作流检出内容。当某个配置档选择多个目标 `docker_lanes` 时，可复用工作流会准备一次软件包和共享镜像，然后将这些轨道展开为并行的目标 Docker 作业，并使用唯一构件。 +3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时运行，并在 Package Acceptance 已解析一个构件时安装同一个 `package-under-test` 构件；独立 Telegram 调度仍然可以安装已发布的 npm 规格。 +4. `summary` 会在软件包解析、Docker 验收或可选 Telegram 轨道失败时使工作流失败。 候选来源： -- `source=npm`：仅接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta/稳定版验收。 -- `source=ref`：打包受信任的 `package_ref` 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支/标签，验证选定提交可从仓库分支历史或发布标签到达，在分离工作树中安装依赖项，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。 +- `source=npm`：只接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta/稳定版验收。 +- `source=ref`：打包受信任的 `package_ref` 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支/标签，验证选定提交可从仓库分支历史或发布标签到达，在分离工作树中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。 - `source=url`：下载 HTTPS `.tgz`；必须提供 `package_sha256`。 -- `source=artifact`：从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 可选，但对于外部共享产物应提供。 +- `source=artifact`：从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 是可选项，但应为外部共享构件提供。 -将 `workflow_ref` 和 `package_ref` 分开。`workflow_ref` 是运行测试的受信任工作流/harness 代码。`package_ref` 是在 `source=ref` 时被打包的源提交。这样当前测试 harness 可以验证较旧的受信任源提交，而无需运行旧的工作流逻辑。 +保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的受信任工作流/harness 代码。`package_ref` 是在 `source=ref` 时被打包的源提交。这使当前测试 harness 能够验证较旧的受信任源提交，而无需运行旧工作流逻辑。 -配置文件映射到 Docker 覆盖： +配置档映射到 Docker 覆盖： - `smoke`：`npm-onboard-channel-agent`、`gateway-network`、`config-reload` - `package`：`npm-onboard-channel-agent`、`doctor-switch`、`update-channel-switch`、`bundled-channel-deps-compat`、`plugins-offline`、`plugin-update` - `product`：`package` 加上 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui` -- `full`：包含 OpenWebUI 的完整 Docker 发布路径分块 +- `full`：带 OpenWebUI 的完整 Docker 发布路径分块 - `custom`：精确的 `docker_lanes`；当 `suite_profile=custom` 时必需 -发布检查会使用 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'` 和 `telegram_mode=mock-openai` 调用 Package Acceptance。发布路径 Docker 分块覆盖重叠的包/更新/插件通道，而 Package Acceptance 保留针对同一已解析包 tarball 的产物原生内置渠道兼容性、离线插件和 Telegram 证明。 -跨 OS 发布检查仍然覆盖特定于 OS 的新手引导、安装器和平台行为；包/更新产品验证应从 Package Acceptance 开始。Windows 打包和安装器全新通道还会验证已安装包能否从原始绝对 Windows 路径导入 browser-control 覆盖。 +发布检查使用 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'` 和 `telegram_mode=mock-openai` 调用软件包验收。发布路径 Docker 分块覆盖重叠的软件包/更新/插件轨道，而软件包验收会针对同一个已解析软件包 tarball 保留构件原生的内置渠道兼容、离线插件和 Telegram 证明。 +跨 OS 发布检查仍覆盖 OS 特定的新手引导、安装程序和平台行为；软件包/更新产品验证应从软件包验收开始。Windows 已打包和安装程序全新安装轨道还会验证已安装软件包能否从原始绝对 Windows 路径导入浏览器控制覆盖。OpenAI 跨 OS 智能体回合冒烟测试在设置时默认使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4-mini`，从而让安装和 Gateway 网关证明保持快速且确定。专用实时提供商/模型轨道仍覆盖更广泛的模型路由，包括较慢的前沿默认项。 -对于已发布的包，Package Acceptance 有有界的旧版兼容窗口。直到 `2026.4.25` 的包（包括 `2026.4.25-beta.*`）可以对 `dist/postinstall-inventory.json` 中指向 tarball 省略文件的已知私有 QA 条目使用兼容路径；当包未暴露 `gateway install --wrapper` 标志时，`doctor-switch` 可以跳过其持久化子用例；`update-channel-switch` 可以从 tarball 派生的假 git fixture 中剪除缺失的 `pnpm.patchedDependencies`，并可以记录缺失的持久化 `update.channel`；插件冒烟可以读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；`plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。已发布的 `2026.4.26` 包也可以对已经随包发布的本地构建元数据戳文件发出警告。之后的包必须满足现代契约；相同条件会失败，而不是警告或跳过。 +软件包验收为已经发布的软件包设置了有边界的旧版兼容窗口。直到 `2026.4.25` 的软件包，包括 `2026.4.25-beta.*`，可以对 `dist/postinstall-inventory.json` 中指向 tarball 已省略文件的已知私有 QA 条目使用兼容路径；当软件包不暴露该标志时，`doctor-switch` 可以跳过 `gateway install --wrapper` 持久化子用例；`update-channel-switch` 可以从 tarball 派生的假 git 夹具中修剪缺失的 `pnpm.patchedDependencies`，并可以记录缺失的已持久化 `update.channel`；插件冒烟测试可以读取旧版安装记录位置，或接受缺少 marketplace 安装记录持久化；`plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。已发布的 `2026.4.26` 软件包也可以对已经发布的本地构建元数据戳记文件发出警告。之后的软件包必须满足现代契约；相同条件会失败，而不是警告或跳过。 示例： @@ -105,23 +105,116 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -调试失败的软件包验收运行时，先从 `resolve_package` 摘要开始，确认软件包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker 产物：`.artifacts/docker-tests/**/summary.json`、`failures.json`、通道日志、阶段耗时和重跑命令。优先重跑失败的软件包 profile 或精确的 Docker 通道，而不是重跑完整发布验证。 +调试失败的包验收运行时，先查看 `resolve_package` +摘要，以确认包来源、版本和 SHA-256。然后检查 +`docker_acceptance` 子运行及其 Docker 产物： +`.artifacts/docker-tests/**/summary.json`、`failures.json`、通道日志、阶段 +计时和重新运行命令。优先重新运行失败的包配置文件或 +精确的 Docker 通道，而不是重新运行完整发布验证。 -QA Lab 有独立于主智能作用域工作流之外的专用 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更和手动派发时运行；它会构建私有 QA 运行时，并比较模拟 GPT-5.5 和 Opus 4.6 智能体包。`QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，也可手动派发；它会将模拟 parity gate、实时 Matrix 通道，以及实时 Telegram 和 Discord 通道作为并行作业展开。实时作业使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex leases。发布检查使用确定性模拟提供商和模拟限定模型（`mock-openai/gpt-5.5` 和 `mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram 实时传输通道，以便将渠道契约与实时模型延迟和正常提供商插件启动隔离开。实时传输 Gateway 网关还会禁用内存搜索，因为 QA parity 会单独覆盖内存行为；提供商连接性由单独的实时模型、原生提供商和 Docker 提供商套件覆盖。Matrix 在计划任务和发布门禁中使用 `--profile fast`，仅在签出的 CLI 支持时添加 `--fail-fast`。CLI 默认值和手动工作流输入仍为 `all`；手动 `matrix_profile=all` 派发始终会将完整 Matrix 覆盖分片到 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业中。`OpenClaw Release Checks` 还会在发布批准前运行发布关键的 QA Lab 通道；其 QA parity gate 会将候选包和基线包作为并行通道作业运行，然后在一个小型报告作业中下载两者的产物，用于最终 parity 对比。除非变更实际触及 QA 运行时、模型包 parity，或 parity 工作流拥有的表面，否则不要把 PR 落地路径放在 `Parity gate` 后面。对于常规渠道、配置、文档或单元测试修复，将它视为可选信号，并遵循作用域内的 CI/检查证据。 +QA Lab 在主智能作用域工作流之外有专用 CI 通道。 +`Parity gate` 工作流会在匹配的 PR 变更和手动分发时运行；它 +构建私有 QA 运行时，并比较模拟 GPT-5.5 和 Opus 4.6 +智能体包。`QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，也可 +手动分发；它会将模拟对等门、实时 Matrix 通道以及实时 +Telegram 和 Discord 通道作为并行作业展开。实时作业使用 +`qa-live-shared` 环境，Telegram/Discord 使用 Convex 租约。发布 +检查会使用确定性模拟提供商和模拟限定模型（`mock-openai/gpt-5.5` 和 +`mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram 实时传输通道，这样渠道 +契约就能与实时模型延迟和正常提供商插件启动隔离。实时传输 Gateway 网关还会 +禁用内存搜索，因为 QA 对等性会单独覆盖内存行为； +提供商连接性由单独的实时模型、原生提供商和 Docker 提供商套件覆盖。Matrix 对计划和发布门使用 `--profile fast`， +仅当检出的 CLI 支持时才添加 `--fail-fast`。CLI 默认值和手动工作流输入保持为 +`all`；手动 `matrix_profile=all` +分发始终将完整 Matrix 覆盖分片为 `transport`、`media`、 +`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。`OpenClaw Release Checks` 也会 +在发布审批前运行发布关键的 QA Lab 通道；其 QA 对等门会将候选包和基线包作为并行通道作业运行，然后把 +两个产物下载到一个小型报告作业中，用于最终对等比较。 +除非变更实际触及 QA 运行时、模型包对等性，或对等工作流负责的表面， +否则不要把 PR 落地路径置于 `Parity gate` 之后。 +对于常规渠道、配置、文档或单元测试修复，应将其视为可选 +信号，并遵循作用域内的 CI/检查证据。 -`Duplicate PRs After Merge` 工作流是用于落地后重复清理的手动维护者工作流。它默认 dry-run，并且仅在 `apply=true` 时关闭显式列出的 PR。在修改 GitHub 前，它会验证落地 PR 已合并，并且每个重复 PR 都有共享的引用 issue 或重叠的变更 hunk。 +`Duplicate PRs After Merge` 工作流是用于落地后重复项清理的手动维护者工作流。 +它默认 dry-run，且仅在 `apply=true` 时关闭明确 +列出的 PR。在修改 GitHub 之前，它会验证 +已落地 PR 已合并，并且每个重复项要么有共同引用的 issue， +要么有重叠的变更块。 -`CodeQL` 工作流刻意作为窄范围的第一轮安全扫描器，而不是完整仓库扫描。每日和手动运行会使用高精度安全查询扫描 Actions 工作流代码，以及风险最高的 JavaScript/TypeScript 凭证、密钥、沙箱、cron 和 Gateway 网关表面。channel-runtime-boundary 作业会在 `/codeql-critical-security/channel-runtime-boundary` 类别下，单独扫描核心渠道实现契约以及渠道插件运行时、Gateway 网关、插件 SDK、密钥和审计触点，以便渠道安全信号能够扩展，而不需要扩大基线 JS/TS 类别。 +`CodeQL` 工作流有意作为窄范围的首轮安全扫描器， +而不是完整仓库扫描。每日和手动运行会使用高精度安全查询扫描 Actions 工作流代码 +以及风险最高的 JavaScript/TypeScript 凭证、密钥、沙箱、cron 和 +Gateway 网关表面。 +channel-runtime-boundary 作业会在 `/codeql-critical-security/channel-runtime-boundary` +类别下单独扫描核心渠道实现 +契约，以及渠道插件运行时、Gateway 网关、插件 SDK、密钥和 +审计接触点，这样渠道安全信号就能在不扩大基线 +JS/TS 类别的情况下扩展。 -`CodeQL Android Critical Security` 工作流是计划运行的 Android 安全分片。它会在 workflow sanity 接受的最小 Blacksmith Linux runner 标签上为 CodeQL 手动构建 Android 应用，并在 `/codeql-critical-security/android` 类别下上传结果。 +`CodeQL Android Critical Security` 工作流是计划执行的 Android +安全分片。它会在工作流完整性检查接受的最小 +Blacksmith Linux runner 标签上为 CodeQL 手动构建 Android 应用，并将结果 +上传到 `/codeql-critical-security/android` 类别下。 -`CodeQL macOS Critical Security` 工作流是每周/手动运行的 macOS 安全分片。它会在 Blacksmith macOS 上为 CodeQL 手动构建 macOS 应用，从上传的 SARIF 中过滤掉依赖构建结果，并在 `/codeql-critical-security/macos` 类别下上传结果。将它保持在每日默认工作流之外，因为即使结果干净，macOS 构建也会主导运行时间。 +`CodeQL macOS Critical Security` 工作流是每周/手动的 macOS +安全分片。它会在 Blacksmith macOS 上为 CodeQL 手动构建 macOS 应用， +从上传的 SARIF 中过滤依赖构建结果，并将结果 +上传到 `/codeql-critical-security/macos` 类别下。将它保持在每日 +默认工作流之外，因为即使干净通过，macOS 构建也会主导运行时间。 -`CodeQL Critical Quality` 工作流是对应的非安全分片。它仅在较小的 Blacksmith Linux runner 上，对窄范围高价值表面运行 error 级别、非安全的 JavaScript/TypeScript 质量查询。其 core-auth-secrets 作业会在单独的 `/codeql-critical-quality/core-auth-secrets` 类别下扫描凭证、密钥、沙箱、cron 和 Gateway 网关安全边界代码。config-boundary 作业会在单独的 `/codeql-critical-quality/config-boundary` 类别下扫描配置 schema、迁移、规范化和 IO 契约。gateway-runtime-boundary 作业会在单独的 `/codeql-critical-quality/gateway-runtime-boundary` 类别下扫描 Gateway 网关协议 schema 和服务器方法契约。channel-runtime-boundary 作业会在单独的 `/codeql-critical-quality/channel-runtime-boundary` 类别下扫描核心渠道实现契约。agent-runtime-boundary 作业会在单独的 `/codeql-critical-quality/agent-runtime-boundary` 类别下扫描命令执行、模型/提供商调度、自动回复调度和队列，以及 ACP 控制平面运行时契约。mcp-process-runtime-boundary 作业会在单独的 `/codeql-critical-quality/mcp-process-runtime-boundary` 类别下扫描 MCP 服务器和工具桥、进程监督辅助函数，以及出站投递契约。memory-runtime-boundary 作业会在单独的 `/codeql-critical-quality/memory-runtime-boundary` 类别下扫描内存宿主 SDK、内存运行时 facade、内存插件 SDK 别名、内存运行时激活胶水代码，以及内存 Doctor 命令。ui-control-plane 作业会在单独的 `/codeql-critical-quality/ui-control-plane` 类别下扫描 Control UI 启动、本地持久化、Gateway 网关控制流，以及任务控制平面运行时契约。web-media-runtime-boundary 作业会在单独的 `/codeql-critical-quality/web-media-runtime-boundary` 类别下扫描核心 Web 获取/搜索、媒体 IO、媒体理解、图像生成和媒体生成运行时契约。plugin-boundary 作业会在单独的 `/codeql-critical-quality/plugin-boundary` 类别下扫描加载器、注册表、公共表面和插件 SDK 入口点契约。让该工作流与安全分离，以便质量发现可以被计划、度量、禁用或扩展，而不遮蔽安全信号。Swift、Python 和内置插件的 CodeQL 扩展应仅在这些窄 profile 具备稳定运行时间和信号后，再作为有作用域或分片的后续工作加回。 +`CodeQL Critical Quality` 工作流是匹配的非安全分片。它 +只在较小的 Blacksmith Linux runner 上，对窄范围高价值表面运行错误严重级别、非安全性的 JavaScript/TypeScript 质量查询。它的 +core-auth-secrets 作业会在单独的 `/codeql-critical-quality/core-auth-secrets` +类别下扫描凭证、密钥、沙箱、cron 和 Gateway 网关安全 +边界代码。config-boundary +作业会在单独的 `/codeql-critical-quality/config-boundary` 类别下扫描配置 schema、迁移、规范化和 IO 契约。 +gateway-runtime-boundary 作业会在单独的 +`/codeql-critical-quality/gateway-runtime-boundary` 类别下扫描 Gateway 网关协议 schema 和服务器方法 +契约。 +channel-runtime-boundary 作业会在单独的 `/codeql-critical-quality/channel-runtime-boundary` 类别下扫描核心渠道实现契约。 +agent-runtime-boundary 作业会在单独的 `/codeql-critical-quality/agent-runtime-boundary` 类别下扫描命令执行、模型/提供商分发、 +自动回复分发和队列，以及 ACP 控制平面运行时契约。 +mcp-process-runtime-boundary 作业会在单独的 +`/codeql-critical-quality/mcp-process-runtime-boundary` 类别下扫描 MCP 服务器和工具桥接、进程 +监督辅助函数，以及出站投递契约。 +memory-runtime-boundary 作业会在单独的 `/codeql-critical-quality/memory-runtime-boundary` +类别下扫描内存宿主 SDK、内存运行时门面、 +内存插件 SDK 别名、内存运行时激活胶水代码，以及内存 Doctor +命令。 +ui-control-plane 作业会在单独的 +`/codeql-critical-quality/ui-control-plane` 类别下扫描 Control UI 启动、本地持久化、Gateway 网关 +控制流，以及任务控制平面运行时契约。 +web-media-runtime-boundary 作业会在单独的 `/codeql-critical-quality/web-media-runtime-boundary` 类别下扫描核心 web 抓取/搜索、媒体 IO、媒体 +理解、图像生成和媒体生成运行时契约。 +plugin-boundary 作业会在单独的 `/codeql-critical-quality/plugin-boundary` +类别下扫描加载器、注册表、公共表面和插件 SDK +入口点契约。将该工作流与安全分开，这样质量发现就能被 +计划执行、度量、禁用或扩展，而不会遮蔽安全信号。 +Swift、Python 和内置插件 CodeQL 扩展应仅在窄范围配置文件拥有稳定的 +运行时和信号之后，作为有作用域或分片的后续工作重新加入。 -`Docs Agent` 工作流是事件驱动的 Codex 维护通道，用于让现有文档与最近落地的变更保持一致。它没有纯计划任务：`main` 上成功的非 bot push CI 运行可以触发它，手动派发也可以直接运行它。当 `main` 已前进，或最近一小时内已创建另一个未跳过的 Docs Agent 运行时，workflow-run 调用会跳过。运行时，它会审查从上一个未跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此一次每小时运行可以覆盖自上次文档通过以来累积的所有 main 变更。 +`Docs Agent` 工作流是事件驱动的 Codex 维护通道，用于让 +现有文档与最近落地的变更保持一致。它没有纯计划任务： +`main` 上成功的非机器人 push CI 运行可以触发它，手动分发也可以 +直接运行它。当 `main` 已向前移动，或过去一小时内 +已有另一个未跳过的 Docs Agent 运行被创建时，workflow-run 调用会跳过。运行时，它会 +审查从上一个未跳过的 Docs Agent 源 SHA 到 +当前 `main` 的提交范围，因此一次每小时运行可以覆盖自 +上次文档处理以来累积的所有 main 变更。 -`Test Performance Agent` 工作流是事件驱动的 Codex 维护通道，用于处理慢测试。它没有纯计划任务：`main` 上成功的非 bot push CI 运行可以触发它，但如果当天 UTC 已经有另一个 workflow-run 调用运行过或正在运行，它会跳过。手动派发会绕过当天活动门禁。该通道会构建完整套件分组 Vitest 性能报告，让 Codex 只进行保留覆盖率的小型测试性能修复，而不是大范围重构，然后重跑完整套件报告，并拒绝降低通过基线测试数量的变更。如果基线存在失败测试，Codex 只能修复明显失败，并且 agent 后的完整套件报告必须通过后才会提交任何内容。当 `main` 在 bot push 落地前前进时，该通道会 rebase 已验证的补丁，重跑 `pnpm check:changed`，并重试 push；有冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，以便 Codex action 可以保持与 docs agent 相同的 drop-sudo 安全姿态。 +`Test Performance Agent` 工作流是事件驱动的 Codex 维护通道， +用于处理慢测试。它没有纯计划任务：`main` 上成功的非机器人 push CI 运行 +可以触发它，但如果当天 UTC 已有另一个 workflow-run 调用 +已经运行或正在运行，它会跳过。手动分发会绕过该每日活动 +门。该通道会构建完整套件分组 Vitest 性能报告，让 Codex +只做小型、保持覆盖率的测试性能修复，而不是大范围 +重构，然后重新运行完整套件报告，并拒绝会降低 +通过基线测试数量的变更。如果基线存在失败测试，Codex 只能修复 +明显失败，并且 agent 之后的完整套件报告必须通过， +才会提交任何内容。当 `main` 在机器人 push 落地前前进时，该通道会 +rebase 已验证的补丁，重新运行 `pnpm check:changed`，并重试 push； +存在冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，这样 Codex +action 就能保持与 docs agent 相同的 drop-sudo 安全姿态。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -132,30 +225,43 @@ gh workflow run duplicate-after-merge.yml \ ## 作业概览 -| 作业 | 目的 | 运行时机 | +| 作业 | 目的 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | 检测仅文档变更、变更作用域、变更插件，并构建 CI manifest | 始终在非草稿 push 和 PR 上运行 | -| `security-scm-fast` | 通过 `zizmor` 执行私钥检测和工作流审计 | 始终在非草稿 push 和 PR 上运行 | -| `security-dependency-audit` | 对照 npm advisories 执行无依赖生产 lockfile 审计 | 始终在非草稿 push 和 PR 上运行 | -| `security-fast` | 快速安全作业的必需聚合项 | 始终在非草稿 push 和 PR 上运行 | -| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查和可复用下游产物 | Node 相关变更 | -| `checks-fast-core` | 快速 Linux 正确性通道，例如内置/插件契约/协议检查 | Node 相关变更 | -| `checks-fast-contracts-channels` | 分片渠道契约检查，并提供稳定的聚合检查结果 | Node 相关变更 | -| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、内置、契约和插件通道 | Node 相关变更 | -| `check` | 分片的主本地门禁等价项：生产类型、lint、guard、测试类型和严格 smoke | Node 相关变更 | -| `check-additional` | 架构、边界、插件表面 guard、软件包边界和 gateway-watch 分片 | Node 相关变更 | -| `build-smoke` | 已构建 CLI smoke 测试和启动内存 smoke | Node 相关变更 | -| `checks` | 构建产物渠道测试的验证器 | Node 相关变更 | -| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke 通道 | 发布的手动 CI 派发 | -| `check-docs` | 文档格式化、lint 和失效链接检查 | 文档已变更 | -| `skills-python` | 针对 Python 支撑的 Skills 运行 Ruff + pytest | Python Skill 相关变更 | -| `checks-windows` | Windows 特定进程/路径测试，以及共享运行时 import specifier 回归 | Windows 相关变更 | -| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试通道 | macOS 相关变更 | -| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | macOS 相关变更 | -| `android` | 两种 flavor 的 Android 单元测试，以及一次 debug APK 构建 | Android 相关变更 | -| `test-performance-agent` | 可信活动后的每日 Codex 慢测试优化 | Main CI 成功或手动派发 | +| `preflight` | 检测仅文档变更、变更范围、变更插件，并构建 CI manifest | 始终在非草稿推送和 PR 上运行 | +| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和 workflow 审计 | 始终在非草稿推送和 PR 上运行 | +| `security-dependency-audit` | 针对 npm advisories 执行无依赖的生产 lockfile 审计 | 始终在非草稿推送和 PR 上运行 | +| `security-fast` | 快速安全作业的必需聚合 | 始终在非草稿推送和 PR 上运行 | +| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查，以及可复用的下游产物 | Node 相关变更 | +| `checks-fast-core` | 快速 Linux 正确性检查线，例如内置/插件契约/协议检查 | Node 相关变更 | +| `checks-fast-contracts-channels` | 带稳定聚合检查结果的分片渠道契约检查 | Node 相关变更 | +| `checks-node-core-test` | Core Node 测试分片，排除渠道、内置、契约和插件检查线 | Node 相关变更 | +| `check` | 分片主本地 gate 等价检查：生产类型、lint、guard、测试类型和严格 smoke | Node 相关变更 | +| `check-additional` | 架构、边界、插件表面 guard、包边界和 gateway-watch 分片 | Node 相关变更 | +| `build-smoke` | 构建后的 CLI smoke 测试和启动内存 smoke | Node 相关变更 | +| `checks` | 构建产物渠道测试的验证器 | Node 相关变更 | +| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke 检查线 | 发布的手动 CI 调度 | +| `check-docs` | 文档格式、lint 和断链检查 | 文档已变更 | +| `skills-python` | 针对 Python 支撑的 Skills 运行 Ruff + pytest | Python 技能相关变更 | +| `checks-windows` | Windows 专用的进程/路径测试，以及共享运行时导入 specifier 回归测试 | Windows 相关变更 | +| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试检查线 | macOS 相关变更 | +| `macos-swift` | macOS app 的 Swift lint、构建和测试 | macOS 相关变更 | +| `android` | 两种 flavor 的 Android 单元测试，加一次 debug APK 构建 | Android 相关变更 | +| `test-performance-agent` | 受信任活动后的每日 Codex 慢测试优化 | main CI 成功或手动调度 | -手动 CI 调度会运行与普通 CI 相同的作业图，但会强制启用每个非 Android 作用域车道：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python skills、Windows、macOS 和 Control UI i18n。独立的手动 CI 调度仅在 `include_android=true` 时运行 Android；完整发布总控流程会通过传入 `include_android=true` 启用 Android。插件预发布静态检查、仅发布使用的 `agentic-plugins` 分片、完整插件批量扫测，以及插件预发布 Docker 车道都排除在 CI 之外。Docker 预发布套件仅在 `Full Release Validation` 调度单独的 `Plugin Prerelease` workflow 且启用发布验证门禁时运行。手动运行使用唯一的并发组，因此发布候选的完整套件不会被同一 ref 上的另一次 push 或 PR 运行取消。可选的 `target_ref` 输入允许受信任的调用方使用所选调度 ref 中的 workflow 文件，针对分支、标签或完整 commit SHA 运行该作业图。 +手动 CI 调度会运行与常规 CI 相同的作业图，但会强制开启所有 +非 Android 范围的检查线：Linux Node 分片、内置插件分片、渠道 +契约、Node 22 兼容性、`check`、`check-additional`、构建 smoke、文档 +检查、Python Skills、Windows、macOS 和 Control UI i18n。独立的手动 CI +调度仅在 `include_android=true` 时运行 Android；完整发布 +总括流程会通过传递 `include_android=true` 启用 Android。插件预发布 +静态检查、仅发布的 `agentic-plugins` 分片、完整插件 +批量扫描，以及插件预发布 Docker 检查线都排除在 CI 之外。Docker +预发布套件仅在 `Full Release Validation` 调度单独的 +`Plugin Prerelease` workflow 并启用发布验证 gate 时运行。 +手动运行使用唯一的并发组，因此候选发布的完整套件不会被 +同一 ref 上的另一个推送或 PR 运行取消。可选的 `target_ref` 输入允许 +受信任调用方针对分支、标签或完整 commit SHA 运行该作业图，同时 +使用所选调度 ref 中的 workflow 文件。 ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -165,47 +271,47 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## 快速失败顺序 -作业经过排序，让低成本检查先于高成本检查失败： +作业按顺序排列，以便低成本检查先失败，再运行昂贵检查： -1. `preflight` 决定哪些车道实际存在。`docs-scope` 和 `changed-scope` 逻辑是此作业内的步骤，而不是独立作业。 -2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，无需等待更重的制品和平台矩阵作业。 -3. `build-artifacts` 与快速 Linux 车道重叠运行，因此下游消费者可以在共享构建就绪后立即开始。 -4. 更重的平台和运行时车道随后扇出：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 +1. `preflight` 决定哪些检查线实际存在。`docs-scope` 和 `changed-scope` 逻辑是该作业内部的步骤，而不是独立作业。 +2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，无需等待更重的产物和平台矩阵作业。 +3. `build-artifacts` 与快速 Linux 检查线重叠运行，因此下游消费者可以在共享构建就绪后立即开始。 +4. 更重的平台和运行时检查线随后展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 -作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 -手动调度会跳过变更作用域检测，并让预检清单表现得好像每个作用域区域都已更改。 -CI workflow 编辑会验证 Node CI 图和 workflow lint，但其本身不会强制 Windows、Android 或 macOS 原生构建；这些平台车道仍然只针对平台源代码变更启用。 -仅 CI 路由编辑、选定的低成本核心测试 fixture 编辑，以及范围很窄的插件契约辅助/测试路由编辑会使用快速的仅 Node 清单路径：preflight、security 和单个 `checks-fast-core` 任务。当变更文件仅限于该快速任务直接覆盖的路由或辅助表面时，该路径会避开构建制品、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片和额外守护矩阵。 -Windows Node 检查的作用域限定为 Windows 特定的进程/路径包装器、npm/pnpm/UI runner 辅助、包管理器配置，以及执行该车道的 CI workflow 表面；无关的源代码、插件、安装冒烟和仅测试变更会留在 Linux Node 车道上，因此不会为了普通测试分片已覆盖的覆盖范围而占用 16-vCPU Windows worker。 -单独的 `install-smoke` workflow 通过自己的 `preflight` 作业复用同一个作用域脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。Pull request 会针对 Docker/包表面、内置插件包/manifest 变更，以及 Docker 冒烟作业覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面运行快速路径。仅源代码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像、检查 CLI、运行 agents delete shared-workspace CLI 冒烟、运行容器 gateway-network e2e、验证内置插件构建参数，并在 240 秒聚合命令超时内运行有界内置插件 Docker profile，其中每个场景的 Docker run 都单独限时。完整路径为夜间定时运行、手动调度、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的 pull request 保留 QR 包安装和安装器 Docker/更新覆盖。`main` push，包括 merge commit，不会强制完整路径；当变更作用域逻辑会在 push 上请求完整覆盖时，workflow 会保留快速 Docker 冒烟，并将完整安装冒烟留给夜间或发布验证。较慢的 Bun 全局安装 image-provider 冒烟由 `run_bun_global_install_smoke` 单独 gating；它会在夜间计划任务和发布检查 workflow 中运行，手动 `install-smoke` 调度可以选择启用它，但 pull request 和 `main` push 不会运行它。QR 和安装器 Docker 测试保留各自面向安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个用于安装器/更新/插件依赖车道的裸 Node/Git runner，以及一个将同一个 tarball 安装到 `/app`、用于普通功能车道的功能性镜像。Docker 车道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，runner 只执行选中的计划。调度器通过 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每个车道选择镜像，然后使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行车道；使用 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整默认 main-pool 槽位数 10，并使用 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整对提供商敏感的 tail-pool 槽位数 10。重型车道上限默认为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，这样 npm install 和多服务车道不会过度占用 Docker，而较轻的车道仍能填满可用槽位。单个比有效上限更重的车道仍可从空池启动，然后独占运行直到释放容量。默认情况下，车道启动会错开 2 秒，以避免本地 Docker daemon create 风暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合会预检 Docker、移除过期的 OpenClaw E2E 容器、输出活动车道 Status、持久化车道耗时以便按最长优先排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 用于调度器检查。默认情况下，它会在首次失败后停止调度新的池化车道，并且每个车道都有 120 分钟的后备超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live/tail 车道使用更严格的单车道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器车道，包括仅发布车道，例如 `install-e2e`，以及拆分的内置更新车道，例如 `bundled-channel-update-acpx`，同时跳过清理冒烟，以便 agent 能够复现某个失败车道。可复用的 live/E2E workflow 会询问 `scripts/test-docker-all.mjs --plan-json` 需要哪些包、镜像类型、live 镜像、车道和凭证覆盖，然后 `scripts/docker-e2e.mjs` 会将该计划转换为 GitHub 输出和摘要。它要么通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，要么下载当前运行的包制品，要么从 `package_artifact_run_id` 下载包制品；验证 tarball 清单；当计划需要已安装包的车道时，通过 Blacksmith 的 Docker layer cache 构建并推送带有包摘要标签的裸/功能性 GHCR Docker E2E 镜像；并复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或已有的包摘要镜像，而不是重新构建。Docker 镜像拉取会以每次尝试 180 秒的有界超时重试，因此卡住的 registry/cache stream 会快速重试，而不是消耗 CI 关键路径的大部分时间。`Package Acceptance` workflow 是高级包门禁：它会从 npm、受信任的 `package_ref`、HTTPS tarball 加 SHA-256，或先前的 workflow 制品中解析候选包，然后将这个单一的 `package-under-test` 制品传入可复用 Docker E2E workflow。它将 `workflow_ref` 与 `package_ref` 分开，使当前验收逻辑能够验证较旧的受信任 commit，而无需检出旧 workflow 代码。发布检查会为目标 ref 运行自定义 Package Acceptance delta：内置渠道兼容性、离线插件 fixture，以及针对解析后 tarball 的 Telegram 包 QA。发布路径 Docker 套件会运行更小的分块作业，并使用 `OPENCLAW_SKIP_DOCKER_BUILD=1`，使每个分块只拉取自己需要的镜像类型，并通过同一个加权调度器执行多个车道（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`、`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-plugins|plugins-runtime-services|plugins-runtime-install-a|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|plugins-runtime-install-e|plugins-runtime-install-f|plugins-runtime-install-g|plugins-runtime-install-h|bundled-channels`）。当完整发布路径覆盖请求 OpenWebUI 时，OpenWebUI 会并入 `plugins-runtime-services`，并且仅在 OpenWebUI-only 调度时保留独立的 `openwebui` 分块。旧版聚合分块名称 `package-update`、`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍可用于手动重跑，但发布 workflow 使用拆分分块，这样安装器 E2E 和内置插件安装/卸载扫测不会主导关键路径。`install-e2e` 车道别名仍是两个提供商安装器车道的聚合手动重跑别名。`bundled-channels` 分块会运行拆分的 `bundled-channel-*` 和 `bundled-channel-update-*` 车道，而不是串行 all-in-one 的 `bundled-channel-deps` 车道。每个分块都会上传 `.artifacts/docker-tests/`，其中包含车道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢车道表和单车道重跑命令。workflow 的 `docker_lanes` 输入会针对准备好的镜像运行选定车道，而不是运行分块作业，这会将失败车道调试限制在一个有针对性的 Docker 作业中，并为该运行准备、下载或复用包制品；如果选定车道是 live Docker 车道，则目标作业会为该次重跑在本地构建 live-test 镜像。生成的单车道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和准备好的镜像输入，因此失败车道可以复用失败运行中的精确包和镜像。使用 `pnpm test:docker:rerun ` 从 GitHub 运行下载 Docker 制品并打印组合/单车道目标重跑命令；使用 `pnpm test:docker:timings ` 查看慢车道和阶段关键路径摘要。定时 live/E2E workflow 每天运行完整的发布路径 Docker 套件。内置更新矩阵按更新目标拆分，因此重复的 npm update 和 Doctor 修复 pass 可以与其他内置检查一起分片。 +范围逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 +手动分发会跳过变更范围检测，并让预检清单表现得像每个作用域区域都已变更。 +CI 工作流编辑会验证 Node CI 图以及工作流 lint，但它们本身不会强制触发 Windows、Android 或 macOS 原生构建；这些平台通道仍然只针对平台源代码变更。 +仅 CI 路由编辑、选定的廉价核心测试夹具编辑，以及窄范围插件契约辅助工具/测试路由编辑会使用快速的仅 Node 清单路径：预检、安全检查和单个 `checks-fast-core` 任务。当变更文件仅限于该快速任务直接覆盖的路由或辅助工具表面时，该路径会避开构建产物、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片和额外守卫矩阵。 +Windows Node 检查的作用域限定在 Windows 专用进程/路径包装器、npm/pnpm/UI 运行器辅助工具、包管理器配置，以及执行该通道的 CI 工作流表面；无关源代码、插件、安装烟测和仅测试变更会留在 Linux Node 通道上，这样它们就不会为正常测试分片已经覆盖的内容占用一个 16-vCPU Windows worker。 +单独的 `install-smoke` 工作流会通过自己的 `preflight` job 复用同一个范围脚本。它将烟测覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。拉取请求会针对 Docker/包表面、内置插件包/清单变更，以及 Docker 烟测 job 覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面运行快速路径。仅源代码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete 共享工作区 CLI 烟测，运行容器 Gateway 网关网络 e2e，验证一个内置插件构建参数，并在 240 秒聚合命令超时内运行有界的内置插件 Docker 配置文件，同时分别限制每个场景的 Docker 运行时长。完整路径会保留 QR 包安装以及安装器 Docker/更新覆盖，用于夜间计划运行、手动分发、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的拉取请求。`main` 推送（包括合并提交）不会强制运行完整路径；当变更范围逻辑会在推送时请求完整覆盖时，工作流会保留快速 Docker 烟测，并将完整安装烟测留给夜间或发布验证。较慢的 Bun 全局安装 image-provider 烟测由 `run_bun_global_install_smoke` 单独门控；它会在夜间计划和发布检查工作流中运行，手动 `install-smoke` 分发可以选择加入它，但拉取请求和 `main` 推送不会运行它。QR 和安装器 Docker 测试保留各自以安装为重点的 Dockerfile。本地 `test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个用于安装器/更新/插件依赖通道的裸 Node/Git 运行器，以及一个会将同一个 tarball 安装到 `/app`、用于正常功能通道的功能镜像。Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，运行器只执行选定的计划。调度器会通过 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每个通道选择镜像，然后使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行通道；用 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整默认值为 10 的主池槽位数，用 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整默认值为 10 的提供商敏感尾池槽位数。重型通道上限默认是 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，这样 npm install 和多服务通道不会让 Docker 过度承诺资源，而较轻通道仍会填满可用槽位。单个比有效上限更重的通道仍可从空池启动，然后独占运行直到释放容量。通道启动默认错开 2 秒，以避免本地 Docker daemon 创建风暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合会预检 Docker，移除陈旧的 OpenClaw E2E 容器，发出活跃通道状态，持久化通道耗时以进行最长优先排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 进行调度器检查。默认在第一次失败后停止调度新的池化通道，每个通道都有一个 120 分钟的回退超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live/tail 通道使用更严格的每通道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器通道，包括仅发布通道（如 `install-e2e`）以及拆分的内置更新通道（如 `bundled-channel-update-acpx`），同时跳过清理烟测，以便智能体复现某个失败通道。可复用 live/E2E 工作流会询问 `scripts/test-docker-all.mjs --plan-json` 需要哪些包、镜像类型、live 镜像、通道和凭证覆盖，然后 `scripts/docker-e2e.mjs` 会将该计划转换为 GitHub 输出和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw、下载当前运行的包产物，或从 `package_artifact_run_id` 下载包产物；验证 tarball 清单；当计划需要已安装包的通道时，通过 Blacksmith 的 Docker 层缓存构建并推送带包摘要标签的裸/功能 GHCR Docker E2E 镜像；并复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或现有包摘要镜像，而不是重新构建。Docker 镜像拉取会以每次尝试 180 秒的有界超时重试，这样卡住的 registry/cache 流会快速重试，而不是消耗大部分 CI 关键路径。`Package Acceptance` 工作流是高级包门禁：它会从 npm、可信 `package_ref`、带 SHA-256 的 HTTPS tarball，或先前工作流产物解析候选包，然后将单个 `package-under-test` 产物传给可复用 Docker E2E 工作流。它将 `workflow_ref` 与 `package_ref` 分离，因此当前验收逻辑可以在不检出旧工作流代码的情况下验证较旧的可信提交。发布检查会针对目标 ref 运行自定义 Package Acceptance 增量：内置渠道兼容性、离线插件夹具，以及针对已解析 tarball 的 Telegram 包 QA。发布路径 Docker 套件会运行较小的分块 job，并使用 `OPENCLAW_SKIP_DOCKER_BUILD=1`，这样每个分块只拉取它需要的镜像类型，并通过同一个加权调度器执行多个通道（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`，`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-plugins|plugins-runtime-services|plugins-runtime-install-a|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|plugins-runtime-install-e|plugins-runtime-install-f|plugins-runtime-install-g|plugins-runtime-install-h|bundled-channels`）。当完整 release-path 覆盖请求它时，OpenWebUI 会并入 `plugins-runtime-services`，并且只为仅 OpenWebUI 分发保留独立的 `openwebui` 分块。旧版聚合分块名称 `package-update`、`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍可用于手动重跑，但发布工作流使用拆分分块，这样安装器 E2E 和内置插件安装/卸载扫描不会主导关键路径。`install-e2e` 通道别名仍是两个提供商安装器通道的聚合手动重跑别名。`bundled-channels` 分块运行拆分的 `bundled-channel-*` 和 `bundled-channel-update-*` 通道，而不是串行的一体化 `bundled-channel-deps` 通道。每个分块都会上传 `.artifacts/docker-tests/`，其中包含通道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢通道表，以及每通道重跑命令。工作流 `docker_lanes` 输入会针对准备好的镜像运行选定通道，而不是运行分块 job，这会将失败通道调试限制在一个定向 Docker job 内，并为该次运行准备、下载或复用包产物；如果选定通道是 live Docker 通道，定向 job 会为该次重跑在本地构建 live-test 镜像。生成的每通道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和准备好的镜像输入，因此失败通道可以复用失败运行中的精确包和镜像。使用 `pnpm test:docker:rerun ` 可从 GitHub 运行下载 Docker 产物并打印组合/每通道定向重跑命令；使用 `pnpm test:docker:timings ` 可查看慢通道和阶段关键路径摘要。计划 live/E2E 工作流每天运行完整 release-path Docker 套件。内置更新矩阵按更新目标拆分，因此重复的 npm update 和 doctor 修复 pass 可以与其他内置检查一起分片。 -当前发布版 Docker 分块为 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b` 和 `bundled-channels-contracts`。聚合的 `bundled-channels` 分块仍可用于手动一次性重跑，`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 也仍作为聚合的插件/运行时别名保留，但发布工作流会使用拆分后的分块，这样渠道冒烟测试、更新目标、插件运行时检查以及内置插件安装/卸载扫描就可以并行运行。定向的 `docker_lanes` 调度也会在一次共享的包/镜像准备步骤之后，将多个选中的 lane 拆分为并行作业，并且内置渠道更新 lane 会针对临时 npm 网络故障重试一次。 +当前发布 Docker 分块是 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b` 和 `bundled-channels-contracts`。聚合 `bundled-channels` 分块仍可用于手动一次性重跑，`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍是聚合插件/运行时别名，但发布工作流使用拆分分块，这样渠道烟测、更新目标、插件运行时检查和内置插件安装/卸载扫描可以并行运行。定向 `docker_lanes` 分发也会在一个共享包/镜像准备步骤之后，将多个选定通道拆分成并行 job，并且内置渠道更新通道会对瞬时 npm 网络失败重试一次。 -本地变更 lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。该本地检查门禁对架构边界的要求比宽泛的 CI 平台范围更严格：core 生产变更会运行 core 生产和 core 测试类型检查，以及 core lint/guard；仅 core 测试的变更只运行 core 测试类型检查和 core lint；扩展生产变更会运行扩展生产和扩展测试类型检查，以及扩展 lint；仅扩展测试的变更会运行扩展测试类型检查和扩展 lint。公共插件 SDK 或插件合约变更会扩展到扩展类型检查，因为扩展依赖这些 core 合约，但 Vitest 扩展扫描属于显式测试工作。仅发布元数据的版本号变更会运行定向的版本/配置/根依赖检查。未知的 root/config 变更会故障安全地落到所有检查 lane。 -本地变更测试路由位于 `scripts/test-projects.test-support.mjs`，并且有意比 `check:changed` 更轻量：直接测试编辑会运行自身，源码编辑优先使用显式映射，然后再使用同级测试和 import graph 依赖项。共享群组房间投递配置是显式映射之一：对群组可见回复配置、源回复投递模式或消息工具系统提示词的变更，会通过 core 回复测试以及 Discord 和 Slack 投递回归测试路由，这样共享默认值变更会在第一次 PR push 之前失败。只有当变更覆盖整个 harness，以至于廉价映射集不能作为可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 +本地变更通道逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。该本地检查门禁在架构边界方面比广泛的 CI 平台范围更严格：核心生产代码变更会运行核心 prod 和核心测试类型检查，以及核心 lint/guard；仅核心测试变更只会运行核心测试类型检查以及核心 lint；插件生产代码变更会运行插件 prod 和插件测试类型检查，以及插件 lint；仅插件测试变更会运行插件测试类型检查以及插件 lint。公共插件 SDK 或插件契约变更会扩展到插件类型检查，因为插件依赖这些核心契约，但 Vitest 插件扫描是显式测试工作。仅发布元数据的版本号变更会运行定向版本/配置/根依赖检查。未知根目录/配置变更会故障安全地进入所有检查通道。 +本地变更测试路由位于 `scripts/test-projects.test-support.mjs`，并且有意比 `check:changed` 更廉价：直接测试编辑会运行自身，源代码编辑优先使用显式映射，然后是同级测试和导入图依赖项。共享群组房间投递配置是其中一个显式映射：对群组可见回复配置、源回复投递模式或消息工具系统提示词的变更，会路由到核心回复测试以及 Discord 和 Slack 投递回归，因此共享默认值变更会在第一个 PR 推送之前失败。仅当变更覆盖整个 harness、廉价映射集合不再是可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 -对于 Testbox 验证，请从仓库根目录运行，并优先为宽泛证明使用新预热的 box。在把缓慢门禁花在一个被复用、已过期或刚报告异常大同步的 box 之前，先在 box 内运行 `pnpm testbox:sanity`。当必需的根文件（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 显示至少 200 个已跟踪删除时，完整性检查会快速失败。这通常意味着远程同步状态不是 PR 的可信副本。停止该 box，并预热一个新的 box，而不是调试产品测试失败。对于有意进行大量删除的 PR，请为该完整性检查运行设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。如果本地 Blacksmith CLI 调用停留在同步阶段超过五分钟且没有同步后输出，`pnpm testbox:run` 也会终止它。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该 guard，或者为异常大的本地 diff 使用更大的毫秒值。 +对于 Testbox 验证，请从仓库根目录运行，并优先使用新预热的 box 来做广泛证明。在把慢速门禁花在一个被复用、已过期，或刚刚报告了异常大量同步内容的 box 上之前，先在 box 内运行 `pnpm testbox:sanity`。当所需的根文件（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 显示至少 200 个已跟踪文件被删除时，完整性检查会快速失败。这通常意味着远端同步状态不是 PR 的可信副本。请停止该 box 并改为预热一个新的 box，而不是调试产品测试失败。对于有意进行大量删除的 PR，请为该次完整性检查设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。如果本地 Blacksmith CLI 调用停留在同步阶段超过五分钟且没有同步后的输出，`pnpm testbox:run` 也会终止它。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该保护；对于异常大的本地 diff，也可以使用更大的毫秒值。 -手动 CI 调度会运行 `checks-node-compat-node22` 作为宽泛兼容性覆盖。Android 对独立手动 CI 需要通过 `include_android=true` 选择启用，并且对 `Full Release Validation` 始终启用。`Plugin Prerelease` 是更昂贵的产品/包覆盖，因此它是一个由 `Full Release Validation` 或显式操作员调度的独立工作流。普通 pull request、`main` push 和独立手动 CI 调度会关闭该套件。 +手动 CI 调度会运行 `checks-node-compat-node22` 作为广泛兼容性覆盖。Android 对独立手动 CI 通过 `include_android=true` 选择启用，并且在 `Full Release Validation` 中始终启用。`Plugin Prerelease` 是成本更高的产品/包覆盖，因此它是一个单独的工作流，由 `Full Release Validation` 或明确的操作员调度。普通拉取请求、`main` 推送和独立手动 CI 调度会关闭该套件。 -最慢的 Node 测试族会被拆分或均衡，使每个作业保持较小且不会过度预留 runner：渠道合约作为三个加权 shard 运行，小型 core 单元 lane 成对运行，auto-reply 作为四个均衡 worker 运行，并将 reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing shard，而智能体式 Gateway 网关/插件配置会分散到现有仅源码的智能体式 Node 作业中，而不是等待构建产物。宽泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。`Plugin Prerelease` 会在八个扩展 worker 间均衡内置插件测试；这些扩展 shard 作业每次最多运行两个插件配置组，每组使用一个 Vitest worker 和更大的 Node heap，这样 import 密集的插件批次不会创建额外 CI 作业。宽泛的智能体 lane 使用共享的 Vitest 文件并行调度器，因为它主要受 import/调度支配，而不是由单个慢测试文件主导。`runtime-config` 与 infra core-runtime shard 一起运行，避免共享 runtime shard 拖住尾部。Include-pattern shard 使用 CI shard 名称记录计时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分完整配置和过滤后的 shard。`check-additional` 将包边界编译/canary 工作放在一起，并将运行时拓扑架构与 Gateway 网关 watch 覆盖分开；边界 guard shard 会在一个作业内并发运行其小型独立 guard。Gateway 网关 watch、渠道测试和 core support-boundary shard 会在 `dist/` 和 `dist-runtime/` 已经构建完成后，在 `build-artifacts` 内并发运行，保留它们旧有的检查名称作为轻量验证作业，同时避免两个额外的 Blacksmith worker 和第二个 artifact-consumer 队列。 -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试 lane 仍会使用 SMS/通话记录 BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关 push 上重复执行 debug APK 打包作业。 -当同一 PR 或 `main` ref 上有更新 push 落地时，GitHub 可能会将已被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则将其视为 CI 噪声。聚合 shard 检查使用 `!cancelled() && always()`，因此它们仍会报告正常的 shard 失败，但不会在整个工作流已经被取代后继续排队。 -自动 CI 并发键带有版本号（`CI-v7-*`），这样 GitHub 端旧队列组里的僵尸项就无法无限期阻塞更新的 main 运行。手动全套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行的运行。 +最慢的 Node 测试家族已被拆分或平衡，让每个作业保持较小规模而不超额预留运行器：渠道契约作为三个加权分片运行，小型核心单元车道被配对，自动回复作为四个平衡 worker 运行，并将回复子树拆成 agent-runner、dispatch 和 commands/state-routing 分片，而 agentic gateway/插件配置会分散到现有的仅源码 agentic Node 作业中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。`Plugin Prerelease` 会在八个扩展 worker 之间平衡内置插件测试；这些扩展分片作业一次最多运行两个插件配置组，每组使用一个 Vitest worker 和更大的 Node 堆，这样 import 密集的插件批次就不会创建额外的 CI 作业。广泛的智能体车道使用共享的 Vitest 文件并行调度器，因为它主要受 import/调度影响，而不是由单个慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，避免共享运行时分片承担尾部耗时。包含模式分片使用 CI 分片名称记录耗时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置和过滤后的分片。`check-additional` 将包边界编译/canary 工作放在一起，并将运行时拓扑架构与 Gateway 网关 watch 覆盖分开；边界守卫分片会在一个作业内并发运行其小型独立守卫。Gateway 网关 watch、渠道测试和核心支持边界分片会在 `dist/` 和 `dist-runtime/` 已构建后于 `build-artifacts` 内并发运行，保留其旧检查名称作为轻量验证作业，同时避免两个额外的 Blacksmith worker 和第二个产物消费队列。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试车道仍会使用短信/通话记录 BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关推送中重复执行 debug APK 打包作业。 +当同一 PR 或 `main` ref 上有更新推送落地时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但在整个工作流已被取代后不会继续排队。 +自动 CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸任务无法无限期阻塞较新的 main 运行。手动全套运行使用 `CI-manual-v1-*`，并且不会取消正在进行的运行。 -## Runners +## 运行器 | 运行器 | 作业 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`，快速安全作业和聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`），快速协议/合约/内置检查，分片渠道合约检查，除 lint 外的 `check` shard，`check-additional` shard 和聚合，Node 测试聚合验证器，文档检查，Python Skills，workflow-sanity，labeler，auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵可以更早排队 | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`，较低权重的扩展 shard，`checks-fast-core`，`checks-node-compat-node22`，`check-prod-types` 和 `check-test-types` | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试 shard、内置插件测试 shard、`android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它仍然对 CPU 足够敏感，以至于 8 vCPU 带来的成本高于节省；install-smoke Docker 构建，其中 32-vCPU 排队时间带来的成本高于节省 | +| `ubuntu-24.04` | `preflight`、快速安全作业和聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速协议/契约/内置检查、分片渠道契约检查、除 lint 外的 `check` 分片、`check-additional` 分片和聚合、Node 测试聚合验证器、文档检查、Python skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵可以更早排队 | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、较低权重的扩展分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types` 和 `check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它仍然对 CPU 足够敏感，使得 8 vCPU 的成本高于节省；install-smoke Docker 构建，其中 32-vCPU 的排队时间成本高于节省 | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | | `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 回退到 `macos-latest` | | `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 回退到 `macos-latest` | -## 本地等价项 +## 本地等效命令 ```bash pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD @@ -231,7 +337,7 @@ pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-per pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json ``` -## 相关内容 +## 相关 - [安装概览](/zh-CN/install) - [发布渠道](/zh-CN/install/development-channels) diff --git a/docs/zh-CN/reference/RELEASING.md b/docs/zh-CN/reference/RELEASING.md index 7436e3d69..1f205d1cc 100644 --- a/docs/zh-CN/reference/RELEASING.md +++ b/docs/zh-CN/reference/RELEASING.md @@ -1,15 +1,15 @@ --- read_when: - 正在查找公开发布渠道定义 - - 运行发布验证或软件包验收 + - 运行发布验证或包验收 - 查找版本命名和发布节奏 summary: 发布通道、操作员检查清单、验证环境、版本命名和节奏 title: 发布策略 x-i18n: - generated_at: "2026-04-29T10:40:12Z" + generated_at: "2026-04-29T11:37:54Z" model: gpt-5.5 provider: openai - source_hash: 815c4bffe7930384584533e934996592114af510ebd775fc873086d63c74203f + source_hash: bc944cc72f61226363cd6684c1b4830c518874da21bcf8127d365772275f17f7 source_path: reference/RELEASING.md workflow: 16 --- @@ -17,7 +17,7 @@ x-i18n: OpenClaw 有三个公开发布通道： - stable：带标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest` -- beta：预发布标签，发布到 npm `beta` +- beta：发布到 npm `beta` 的预发布标签 - dev：`main` 的移动头部 ## 版本命名 @@ -30,95 +30,117 @@ OpenClaw 有三个公开发布通道： - Git 标签：`vYYYY.M.D-beta.N` - 月份或日期不要补零 - `latest` 表示当前已提升的稳定 npm 发布版本 -- `beta` 表示当前的 beta 安装目标 -- 稳定和稳定修正发布版本默认发布到 npm `beta`；发布操作者可以明确指定 `latest`，或稍后提升一个经过验证的 beta 构建 -- 每个稳定的 OpenClaw 发布版本都会同时交付 npm 包和 macOS 应用； - beta 发布通常先验证并发布 npm/包路径，mac 应用构建/签名/公证默认保留给稳定版本，除非明确请求 +- `beta` 表示当前 beta 安装目标 +- 稳定版和稳定修正发布版本默认发布到 npm `beta`；发布操作者可以明确指定 `latest`，也可以稍后提升经过验证的 beta 构建 +- 每个稳定的 OpenClaw 发布版本都会同时交付 npm 软件包和 macOS 应用； + beta 发布通常会先验证并发布 npm/软件包路径，除非明确请求， + 否则 mac 应用的构建、签名和公证保留给稳定版 ## 发布节奏 - 发布按 beta 优先推进 -- 只有在最新 beta 验证通过后才会进入稳定版本 -- 维护者通常从基于当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布版本， +- 只有最新 beta 验证通过后才会发布稳定版 +- 维护者通常会从当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布版本， 这样发布验证和修复不会阻塞 `main` 上的新开发 -- 如果 beta 标签已经推送或发布并且需要修复，维护者会切出下一个 `-beta.N` 标签，而不是删除或重新创建旧的 beta 标签 -- 详细的发布流程、审批、凭证和恢复说明仅限维护者使用 +- 如果 beta 标签已经推送或发布并且需要修复，维护者会切出下一个 + `-beta.N` 标签，而不是删除或重新创建旧 beta 标签 +- 详细发布流程、审批、凭证和恢复说明仅限维护者 ## 发布操作者清单 -此清单展示发布流程的公开形态。私有凭证、签名、公证、dist-tag 恢复和紧急回滚细节保留在仅限维护者使用的发布运行手册中。 +此清单是发布流程的公开形态。私有凭证、签名、公证、dist-tag 恢复和紧急回滚详情保留在仅限维护者的发布运行手册中。 -1. 从当前 `main` 开始：拉取最新内容，确认目标提交已推送，并确认当前 `main` CI 足够健康，可以从它创建分支。 -2. 使用 `/changelog` 根据真实提交历史重写顶部 `CHANGELOG.md` 章节，保持条目面向用户，提交它、推送它，并在创建分支前再执行一次 rebase/pull。 -3. 审查 `src/plugins/compat/registry.ts` 和 `src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。只有在升级路径仍被覆盖时才移除已过期兼容性，或记录为什么有意继续保留。 +1. 从当前 `main` 开始：拉取最新内容，确认目标提交已推送， + 并确认当前 `main` 的 CI 足够健康，可以从它创建分支。 +2. 使用 `/changelog` 根据真实提交历史重写顶部 `CHANGELOG.md` 章节， + 保持条目面向用户，提交它，推送它，并在创建分支前再 rebase/pull 一次。 +3. 审查 + `src/plugins/compat/registry.ts` 和 + `src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。仅当升级路径仍然被覆盖时才移除过期兼容性，或者记录为什么要有意保留它。 4. 从当前 `main` 创建 `release/YYYY.M.D`；不要直接在 `main` 上执行常规发布工作。 -5. 为目标标签提升每个必需位置的版本号，然后运行本地确定性预检： - `pnpm check:test-types`、`pnpm check:architecture`、`pnpm build && pnpm ui:build` 和 `pnpm release:check`。 -6. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true`。在标签存在之前，允许使用完整的 40 字符发布分支 SHA 进行仅验证预检。保存成功的 `preflight_run_id`。 -7. 使用 `Full Release Validation` 为发布分支、标签或完整提交 SHA 启动所有预发布测试。这是四个大型发布测试箱的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。 -8. 如果验证失败，在发布分支上修复，并重新运行能够证明修复的最小失败文件、通道、工作流作业、包配置、提供商或模型允许列表。只有当变更表面使先前证据失效时，才重新运行完整总控流程。 -9. 对于 beta，标记 `vYYYY.M.D-beta.N`，使用 npm dist-tag `beta` 发布，然后针对已发布的 `openclaw@YYYY.M.D-beta.N` 或 `openclaw@beta` 包运行发布后包验收。如果已推送或已发布的 beta 需要修复，切出下一个 `-beta.N`；不要删除或重写旧 beta。 -10. 对于稳定版本，只有在经过验证的 beta 或候选发布版本具备所需验证证据后才继续。稳定 npm 发布通过 `preflight_run_id` 复用成功的预检制品；稳定 macOS 发布就绪还要求打包后的 `.zip`、`.dmg`、`.dSYM.zip` 以及更新后的 `appcast.xml` 位于 `main` 上。 -11. 发布后，运行 npm 发布后验证器；在需要发布后渠道证明时，可选运行独立的已发布 npm Telegram E2E；按需执行 dist-tag 提升；根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub 发布/预发布说明；并执行发布公告步骤。 +5. 为预期标签提升每个必需位置的版本，然后运行本地确定性预检： + `pnpm check:test-types`、`pnpm check:architecture`、 + `pnpm build && pnpm ui:build` 和 `pnpm release:check`。 +6. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签存在之前， + 允许使用完整的 40 字符发布分支 SHA 进行仅验证预检。 + 保存成功的 `preflight_run_id`。 +7. 对发布分支、标签或完整提交 SHA 使用 `Full Release Validation` 启动所有预发布测试。 + 这是四个大型发布测试箱的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。 +8. 如果验证失败，在发布分支上修复，并重新运行能够证明修复的最小失败文件、通道、工作流作业、软件包配置、提供商或模型 allowlist。只有当变更表面让之前证据失效时，才重新运行完整的总控流程。 +9. 对于 beta，标记 `vYYYY.M.D-beta.N`，使用 npm dist-tag `beta` 发布， + 然后针对已发布的 `openclaw@YYYY.M.D-beta.N` + 或 `openclaw@beta` 软件包运行发布后软件包验收。如果已推送或已发布的 beta 需要修复， + 切出下一个 `-beta.N`；不要删除或重写旧 beta。 +10. 对于稳定版，只有经过验证的 beta 或候选发布版本具备所需验证证据后才能继续。稳定版 npm 发布会通过 `preflight_run_id` 复用成功的预检工件；稳定版 macOS 发布就绪还要求 `main` 上存在打包好的 `.zip`、`.dmg`、`.dSYM.zip` 和已更新的 + `appcast.xml`。 +11. 发布后，运行 npm 发布后验证器，在你需要发布后渠道证明时可选择运行独立的已发布 npm Telegram E2E，按需提升 dist-tag，根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub release/prerelease 说明，并执行发布公告步骤。 ## 发布预检 -- 在发布预检前运行 `pnpm check:test-types`，确保测试 TypeScript 在更快的本地 `pnpm check` 门禁之外也被覆盖 -- 在发布预检前运行 `pnpm check:architecture`，确保更广泛的导入循环和架构边界检查在更快的本地门禁之外也保持通过 -- 在 `pnpm release:check` 前运行 `pnpm build && pnpm ui:build`，确保预期的 `dist/*` 发布产物和 Control UI 包已存在，可供打包验证步骤使用 -- 在发布批准前运行手动 `Full Release Validation` workflow，从一个入口点启动所有预发布测试箱。它接受分支、标签或完整提交 SHA，触发手动 `CI`，并触发 `OpenClaw Release Checks`，覆盖安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 通道。仅在包已发布且发布后 Telegram E2E 也应运行时，才提供 `npm_telegram_package_spec`。当私有证据报告需要证明验证匹配已发布的 npm 包、但不强制运行 Telegram E2E 时，提供 `evidence_package_spec`。示例： +- 在发布预检前运行 `pnpm check:test-types`，确保测试 TypeScript 在更快的本地 `pnpm check` 门禁之外仍被覆盖 +- 在发布预检前运行 `pnpm check:architecture`，确保更广泛的导入循环和架构边界检查在更快的本地门禁之外保持绿色 +- 在 `pnpm release:check` 前运行 `pnpm build && pnpm ui:build`，确保打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在 +- 在发布批准前运行手动 `Full Release Validation` workflow，从一个入口启动所有预发布 test boxes。它接受分支、标签或完整 commit SHA，分发手动 `CI`，并分发 `OpenClaw Release Checks`，用于安装 smoke、package acceptance、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 线。仅在 package 已发布且也应运行发布后 Telegram E2E 时提供 `npm_telegram_package_spec`。当私有证据报告应证明验证匹配已发布的 npm package、但不强制运行 Telegram E2E 时，提供 `evidence_package_spec`。 + 示例： `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- 当你想在发布工作继续推进的同时，为包候选版本取得旁路证明时，运行手动 `Package Acceptance` workflow。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 可用当前 `workflow_ref` harness 打包可信的 `package_ref` 分支/标签/SHA；对带有必需 SHA-256 的 HTTPS tarball 使用 `source=url`；或对另一个 GitHub Actions 运行上传的 tarball 使用 `source=artifact`。该 workflow 会将候选项解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并可通过 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一 tarball 运行 Telegram QA。 +- 当你希望在发布工作继续进行时，为 package 候选项获取旁路证明，请运行手动 `Package Acceptance` workflow。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 以当前 `workflow_ref` harness 打包可信的 `package_ref` 分支/标签/SHA；对需要 SHA-256 的 HTTPS tarball 使用 `source=url`；或对另一个 GitHub Actions run 上传的 tarball 使用 `source=artifact`。该 workflow 会将候选项解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并且可以用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一个 tarball 运行 Telegram QA。 示例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai` - 常见配置： - - `smoke`：安装/渠道/智能体、Gateway 网关网络和配置热重载通道 - - `package`：artifact 原生的包/更新/插件通道，不包含 OpenWebUI 或 live ClawHub - - `product`：包配置加上 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI - - `full`：带 OpenWebUI 的 Docker 发布路径分块 + 常用 profile： + - `smoke`：安装/渠道/智能体、Gateway 网关网络和配置重载线 + - `package`：不含 OpenWebUI 或 live ClawHub 的 artifact-native package/update/plugin 线 + - `product`：package profile 外加 MCP 渠道、cron/subagent 清理、OpenAI web search 和 OpenWebUI + - `full`：带 OpenWebUI 的 Docker 发布路径分片 - `custom`：用于聚焦重跑的精确 `docker_lanes` 选择 -- 当你只需要发布候选版本的完整常规 CI 覆盖时，直接运行手动 `CI` workflow。手动 CI 触发会绕过变更范围限定，并强制运行 Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n 通道。 +- 当你只需要发布候选项的完整普通 CI 覆盖时，直接运行手动 `CI` workflow。手动 CI 分发会绕过 changed scoping，并强制运行 Linux Node 分片、内置插件分片、渠道 contract、Node 22 兼容性、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android 和 Control UI i18n 线。 示例：`gh workflow run ci.yml --ref release/YYYY.M.D` -- 验证发布遥测时运行 `pnpm qa:otel:smoke`。它会通过本地 OTLP/HTTP 接收器执行 QA-lab，并验证导出的 trace span 名称、有界属性以及内容/标识符脱敏，不需要 Opik、Langfuse 或其他外部 collector。 -- 每次打标签发布前运行 `pnpm release:check` +- 验证发布 telemetry 时运行 `pnpm qa:otel:smoke`。它通过本地 OTLP/HTTP receiver 运行 QA-lab，并验证导出的 trace span 名称、有界 attributes，以及内容/标识符脱敏；不需要 Opik、Langfuse 或其他外部 collector。 +- 每次带标签发布前运行 `pnpm release:check` - 发布检查现在在单独的手动 workflow 中运行： `OpenClaw Release Checks` -- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock parity 门禁，以及快速 live Matrix 配置和 Telegram QA 通道。live 通道使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭证租约。当你想并行运行完整 Matrix 传输、媒体和 E2EE 清单时，用 `matrix_profile=all` 和 `matrix_shards=true` 运行手动 `QA-Lab - All Lanes` workflow。 -- 跨 OS 安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用 workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- 这种拆分是有意的：让真正的 npm 发布路径保持短小、确定且聚焦产物，同时较慢的 live 检查保留在自己的通道中，避免拖慢或阻塞发布 -- 带有 secret 的发布检查应通过 `Full Release Validation` 触发，或从 `main`/release workflow ref 触发，以便 workflow 逻辑和 secret 保持受控 -- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，只要解析出的提交可从 OpenClaw 分支或发布标签到达 -- `OpenClaw NPM Release` 的仅验证预检也接受当前 workflow 分支的完整 40 字符提交 SHA，不要求已推送标签 -- 该 SHA 路径仅用于验证，不能提升为真正发布 -- 在 SHA 模式下，workflow 只会为包元数据检查合成 `v`；真正发布仍然需要真实发布标签 -- 两个 workflow 都将真正发布和提升路径保留在 GitHub 托管 runner 上，而非变更性的验证路径可以使用更大的 Blacksmith Linux runner -- 该 workflow 使用 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` 运行，并同时使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` workflow secret -- npm 发布预检不再等待单独的发布检查通道 -- 在批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（或匹配的 beta/correction 标签） -- npm 发布后，运行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或匹配的 beta/correction 版本），在新的临时前缀中验证已发布注册表安装路径 -- beta 发布后，运行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`，使用共享租约 Telegram 凭证池，针对已发布 npm 包验证已安装包的新手引导、Telegram 设置和真实 Telegram E2E。本地维护者一次性运行时可以省略 Convex 变量，并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境凭证。 -- 维护者可以通过手动 `NPM Telegram Beta E2E` workflow，从 GitHub Actions 运行相同的发布后检查。它有意仅限手动，不会在每次合并时运行。 -- 维护者发布自动化现在使用先预检后提升： - - 真正的 npm 发布必须通过一次成功的 npm `preflight_run_id` - - 真正的 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支触发 - - stable npm 发布默认使用 `beta` - - stable npm 发布可通过 workflow 输入显式指向 `latest` - - 基于 token 的 npm dist-tag 变更现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，出于安全原因，因为 `npm dist-tag add` 仍然需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布 +- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock 一致性门禁，以及快速 live Matrix profile 和 Telegram QA 线。live 线使用 `qa-live-shared` environment；Telegram 还使用 Convex CI credential leases。当你希望并行获取完整 Matrix 传输、媒体和 E2EE inventory 时，运行手动 `QA-Lab - All Lanes` workflow，并设置 `matrix_profile=all` 和 `matrix_shards=true`。 +- 跨 OS 安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用 reusable workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- 这种拆分是有意的：让真实 npm 发布路径保持简短、确定且专注于 artifact，同时让较慢的 live 检查留在自己的线中，避免它们拖慢或阻塞发布 +- 带 secret 的发布检查应通过 `Full Release Validation` 分发，或从 `main`/release workflow ref 分发，以便 workflow 逻辑和 secrets 保持受控 +- `OpenClaw Release Checks` 接受分支、标签或完整 commit SHA，只要解析出的 commit 可从 OpenClaw 分支或 release tag 到达 +- `OpenClaw NPM Release` validation-only 预检也接受当前完整 40 字符 workflow 分支 commit SHA，无需推送 tag +- 该 SHA 路径仅用于验证，不能升级为真实发布 +- 在 SHA 模式下，workflow 只为 package metadata check 合成 `v`；真实发布仍需要真实 release tag +- 两个 workflow 都将真实 publish 和 promotion 路径保留在 GitHub-hosted runners 上，而非变更性 validation 路径可以使用更大的 Blacksmith Linux runners +- 该 workflow 使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` workflow secrets 运行 + `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` +- npm 发布预检不再等待单独的发布检查线 +- 批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` + （或匹配的 beta/correction tag） +- npm publish 后，运行 + `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` + （或匹配的 beta/correction version），在全新的临时 prefix 中验证已发布 registry 安装路径 +- beta publish 后，运行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` + 以使用共享租赁 Telegram credential pool，针对已发布 npm package 验证 installed-package 新手引导、Telegram 设置和真实 Telegram E2E。本地 maintainer 一次性操作可以省略 Convex vars，并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭证。 +- Maintainers 可以通过手动 `NPM Telegram Beta E2E` workflow 从 GitHub Actions 运行相同的发布后检查。它有意仅允许手动运行，不会在每次 merge 时运行。 +- Maintainer 发布自动化现在使用 preflight-then-promote： + - 真实 npm publish 必须通过成功的 npm `preflight_run_id` + - 真实 npm publish 必须从与成功 preflight run 相同的 `main` 或 `release/YYYY.M.D` 分支分发 + - stable npm releases 默认指向 `beta` + - stable npm publish 可以通过 workflow input 明确指定 `latest` + - 基于 token 的 npm dist-tag 变更现在位于 + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + 以保障安全，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而 public repo 保持 OIDC-only publish - 公开 `macOS Release` 仅用于验证 - - 真正的私有 mac 发布必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id` - - 真正发布路径会提升已准备好的产物，而不是再次重建它们 -- 对于 `YYYY.M.D-N` 这样的 stable correction 发布，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径，确保发布修正不会静默地让旧版全局安装停留在基础 stable payload 上 -- npm 发布预检默认失败，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` payload，以避免再次发布空的浏览器仪表盘 -- 发布后验证还会检查已发布注册表安装是否在根 `dist/*` 布局下包含非空的内置插件运行时依赖。若发布缺失或包含空的内置插件依赖 payload，发布后验证器会失败，且不能提升到 `latest`。 -- `pnpm test:install:smoke` 也会对候选更新 tarball 强制执行 npm pack `unpackedSize` 预算，因此 installer e2e 会在发布路径前捕获意外的包体积膨胀 -- 如果发布工作涉及 CI 规划、插件时序清单或插件测试矩阵，请在批准前重新生成并审查 `.github/workflows/plugin-prerelease.yml` 中 planner 拥有的 `plugin-prerelease-extension-shard` 矩阵输出，确保发布说明不会描述过时的 CI 布局 -- stable macOS 发布就绪性还包括 updater 表面： - - GitHub 发布最终必须包含打包的 `.zip`、`.dmg` 和 `.dSYM.zip` - - 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip - - 打包后的 app 必须保留非 debug bundle id、非空 Sparkle feed URL，以及不低于该发布版本 canonical Sparkle 构建下限的 `CFBundleVersion` + - 真实私有 mac publish 必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id` + - 真实 publish 路径会提升已准备好的 artifacts，而不是再次 rebuild 它们 +- 对于 `YYYY.M.D-N` 这样的 stable correction releases，发布后 verifier 还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的相同 temp-prefix 升级路径，确保 release corrections 不会静默地让旧的 global installs 停留在 base stable payload 上 +- npm 发布预检会 fail closed，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` payload，以免我们再次发布空的浏览器 dashboard +- 发布后验证还会检查已发布 registry install 是否在根 `dist/*` 布局下包含非空的内置插件 runtime deps。若某个发布缺失或包含空的内置插件依赖 payload，则 postpublish verifier 会失败，且不能 promoted 到 `latest`。 +- `pnpm test:install:smoke` 还会对候选 update tarball 强制执行 npm pack `unpackedSize` 预算，因此 installer e2e 会在 release publish 路径前捕获意外的 pack bloat +- 如果发布工作触及 CI planning、extension timing manifests 或 extension test matrices，请在批准前重新生成并审查由 planner 拥有的 `plugin-prerelease-extension-shard` matrix outputs，来源为 `.github/workflows/plugin-prerelease.yml`，确保 release notes 不会描述过时的 CI 布局 +- Stable macOS 发布就绪性还包括 updater surfaces： + - GitHub release 最终必须包含打包的 `.zip`、`.dmg` 和 `.dSYM.zip` + - publish 后，`main` 上的 `appcast.xml` 必须指向新的 stable zip + - 打包后的 app 必须保留非 debug bundle id、非空 Sparkle feed URL，以及对该 release version 而言不低于 canonical Sparkle build floor 的 `CFBundleVersion` -## 发布测试箱 +## 发布 test boxes -`Full Release Validation` 是操作者从一个入口点启动所有预发布测试的方式。从可信的 `main` workflow ref 运行它，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入： +`Full Release Validation` 是 operators 从一个入口启动所有预发布测试的方式。请从可信的 `main` workflow ref 运行它，并将 release branch、tag 或完整 commit SHA 作为 `ref` 传入： ```bash gh workflow run full-release-validation.yml \ @@ -130,18 +152,19 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -该 workflow 解析目标 ref，使用 `target_ref=` 触发手动 `CI`，触发 `OpenClaw Release Checks`，并在设置 `npm_telegram_package_spec` 时可选地触发独立的发布后 Telegram E2E。随后 `OpenClaw Release Checks` 会扩展运行安装冒烟、跨 OS 发布检查、live/E2E Docker 发布路径覆盖、带 Telegram 包 QA 的 Package Acceptance、QA Lab parity、live Matrix 和 live Telegram。只有当 `Full Release Validation` 摘要显示 `normal_ci` 和 `release_checks` 成功，且任何可选的 `npm_telegram` 子项成功或有意跳过时，完整运行才可接受。最终验证器摘要包含每个子运行的最慢 job 表，因此发布经理无需下载日志即可看到当前关键路径。 -子 workflow 从运行 `Full Release Validation` 的可信 ref 触发，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签。没有单独的 Full Release Validation workflow-ref 输入；通过选择 workflow 运行 ref 来选择可信 harness。 +该 workflow 会解析目标 ref，使用 `target_ref=` 分发手动 `CI`，分发 `OpenClaw Release Checks`，并在设置 `npm_telegram_package_spec` 时可选地分发独立的发布后 Telegram E2E。`OpenClaw Release Checks` 随后会扇出安装 smoke、跨 OS 发布检查、live/E2E Docker 发布路径覆盖、带 Telegram package QA 的 Package Acceptance、QA Lab 一致性、live Matrix 和 live Telegram。仅当 `Full Release Validation` summary 显示 `normal_ci` 和 `release_checks` 成功，并且任何可选的 `npm_telegram` child 成功或有意跳过时，完整 run 才可接受。最终 verifier summary 包含每个 child run 的最慢 job 表格，因此 release manager 可以在不下载日志的情况下看到当前关键路径。 +Child workflows 从运行 `Full Release Validation` 的可信 ref 分发，通常为 `--ref main`，即使目标 `ref` 指向较旧的 release branch 或 tag。没有单独的 Full Release Validation workflow-ref input；请通过选择 workflow run ref 来选择可信 harness。 -使用 `release_profile` 选择 live/provider 覆盖范围： +使用 `release_profile` 选择 live/provider 覆盖广度： -- `minimum`：最快的发布关键 OpenAI/core live 和 Docker 路径 -- `stable`：minimum 加上用于发布批准的 stable provider/backend 覆盖 +- `minimum`：最快的 release-critical OpenAI/core live 和 Docker 路径 +- `stable`：minimum 加上用于 release approval 的 stable provider/backend 覆盖 - `full`：stable 加上广泛的 advisory provider/media 覆盖 -`OpenClaw Release Checks` 使用可信 workflow ref 将目标 ref 解析一次为 `release-package-under-test`，并在发布路径 Docker 检查和 Package Acceptance 中复用该 artifact。这会让所有面向包的测试箱使用相同字节，并避免重复构建包。 +`OpenClaw Release Checks` 使用可信 workflow ref 将目标 ref 解析一次为 `release-package-under-test`，并在 release-path Docker checks 和 Package Acceptance 中复用该 artifact。这让所有面向 package 的 boxes 使用相同字节，并避免重复 package builds。 +当 repo/org variable 已设置时，跨 OS OpenAI install smoke 使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4-mini`，因为这条线证明的是 package install、新手引导、gateway startup 和一次 live 智能体 turn，而不是对最慢默认模型进行 benchmark。更广泛的 live provider matrix 仍然是进行 model-specific 覆盖的地方。 -根据发布阶段使用这些变体： +请根据 release stage 使用这些 variants： ```bash # Validate an unpublished release candidate branch. @@ -170,22 +193,22 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -不要在聚焦修复后的第一次重跑中使用完整总流程。如果一个盒子失败，请使用失败的子工作流、作业、Docker 通道、包配置、模型提供商或 QA 通道作为下一次证明。只有当修复更改了共享发布编排，或使之前的所有盒子证据过期时，才再次运行完整总流程。总流程的最终验证器会重新检查记录的子工作流运行 ID，因此在子工作流成功重跑后，只需重跑失败的 `Verify full validation` 父作业。 +不要把完整总控工作流作为聚焦修复后的首次重跑。如果某个检查盒失败，请使用失败的子工作流、作业、Docker 通道、包配置文件、模型提供商或 QA 通道作为下一次验证。只有当修复更改了共享发布编排，或让之前的全检查盒证据变得过期时，才再次运行完整总控工作流。总控工作流的最终验证器会重新检查记录的子工作流运行 ID，因此当某个子工作流成功重跑后，只需重跑失败的 `Verify full validation` 父作业。 -对于有界恢复，请向总流程传入 `rerun_group`。`all` 是真正的发布候选运行，`ci` 只运行常规 CI 子项，`plugin-prerelease` 只运行仅发布用的插件子项，`release-checks` 运行每个发布盒子，更窄的发布组包括 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`，以及在提供独立包 Telegram 通道时的 `npm-telegram`。 +对于有边界的恢复，请将 `rerun_group` 传给总控工作流。`all` 是真正的候选发布运行，`ci` 只运行常规 CI 子工作流，`plugin-prerelease` 只运行仅发布用的插件子工作流，`release-checks` 运行所有发布检查盒，而更窄的发布分组包括 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`，以及在提供独立包 Telegram 通道时的 `npm-telegram`。 ### Vitest -Vitest 盒子是手动 `CI` 子工作流。手动 CI 会有意绕过变更范围限定，并为发布候选强制运行常规测试图：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建烟雾测试、文档检查、Python Skills、Windows、macOS、Android，以及 Control UI i18n。 +Vitest 检查盒是手动 `CI` 子工作流。手动 CI 会有意绕过变更范围限定，并为候选发布强制运行常规测试图：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n。 -使用这个盒子来回答“源代码树是否通过了完整的常规测试套件？”它不同于发布路径的产品验证。需要保留的证据： +使用此检查盒回答“源代码树是否通过了完整的常规测试套件？”它不同于发布路径的产品验证。需要保留的证据： -- 显示已派发 `CI` 运行 URL 的 `Full Release Validation` 摘要 -- 精确目标 SHA 上绿色通过的 `CI` 运行 -- 调查回归时来自 CI 作业的失败或较慢分片名称 -- 当某次运行需要性能分析时，保留 `.artifacts/vitest-shard-timings.json` 等 Vitest 计时产物 +- `Full Release Validation` 摘要，显示已调度的 `CI` 运行 URL +- `CI` 在精确目标 SHA 上通过 +- 调查回归时来自 CI 作业的失败或缓慢分片名称 +- 当运行需要性能分析时，保留 Vitest 计时产物，例如 `.artifacts/vitest-shard-timings.json` -只有当发布需要确定性的常规 CI，但不需要 Docker、QA Lab、实时、跨 OS 或包盒子时，才直接运行手动 CI： +仅当发布需要确定性的常规 CI，但不需要 Docker、QA Lab、实时、跨 OS 或包检查盒时，才直接运行手动 CI： ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -193,49 +216,49 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Docker 盒子通过 `openclaw-live-and-e2e-checks-reusable.yml` 位于 `OpenClaw Release Checks` 中，另外还包括发布模式的 `install-smoke` 工作流。它通过打包后的 Docker 环境验证发布候选，而不只是源码级测试。 +Docker 检查盒位于 `OpenClaw Release Checks` 中，通过 `openclaw-live-and-e2e-checks-reusable.yml` 运行，并包含发布模式的 `install-smoke` 工作流。它通过打包后的 Docker 环境验证候选发布，而不只是源代码级测试。 发布 Docker 覆盖范围包括： -- 启用较慢 Bun 全局安装烟雾测试的完整安装烟雾测试 +- 启用较慢 Bun 全局安装冒烟的完整安装冒烟 - 仓库 E2E 通道 - 发布路径 Docker 分块：`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b` 和 `bundled-channels-contracts` -- 请求时，`plugins-runtime-services` 分块内的 OpenWebUI 覆盖 -- 将内置渠道依赖通道拆分到 channel-smoke、update-target 和 setup/runtime 契约分块，而不是一个大型内置渠道作业 +- 按需在 `plugins-runtime-services` 分块中覆盖 OpenWebUI +- 将内置渠道依赖通道拆分到 channel-smoke、update-target 和 setup/runtime 契约分块中，而不是放在一个大型内置渠道作业里 - 拆分内置插件安装/卸载通道 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23` -- 当发布检查包含实时套件时，包含实时/E2E 提供商套件和 Docker 实时模型覆盖 +- 当发布检查包含实时套件时，覆盖 live/E2E 提供商套件和 Docker 实时模型 -重跑前先使用 Docker 产物。发布路径调度器会上传 `.artifacts/docker-tests/`，其中包含通道日志、`summary.json`、`failures.json`、阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复，请在可复用实时/E2E 工作流上使用 `docker_lanes=`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含之前的 `package_artifact_run_id` 和已准备的 Docker 镜像输入，因此失败通道可以复用同一个 tarball 和 GHCR 镜像。 +重跑前先使用 Docker 产物。发布路径调度器会上传 `.artifacts/docker-tests/`，其中包含通道日志、`summary.json`、`failures.json`、阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复，请在可复用 live/E2E 工作流上使用 `docker_lanes=`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含之前的 `package_artifact_run_id` 和已准备的 Docker 镜像输入，因此失败通道可以复用同一个 tarball 和 GHCR 镜像。 ### QA Lab -QA Lab 盒子也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布门禁，独立于 Vitest 和 Docker 包机制。 +QA Lab 检查盒也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布门禁，独立于 Vitest 和 Docker 包机制。 发布 QA Lab 覆盖范围包括： -- 使用智能体对等包，将 OpenAI 候选通道与 Opus 4.6 基线进行比较的模拟对等门禁 -- 使用 `qa-live-shared` 环境的快速实时 Matrix QA 配置 -- 使用 Convex CI 凭证租约的实时 Telegram QA 通道 -- 当发布遥测需要明确本地证明时运行 `pnpm qa:otel:smoke` +- 使用 agentic parity pack，将 OpenAI 候选通道与 Opus 4.6 基线进行比较的模拟一致性门禁 +- 使用 `qa-live-shared` 环境的快速实时 Matrix QA 配置文件 +- 使用 Convex CI 凭据租约的实时 Telegram QA 通道 +- 当发布遥测需要明确的本地证明时运行 `pnpm qa:otel:smoke` -使用这个盒子来回答“发布在 QA 场景和实时渠道流程中的行为是否正确？”批准发布时，请保留对等、Matrix 和 Telegram 通道的产物 URL。完整 Matrix 覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认的发布关键通道。 +使用此检查盒回答“发布在 QA 场景和实时渠道流程中是否行为正确？”批准发布时保留 parity、Matrix 和 Telegram 通道的产物 URL。完整 Matrix 覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认的发布关键通道。 -### 包 +### Package -包盒子是可安装产品门禁。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支撑。解析器会将候选规范化为 Docker E2E 使用的 `package-under-test` tarball，验证包清单，记录包版本和 SHA-256，并将工作流 harness ref 与包源码 ref 分开。 +Package 检查盒是可安装产品门禁。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支撑。解析器会将候选项规范化为 Docker E2E 使用的 `package-under-test` tarball，验证包清单，记录包版本和 SHA-256，并将工作流 harness ref 与包源 ref 分开。 支持的候选来源： -- `source=npm`：`openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本 -- `source=ref`：用所选 `workflow_ref` harness 打包可信的 `package_ref` 分支、标签或完整提交 SHA -- `source=url`：下载带有必需 `package_sha256` 的 HTTPS `.tgz` +- `source=npm`：`openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本 +- `source=ref`：使用选定的 `workflow_ref` harness 打包受信任的 `package_ref` 分支、标签或完整提交 SHA +- `source=url`：下载 HTTPS `.tgz`，并要求提供 `package_sha256` - `source=artifact`：复用另一个 GitHub Actions 运行上传的 `.tgz` -`OpenClaw Release Checks` 会以 `source=ref`、`package_ref=`、`suite_profile=custom`、`docker_lanes=bundled-channel-deps-compat plugins-offline` 和 `telegram_mode=mock-openai` 运行 Package Acceptance。发布路径 Docker 分块覆盖重叠的安装、更新和插件更新通道；Package Acceptance 则针对同一个已解析 tarball 保留产物原生的内置渠道兼容性、离线插件 fixture，以及 Telegram 包 QA。它是以前大多数需要 Parallels 的包/更新覆盖的 GitHub 原生替代方案。跨 OS 发布检查对 OS 特定的新手引导、安装器和平台行为仍然重要，但包/更新产品验证应优先使用 Package Acceptance。 +`OpenClaw Release Checks` 使用 `source=ref`、`package_ref=`、`suite_profile=custom`、`docker_lanes=bundled-channel-deps-compat plugins-offline` 和 `telegram_mode=mock-openai` 运行 Package Acceptance。发布路径 Docker 分块覆盖重叠的安装、更新和插件更新通道；Package Acceptance 保留面向同一已解析 tarball 的产物原生内置渠道兼容性、离线插件 fixture 和 Telegram 包 QA。它是此前大部分需要 Parallels 的包/更新覆盖的 GitHub 原生替代方案。跨 OS 发布检查对 OS 特定的新手引导、安装器和平台行为仍然重要，但包/更新产品验证应优先使用 Package Acceptance。 -旧版 package-acceptance 宽容路径被有意限定在时间范围内。到 `2026.4.25` 为止的包可以对已经发布到 npm 的元数据缺口使用兼容路径：tarball 中缺失的私有 QA 清单条目、缺失的 `gateway install --wrapper`、tarball 派生 git fixture 中缺失的补丁文件、缺失的持久化 `update.channel`、旧版插件安装记录位置、缺失的 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` 包可以对已经发布的本地构建元数据戳文件发出警告。之后的包必须满足现代包契约；这些相同缺口会导致发布验证失败。 +旧版 package-acceptance 宽松规则是有意限时的。直到 `2026.4.25` 的包，可以对已经发布到 npm 的元数据缺口使用兼容路径：tarball 中缺失私有 QA 清单条目、缺失 `gateway install --wrapper`、tarball 派生 git fixture 中缺失补丁文件、缺失持久化的 `update.channel`、旧版插件安装记录位置、缺失 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` 包可以对已发布的本地构建元数据戳文件发出警告。之后的包必须满足现代包契约；这些相同缺口会导致发布验证失败。 -当发布问题涉及实际可安装包时，使用更广泛的 Package Acceptance 配置： +当发布问题涉及实际可安装包时，请使用更宽的 Package Acceptance 配置文件： ```bash gh workflow run package-acceptance.yml \ @@ -246,58 +269,60 @@ gh workflow run package-acceptance.yml \ -f suite_profile=product ``` -常见包配置： +常见包配置文件： - `smoke`：快速包安装/渠道/智能体、Gateway 网关网络和配置重载通道 -- `package`：不带实时 ClawHub 的安装/更新/插件包契约；这是 release-check 默认值 -- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI -- `full`：带 OpenWebUI 的 Docker 发布路径分块 +- `package`：不含实时 ClawHub 的安装/更新/插件包契约；这是 release-check 默认值 +- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI web search 和 OpenWebUI +- `full`：包含 OpenWebUI 的 Docker 发布路径分块 - `custom`：用于聚焦重跑的精确 `docker_lanes` 列表 -对于包候选 Telegram 证明，请在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该工作流会将解析后的 `package-under-test` tarball 传入 Telegram 通道；独立 Telegram 工作流仍接受已发布的 npm 规格，用于发布后检查。 +对于包候选 Telegram 证明，请在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该工作流会把已解析的 `package-under-test` tarball 传入 Telegram 通道；独立 Telegram 工作流仍接受已发布的 npm spec，用于发布后检查。 ## NPM 工作流输入 `OpenClaw NPM Release` 接受这些由操作员控制的输入： -- `tag`：必需的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 `v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前完整的 40 字符工作流分支提交 SHA，用于仅验证的预检 +- `tag`：必需的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 `v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前完整 40 字符工作流分支提交 SHA，用于仅验证的预检 - `preflight_only`：`true` 表示仅验证/构建/打包，`false` 表示真实发布路径 -- `preflight_run_id`：真实发布路径上必需，因此工作流会复用成功预检运行中准备好的 tarball +- `preflight_run_id`：真实发布路径必需，以便工作流复用成功预检运行准备的 tarball - `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta` `OpenClaw Release Checks` 接受这些由操作员控制的输入： -- `ref`：要验证的分支、标签或完整提交 SHA。带密钥的检查要求解析后的提交可从 OpenClaw 分支或发布标签访问。 +- `ref`：要验证的分支、标签或完整提交 SHA。带密钥的检查要求已解析提交可从 OpenClaw 分支或发布标签访问。 规则： -- 稳定版和修正版标签可以发布到 `beta` 或 `latest` +- 稳定标签和修正标签可以发布到 `beta` 或 `latest` - Beta 预发布标签只能发布到 `beta` -- 对于 `OpenClaw NPM Release`，只有在 `preflight_only=true` 时才允许完整提交 SHA 输入 -- `OpenClaw Release Checks` 和 `Full Release Validation` 始终仅用于验证 -- 真实发布路径必须使用预检期间使用的同一个 `npm_dist_tag`；工作流会在发布继续之前验证该元数据 +- 对于 `OpenClaw NPM Release`，仅当 `preflight_only=true` 时才允许输入完整提交 SHA +- `OpenClaw Release Checks` 和 `Full Release Validation` 始终只做验证 +- 真实发布路径必须使用预检期间使用的同一个 `npm_dist_tag`；工作流会在发布继续前验证该元数据 -## 稳定版 npm 发布流程 +## 稳定 npm 发布流程 -切稳定版 npm 发布时： +切稳定 npm 发布时： 1. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release` - - 在标签存在之前，你可以使用当前完整工作流分支提交 SHA，对预检工作流进行仅验证的试运行 -2. 对于常规的先 beta 流程，选择 `npm_dist_tag=beta`；只有当你明确想要直接稳定版发布时，才选择 `latest` -3. 当你想从一个手动工作流获得常规 CI 加实时提示缓存、Docker、QA Lab、Matrix 和 Telegram 覆盖时，请在发布分支、发布标签或完整提交 SHA 上运行 `Full Release Validation` -4. 如果你明确只需要确定性的常规测试图，请改为在发布 ref 上运行手动 `CI` 工作流 + - 在标签存在之前，你可以使用当前完整工作流分支提交 SHA，对预检工作流进行仅验证的空运行 +2. 对常规 beta 优先流程选择 `npm_dist_tag=beta`，或者仅在你有意直接发布稳定版时选择 `latest` +3. 当你希望从一个手动工作流获得常规 CI 加上实时 prompt cache、Docker、QA Lab、Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整提交 SHA 上运行 `Full Release Validation` +4. 如果你有意只需要确定性的常规测试图，请改为在发布 ref 上运行手动 `CI` 工作流 5. 保存成功的 `preflight_run_id` -6. 再次运行 `OpenClaw NPM Release`，并使用 `preflight_only=false`、相同的 `tag`、相同的 `npm_dist_tag` 和保存的 `preflight_run_id` -7. 如果发布落在 `beta` 上，请使用私有 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` 工作流，将该稳定版本从 `beta` 提升到 `latest` -8. 如果发布有意直接发布到 `latest`，并且 `beta` 应立即跟随同一个稳定构建，请使用同一个私有工作流将两个 dist-tags 都指向该稳定版本，或让它的定时自愈同步稍后移动 `beta` +6. 再次运行 `OpenClaw NPM Release`，并使用 `preflight_only=false`、相同的 `tag`、相同的 `npm_dist_tag` 和已保存的 `preflight_run_id` +7. 如果发布落在 `beta`，使用私有 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` 工作流，将该稳定版本从 `beta` 提升到 `latest` +8. 如果发布有意直接发布到 `latest`，且 `beta` 应立即跟随同一个稳定构建，请使用同一个私有工作流将两个 dist-tag 都指向该稳定版本，或者让它的计划自修复同步稍后移动 `beta` -dist-tag 变更位于私有仓库中是出于安全原因，因为它仍然需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布。 +dist-tag 变更位于私有仓库中，是出于安全原因，因为它仍然需要 `NPM_TOKEN`，而公共仓库保持仅 OIDC 发布。 -这会让直接发布路径和先 beta 后提升路径都保持文档化，并对操作员可见。 +这会让直接发布路径和 beta 优先提升路径都保持已文档化，并对操作员可见。 -如果维护者必须回退到本地 npm 身份验证，请只在专用 tmux 会话内运行任何 1Password CLI（`op`）命令。不要直接从主智能体 shell 调用 `op`；把它放在 tmux 内可以让提示、警报和 OTP 处理可观察，并防止重复的主机警报。 +如果维护者必须回退到本地 npm 认证，请仅在专用 tmux 会话内运行任何 1Password +CLI (`op`) 命令。不要直接从主智能体 shell 调用 `op`；将其保持在 tmux 内可以让提示、 +警报和 OTP 处理过程可观察，并防止重复的主机警报。 -## 公开参考资料 +## 公共参考资料 - [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml) - [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml)