diff --git a/docs/zh-CN/reference/RELEASING.md b/docs/zh-CN/reference/RELEASING.md index cfcd71cdb..4cd4b40d0 100644 --- a/docs/zh-CN/reference/RELEASING.md +++ b/docs/zh-CN/reference/RELEASING.md @@ -1,24 +1,24 @@ --- read_when: - - 正在查找公共发布渠道定义 + - 正在查找公开发布渠道定义 - 运行发布验证或包验收 - 想了解版本命名和发布节奏 -summary: 发布通道、操作员检查清单、验证环境、版本命名和发布节奏 +summary: 发布通道、操作员检查清单、验证环境、版本命名和节奏 title: 发布策略 x-i18n: - generated_at: "2026-05-02T22:44:56Z" + generated_at: "2026-05-03T11:28:45Z" model: gpt-5.5 provider: openai - source_hash: ba316d1736eae8edd2fb0a71b9a3da345f8895c3b536e9a1f619718ea12fc851 + source_hash: edfd7d6a17da68c76d7196856702c59d1e3c2749907f591fe18b4f9df2eb097d source_path: reference/RELEASING.md workflow: 16 --- OpenClaw 有三个公开发布通道： -- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest` +- stable：默认发布到 npm `beta` 的标记发布，或在明确请求时发布到 npm `latest` - beta：发布到 npm `beta` 的预发布标签 -- dev：`main` 的持续移动头 +- dev：`main` 的移动头部 ## 版本命名 @@ -28,114 +28,125 @@ OpenClaw 有三个公开发布通道： - Git 标签：`vYYYY.M.D-N` - Beta 预发布版本：`YYYY.M.D-beta.N` - Git 标签：`vYYYY.M.D-beta.N` -- 月或日不要补零 -- `latest` 表示当前已提升的稳定 npm 发布版本 +- 不要给月份或日期补零 +- `latest` 表示当前已提升的稳定 npm 发布 - `beta` 表示当前 beta 安装目标 -- 稳定版和稳定修正版默认发布到 npm `beta`；发布操作员可以明确指定 `latest`，也可以稍后提升已验证的 beta 构建 -- 每个稳定 OpenClaw 发布版本都会同时交付 npm 包和 macOS 应用； - beta 发布版本通常先验证并发布 npm/包路径，mac 应用构建/签名/公证则保留给稳定版，除非明确请求 +- 稳定版和稳定修正版默认发布到 npm `beta`；发布操作员可以明确指定 `latest`，或稍后提升经过验证的 beta 构建 +- 每个稳定版 OpenClaw 发布都会同时交付 npm 包和 macOS 应用； + beta 发布通常先验证并发布 npm/包路径，除非明确请求，否则 + mac 应用构建/签名/公证会保留给稳定版 ## 发布节奏 -- 发布按 beta 优先推进 -- 只有在最新 beta 通过验证后，稳定版才会跟进 +- 发布先进入 beta +- 只有在最新 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. 检查 + 并确认当前 `main` CI 足够稳定，可以从它创建分支。 +2. 使用 `/changelog` 基于真实提交历史重写顶部 `CHANGELOG.md` 章节， + 保持条目面向用户，提交并推送，然后在创建分支前再 rebase/pull + 一次。 +3. 审查 `src/plugins/compat/registry.ts` 和 - `src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。只有在升级路径仍然被覆盖时才移除过期兼容性，或记录为什么有意继续保留。 + `src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。只有在升级路径仍然被覆盖时才移除过期兼容性，或记录为什么有意继续保留它。 4. 从当前 `main` 创建 `release/YYYY.M.D`；不要直接在 `main` 上执行常规发布工作。 5. 为预期标签更新所有必需的版本位置，运行 - `pnpm plugins:sync`，使可发布的插件包共享该发布版本和兼容性元数据，然后运行本地确定性预检： + `pnpm plugins:sync`，让可发布的插件包共享发布版本和兼容性元数据，然后运行本地确定性预检： `pnpm check:test-types`、`pnpm check:architecture`、 `pnpm build && pnpm ui:build`、`pnpm plugins:sync:check` 和 `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. 如果验证失败，在发布分支上修复，并重新运行能够证明修复的最小失败文件、通道、工作流任务、包配置文件、提供商或模型允许列表。只有当变更范围使先前证据失效时，才重新运行完整总入口。 -9. 对于 beta，标记 `vYYYY.M.D-beta.N`，然后从匹配的 `release/YYYY.M.D` 分支运行 `OpenClaw Release Publish`。它会验证 `pnpm plugins:sync:check`，先将所有可发布的插件包发布到 npm，再将同一批发布到 ClawHub，然后使用匹配的 dist-tag 提升已准备好的 OpenClaw npm 预检制品。发布后，针对已发布的 `openclaw@YYYY.M.D-beta.N` 或 `openclaw@beta` 包运行发布后包验收。如果已推送或已发布的预发布版本需要修复，切出下一个匹配的预发布编号；不要删除或重写旧预发布版本。 -10. 对于稳定版，只有在已验证的 beta 或发布候选版本具备所需验证证据后才继续。稳定版 npm 发布也通过 - `OpenClaw Release Publish`，通过 `preflight_run_id` 复用成功的预检制品；稳定版 macOS 发布就绪还需要 `main` 上存在打包后的 `.zip`、`.dmg`、`.dSYM.zip` 和更新后的 `appcast.xml`。 -11. 发布后，运行 npm 发布后验证器；在需要发布后渠道证明时，可选运行独立的已发布 npm Telegram E2E；按需执行 dist-tag 提升；根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub 发布/预发布说明；并执行发布公告步骤。 +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`，然后从匹配的 `release/YYYY.M.D` 分支运行 `OpenClaw Release Publish`。它会验证 `pnpm plugins:sync:check`，先将所有可发布的插件包发布到 npm，再将同一批插件发布到 ClawHub，然后使用匹配的 dist-tag 提升已准备好的 OpenClaw npm 预检产物。发布后，对已发布的 `openclaw@YYYY.M.D-beta.N` 或 + `openclaw@beta` 包运行发布后包验收。如果已推送或已发布的预发布版本需要修复， + 切出下一个匹配的预发布编号；不要删除或重写旧的预发布版本。 +10. 对于稳定版，只有在经过验证的 beta 或候选发布版本具备所需验证证据后才继续。 + 稳定版 npm 发布同样通过 `OpenClaw Release Publish` 进行，并通过 + `preflight_run_id` 复用成功的预检产物；稳定版 macOS 发布就绪还要求 + `main` 上存在打包后的 `.zip`、`.dmg`、`.dSYM.zip` 和已更新的 `appcast.xml`。 +11. 发布后，运行 npm 发布后验证器，在需要发布后渠道证明时运行可选的独立 + 已发布 npm Telegram E2E，按需执行 dist-tag 提升，根据完整匹配的 + `CHANGELOG.md` 章节创建 GitHub release/prerelease notes，并完成发布公告步骤。 ## 发布预检 -- 在发布预检前运行 `pnpm check:test-types`，以便测试 TypeScript 仍在更快的本地 `pnpm check` gate 之外得到覆盖 -- 在发布预检前运行 `pnpm check:architecture`，以便更广泛的导入循环和架构边界检查在更快的本地 gate 之外保持通过 -- 在 `pnpm release:check` 前运行 `pnpm build && pnpm ui:build`，以便预期的 `dist/*` 发布构件和 Control UI bundle 存在，可供打包验证步骤使用 -- 在根版本号提升后、打标签前运行 `pnpm plugins:sync`。它会更新可发布插件包版本、OpenClaw peer/API 兼容性元数据、构建元数据和插件 changelog 存根，使其匹配核心发布版本。`pnpm plugins:sync:check` 是非变更型发布保护；如果忘记这一步，发布工作流会在任何 registry 变更前失败。 -- 在发布批准前运行手动 `Full Release Validation` 工作流，以便从一个入口点启动所有发布前测试盒。它接受分支、标签或完整提交 SHA，调度手动 `CI`，并为安装 smoke、package acceptance、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram lanes 调度 `OpenClaw Release Checks`。使用 `release_profile=full` 和 `rerun_group=all` 时，它还会针对 release checks 的 `release-package-under-test` 构件运行 package Telegram E2E。发布后，如果同一个 Telegram E2E 也应证明已发布的 npm 包，请提供 `npm_telegram_package_spec`。发布后，如果 Package Acceptance 应针对已发布的 npm 包而不是 SHA 构建构件运行其 package/update matrix，请提供 `package_acceptance_package_spec`。如果私有证据报告应证明验证匹配已发布的 npm 包而不强制运行 Telegram E2E，请提供 `evidence_package_spec`。示例： - `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- 当你希望在发布工作继续进行时，为包候选提供旁路证明，请运行手动 `Package Acceptance` 工作流。对 `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`。该工作流会将候选解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并可使用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一个 tarball 运行 Telegram QA。当所选 Docker lanes 包含 `published-upgrade-survivor` 时，包构件就是候选，`published_upgrade_survivor_baseline` 选择已发布的基线。 +- 在发布预检前运行 `pnpm check:test-types`，这样测试 TypeScript 仍会在更快的本地 `pnpm check` 门禁之外得到覆盖 +- 在发布预检前运行 `pnpm check:architecture`，这样更广泛的导入循环和架构边界检查会在更快的本地门禁之外保持绿色 +- 在 `pnpm release:check` 前运行 `pnpm build && pnpm ui:build`，这样用于打包验证步骤的预期 `dist/*` 发布产物和 Control UI 包会存在 +- 在根版本号提升之后、打标签之前运行 `pnpm plugins:sync`。它会更新可发布插件包版本、OpenClaw 对等/API 兼容性元数据、构建元数据和插件变更日志存根，使其匹配核心发布版本。`pnpm plugins:sync:check` 是非变更式发布防护；如果忘记这一步，发布工作流会在任何注册表变更前失败。 +- 在发布审批前运行手动 `Full Release Validation` 工作流，从一个入口点启动所有预发布测试盒。它接受分支、标签或完整提交 SHA，分派手动 `CI`，并分派 `OpenClaw Release Checks`，覆盖安装冒烟、包验收、Docker 发布路径套件、实时/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 车道。使用 `release_profile=full` 和 `rerun_group=all` 时，它还会针对发布检查中的 `release-package-under-test` 产物运行包 Telegram E2E。发布后，如果同一个 Telegram E2E 也应证明已发布的 npm 包，请提供 `npm_telegram_package_spec`。发布后，如果 Package Acceptance 应针对已交付的 npm 包而不是 SHA 构建产物运行其包/更新矩阵，请提供 `package_acceptance_package_spec`。如果私有证据报告应证明验证匹配已发布的 npm 包但不强制运行 Telegram E2E，请提供 `evidence_package_spec`。示例：`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` +- 当你想在发布工作继续进行时为包候选版本提供旁路证明，请运行手动 `Package Acceptance` 工作流。对于 `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`。该工作流会将候选版本解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并可使用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一个 tarball 运行 Telegram QA。当选定的 Docker 车道包含 `published-upgrade-survivor` 时，包产物就是候选版本，`published_upgrade_survivor_baseline` 选择已发布基线。 示例：`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 published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` - 常见 profiles： - - `smoke`：install/channel/agent、Gateway 网关网络和配置重载 lanes - - `package`：构件原生的 package/update/plugin lanes，不包含 OpenWebUI 或 live ClawHub - - `product`：package profile 加上 MCP 渠道、cron/subagent 清理、OpenAI web search 和 OpenWebUI + 常用配置： + - `smoke`：安装/渠道/智能体、Gateway 网关网络和配置重载车道 + - `package`：产物原生的包/更新/插件车道，不包含 OpenWebUI 或实时 ClawHub + - `product`：包配置加上 MCP 渠道、cron/子智能体清理、OpenAI web 搜索和 OpenWebUI - `full`：带 OpenWebUI 的 Docker 发布路径分块 - `custom`：用于聚焦重跑的精确 `docker_lanes` 选择 -- 当你只需要发布候选的完整常规 CI 覆盖时，直接运行手动 `CI` 工作流。手动 CI 调度会绕过变更范围限定，并强制运行 Linux Node shards、内置插件 shards、渠道 contracts、Node 22 兼容性、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android 和 Control UI i18n lanes。 +- 当你只需要为发布候选版本获得完整常规 CI 覆盖时，直接运行手动 `CI` 工作流。手动 CI 分派会绕过变更范围限定，并强制运行 Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、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 名称、有界 attributes 以及 content/identifier 脱敏，而不需要 Opik、Langfuse 或其他外部 collector。 -- 每个打标签发布前运行 `pnpm release:check` -- 标签存在后，为会产生变更的发布序列运行 `OpenClaw Release Publish`。从 `release/YYYY.M.D` 调度它（或在发布 main 可达标签时从 `main` 调度），传入发布标签和成功的 OpenClaw npm `preflight_run_id`，并保持默认插件发布范围 `all-publishable`，除非你有意运行聚焦修复。该工作流会串行化插件 npm 发布、插件 ClawHub 发布和 OpenClaw npm 发布，确保核心包不会早于其外置插件发布。 +- 验证发布遥测时运行 `pnpm qa:otel:smoke`。它通过本地 OTLP/HTTP 接收器执行 QA-lab，并验证导出的追踪 span 名称、有界属性以及内容/标识符脱敏，不需要 Opik、Langfuse 或其他外部收集器。 +- 每次带标签发布前运行 `pnpm release:check` +- 标签存在后，为变更式发布序列运行 `OpenClaw Release Publish`。从 `release/YYYY.M.D` 分派它（或在发布 main 可达标签时从 `main` 分派），传入发布标签和成功的 OpenClaw npm `preflight_run_id`，并保持默认插件发布范围 `all-publishable`，除非你有意运行聚焦修复。该工作流会串行化插件 npm 发布、插件 ClawHub 发布和 OpenClaw npm 发布，确保核心包不会在其外置插件之前发布。 - 发布检查现在在单独的手动工作流中运行： `OpenClaw Release Checks` -- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock parity lane、快速 live Matrix profile 和 Telegram QA lane。live lanes 使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭据租约。当你希望并行获得完整 Matrix transport、media 和 E2EE inventory 时，请使用 `matrix_profile=all` 和 `matrix_shards=true` 运行手动 `QA-Lab - All Lanes` 工作流。 -- 跨 OS 安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用工作流 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- 这种拆分是有意设计的：保持真实 npm 发布路径短小、确定且聚焦构件，同时让较慢的 live checks 留在自己的 lane 中，避免卡住或阻塞发布 -- 带 secret 的发布检查应通过 `Full Release Validation` 调度，或从 `main`/release workflow ref 调度，以便工作流逻辑和 secrets 保持受控 -- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，只要解析后的提交可从 OpenClaw 分支或发布标签到达 -- `OpenClaw NPM Release` 仅验证预检也接受当前完整 40 字符 workflow-branch 提交 SHA，而不要求已推送标签 +- `OpenClaw Release Checks` 也会在发布审批前运行 QA Lab 模拟 parity 车道以及快速实时 Matrix 配置和 Telegram QA 车道。实时车道使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭证租约。当你想并行获得完整 Matrix 传输、媒体和 E2EE 清单时，请使用 `matrix_profile=all` 和 `matrix_shards=true` 运行手动 `QA-Lab - All Lanes` 工作流。 +- 跨 OS 安装和升级运行时验证属于公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用工作流 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- 这种拆分是有意的：保持真实 npm 发布路径短小、确定且聚焦产物，同时较慢的实时检查保留在自己的车道中，避免拖慢或阻塞发布 +- 携带密钥的发布检查应通过 `Full Release +Validation` 分派，或从 `main`/release 工作流 ref 分派，以便工作流逻辑和密钥保持受控 +- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，只要解析出的提交可从 OpenClaw 分支或发布标签到达 +- `OpenClaw NPM Release` 仅验证预检也接受当前完整 40 字符工作流分支提交 SHA，不要求已推送标签 - 该 SHA 路径仅用于验证，不能提升为真实发布 - 在 SHA 模式下，工作流只为包元数据检查合成 `v`；真实发布仍需要真实发布标签 -- 两个工作流都将真实发布和提升路径保留在 GitHub-hosted runners 上，而非变更型验证路径可以使用更大的 Blacksmith Linux runners -- 该工作流会使用 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`，并同时使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 工作流 secrets -- npm 发布预检不再等待单独的 release checks lane -- 批准前运行 `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 版本），在新的临时前缀中验证已发布 registry 安装路径 -- 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 vars，并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭据。 -- 维护者也可以通过手动 `NPM Telegram Beta E2E` 工作流，从 GitHub Actions 运行同一个发布后检查。它有意仅支持手动运行，不会在每次 merge 时运行。 -- 维护者发布自动化现在使用 preflight-then-promote： - - 真实 npm 发布必须通过成功的 npm `preflight_run_id` - - 真实 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支调度 - - stable npm 发布默认使用 `beta` - - stable npm 发布可以通过工作流输入显式目标为 `latest` - - 基于 token 的 npm dist-tag 变更现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，这是出于安全考虑，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布 - - 公开 `macOS Release` 仅用于验证；当标签只存在于发布分支上但工作流从 `main` 调度时，设置 `public_release_branch=release/YYYY.M.D` - - 真实私有 mac 发布必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id` - - 真实发布路径会提升已准备好的构件，而不是再次重建它们 -- 对于像 `YYYY.M.D-N` 这样的 stable correction releases，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一个临时前缀升级路径，确保发布修正不会静默地让较旧的全局安装停留在基础 stable payload 上 -- npm 发布预检会默认失败，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空 `dist/control-ui/assets/` payload，这样我们就不会再次发布空的浏览器 dashboard -- 发布后验证还会检查已发布插件入口点和包元数据是否存在于已安装 registry 布局中。缺少插件运行时 payload 的发布会使 postpublish 验证器失败，并且不能提升到 `latest`。 -- `pnpm test:install:smoke` 还会对候选更新 tarball 强制执行 npm pack `unpackedSize` 预算，因此 installer e2e 会在发布发布路径前捕获意外的 pack 膨胀 -- 如果发布工作触及 CI planning、插件 timing manifests 或插件 test matrices，请在批准前重新生成并审查由 planner 拥有的 `.github/workflows/plugin-prerelease.yml` 的 `plugin-prerelease-extension-shard` matrix 输出，确保 release notes 不会描述过时的 CI 布局 -- stable macOS 发布就绪性还包括 updater surfaces： - - GitHub release 最终必须包含已打包的 `.zip`、`.dmg` 和 `.dSYM.zip` - - 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip - - 打包后的 app 必须保留非 debug bundle id、非空 Sparkle feed URL，以及达到或高于该发布版本规范 Sparkle build floor 的 `CFBundleVersion` +- 两个工作流都将真实发布和提升路径保留在 GitHub 托管运行器上，而非变更式验证路径可以使用更大的 Blacksmith Linux 运行器 +- 该工作流会使用 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` 运行，并使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 两个工作流密钥 +- npm 发布预检不再等待单独的发布检查车道 +- 审批前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（或匹配的 beta/修正标签） +- npm 发布后，运行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或匹配的 beta/修正版本），在全新的临时前缀中验证已发布注册表安装路径 +- 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` 工作流从 GitHub Actions 运行同一个发布后检查。它有意仅支持手动运行，不会在每次合并时运行。 +- 维护者发布自动化现在使用先预检再提升： + - 真实 npm 发布必须传入成功的 npm `preflight_run_id` + - 真实 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支分派 + - 稳定版 npm 发布默认使用 `beta` + - 稳定版 npm 发布可以通过工作流输入显式目标为 `latest` + - 基于令牌的 npm dist-tag 变更现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` 中以保障安全，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布 + - 公开 `macOS Release` 仅用于验证；当标签只存在于发布分支但工作流从 `main` 分派时，设置 `public_release_branch=release/YYYY.M.D` + - 真实私有 mac 发布必须传入成功的私有 mac `preflight_run_id` 和 `validate_run_id` + - 真实发布路径会提升已准备好的产物，而不是再次重新构建它们 +- 对于 `YYYY.M.D-N` 这样的稳定版修正发布，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径，确保发布修正不会静默地让较旧的全局安装停留在基础稳定版载荷上 +- npm 发布预检会默认失败，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 载荷，这样我们就不会再次发布空的浏览器仪表盘 +- 发布后验证还会检查已发布插件入口点和包元数据是否存在于已安装的注册表布局中。发布版本如果缺少插件运行时载荷，发布后验证器会失败，并且不能提升到 `latest`。 +- `pnpm test:install:smoke` 也会在候选更新 tarball 上强制执行 npm 包 `unpackedSize` 预算，这样安装器 e2e 会在发布路径之前捕获意外的包体积膨胀 +- 如果发布工作触及 CI 规划、插件时序清单或插件测试矩阵，请在审批前重新生成并审查由规划器拥有的 `.github/workflows/plugin-prerelease.yml` 中的 `plugin-prerelease-extension-shard` 矩阵输出，确保发布说明不会描述过期的 CI 布局 +- 稳定版 macOS 发布就绪还包括更新器表面： + - GitHub release 最终必须包含打包的 `.zip`、`.dmg` 和 `.dSYM.zip` + - 发布后，`main` 上的 `appcast.xml` 必须指向新的稳定版 zip + - 打包应用必须保持非调试 bundle id、非空 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion` ## 发布测试盒 -`Full Release Validation` 是操作者从一个入口点启动所有发布前测试的方式。要在快速变化分支上获得固定提交证明，请使用 helper，让每个子工作流都从固定到目标 SHA 的临时分支运行： +`Full Release Validation` 是操作员从一个入口点启动所有预发布测试的方式。对于快速移动分支上的固定提交证明，使用辅助工具，确保每个子工作流都从固定到目标 SHA 的临时分支运行： ```bash pnpm ci:full-release --sha ``` -该 helper 会推送 `release-ci/-...`，从该分支调度 `Full Release Validation` 并传入 `ref=`，验证每个子工作流 `headSha` 都匹配目标，然后删除临时分支。这避免了意外证明更新的 `main` 子运行。 +该辅助工具会推送 `release-ci/-...`，从该分支以 `ref=` 分派 `Full Release Validation`，验证每个子工作流的 `headSha` 都匹配目标，然后删除临时分支。这样可以避免意外证明更新的 `main` 子运行。 -对于发布分支或标签验证，请从可信的 `main` workflow ref 运行，并将发布分支或标签作为 `ref` 传入： +对于发布分支或标签验证，请从受信任的 `main` 工作流 ref 运行，并将发布分支或标签作为 `ref` 传入： ```bash gh workflow run full-release-validation.yml \ @@ -147,18 +158,25 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -该工作流会解析目标 ref，使用 `target_ref=` 触发手动 `CI`，触发 `OpenClaw Release Checks`，并在 `release_profile=full` 且 `rerun_group=all` 时，或在设置了 `npm_telegram_package_spec` 时，触发独立的 package Telegram E2E。随后，`OpenClaw Release Checks` 会展开安装冒烟测试、跨操作系统发布检查、live/E2E Docker 发布路径覆盖、包含 Telegram package QA 的 Package Acceptance、QA Lab 对等性、live Matrix，以及 live Telegram。只有当 `Full Release Validation` 摘要显示 `normal_ci` 和 `release_checks` 成功时，完整运行才可接受。在 full/all 模式下，`npm_telegram` 子项也必须成功；在 full/all 之外，它会被跳过，除非提供了已发布的 `npm_telegram_package_spec`。最终验证器摘要会包含每个子运行的最慢作业表，因此发布经理无需下载日志即可看到当前关键路径。 -请参阅[完整发布验证](/zh-CN/reference/full-release-validation)，了解完整阶段矩阵、确切的工作流作业名称、stable 与 full 配置差异、构件，以及聚焦重跑句柄。 -子工作流会从运行 `Full Release Validation` 的可信 ref 触发，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签也是如此。没有单独的 Full Release Validation workflow-ref 输入；通过选择工作流运行 ref 来选择可信 harness。不要在移动的 `main` 上使用 `--ref main -f ref=` 做精确提交证明；原始提交 SHA 不能作为工作流触发 ref，因此请使用 `pnpm ci:full-release --sha ` 创建固定的临时分支。 +工作流会解析目标 ref，使用 +`target_ref=` 调度手动 `CI`，调度 `OpenClaw Release Checks`，为面向软件包的检查准备父级 `release-package-under-test` 构件，并在 `release_profile=full` 且 `rerun_group=all`，或设置了 `npm_telegram_package_spec` 时，调度独立的软件包 Telegram E2E。随后，`OpenClaw Release +Checks` 会展开安装冒烟、跨 OS 发布检查、实时/E2E Docker 发布路径覆盖、带 Telegram 软件包 QA 的 Package Acceptance、QA Lab 对等性、实时 Matrix 和实时 Telegram。只有当 +`Full Release Validation` +摘要显示 `normal_ci` 和 `release_checks` 成功时，一次完整运行才可接受。在 full/all 模式下，`npm_telegram` 子项也必须成功；在 full/all 之外，除非提供了已发布的 `npm_telegram_package_spec`，否则会跳过它。最终验证器摘要包含每个子运行的最慢作业表，因此发布经理无需下载日志即可看到当前关键路径。 +参见 [完整发布验证](/zh-CN/reference/full-release-validation)，了解完整阶段矩阵、精确的工作流作业名称、stable 与 full 配置的差异、构件以及聚焦重跑句柄。 +子工作流从运行 `Full Release +Validation` 的可信 ref 调度，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签也是如此。没有单独的 Full Release Validation workflow-ref 输入；通过选择工作流运行 ref 来选择可信 harness。 +不要使用 `--ref main -f ref=` 在移动的 `main` 上证明精确提交；原始提交 SHA 不能作为工作流调度 ref，因此请使用 +`pnpm ci:full-release --sha ` 创建固定的临时分支。 -使用 `release_profile` 选择 live/provider 覆盖宽度： +使用 `release_profile` 选择实时/提供商覆盖范围： -- `minimum`：最快的发布关键 OpenAI/core live 与 Docker 路径 +- `minimum`：最快的发布关键 OpenAI/core 实时与 Docker 路径 - `stable`：minimum 加上用于发布批准的稳定提供商/后端覆盖 -- `full`：stable 加上广泛的 advisory 提供商/媒体覆盖 +- `full`：stable 加上广泛的咨询提供商/媒体覆盖 -`OpenClaw Release Checks` 使用可信工作流 ref 将目标 ref 解析一次为 `release-package-under-test`，并在发布路径 Docker 检查和 Package Acceptance 中复用该构件。这会让所有面向 package 的 box 使用相同字节，并避免重复 package 构建。 -跨操作系统 OpenAI 安装冒烟测试会在设置了 repo/org 变量时使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4`，因为这个 lane 证明的是 package 安装、新手引导、Gateway 网关启动和一次 live 智能体 turn，而不是对最慢默认模型进行基准测试。更广泛的 live 提供商矩阵仍然是模型特定覆盖的位置。 +`OpenClaw Release Checks` 使用可信工作流 ref 将目标 ref 解析一次为 `release-package-under-test`，并在发布路径 Docker 检查和 Package Acceptance 中复用该构件。这会让所有面向软件包的盒子使用相同字节，并避免重复构建软件包。 +当设置了 repo/org 变量时，跨 OS OpenAI 安装冒烟使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4`，因为该 lane 证明的是软件包安装、新手引导、Gateway 网关启动和一次实时智能体回合，而不是对最慢的默认模型做基准测试。更广泛的实时提供商矩阵仍然是进行模型特定覆盖的地方。 根据发布阶段使用这些变体： @@ -190,23 +208,24 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -不要把完整 umbrella 作为聚焦修复后的第一次重跑。如果某个 box 失败，请使用失败的子工作流、作业、Docker lane、package profile、模型提供商或 QA lane 做下一次证明。只有当修复更改了共享发布编排，或使先前的 all-box 证据失效时，才再次运行完整 umbrella。umbrella 的最终验证器会重新检查记录的子工作流运行 ID，因此在子工作流成功重跑后，只需重跑失败的 `Verify full validation` 父作业。 +不要把完整 umbrella 作为聚焦修复后的第一次重跑。如果一个盒子失败，请使用失败的子工作流、作业、Docker lane、软件包配置、模型提供商或 QA lane 作为下一次证明。只有当修复更改了共享发布编排，或使之前的全盒子证据过期时，才再次运行完整 umbrella。umbrella 的最终验证器会重新检查记录的子工作流运行 ID，因此在某个子工作流成功重跑后，只需重跑失败的 `Verify full validation` 父作业。 -对于有界恢复，请向 umbrella 传递 `rerun_group`。`all` 是真正的候选发布运行，`ci` 仅运行普通 CI 子项，`plugin-prerelease` 仅运行仅发布插件子项，`release-checks` 运行每个发布 box，而更窄的发布组是 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 和 `npm-telegram`。 -聚焦的 `npm-telegram` 重跑需要 `npm_telegram_package_spec`；带有 `release_profile=full` 的 full/all 运行会使用 release-checks package 构件。 +对于有界恢复，将 `rerun_group` 传给 umbrella。`all` 是真正的发布候选运行，`ci` 仅运行普通 CI 子项，`plugin-prerelease` 仅运行发布专用插件子项，`release-checks` 运行每个发布盒子，更窄的发布组是 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 和 `npm-telegram`。 +聚焦的 `npm-telegram` 重跑需要 `npm_telegram_package_spec`；带有 `release_profile=full` 的 full/all 运行会使用 release-checks 软件包构件。 ### Vitest -Vitest box 是手动 `CI` 子工作流。手动 CI 会有意绕过 changed 作用域，并强制候选发布的普通测试图：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。 -使用此 box 回答“源代码树是否通过了完整普通测试套件？”它不同于发布路径产品验证。需要保留的证据： +用这个盒子回答“源代码树是否通过了完整的普通测试套件？” +它不同于发布路径产品验证。需要保留的证据： -- `Full Release Validation` 摘要，显示已触发的 `CI` 运行 URL -- `CI` 在确切目标 SHA 上为绿色 -- 调查回归时来自 CI 作业的失败或较慢分片名称 +- 显示已调度 `CI` 运行 URL 的 `Full Release Validation` 摘要 +- 精确目标 SHA 上绿色的 `CI` 运行 +- 调查回归时来自 CI 作业的失败或缓慢分片名称 - 当一次运行需要性能分析时，保留 Vitest 计时构件，例如 `.artifacts/vitest-shard-timings.json` -仅在发布需要确定性的普通 CI，但不需要 Docker、QA Lab、live、跨操作系统或 package box 时，才直接运行手动 CI： +仅当发布需要确定性的普通 CI，但不需要 Docker、QA Lab、实时、跨 OS 或软件包盒子时，才直接运行手动 CI： ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -214,52 +233,70 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Docker box 位于 `OpenClaw Release Checks` 中，通过 `openclaw-live-and-e2e-checks-reusable.yml` 以及发布模式 `install-smoke` 工作流提供。它通过打包的 Docker 环境验证候选发布，而不是仅使用源代码级测试。 +Docker 盒子位于 `OpenClaw Release Checks` 中，通过 +`openclaw-live-and-e2e-checks-reusable.yml` 以及 release-mode +`install-smoke` 工作流实现。它通过打包后的 Docker 环境验证发布候选，而不只是源代码级测试。 发布 Docker 覆盖包括： -- 启用较慢 Bun 全局安装冒烟测试的完整安装冒烟测试 -- 按目标 SHA 准备/复用根 Dockerfile 冒烟镜像，并将 QR、root/gateway 和 installer/Bun 冒烟作业作为单独的 install-smoke 分片运行 +- 启用慢速 Bun 全局安装冒烟的完整安装冒烟 +- 按目标 SHA 准备/复用根 Dockerfile 冒烟镜像，其中 QR、root/gateway 和 installer/Bun 冒烟作业作为独立 install-smoke 分片运行 - 仓库 E2E lane -- 发布路径 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` -- 请求时在 `plugins-runtime-services` 分块内提供 OpenWebUI 覆盖 -- 拆分的内置插件安装/卸载 lane，从 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23` -- 当发布检查包含 live 套件时，包含 live/E2E 提供商套件和 Docker live 模型覆盖 +- 发布路径 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` +- 按请求在 `plugins-runtime-services` 分块内包含 OpenWebUI 覆盖 +- 拆分的内置插件安装/卸载 lane + `bundled-plugin-install-uninstall-0` 到 + `bundled-plugin-install-uninstall-23` +- 当发布检查包含实时套件时，包含实时/E2E 提供商套件和 Docker 实时模型覆盖 -重跑前先使用 Docker 构件。发布路径调度器会上传 `.artifacts/docker-tests/`，其中包含 lane 日志、`summary.json`、`failures.json`、阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复，请在可复用 live/E2E 工作流上使用 `docker_lanes=`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含先前的 `package_artifact_run_id` 和已准备的 Docker 镜像输入，因此失败 lane 可以复用相同 tarball 和 GHCR 镜像。 +重跑前先使用 Docker 构件。发布路径调度器会上传 +`.artifacts/docker-tests/`，其中包含 lane 日志、`summary.json`、`failures.json`、阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复，请在可复用实时/E2E 工作流上使用 `docker_lanes=`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含之前的 +`package_artifact_run_id` 和已准备的 Docker 镜像输入，因此失败的 lane 可以复用相同 tarball 和 GHCR 镜像。 ### QA Lab -QA Lab box 也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布门禁，独立于 Vitest 和 Docker package 机制。 +QA Lab 盒子也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布门禁，独立于 Vitest 和 Docker 软件包机制。 发布 QA Lab 覆盖包括： -- mock 对等性 lane，使用 agentic parity pack 将 OpenAI 候选 lane 与 Opus 4.6 基线进行比较 -- 使用 `qa-live-shared` 环境的快速 live Matrix QA profile -- 使用 Convex CI 凭证租约的 live Telegram QA lane -- 当发布遥测需要明确本地证明时运行 `pnpm qa:otel:smoke` +- 使用 agentic parity pack 将 OpenAI 候选 lane 与 Opus 4.6 基线比较的 mock 对等性 lane +- 使用 `qa-live-shared` 环境的快速实时 Matrix QA 配置 +- 使用 Convex CI 凭据租约的实时 Telegram QA lane +- 当发布遥测需要明确本地证明时，运行 `pnpm qa:otel:smoke` -使用此 box 回答“该发布在 QA 场景和 live 渠道流中行为是否正确？”批准发布时，请保留 parity、Matrix 和 Telegram lane 的构件 URL。完整 Matrix 覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认发布关键 lane。 +用这个盒子回答“发布在 QA 场景和实时渠道流中是否行为正确？”批准发布时，保留对等性、Matrix 和 Telegram lane 的构件 URL。完整 Matrix 覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认发布关键 lane。 -### Package +### 软件包 -Package box 是可安装产品门禁。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支持。解析器会将候选项规范化为 Docker E2E 消费的 `package-under-test` tarball，验证 package 清单，记录 package 版本和 SHA-256，并将工作流 harness ref 与 package 源 ref 分离。 +软件包盒子是可安装产品门禁。它由 +`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=npm`：`openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本 +- `source=ref`：使用所选 `workflow_ref` harness 打包可信 `package_ref` 分支、标签或完整提交 SHA - `source=url`：下载需要 `package_sha256` 的 HTTPS `.tgz` - `source=artifact`：复用另一个 GitHub Actions 运行上传的 `.tgz` -`OpenClaw Release Checks` 使用 `source=artifact`、已准备的发布 package 构件、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai` 运行 Package Acceptance。Package Acceptance 会针对相同解析后的 tarball 保持迁移、更新、陈旧插件依赖清理、离线插件夹具、插件更新，以及 Telegram package QA。升级矩阵覆盖从 `2026.4.23` 到 `latest` 的每个稳定 npm 已发布基线；对于已经发布的候选项，请使用带 `source=npm` 的 Package Acceptance；对于发布前基于 SHA 的本地 npm tarball，请使用 `source=ref`/`source=artifact`。它是 GitHub 原生替代方案，可替代以前大部分需要 Parallels 的 package/update 覆盖。跨操作系统发布检查对于操作系统特定的新手引导、安装器和平台行为仍然重要，但 package/update 产品验证应优先使用 Package Acceptance。 +`OpenClaw Release Checks` 使用 `source=artifact`、准备好的发布软件包构件、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues` 和 +`telegram_mode=mock-openai` 运行 Package Acceptance。Package Acceptance 会针对同一个已解析 tarball 保持迁移、更新、陈旧插件依赖清理、离线插件 fixture、插件更新和 Telegram 软件包 QA。升级矩阵覆盖从 `2026.4.23` 到 `latest` 的每个稳定 npm 已发布基线；对于已发布的候选，使用带 `source=npm` 的 Package Acceptance；对于发布前由 SHA 支撑的本地 npm tarball，使用 `source=ref`/`source=artifact`。它是之前大多数需要 Parallels 的软件包/更新覆盖的 GitHub 原生替代方案。跨 OS 发布检查对 OS 特定的新手引导、安装器和平台行为仍然重要，但软件包/更新产品验证应优先使用 Package Acceptance。 -更新和插件验证的规范清单是[更新和插件测试](/zh-CN/help/testing-updates-plugins)。在决定哪个本地、Docker、Package Acceptance 或 release-check lane 能证明插件安装/更新、Doctor 清理或已发布 package 迁移变更时，请使用它。 -从每个稳定 `2026.4.23+` package 进行的穷尽式已发布更新迁移是单独的手动 `Update Migration` 工作流，不属于 Full Release CI。 +更新和插件验证的规范检查清单是 +[更新和插件测试](/zh-CN/help/testing-updates-plugins)。在决定哪个本地、Docker、Package Acceptance 或 release-check lane 能证明插件安装/更新、Doctor 清理或已发布软件包迁移变更时，请使用它。 +从每个稳定 `2026.4.23+` 软件包进行穷尽式已发布更新迁移，是单独的手动 `Update Migration` 工作流，不属于 Full Release CI。 -旧版 package-acceptance 宽容是有意限时的。截至 `2026.4.25` 的 package 可以针对已经发布到 npm 的元数据缺口使用兼容路径：tarball 中缺失的私有 QA 清单条目、缺失的 `gateway install --wrapper`、tarball 派生 git 夹具中缺失的补丁文件、缺失的持久化 `update.channel`、旧版插件安装记录位置、缺失的 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` package 可能会对已经交付的本地构建元数据戳文件发出警告。后续 package 必须满足现代 package 契约；相同缺口会导致发布验证失败。 +旧版 package-acceptance 宽容策略有意设置了时限。截至 +`2026.4.25` 的软件包可以对已发布到 npm 的元数据缺口使用兼容路径：tarball 中缺少私有 QA 清单条目、缺少 +`gateway install --wrapper`、tarball 派生的 git fixture 中缺少补丁文件、缺少持久化的 `update.channel`、旧版插件安装记录位置、缺少 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` 软件包可以对已发布的本地构建元数据戳文件发出警告。之后的软件包必须满足现代软件包契约；这些相同缺口会导致发布验证失败。 -当发布问题涉及实际可安装 package 时，请使用更广泛的 Package Acceptance profile： +当发布问题涉及实际可安装软件包时，使用更广泛的 Package Acceptance 配置： ```bash gh workflow run package-acceptance.yml \ @@ -271,29 +308,35 @@ gh workflow run package-acceptance.yml \ -f published_upgrade_survivor_baseline=openclaw@2026.4.26 ``` -常见 package profile： +常见软件包配置： -- `smoke`：快速 package 安装/渠道/智能体、Gateway 网关网络和配置重载 lane -- `package`：不包含 live ClawHub 的安装/更新/插件 package 契约；这是 release-check 默认值 -- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI Web 搜索和 OpenWebUI +- `smoke`：快速的软件包安装/渠道/智能体、Gateway 网关网络和配置 + 重新加载通道 +- `package`：在没有实时 ClawHub 的情况下验证安装/更新/插件软件包契约；这是发布检查的 + 默认值 +- `product`：`package` 加上 MCP 渠道、cron/子智能体清理、OpenAI web + search 和 OpenWebUI - `full`：带 OpenWebUI 的 Docker 发布路径分块 - `custom`：用于聚焦重跑的精确 `docker_lanes` 列表 -对于 package-candidate Telegram 证明，请在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或 -`telegram_mode=live-frontier`。该工作流会把解析出的 -`package-under-test` tarball 传入 Telegram lane；独立的 -Telegram 工作流仍接受已发布的 npm spec，用于发布后检查。 +对于软件包候选版本的 Telegram 验证，请在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或 +`telegram_mode=live-frontier`。该工作流会将解析出的 +`package-under-test` tarball 传入 Telegram 通道；独立的 +Telegram 工作流仍接受已发布的 npm 规范，用于发布后检查。 -## 发布自动化 +## 发布发布自动化 -`OpenClaw Release Publish` 是常规的变更型发布入口点。它会按发布所需的顺序编排 trusted-publisher 工作流： +`OpenClaw Release Publish` 是常规的可变更发布入口点。它会按发布所需顺序 +编排受信任发布者工作流： -1. 检出发布标签并解析其 commit SHA。 -2. 验证该标签可从 `main` 或 `release/*` 访问。 +1. 签出发布标签并解析其提交 SHA。 +2. 验证该标签可从 `main` 或 `release/*` 到达。 3. 运行 `pnpm plugins:sync:check`。 -4. 使用 `publish_scope=all-publishable` 和 `ref=` 分派 `Plugin NPM Release`。 -5. 使用相同的范围和 SHA 分派 `Plugin ClawHub Release`。 -6. 使用发布标签、npm dist-tag 和保存的 `preflight_run_id` 分派 `OpenClaw NPM Release`。 +4. 使用 `publish_scope=all-publishable` 和 + `ref=` 分发 `Plugin NPM Release`。 +5. 使用相同的范围和 SHA 分发 `Plugin ClawHub Release`。 +6. 使用发布标签、npm dist-tag 和保存的 `preflight_run_id` + 分发 `OpenClaw NPM Release`。 Beta 发布示例： @@ -305,7 +348,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -稳定版发布到默认的 beta dist-tag： +Stable 发布到默认 beta dist-tag： ```bash gh workflow run openclaw-release-publish.yml \ @@ -315,7 +358,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -直接将稳定版提升到 `latest` 是显式操作： +直接提升 Stable 到 `latest` 是显式操作： ```bash gh workflow run openclaw-release-publish.yml \ @@ -325,59 +368,90 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=latest ``` -仅在聚焦修复或重新发布工作时使用更底层的 `Plugin NPM Release` 和 `Plugin ClawHub Release` 工作流。对于选定的插件修复，请将 `plugin_publish_scope=selected` 和 `plugins=@openclaw/name` 传给 `OpenClaw Release Publish`；或者在不得发布 OpenClaw 包时直接分派子工作流。 +仅在聚焦修复或重新发布工作时使用较低层级的 `Plugin NPM Release` 和 `Plugin ClawHub Release` 工作流。对于选定插件修复，将 +`plugin_publish_scope=selected` 和 `plugins=@openclaw/name` 传给 +`OpenClaw Release Publish`；或者在不得发布 OpenClaw 软件包时，直接分发子工作流。 ## NPM 工作流输入 -`OpenClaw NPM Release` 接受这些由操作员控制的输入： +`OpenClaw NPM Release` 接受这些由操作者控制的输入： -- `tag`：必需的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 `v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前完整的 40 字符 workflow-branch commit SHA，用于仅验证的预检 -- `preflight_only`：`true` 表示仅验证/构建/package，`false` 表示真实发布路径 -- `preflight_run_id`：真实发布路径中必需，这样工作流会复用成功预检运行中准备好的 tarball +- `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 - `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta` -`OpenClaw Release Publish` 接受这些由操作员控制的输入： +`OpenClaw Release Publish` 接受这些由操作者控制的输入： -- `tag`：必需的发布标签；必须已存在 -- `preflight_run_id`：成功的 `OpenClaw NPM Release` 预检运行 ID；当 `publish_openclaw_npm=true` 时必需 -- `npm_dist_tag`：OpenClaw 包的 npm 目标标签 -- `plugin_publish_scope`：默认为 `all-publishable`；仅在聚焦修复工作时使用 `selected` -- `plugins`：当 `plugin_publish_scope=selected` 时，逗号分隔的 `@openclaw/*` 包名 -- `publish_openclaw_npm`：默认为 `true`；仅在将该工作流作为纯插件修复编排器使用时设置为 `false` +- `tag`：必需的发布标签；必须已经存在 +- `preflight_run_id`：成功的 `OpenClaw NPM Release` 预检运行 id； + 当 `publish_openclaw_npm=true` 时必需 +- `npm_dist_tag`：OpenClaw 软件包的 npm 目标标签 +- `plugin_publish_scope`：默认为 `all-publishable`；仅在 + 聚焦修复工作时使用 `selected` +- `plugins`：当 + `plugin_publish_scope=selected` 时，为逗号分隔的 `@openclaw/*` 软件包名称 +- `publish_openclaw_npm`：默认为 `true`；仅当使用该 + 工作流作为仅插件修复编排器时设为 `false` -`OpenClaw Release Checks` 接受这些由操作员控制的输入： +`OpenClaw Release Checks` 接受这些由操作者控制的输入： -- `ref`：要验证的分支、标签或完整 commit SHA。携带 secret 的检查要求解析出的提交可从 OpenClaw 分支或发布标签访问。 +- `ref`：要验证的分支、标签或完整提交 SHA。带有密钥的检查 + 要求解析出的提交可从 OpenClaw 分支或 + 发布标签到达。 规则： -- 稳定版和修正版标签可以发布到 `beta` 或 `latest` +- Stable 和修正标签可以发布到 `beta` 或 `latest` - Beta 预发布标签只能发布到 `beta` -- 对于 `OpenClaw NPM Release`，仅当 `preflight_only=true` 时才允许输入完整 commit 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 发布序列 +## Stable npm 发布顺序 -切稳定版 npm 发布时： +切出 Stable npm 发布时： 1. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release` - - 在标签存在之前，你可以使用当前完整的 workflow-branch commit SHA，对预检工作流执行仅验证的 dry run -2. 对常规的先 beta 流程选择 `npm_dist_tag=beta`，或仅在你有意直接发布稳定版时选择 `latest` -3. 当你希望通过一个手动工作流获得常规 CI，以及 live prompt cache、Docker、QA Lab、Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整 commit SHA 上运行 `Full Release Validation` -4. 如果你明确只需要确定性的常规测试图，请改为在发布 ref 上运行手动 `CI` 工作流 + - 在标签存在前，你可以使用当前完整工作流分支提交 + SHA，对预检工作流进行仅验证的试运行 +2. 对常规 beta 优先流程选择 `npm_dist_tag=beta`，或仅在 + 你有意直接发布 Stable 时选择 `latest` +3. 当你希望通过一个手动工作流获得常规 CI 加实时提示缓存、Docker、QA Lab、 + Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整 + 提交 SHA 上运行 `Full Release Validation` +4. 如果你有意只需要确定性的常规测试图，请改为在发布 ref 上运行 + 手动 `CI` 工作流 5. 保存成功的 `preflight_run_id` -6. 使用相同的 `tag`、相同的 `npm_dist_tag` 和保存的 `preflight_run_id` 运行 `OpenClaw Release Publish`；它会先将外部化插件发布到 npm 和 ClawHub，再提升 OpenClaw npm 包 -7. 如果发布落在 `beta` 上，请使用私有的 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` 工作流，将该稳定版本从 `beta` 提升到 `latest` -8. 如果发布有意直接发布到 `latest`，并且 `beta` 应立即跟随相同的稳定构建，请使用同一个私有工作流将两个 dist-tags 都指向该稳定版本，或让其定时自修复同步稍后移动 `beta` +6. 使用相同的 `tag`、相同的 `npm_dist_tag` + 和保存的 `preflight_run_id` 运行 `OpenClaw Release Publish`；它会先将外部化插件发布到 npm + 和 ClawHub，再提升 OpenClaw npm 软件包 +7. 如果发布落在 `beta` 上，请使用私有 + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + 工作流，将该 Stable 版本从 `beta` 提升到 `latest` +8. 如果该发布有意直接发布到 `latest`，并且 `beta` + 应立即跟随同一个 Stable 构建，请使用同一个私有 + 工作流将两个 dist-tag 都指向该 Stable 版本，或让它的定时 + 自愈同步稍后移动 `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) @@ -389,9 +463,9 @@ gh workflow run openclaw-release-publish.yml \ - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -维护者使用私有发布文档 +维护者使用 [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) -作为实际运行手册。 +中的私有发布文档作为实际运行手册。 ## 相关 diff --git a/docs/zh-CN/reference/full-release-validation.md b/docs/zh-CN/reference/full-release-validation.md index 7c0ae161f..990177460 100644 --- a/docs/zh-CN/reference/full-release-validation.md +++ b/docs/zh-CN/reference/full-release-validation.md @@ -1,22 +1,22 @@ --- read_when: - 运行或重新运行完整发布验证 - - 比较稳定版和完整发布验证配置 + - 比较稳定版和完整版发布验证配置方案 - 调试发布验证阶段失败 -summary: 完整发布验证阶段、子工作流、发布配置、重新运行句柄和证据 +summary: 完整发布验证阶段、子工作流、发布配置文件、重新运行句柄和证据 title: 完整发布验证 x-i18n: - generated_at: "2026-05-02T18:56:29Z" + generated_at: "2026-05-03T11:28:41Z" model: gpt-5.5 provider: openai - source_hash: 3ce1e5a72227ca202335fe68b537491a0b68a0bb2af431aa56c41cf20989e88c + source_hash: f5ebe41b7f1fdd019bf7d4adc64648e7aa7ff1691314bc19ba78008e9e6858f2 source_path: reference/full-release-validation.md workflow: 16 --- -`Full Release Validation` 是发布总控流程。它是预发布验证的唯一手动入口点，但大多数工作都在子工作流中完成，因此失败的运行单元可以重跑，而无需重新启动整个发布流程。 +`Full Release Validation` 是发布总控流程。它是发布前验证的唯一手动入口点，但大多数工作会在子工作流中完成，因此失败的验证任务可以重新运行，而不必重启整个发布流程。 -从受信任的工作流 ref 运行它，通常是 `main`，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入： +请从受信任的工作流 ref 运行它，通常是 `main`，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入： ```bash gh workflow run full-release-validation.yml \ @@ -27,40 +27,41 @@ gh workflow run full-release-validation.yml \ -f release_profile=stable ``` -子工作流使用受信任的工作流 ref 作为 harness，并使用输入 `ref` 作为待测候选版本。这样，在验证较旧的发布分支或标签时，新的验证逻辑仍然可用。 +子工作流使用受信任的工作流 ref 作为执行框架，并使用输入的 `ref` 作为被测候选版本。这样在验证较旧的发布分支或标签时，也能使用新的验证逻辑。 -Package Acceptance 通常会从解析后的 `ref` 构建候选 tarball，包括通过 `pnpm ci:full-release` 分发的完整 SHA 运行。发布后，传入 `package_acceptance_package_spec=openclaw@YYYY.M.D`（或 `openclaw@beta`/`openclaw@latest`），改为针对已发布的 npm 包运行相同的包/更新矩阵。 +Package Acceptance 通常会从解析后的 `ref` 构建候选 tarball，包括通过 `pnpm ci:full-release` 分派的完整 SHA 运行。发布后，传入 `package_acceptance_package_spec=openclaw@YYYY.M.D`（或 `openclaw@beta`/`openclaw@latest`），即可改为针对已发布的 npm 包运行相同的包/更新矩阵。 ## 顶层阶段 -| 阶段 | 详情 | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 目标解析 | **Job:** `Resolve target ref`
**子工作流：** 无
**证明内容：** 解析发布分支、标签或完整提交 SHA，并记录选定输入。
**重跑：** 如果此项失败，重跑总控流程。 | -| Vitest 和常规 CI | **Job:** `Run normal full CI`
**子工作流：** `CI`
**证明内容：** 针对目标 ref 的手动完整 CI 图，包括 Linux Node lanes、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Control UI i18n，以及通过总控流程运行的 Android。
**重跑：** `rerun_group=ci`。 | -| 插件预发布 | **Job:** `Run plugin prerelease validation`
**子工作流：** `Plugin Prerelease`
**证明内容：** 仅发布时运行的插件静态检查、agentic 插件覆盖率、完整插件批量分片，以及插件预发布 Docker lanes。
**重跑：** `rerun_group=plugin-prerelease`。 | -| 发布检查 | **Job:** `Run release/live/Docker/QA validation`
**子工作流：** `OpenClaw Release Checks`
**证明内容：** 安装冒烟、跨操作系统包检查、live/E2E 套件、Docker 发布路径分块、Package Acceptance、QA Lab parity、live Matrix，以及 live Telegram。
**重跑：** `rerun_group=release-checks` 或更窄的 release-checks 句柄。 | -| Package Telegram | **Job:** `Run package Telegram E2E`
**子工作流：** `NPM Telegram Beta E2E`
**证明内容：** 在 `rerun_group=all` 且 `release_profile=full` 时提供基于工件的 Telegram 包验证；或在设置 `npm_telegram_package_spec` 时提供已发布包的 Telegram 验证。
**重跑：** 使用 `npm_telegram_package_spec` 的 `rerun_group=npm-telegram`。 | -| 总控验证器 | **Job:** `Verify full validation`
**子工作流：** 无
**证明内容：** 重新检查已记录的子运行结论，并附加来自子工作流的最慢 Job 表格。
**重跑：** 在重跑失败子项并转绿后，仅重跑此 Job。 | +| 阶段 | 详情 | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 目标解析 | **任务：** `Resolve target ref`
**子工作流：** 无
**证明：** 解析发布分支、标签或完整提交 SHA，并记录选定输入。
**重新运行：** 如果此项失败，重新运行总控流程。 | +| Vitest 和常规 CI | **任务：** `Run normal full CI`
**子工作流：** `CI`
**证明：** 针对目标 ref 的手动完整 CI 图，包括 Linux Node 通道、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Control UI i18n，以及通过总控流程运行的 Android。
**重新运行：** `rerun_group=ci`。 | +| 插件预发布 | **任务：** `Run plugin prerelease validation`
**子工作流：** `Plugin Prerelease`
**证明：** 仅发布时运行的插件静态检查、智能体化插件覆盖、完整插件批次分片，以及插件预发布 Docker 通道。
**重新运行：** `rerun_group=plugin-prerelease`。 | +| 发布检查 | **任务：** `Run release/live/Docker/QA validation`
**子工作流：** `OpenClaw Release Checks`
**证明：** 安装冒烟、跨 OS 包检查、live/E2E 套件、Docker 发布路径分块、Package Acceptance、QA Lab parity、live Matrix 和 live Telegram。
**重新运行：** `rerun_group=release-checks` 或更窄的 release-checks 句柄。 | +| 包产物 | **任务：** `Prepare release package artifact`
**子工作流：** 无
**证明：** 提前创建父级 `release-package-under-test` tarball，使不需要等待 `OpenClaw Release Checks` 的面向包检查可以使用。
**重新运行：** 重新运行总控流程，或为 `rerun_group=npm-telegram` 提供 `npm_telegram_package_spec`。 | +| 包 Telegram | **任务：** `Run package Telegram E2E`
**子工作流：** `NPM Telegram Beta E2E`
**证明：** 在 `rerun_group=all` 且 `release_profile=full` 时，提供基于父级产物的 Telegram 包验证；或在设置 `npm_telegram_package_spec` 时，提供已发布包的 Telegram 验证。
**重新运行：** 使用 `npm_telegram_package_spec` 运行 `rerun_group=npm-telegram`。 | +| 总控验证器 | **任务：** `Verify full validation`
**子工作流：** 无
**证明：** 重新检查已记录的子运行结论，并追加来自子工作流的最慢任务表。
**重新运行：** 在重新运行失败的子流程并转绿后，只重新运行此任务。 | -对于 `ref=main` 和 `rerun_group=all`，较新的总控流程会取代较旧的总控流程。当父级被取消时，它的监控器会取消任何已经分发的子工作流。默认情况下，发布分支和标签验证运行不会互相取消。 +对于 `ref=main` 和 `rerun_group=all`，较新的总控流程会取代较旧的总控流程。当父流程被取消时，它的监控器会取消所有已分派的子工作流。默认情况下，发布分支和标签验证运行不会相互取消。 ## 发布检查阶段 -`OpenClaw Release Checks` 是最大的子工作流。它只解析一次目标，并在面向包或 Docker 的阶段需要时准备共享的 `release-package-under-test` 工件。 +`OpenClaw Release Checks` 是最大的子工作流。它会解析一次目标，并在面向包或 Docker 的阶段需要时准备共享的 `release-package-under-test` 产物。 -| 阶段 | 详情 | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 发布目标 | **Job:** `Resolve target ref`
**底层工作流：** 无
**测试内容：** 选定的 ref、可选的预期 SHA、profile、重跑组，以及聚焦的 live 套件过滤器。
**重跑：** `rerun_group=release-checks`。 | -| 包工件 | **Job:** `Prepare release package artifact`
**底层工作流：** 无
**测试内容：** 打包或解析一个候选 tarball，并上传 `release-package-under-test`，供下游面向包的检查使用。
**重跑：** 受影响的包、跨操作系统或 live/E2E 组。 | -| 安装冒烟 | **Job:** `Run install smoke`
**底层工作流：** `Install Smoke`
**测试内容：** 完整安装路径，复用根 Dockerfile 冒烟镜像、QR 包安装、根和 Gateway 网关 Docker 冒烟、安装器 Docker 测试、Bun 全局安装 image-provider 冒烟，以及快速内置插件安装/卸载 E2E。
**重跑：** `rerun_group=install-smoke`。 | -| 跨操作系统 | **Job:** `cross_os_release_checks`
**底层工作流：** `OpenClaw Cross-OS Release Checks (Reusable)`
**测试内容：** 针对选定提供商和模式，在 Linux、Windows 和 macOS 上运行全新安装与升级 lanes，使用候选 tarball 加基线包。
**重跑：** `rerun_group=cross-os`。 | -| 仓库和 live E2E | **Job:** `Run repo/live E2E validation`
**底层工作流：** `OpenClaw Live And E2E Checks (Reusable)`
**测试内容：** 仓库 E2E、live cache、OpenAI websocket streaming、原生 live 提供商和插件分片，以及由 `release_profile` 选择的 Docker 支持的 live 模型/backend/gateway harnesses。
**重跑：** `rerun_group=live-e2e`，可选附带 `live_suite_filter`。 | -| Docker 发布路径 | **Job:** `Run Docker release-path validation`
**底层工作流：** `OpenClaw Live And E2E Checks (Reusable)`
**测试内容：** 针对共享包工件运行 release-path Docker 分块。
**重跑：** `rerun_group=live-e2e`。 | -| Package Acceptance | **Job:** `Run package acceptance`
**底层工作流：** `Package Acceptance`
**测试内容：** 离线插件包 fixtures、插件更新、mock-OpenAI Telegram 包验收，以及从 `2026.4.23` 或之后的每个稳定 npm 发布版本到同一 tarball 的已发布升级幸存检查。
**重跑：** `rerun_group=package`。 | -| QA parity | **Job:** `Run QA Lab parity lane` 和 `Run QA Lab parity report`
**底层工作流：** 直接 Job
**测试内容：** 候选版本和基线的 agentic parity packs，然后生成 parity report。
**重跑：** `rerun_group=qa-parity` 或 `rerun_group=qa`。 | -| QA live Matrix | **Job:** `Run QA Lab live Matrix lane`
**底层工作流：** 直接 Job
**测试内容：** 在 `qa-live-shared` 环境中运行快速 live Matrix QA profile。
**重跑：** `rerun_group=qa-live` 或 `rerun_group=qa`。 | -| QA live Telegram | **Job:** `Run QA Lab live Telegram lane`
**底层工作流：** 直接 Job
**测试内容：** 使用 Convex CI 凭证租约的 live Telegram QA。
**重跑：** `rerun_group=qa-live` 或 `rerun_group=qa`。 | -| 发布验证器 | **Job:** `Verify release checks`
**底层工作流：** 无
**测试内容：** 选定重跑组所需的 release-check Job。
**重跑：** 聚焦的子 Job 通过后重跑。 | +| 阶段 | 详情 | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 发布目标 | **任务：** `Resolve target ref`
**支撑工作流：** 无
**测试：** 选定的 ref、可选的预期 SHA、配置文件、重新运行组，以及聚焦的 live 套件过滤器。
**重新运行：** `rerun_group=release-checks`。 | +| 包产物 | **任务：** `Prepare release package artifact`
**支撑工作流：** 无
**测试：** 打包或解析一个候选 tarball，并上传 `release-package-under-test`，供下游面向包的检查使用。
**重新运行：** 受影响的包、跨 OS 或 live/E2E 组。 | +| 安装冒烟 | **任务：** `Run install smoke`
**支撑工作流：** `Install Smoke`
**测试：** 完整安装路径，包括复用根 Dockerfile 冒烟镜像、QR 包安装、根和 Gateway 网关 Docker 冒烟、安装器 Docker 测试、Bun 全局安装 image-provider 冒烟，以及快速内置插件安装/卸载 E2E。
**重新运行：** `rerun_group=install-smoke`。 | +| 跨 OS | **任务：** `cross_os_release_checks`
**支撑工作流：** `OpenClaw Cross-OS Release Checks (Reusable)`
**测试：** 在 Linux、Windows 和 macOS 上，针对选定提供商和模式运行全新安装和升级通道，使用候选 tarball 加基线包。
**重新运行：** `rerun_group=cross-os`。 | +| 仓库和 live E2E | **任务：** `Run repo/live E2E validation`
**支撑工作流：** `OpenClaw Live And E2E Checks (Reusable)`
**测试：** 仓库 E2E、live 缓存、OpenAI websocket 流式传输、原生 live 提供商和插件分片，以及由 `release_profile` 选择的 Docker 支撑 live 模型/后端/Gateway 网关执行框架。
**重新运行：** `rerun_group=live-e2e`，可选配 `live_suite_filter`。 | +| Docker 发布路径 | **任务：** `Run Docker release-path validation`
**支撑工作流：** `OpenClaw Live And E2E Checks (Reusable)`
**测试：** 针对共享包产物运行发布路径 Docker 分块。
**重新运行：** `rerun_group=live-e2e`。 | +| Package Acceptance | **任务：** `Run package acceptance`
**支撑工作流：** `Package Acceptance`
**测试：** 离线插件包夹具、插件更新、mock-OpenAI Telegram 包验收，以及从 `2026.4.23` 或之后每个稳定 npm 发布版本到同一个 tarball 的已发布升级存活检查。
**重新运行：** `rerun_group=package`。 | +| QA parity | **任务：** `Run QA Lab parity lane` 和 `Run QA Lab parity report`
**支撑工作流：** 直接任务
**测试：** 候选版本和基线的智能体化 parity 包，然后生成 parity 报告。
**重新运行：** `rerun_group=qa-parity` 或 `rerun_group=qa`。 | +| QA live Matrix | **任务：** `Run QA Lab live Matrix lane`
**支撑工作流：** 直接任务
**测试：** 在 `qa-live-shared` 环境中运行快速 live Matrix QA 配置。
**重新运行：** `rerun_group=qa-live` 或 `rerun_group=qa`。 | +| QA live Telegram | **任务：** `Run QA Lab live Telegram lane`
**支撑工作流：** 直接任务
**测试：** 使用 Convex CI 凭证租约运行 live Telegram QA。
**重新运行：** `rerun_group=qa-live` 或 `rerun_group=qa`。 | +| 发布验证器 | **任务：** `Verify release checks`
**支撑工作流：** 无
**测试：** 针对选定重新运行组所需的发布检查任务。
**重新运行：** 在聚焦的子任务通过后重新运行。 | ## Docker 发布路径分块 @@ -68,48 +69,43 @@ Package Acceptance 通常会从解析后的 `ref` 构建候选 tarball，包括 | 分块 | 覆盖范围 | | --------------------------------------------------------------- | ----------------------------------------------------------------------- | -| `core` | Core Docker 发布路径冒烟 lanes。 | +| `core` | Core Docker 发布路径冒烟通道。 | | `package-update-openai` | OpenAI 包安装和更新行为。 | | `package-update-anthropic` | Anthropic 包安装和更新行为。 | | `package-update-core` | 提供商中立的包和更新行为。 | -| `plugins-runtime-plugins` | 运行插件行为的插件运行时 lanes。 | -| `plugins-runtime-services` | 服务支持的插件运行时 lanes；在请求时包含 OpenWebUI。 | -| `plugins-runtime-install-a` through `plugins-runtime-install-h` | 为并行发布验证拆分的插件安装/运行时批次。 | +| `plugins-runtime-plugins` | 执行插件行为的插件运行时通道。 | +| `plugins-runtime-services` | 服务支撑的插件运行时通道；按请求包含 OpenWebUI。 | +| `plugins-runtime-install-a` through `plugins-runtime-install-h` | 为并行发布验证而拆分的插件安装/运行时批次。 | -当只有一个 Docker lane 失败时，在可复用 live/E2E 工作流上使用定向的 `docker_lanes=`。发布工件包含按 lane 划分的重跑命令，并在可用时包含包工件和镜像复用输入。 +在可复用的 live/E2E 工作流中，当只有一个 Docker lane 失败时，使用有针对性的 `docker_lanes=`。发布工件会在可用时包含每个 lane 的重跑命令，并带有 package artifact 和 image reuse 输入。 -## 发布 profiles +## 发布配置文件 -`release_profile` 主要控制发布检查中的实时/提供商覆盖广度。 -它不会移除正常的完整 CI、插件预发布、安装冒烟测试、包 -验收、QA Lab 或 Docker 发布路径分块。`full` 还会让 -总控运行在 `rerun_group=all` 时针对发布包产物执行 Telegram 包 E2E，因此完整的预发布候选版本不会静默跳过该 -Telegram 包通道。 +`release_profile` 主要控制发布检查中的 live/provider 覆盖范围。它不会移除正常的完整 CI、插件预发布、安装冒烟测试、package acceptance、QA Lab 或 Docker release-path 分块。`full` 还会在 `rerun_group=all` 时，让总控运行针对父级 release package artifact 的 package Telegram E2E，因此完整的预发布候选不会静默跳过该 Telegram package lane。 -| Profile | 预期用途 | 包含的实时/提供商覆盖范围 | -| --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `minimum` | 最快的发布关键冒烟测试。 | OpenAI/核心实时路径、用于 OpenAI 的 Docker 实时模型、原生 Gateway 网关核心、原生 OpenAI Gateway 网关配置文件、原生 OpenAI 插件，以及 Docker 实时 Gateway 网关 OpenAI。 | -| `stable` | 默认发布批准配置文件。 | `minimum` 加上 Anthropic、Google、MiniMax、后端、原生实时测试 harness、Docker 实时 CLI 后端、Docker ACP 绑定、Docker Codex harness，以及一个 OpenCode Go 冒烟分片。 | -| `full` | 广泛的建议性扫描。 | `stable` 加上建议性提供商、插件实时分片和媒体实时分片。 | +| 配置文件 | 预期用途 | 包含的 live/provider 覆盖范围 | +| --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `minimum` | 最快的发布关键冒烟测试。 | OpenAI/core live 路径、OpenAI 的 Docker live 模型、原生 Gateway 网关 core、原生 OpenAI Gateway 网关配置文件、原生 OpenAI 插件，以及 Docker live Gateway 网关 OpenAI。 | +| `stable` | 默认发布审批配置文件。 | `minimum` 加上 Anthropic 冒烟测试、Google、MiniMax、backend、原生 live 测试 harness、Docker live CLI backend、Docker ACP bind、Docker Codex harness，以及一个 OpenCode Go 冒烟 shard。 | +| `full` | 广泛的 advisory sweep。 | `stable` 加上 advisory providers、插件 live shards 和 media live shards。 | -## 仅 full 增加项 +## 仅 full 包含的附加项 这些套件会被 `stable` 跳过，并由 `full` 包含： -| 区域 | 仅 full 覆盖范围 | -| -------------------------------- | ------------------------------------------------------------------------------- | -| Docker 实时模型 | OpenCode Go、OpenRouter、xAI、Z.ai 和 Fireworks。 | -| Docker 实时 Gateway 网关 | 用于 DeepSeek、Fireworks、OpenCode Go、OpenRouter、xAI 和 Z.ai 的建议性分片。 | -| 原生 Gateway 网关提供商配置文件 | Fireworks、DeepSeek、完整 OpenCode Go 模型分片、OpenRouter、xAI 和 Z.ai。 | -| 原生插件实时分片 | 插件 A-K、L-N、O-Z 其他、Moonshot 和 xAI。 | -| 原生媒体实时分片 | 音频、Google 音乐、MiniMax 音乐和视频组 A-D。 | +| 区域 | 仅 full 覆盖范围 | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| Docker live models | OpenCode Go、OpenRouter、xAI、Z.ai 和 Fireworks。 | +| Docker live gateway | DeepSeek、Fireworks、OpenCode Go、OpenRouter、xAI 和 Z.ai 的 advisory shard。 | +| 原生 Gateway 网关 provider 配置文件 | 完整 Anthropic Opus 和 Sonnet/Haiku shards、Fireworks、DeepSeek、完整 OpenCode Go model shards、OpenRouter、xAI 和 Z.ai。 | +| 原生插件 live shards | Plugins A-K、L-N、O-Z other、Moonshot 和 xAI。 | +| 原生 media live shards | Audio、Google music、MiniMax music 和 video groups A-D。 | -`stable` 包含 `native-live-src-gateway-profiles-opencode-go-smoke`；`full` -则使用更广泛的 OpenCode Go 模型分片。 +`stable` 包含 `native-live-src-gateway-profiles-anthropic-smoke` 和 `native-live-src-gateway-profiles-opencode-go-smoke`；`full` 则使用更广泛的 Anthropic 和 OpenCode Go model shards。定向重跑仍可使用聚合的 `native-live-src-gateway-profiles-anthropic` 或 `native-live-src-gateway-profiles-opencode-go` 句柄。 -## 聚焦重跑 +## 定向重跑 -使用 `rerun_group` 以避免重复运行无关的发布盒子： +使用 `rerun_group` 避免重复运行无关的发布 boxes： | 句柄 | 范围 | | ------------------- | --------------------------------------------------------------------- | @@ -117,36 +113,28 @@ Telegram 包通道。 | `ci` | 仅手动完整 CI 子项。 | | `plugin-prerelease` | 仅插件预发布子项。 | | `release-checks` | 所有 OpenClaw 发布检查阶段。 | -| `install-smoke` | 通过发布检查执行安装冒烟测试。 | -| `cross-os` | 跨 OS 发布检查。 | -| `live-e2e` | 仓库/实时 E2E 和 Docker 发布路径验证。 | -| `package` | 包验收。 | -| `qa` | QA 奇偶校验加 QA 实时通道。 | -| `qa-parity` | 仅 QA 奇偶校验通道和报告。 | -| `qa-live` | 仅 QA 实时 Matrix 和 Telegram。 | -| `npm-telegram` | 已发布包 Telegram E2E；需要 `npm_telegram_package_spec`。 | +| `install-smoke` | 安装冒烟测试到发布检查。 | +| `cross-os` | 跨操作系统发布检查。 | +| `live-e2e` | Repo/live E2E 和 Docker release-path 验证。 | +| `package` | Package Acceptance。 | +| `qa` | QA parity 加 QA live lanes。 | +| `qa-parity` | 仅 QA parity lanes 和报告。 | +| `qa-live` | 仅 QA live Matrix 和 Telegram。 | +| `npm-telegram` | 已发布 package Telegram E2E；需要 `npm_telegram_package_spec`。 | -当某个实时套件失败时，将 `live_suite_filter` 与 `rerun_group=live-e2e` 一起使用。 -有效的过滤器 ID 定义在可复用实时/E2E 工作流中，包括 -`docker-live-models`、`live-gateway-docker`、 -`live-gateway-anthropic-docker`、`live-gateway-google-docker`、 -`live-gateway-minimax-docker`、`live-gateway-advisory-docker`、 -`live-cli-backend-docker`、`live-acp-bind-docker` 和 -`live-codex-harness-docker`。 +当一个 live suite 失败时，将 `live_suite_filter` 与 `rerun_group=live-e2e` 配合使用。有效的 filter ids 定义在可复用 live/E2E 工作流中，包括 `docker-live-models`、`live-gateway-docker`、`live-gateway-anthropic-docker`、`live-gateway-google-docker`、`live-gateway-minimax-docker`、`live-gateway-advisory-docker`、`live-cli-backend-docker`、`live-acp-bind-docker` 和 `live-codex-harness-docker`。 -## 需要保留的证据 +## 要保留的证据 -保留 `Full Release Validation` 摘要作为发布级索引。它会链接 -子运行 ID，并包含最慢任务表。对于失败，先检查子 -工作流，然后重跑上面匹配的最小句柄。 +保留 `Full Release Validation` 摘要作为发布级索引。它会链接子运行 id，并包含最慢作业表。对于失败项，先检查子工作流，然后重跑上方匹配范围最小的句柄。 -有用的产物： +有用的工件： -- 来自 `OpenClaw Release Checks` 的 `release-package-under-test` -- `.artifacts/docker-tests/` 下的 Docker 发布路径产物 -- 包验收 `package-under-test` 和 Docker 验收产物 -- 每个 OS 和套件的跨 OS 发布检查产物 -- QA 奇偶校验、Matrix 和 Telegram 产物 +- 来自 Full Release Validation 父项和 `OpenClaw Release Checks` 的 `release-package-under-test` +- `.artifacts/docker-tests/` 下的 Docker release-path 工件 +- Package Acceptance `package-under-test` 和 Docker acceptance 工件 +- 每个 OS 和套件的 Cross-OS release-check 工件 +- QA parity、Matrix 和 Telegram 工件 ## 工作流文件