From 8fca2d01419cbe7535b32259d4df65c64d1a9b3b Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 27 Apr 2026 00:41:45 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/ci.md | 120 +++++++++++---------- docs/zh-CN/reference/RELEASING.md | 168 ++++++++++++++---------------- 2 files changed, 140 insertions(+), 148 deletions(-) diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 665635786..b829d6421 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -1,27 +1,27 @@ --- read_when: - - 你需要了解某个 CI 作业为何运行或未运行 + - 你需要了解某个 CI 作业为什么运行了或没有运行 - 你正在调试失败的 GitHub Actions 检查 -summary: CI 作业图、作用域门控，以及本地命令对应项 +summary: CI 作业图、范围门控，以及本地等效命令 title: CI 流水线 x-i18n: - generated_at: "2026-04-26T23:58:26Z" + generated_at: "2026-04-27T00:40:13Z" model: gpt-5.4 provider: openai - source_hash: e327836428668034714c3b2dcc880dd1da37426cefd1ef7956101253193f811c + source_hash: 9d2003fd1c7c09b32e6b677b3b4037ab5b75f3be8984d8dfc1116f5b2aaaa408 source_path: ci.md workflow: 15 --- -CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能作用域划分，在仅有不相关区域发生变更时跳过昂贵的作业。手动 `workflow_dispatch` 运行会有意绕过智能作用域划分，并展开完整的 CI 作业图，用于候选发布版本或大范围验证。 +CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能范围门控，在只有不相关区域发生变更时跳过高开销作业。手动 `workflow_dispatch` 运行会有意绕过智能范围门控，并展开完整的 CI 作业图，以用于候选发布版本或广泛验证。 -QA Lab 在主智能作用域工作流之外有专用的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更和手动分发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.5 和 Opus 4.6 agentic pack。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，并在手动分发时运行；它会将模拟 parity gate、实时 Matrix 通道和实时 Telegram 通道作为并行作业展开。实时作业使用 `qa-live-shared` 环境，而 Telegram 通道使用 Convex 租约。`OpenClaw Release Checks` 也会在发布批准前运行相同的 QA Lab 通道。 +QA Lab 在主智能范围工作流之外有专用的 CI 分支。`Parity gate` 工作流会在匹配的 PR 变更和手动派发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.5 和 Opus 4.6 智能体包。`QA-Lab - All Lanes` 工作流会在 `main` 上每夜运行，并在手动派发时运行；它会将模拟 parity gate、实时 Matrix 分支和实时 Telegram 分支作为并行作业展开。实时作业使用 `qa-live-shared` environment，而 Telegram 分支使用 Convex 租约。`OpenClaw Release Checks` 也会在发布审批前运行相同的 QA Lab 分支。 -`Duplicate PRs After Merge` 工作流是一个供维护者在合并后清理重复 PR 的手动工作流。它默认以 dry-run 模式运行，只有在 `apply=true` 时才会关闭明确列出的 PR。在修改 GitHub 之前，它会验证已落地的 PR 确实已合并，并且每个重复 PR 都具有共享的引用 issue 或重叠的变更代码块。 +`Duplicate PRs After Merge` 工作流是一个供维护者使用的手动工作流，用于合并后的重复项清理。它默认以 dry-run 模式运行，只有当 `apply=true` 时才会关闭明确列出的 PR。在修改 GitHub 之前，它会验证已落地的 PR 是否已合并，并验证每个重复 PR 是否具有共享的引用 issue 或重叠的变更代码块。 -`Docs Agent` 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与最近已落地的变更保持一致。它没有纯定时调度：`main` 上一次成功的非机器人 push CI 运行可以触发它，手动分发也可以直接运行它。workflow-run 调用会在 `main` 已继续前进，或过去一小时内已创建另一个未跳过的 Docs Agent 运行时跳过。当它运行时，会审查从上一个未跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此一次每小时运行即可覆盖自上次文档处理以来累积的所有 main 变更。 +`Docs Agent` 工作流是一个事件驱动的 Codex 维护分支，用于让现有文档与最近已落地的更改保持一致。它没有纯定时调度：在 `main` 上成功完成的一次非机器人推送 CI 运行可以触发它，手动派发也可以直接运行它。workflow-run 调用会在 `main` 已继续前进，或最近一小时内已创建了另一次未被跳过的 Docs Agent 运行时跳过。当它运行时，它会审查从上一次未被跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此每小时一次运行可以覆盖自上次文档处理以来积累的所有 main 变更。 -`Test Performance Agent` 工作流是一个面向慢测试的事件驱动 Codex 维护通道。它没有纯定时调度：`main` 上一次成功的非机器人 push CI 运行可以触发它，但如果同一个 UTC 日已有另一条 workflow-run 调用已运行或正在运行，它就会跳过。手动分发会绕过这一每日活动门控。该通道会构建完整测试套件的分组 Vitest 性能报告，让 Codex 仅进行小范围、保持覆盖率不变的测试性能修复，而不是大规模重构，然后重新运行完整测试套件报告，并拒绝任何会降低通过基线测试数量的更改。如果基线存在失败测试，Codex 只能修复明显的失败项，并且变更后的完整测试套件报告必须通过，之后才会提交任何内容。当 `main` 在机器人推送落地前继续前进时，该通道会对已验证补丁执行 rebase，重新运行 `pnpm check:changed`，并重试推送；存在冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，这样 Codex action 就能与 docs agent 保持相同的 drop-sudo 安全策略。 +`Test Performance Agent` 工作流是一个事件驱动的 Codex 维护分支，用于处理慢速测试。它没有纯定时调度：在 `main` 上成功完成的一次非机器人推送 CI 运行可以触发它，但如果当个 UTC 日已有另一次 workflow-run 调用已经运行或正在运行，它就会跳过。手动派发会绕过这个按日活动门控。该分支会构建完整测试套件的分组 Vitest 性能报告，让 Codex 仅做小范围且保留覆盖率的测试性能修复，而不是进行大规模重构，然后重新运行完整测试套件报告，并拒绝那些降低通过基线测试数量的更改。如果基线存在失败测试，Codex 只能修复明显失败项，并且智能体处理后的完整测试套件报告必须通过，之后才会提交任何内容。当 `main` 在机器人推送落地前继续前进时，该分支会对已验证补丁执行 rebase，重新运行 `pnpm check:changed`，并重试推送；发生冲突的过时补丁会被跳过。它使用 GitHub 托管的 Ubuntu，这样 Codex action 就能与 docs agent 保持相同的 drop-sudo 安全策略。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -34,29 +34,29 @@ gh workflow run duplicate-after-merge.yml \ | 作业 | 用途 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | 检测是否仅有文档变更、变更作用域、变更的扩展，并构建 CI 清单 | 在所有非 draft 的 push 和 PR 上始终运行 | -| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 在所有非 draft 的 push 和 PR 上始终运行 | -| `security-dependency-audit` | 针对 npm advisory 执行无依赖的生产 lockfile 审计 | 在所有非 draft 的 push 和 PR 上始终运行 | -| `security-fast` | 快速安全作业的必需聚合作业 | 在所有非 draft 的 push 和 PR 上始终运行 | +| `preflight` | 检测是否仅文档变更、变更范围、变更的扩展，并构建 CI 清单 | 在所有非草稿 push 和 PR 上始终运行 | +| `security-scm-fast` | 通过 `zizmor` 执行私钥检测和工作流审计 | 在所有非草稿 push 和 PR 上始终运行 | +| `security-dependency-audit` | 针对 npm 安全通告执行无依赖的生产 lockfile 审计 | 在所有非草稿 push 和 PR 上始终运行 | +| `security-fast` | 快速安全作业的必需聚合作业 | 在所有非草稿 push 和 PR 上始终运行 | | `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查，以及可复用的下游产物 | 与 Node 相关的变更 | -| `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 | -| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | 与 Node 相关的变更 | -| `checks-node-extensions` | 对整个扩展套件执行完整的内置插件测试分片 | 与 Node 相关的变更 | -| `checks-node-core-test` | Core Node 测试分片，不包括渠道、内置插件、契约和扩展通道 | 与 Node 相关的变更 | -| `extension-fast` | 仅针对发生变更的内置插件执行聚焦测试 | 带有扩展变更的拉取请求 | -| `check` | 分片后的主本地门控对应项：生产类型、lint、守卫、测试类型和严格 smoke | 与 Node 相关的变更 | -| `check-additional` | 架构、边界、扩展表面守卫、包边界和 gateway-watch 分片 | 与 Node 相关的变更 | +| `checks-fast-core` | 快速 Linux 正确性分支，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 | +| `checks-fast-contracts-channels` | 分片的渠道契约检查，并产出稳定的聚合检查结果 | 与 Node 相关的变更 | +| `checks-node-extensions` | 针对整个扩展套件的完整内置插件测试分片 | 与 Node 相关的变更 | +| `checks-node-core-test` | Core Node 测试分片，不包括渠道、内置插件、契约和扩展分支 | 与 Node 相关的变更 | +| `check` | 分片后的主本地门控等效项：生产类型、lint、守卫、测试类型和严格 smoke | 与 Node 相关的变更 | +| `check-additional` | 架构、边界、扩展表面守卫、包边界以及 gateway-watch 分片 | 与 Node 相关的变更 | | `build-smoke` | 已构建 CLI 的 smoke 测试和启动内存 smoke 测试 | 与 Node 相关的变更 | -| `checks` | 已构建产物渠道测试的验证器，以及仅 push 的 Node 22 兼容性检查 | 与 Node 相关的变更 | -| `check-docs` | 文档格式、lint 和断链检查 | 文档发生变更 | -| `skills-python` | 面向 Python 支持的 Skills 的 Ruff + pytest | 与 Python Skills 相关的变更 | -| `checks-windows` | Windows 专用测试通道 | 与 Windows 相关的变更 | -| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试通道 | 与 macOS 相关的变更 | +| `checks` | 已构建产物渠道测试的验证器 | 与 Node 相关的变更 | +| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke 分支 | `main` push 和手动 CI 派发 | +| `check-docs` | 文档格式化、lint 和失效链接检查 | 文档发生变更时 | +| `skills-python` | 针对 Python 支持的 Skills 运行 Ruff + pytest | 与 Python Skills 相关的变更 | +| `checks-windows` | Windows 专用测试分支 | 与 Windows 相关的变更 | +| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试分支 | 与 macOS 相关的变更 | | `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 | -| `android` | 两个 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的变更 | -| `test-performance-agent` | 在可信活动之后进行的每日 Codex 慢测试优化 | Main CI 成功后或手动分发 | +| `android` | 两种 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的变更 | +| `test-performance-agent` | 在可信活动之后按日运行的 Codex 慢测试优化 | 主 CI 成功后或手动派发 | -手动 CI 分发会运行与常规 CI 相同的作业图，但会强制开启所有按作用域划分的通道：Linux Node 分片、内置插件分片、渠道契约、`check`、`check-additional`、构建 smoke、文档检查、Python Skills、Windows、macOS、Android，以及 Control UI i18n。它们不会运行仅限 PR 的 `extension-fast` 通道，因为完整的内置插件分片矩阵已经覆盖了内置插件测试。手动运行使用唯一的并发组，因此候选发布版本的完整套件不会被同一 ref 上的其他 push 或 PR 运行取消。 +手动 CI 派发会运行与普通 CI 相同的作业图，但会强制开启所有范围分支：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、build smoke、文档检查、Python Skills、Windows、macOS、Android，以及 Control UI i18n。手动运行使用唯一的并发组，因此候选发布版本的完整套件不会因为同一引用上的另一次 push 或 PR 运行而被取消。 ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -64,71 +64,69 @@ gh workflow run ci.yml --ref release/YYYY.M.D ## 快速失败顺序 -作业的排序方式是让低成本检查先于高成本作业失败： +作业的排序方式是让低成本检查先失败，再决定是否运行高成本作业： -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-extensions`、`checks-node-core-test`、仅限 PR 的 `extension-fast`、`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-extensions`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 -作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 -手动分发会跳过 changed-scope 检测，并使 preflight 清单表现得像每个作用域区域都发生了变更。 +范围逻辑位于 `scripts/ci-changed-scope.mjs`，其单元测试位于 `src/scripts/ci-changed-scope.test.ts`。 +手动派发会跳过 changed-scope 检测，并让 preflight 清单表现得像每个范围区域都已发生变更。 -CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但不会仅因为这些更改就强制运行 Windows、Android 或 macOS 原生构建；这些平台通道仍然仅根据平台源代码变更来决定是否运行。 +CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但不会仅因这些编辑就强制运行 Windows、Android 或 macOS 原生构建；这些平台分支仍然只由平台源码变更触发。 -仅涉及 CI 路由的编辑、选定的低成本 core-test fixture 编辑，以及范围很窄的插件契约辅助函数 / 测试路由编辑，会走快速的仅 Node 清单路径：preflight、安全检查，以及单个 `checks-fast-core` 任务。当前变更文件仅限于该快速任务可直接覆盖的路由或辅助表面时，这一路径会跳过构建产物、Node 22 兼容性、渠道契约、完整 core 分片、内置插件分片，以及附加守卫矩阵。 +纯 CI 路由编辑、选定的低成本 core-test fixture 编辑，以及狭义的插件契约辅助工具 / 测试路由编辑，会走快速的仅 Node 清单路径：preflight、安全检查，以及单个 `checks-fast-core` 任务。该路径会避开构建产物、Node 22 兼容性、渠道契约、完整 core 分片、内置插件分片，以及额外的守卫矩阵，前提是变更文件仅限于快速任务可直接覆盖的路由或辅助工具表面。 -Windows Node 检查的作用域仅限于 Windows 专用的进程 / 路径包装器、npm / pnpm / UI runner 辅助函数、包管理器配置，以及执行该通道的 CI 工作流表面；不相关的源代码、插件、install-smoke 和纯测试变更会继续留在 Linux Node 通道上，这样它们就不会为正常测试分片已覆盖的内容额外占用一个 16-vCPU 的 Windows worker。 +Windows Node 检查的范围限定在 Windows 专用的进程 / 路径包装器、npm/pnpm/UI 运行器辅助工具、包管理器配置，以及执行该分支的 CI 工作流表面；不相关的源码、插件、install-smoke 和纯测试变更仍然留在 Linux Node 分支上，因此不会为了已由常规测试分片覆盖的内容占用 16 vCPU 的 Windows worker。 -独立的 `install-smoke` 工作流会通过它自己的 `preflight` 作业复用同一个作用域脚本。它将 smoke 覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。对于拉取请求，Docker / package 表面、内置插件 package / manifest 变更，以及 Docker smoke 作业会覆盖到的 core 插件 / 渠道 / Gateway 网关 / 插件 SDK 表面，会运行快速路径。仅源码级的内置插件变更、纯测试编辑和纯文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI smoke，运行 container gateway-network e2e，验证一个内置扩展 build arg，并在总命令超时 240 秒的限制下运行受限的内置插件 Docker profile，同时每个场景的 Docker 运行也分别受到上限控制。完整路径则为每晚定时运行、手动分发、workflow-call 发布检查，以及确实触及 installer / package / Docker 表面的拉取请求保留 QR package 安装和 installer Docker / update 覆盖。推送到 `main`，包括 merge commit，不会强制完整路径；当 changed-scope 逻辑在 push 上请求完整覆盖时，工作流仍会保留快速 Docker smoke，而将完整 install smoke 留给夜间运行或发布验证。较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独门控；它会在夜间调度和发布检查工作流中运行，手动 `install-smoke` 分发也可以选择启用它，但拉取请求和 `main` push 不会运行它。QR 和 installer Docker 测试保留它们各自面向安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像，将 OpenClaw 一次性打包为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个裸 Node / Git runner，用于 installer / update / plugin-dependency 通道；另一个是功能型镜像，它会将同一个 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` 运行各通道；默认主池槽位数为 10，可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整；对提供商敏感的尾池槽位数也默认为 10，可通过 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整。重型通道上限默认分别为 `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 storm；可通过 `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`，同时跳过 cleanup smoke，以便智能体能够复现某个失败通道。可复用的 live / E2E 工作流会通过 `scripts/test-docker-all.mjs --plan-json` 询问需要哪些 package、镜像类型、live 镜像、通道和凭证覆盖，然后 `scripts/docker-e2e.mjs` 会将该计划转换为 GitHub outputs 和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，校验 tarball 清单，并在计划需要 install / update / plugin-dependency 通道时构建并推送一个带 SHA 标签的 bare GHCR Docker E2E 镜像；当计划需要 package-installed 功能通道时，则构建一个带 SHA 标签的 functional GHCR Docker E2E 镜像；如果任一带 SHA 标签的镜像已经存在，工作流会跳过重建该镜像，但仍会创建目标重跑所需的新 tarball artifact。发布路径 Docker 套件最多以三个分块作业运行，并使用 `OPENCLAW_SKIP_DOCKER_BUILD=1`，因此每个分块只会拉取它所需的镜像类型，并通过同一个加权调度器执行多个通道（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`，`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update|plugins-integrations`）。每个分块都会上传 `.artifacts/docker-tests/`，其中包括通道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON，以及每通道重跑命令。工作流输入 `docker_lanes` 会针对已准备好的镜像运行所选通道，而不是运行那三个分块作业，这样就能将失败通道调试限制在一个有针对性的 Docker 作业内，并为所选 ref 准备一个新的 npm tarball；如果所选通道是 live Docker 通道，则该定向作业会为此次重跑在本地构建 live-test 镜像。使用 `pnpm test:docker:rerun ` 可从 GitHub 某次运行下载 Docker artifact，并输出合并后的 / 每通道定向重跑命令；使用 `pnpm test:docker:timings ` 可查看慢通道和阶段关键路径摘要。当发布路径套件请求 Open WebUI 时，它会在 plugins / integrations 分块中运行，而不是额外占用第四个 Docker worker；只有 openwebui-only 分发时，Open WebUI 才保留独立作业。定时的 live / E2E 工作流每天运行完整的发布路径 Docker 套件。内置更新矩阵会按更新目标拆分，以便重复的 npm update 和 doctor repair 过程可以与其他内置检查一起分片运行。 +独立的 `install-smoke` 工作流通过其自己的 `preflight` 作业复用同一个范围脚本。它将 smoke 覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。对于拉取请求，Docker/包表面、内置插件包 / manifest 变更，以及 Docker smoke 作业所覆盖的 core 插件 / 渠道 / Gateway 网关 / 插件 SDK 表面，会运行快速路径。仅源码的内置插件变更、纯测试编辑和纯文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI smoke，运行容器 gateway-network e2e，验证一个内置扩展 build arg，并在总命令超时 240 秒的限制下运行受限的内置插件 Docker profile，同时每个场景的 Docker run 也有单独上限。完整路径则保留 QR 包安装以及 installer Docker/update 覆盖，用于每夜定时运行、手动派发、workflow-call 发布检查，以及真正触及 installer/package/Docker 表面的拉取请求。`main` push（包括合并提交）不会强制完整路径；当 changed-scope 逻辑会在 push 上请求完整覆盖时，该工作流会保留快速 Docker smoke，并把完整 install smoke 留给每夜运行或发布验证。较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独门控；它会在每夜调度和发布检查工作流中运行，手动 `install-smoke` 派发也可以选择启用它，但拉取请求和 `main` push 不会运行它。QR 和 installer Docker 测试保留各自面向安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像，将 OpenClaw 一次性打包为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个是用于 installer/update/plugin-dependency 分支的裸 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` 调整 provider 敏感尾池默认 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`），同时跳过 cleanup smoke，以便智能体复现某一个失败分支。可复用的 live/E2E 工作流会通过 `scripts/test-docker-all.mjs --plan-json` 询问需要哪些包、镜像类型、live 镜像、分支和凭证覆盖，然后由 `scripts/docker-e2e.mjs` 将该计划转换为 GitHub 输出和摘要。它通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，验证 tarball 清单，并在计划需要 install/update/plugin-dependency 分支时构建并推送一个带 SHA 标签的裸 GHCR Docker E2E 镜像；在计划需要 package-installed 功能分支时，则构建一个带 SHA 标签的功能型 GHCR Docker E2E 镜像；如果任一带 SHA 标签的镜像已存在，工作流会跳过重建该镜像，但仍会创建目标重跑所需的最新 tarball 产物。发布路径 Docker 套件最多会作为三个分块作业运行，并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`，这样每个分块只会拉取自身所需的镜像类型，并通过同一个加权调度器执行多个分支（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`、`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update|plugins-integrations`）。每个分块都会上传 `.artifacts/docker-tests/`，其中包含分支日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON，以及每个分支的重跑命令。工作流的 `docker_lanes` 输入会针对已准备好的镜像运行所选分支，而不是运行三个分块作业，这样失败分支的调试就被限制在单个目标 Docker 作业内，并且会为所选引用准备一个新的 npm tarball；如果所选分支是 live Docker 分支，则该目标作业会为这次重跑在本地构建 live-test 镜像。使用 `pnpm test:docker:rerun ` 可以从某个 GitHub 运行下载 Docker 产物，并打印合并后的 / 每分支的目标重跑命令；使用 `pnpm test:docker:timings ` 可以查看慢速分支和阶段关键路径摘要。当发布路径套件请求 Open WebUI 时，它会在 plugins/integrations 分块中运行，而不会额外占用第四个 Docker worker；只有在 openwebui-only 派发时，Open WebUI 才保留独立作业。定时 live/E2E 工作流每天运行完整的发布路径 Docker 套件。内置更新矩阵按更新目标拆分，这样重复的 npm update 和 doctor repair 过程可以与其他内置检查一起分片运行。 -本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。与宽泛的 CI 平台作用域相比，这一本地检查门控对架构边界更严格：core 生产变更会运行 core 生产和 core 测试 typecheck，以及 core lint / guards；core 纯测试变更只会运行 core 测试 typecheck 加 core lint；扩展生产变更会运行扩展生产和扩展测试 typecheck，以及扩展 lint；扩展纯测试变更会运行扩展测试 typecheck 加扩展 lint。公开的插件 SDK 或插件契约变更会扩展到扩展 typecheck，因为扩展依赖这些 core 契约，但 Vitest 扩展全量扫描属于显式测试工作。仅发布元数据的版本提升会运行有针对性的版本 / 配置 / 根依赖检查。未知的根目录 / 配置变更会以安全优先方式落到所有检查通道。 +本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，由 `scripts/check-changed.mjs` 执行。这个本地检查门控在架构边界方面比广义的 CI 平台范围更严格：core 生产变更会运行 core 生产和 core 测试 typecheck，以及 core lint/guards；core 纯测试变更只运行 core 测试 typecheck 和 core lint；扩展生产变更会运行扩展生产和扩展测试 typecheck，以及扩展 lint；扩展纯测试变更只运行扩展测试 typecheck 和扩展 lint。公开的插件 SDK 或插件契约变更会扩展到扩展 typecheck，因为扩展依赖这些 core 契约，但 Vitest 扩展全量扫描仍然属于显式测试工作。仅发布元数据的版本号提升会运行有针对性的版本 / 配置 / 根依赖检查。未知的根目录 / 配置变更会以安全优先方式退回到所有检查分支。 -在 push 上，`checks` 矩阵会添加仅 push 的 `compat-node22` 通道。在拉取请求上，该通道会被跳过，矩阵会聚焦于常规测试 / 渠道通道。 +在 push 和手动派发时，`checks-node-compat-node22` 会运行 Node 22 兼容性构建 / smoke 分支。在拉取请求中，该分支会被跳过，矩阵会专注于常规的 Node 24 测试 / 渠道分支。 -最慢的 Node 测试族会被拆分或平衡，以便每个作业都保持较小规模而不会过度占用 runner：渠道契约会作为三个加权分片运行，内置插件测试会在六个扩展 worker 之间平衡，小型 core 单元通道会成对组合，auto-reply 会以四个平衡 worker 运行，并将 reply 子树拆分为 agent-runner、dispatch 以及 commands / state-routing 分片，而 agentic Gateway 网关 / 插件配置则分布到现有的仅源码 agentic Node 作业中，而不是等待构建产物。宽范围的浏览器、QA、媒体和杂项插件测试使用它们各自专用的 Vitest 配置，而不是共享的插件兜底配置。扩展分片作业一次最多运行两组插件配置，每组只用一个 Vitest worker，并配备更大的 Node heap，这样导入密集型插件批次就不会额外制造更多 CI 作业。宽范围的 agents 通道使用共享的 Vitest 文件并行调度器，因为它主要受导入 / 调度支配，而不是由某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片独自拖尾。基于 include-pattern 的分片会使用 CI 分片名称记录耗时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分完整配置和过滤后的分片。`check-additional` 会将 package-boundary compile / canary 工作保持在一起，并将运行时拓扑架构与 gateway watch 覆盖拆开；boundary guard 分片会在一个作业内部并发运行其小型独立守卫。Gateway watch、渠道测试以及 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，在 `build-artifacts` 内并发运行，从而在保留它们旧检查名称作为轻量验证作业的同时，避免额外占用两个 Blacksmith worker 和第二条 artifact consumer 队列。 +最慢的 Node 测试族已被拆分或平衡，以便每个作业保持较小规模，同时又不会过度占用 runner：渠道契约作为三个加权分片运行，内置插件测试在六个扩展 worker 之间平衡，小型 core 单元分支成对组合，auto-reply 作为四个平衡 worker 运行，并将 reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片，而 agentic Gateway 网关 / 插件配置则分布到现有的仅源码 agentic Node 作业中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用它们各自专用的 Vitest 配置，而不是共享的插件兜底配置。扩展分片作业一次最多运行两组插件配置，每组使用一个 Vitest worker，并配备更大的 Node 堆，这样导入密集型插件批次就不会制造额外的 CI 作业。广泛的 agents 分支使用共享的 Vitest 文件并行调度器，因为它主要受导入 / 调度限制，而不是由某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享 runtime 分片拖尾。包含模式的分片会使用 CI 分片名称记录耗时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置与过滤后的分片。`check-additional` 会将包边界 compile/canary 工作保持在一起，并将运行时拓扑架构与 gateway watch 覆盖分离；边界守卫分片会在一个作业内并发运行其小型独立守卫。Gateway 网关 watch、渠道测试和 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，在 `build-artifacts` 内并发运行；这样既能保留它们原有的检查名称作为轻量验证器作业，又能避免额外两个 Blacksmith worker 和第二个产物消费者队列。 -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试通道仍会使用 SMS / call-log BuildConfig 标志编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行 debug APK 打包作业。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；它的单元测试分支仍会使用 SMS/call-log BuildConfig 标志编译该 flavor，同时避免在每次与 Android 相关的 push 上重复进行 debug APK 打包作业。 -`extension-fast` 仅限 PR，因为 push 运行已经执行完整的内置插件分片。这样既能为评审提供已变更插件的反馈，又不会在 `main` 上为 `checks-node-extensions` 已经覆盖的内容额外占用一个 Blacksmith worker。 +当同一个 PR 或 `main` 引用上有新的 push 到来时，GitHub 可能会将被替代的作业标记为 `cancelled`。除非同一引用的最新运行也失败，否则应将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已被替代后继续排队。 -当同一个 PR 或 `main` ref 上有更新的 push 到来时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则应将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但在整个工作流已被更新运行取代后不会再排队。 - -自动 CI 并发键带有版本号（`CI-v7-*`），这样 GitHub 端旧队列组中的僵尸任务就不会无限期阻塞新的 main 运行。手动完整套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行中的运行。 +自动 CI 并发键是带版本的（`CI-v7-*`），这样 GitHub 端旧队列组中的僵尸任务就不会无限期阻塞较新的 main 运行。手动完整套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行中的运行。 ## 运行器 | 运行器 | 作业 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`、快速安全作业及其聚合作业（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速 protocol / contract / bundled 检查、分片的渠道契约检查、除 lint 之外的 `check` 分片、`check-additional` 分片及其聚合作业、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke 的 preflight 也使用 GitHub 托管的 Ubuntu，这样 Blacksmith 矩阵就能更早进入队列 | +| `ubuntu-24.04` | `preflight`、快速安全作业及其聚合项（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速 protocol/contract/bundled 检查、分片的渠道契约检查、除 lint 外的 `check` 分片、`check-additional` 分片及聚合项、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，这样 Blacksmith 矩阵可以更早排队 | | `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-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 # 检查针对 origin/main...HEAD 的本地 changed-lane 分类器 -pnpm check:changed # 智能本地检查门控：按边界通道执行变更 typecheck/lint/guards +pnpm changed:lanes # 检查 origin/main...HEAD 的本地 changed-lane 分类器 +pnpm check:changed # 智能本地检查门控：按边界分支运行变更相关的 typecheck/lint/guards pnpm check # 快速本地门控：生产 tsgo + 分片 lint + 并行快速 guards pnpm check:test-types -pnpm check:timed # 相同门控，但带各阶段耗时 +pnpm check:timed # 与上述相同的门控，但带有各阶段耗时 pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # Vitest 测试 -pnpm test:changed # 低成本智能 changed Vitest 目标 +pnpm test:changed # 低成本的智能 changed Vitest 目标 pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # 文档格式 + lint + 断链检查 -pnpm build # 当 CI artifact / build-smoke 通道相关时，构建 dist -pnpm ci:timings # 汇总最近一次 origin/main push CI 运行 -pnpm ci:timings:recent # 比较最近成功的 main CI 运行 -node scripts/ci-run-timings.mjs # 汇总总耗时、排队时间和最慢的作业 -node scripts/ci-run-timings.mjs --latest-main # 忽略 issue / comment 噪声并选择 origin/main push CI -node scripts/ci-run-timings.mjs --recent 10 # 比较最近成功的 main CI 运行 +pnpm check:docs # 文档格式化 + lint + 失效链接 +pnpm build # 当 CI artifact/build-smoke 分支相关时，构建 dist +pnpm ci:timings # 汇总最新一次 origin/main push CI 运行 +pnpm ci:timings:recent # 对比最近成功的 main CI 运行 +node scripts/ci-run-timings.mjs # 汇总总耗时、排队时间和最慢作业 +node scripts/ci-run-timings.mjs --latest-main # 忽略 issue/comment 噪声，并选择 origin/main push CI +node scripts/ci-run-timings.mjs --recent 10 # 对比最近成功的 main CI 运行 pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json ``` diff --git a/docs/zh-CN/reference/RELEASING.md b/docs/zh-CN/reference/RELEASING.md index b5d67d03c..3c09bc083 100644 --- a/docs/zh-CN/reference/RELEASING.md +++ b/docs/zh-CN/reference/RELEASING.md @@ -1,161 +1,155 @@ --- read_when: - - 正在查找公开发布渠道的定义 - - 正在查找版本命名和发布节奏 + - 查找公开发布渠道的定义 + - 查找版本命名和发布节奏的说明 summary: 公开发布渠道、版本命名和发布节奏 title: 发布策略 x-i18n: - generated_at: "2026-04-26T23:58:25Z" + generated_at: "2026-04-27T00:40:12Z" model: gpt-5.4 provider: openai - source_hash: 123e9410e268f4b2a9c16acb2a4c9ff3b5184cd41f678f1a0d28751108f04bfd + source_hash: 32ec1b74f2f3277bdf92da1874625064d09f21245d99b64c183a8bd08f6d4e4a source_path: reference/RELEASING.md workflow: 15 --- -OpenClaw 有三个公开发布通道： +OpenClaw 有三个公开发布渠道： -- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest` +- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确要求时发布到 npm `latest` - beta：预发布标签，发布到 npm `beta` -- dev：`main` 的滚动最新版本 +- dev：`main` 的持续更新头部版本 ## 版本命名 - Stable 发布版本：`YYYY.M.D` - Git 标签：`vYYYY.M.D` -- Stable 修正发布版本：`YYYY.M.D-N` +- Stable 修正版发布版本：`YYYY.M.D-N` - Git 标签：`vYYYY.M.D-N` - Beta 预发布版本：`YYYY.M.D-beta.N` - Git 标签：`vYYYY.M.D-beta.N` -- 月和日不要补零 -- `latest` 表示当前已提升的 stable npm 发布版本 +- 不要对月份或日期补零 +- `latest` 表示当前已提升为正式版本的 stable npm 发布 - `beta` 表示当前 beta 安装目标 -- Stable 和 stable 修正发布默认发布到 npm `beta`；发布操作人员可以显式指定 `latest`，或者稍后将经过验证的 beta 构建提升过去 +- Stable 和 stable 修正版发布默认发布到 npm `beta`；发布操作人员可以显式指定为 `latest`，或者稍后再提升一个已验证的 beta 构建 - 每个 stable OpenClaw 发布都会同时交付 npm 包和 macOS 应用； - beta 发布通常会先验证并发布 npm/包路径，而 macOS 应用的构建/签名/公证保留给 stable，除非有明确请求 + beta 发布通常会先验证并发布 npm / package 路径，而 macOS 应用的构建 / 签名 / 公证默认保留给 stable，除非明确要求 ## 发布节奏 -- 发布采用 beta 优先流程 -- 只有在最新 beta 经过验证后，才会跟进 stable -- 维护者通常会从当前 `main` 创建的 `release/YYYY.M.D` 分支切发布， +- 发布遵循 beta 优先 +- 只有在最新 beta 完成验证后，才会继续 stable +- 维护者通常会从当前 `main` 创建 `release/YYYY.M.D` 分支来切发布， 这样发布验证和修复就不会阻塞 `main` 上的新开发 -- 如果某个 beta 标签已经推送或发布且需要修复，维护者会切下一个 `-beta.N` 标签， - 而不是删除或重建旧的 beta 标签 -- 详细的发布流程、审批、凭证和恢复说明仅对维护者开放 +- 如果某个 beta 标签已经推送或发布且需要修复，维护者会切下一个 `-beta.N` 标签，而不是删除或重建旧的 beta 标签 +- 详细的发布流程、审批、凭证和恢复说明仅供维护者使用 -## 发布预检 +## 发布前预检 -- 在发布预检前运行 `pnpm check:test-types`，这样测试 TypeScript 仍然会在更快的本地 `pnpm check` 门禁之外得到覆盖 -- 在发布预检前运行 `pnpm check:architecture`，这样更广泛的导入循环和架构边界检查会在更快的本地门禁之外保持绿色 -- 在运行 `pnpm release:check` 之前先运行 `pnpm build && pnpm ui:build`，这样打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 才会存在 -- 当你需要对候选发布进行完整的常规 CI 覆盖时，在发布批准前运行手动 `CI` workflow。手动 CI 调度会绕过变更范围限制，并强制运行 Linux Node 分片、内置插件分片、渠道契约、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n 通道。 +- 在发布前预检之前运行 `pnpm check:test-types`，以便测试 TypeScript 也能在更快的本地 `pnpm check` 检查之外得到覆盖 +- 在发布前预检之前运行 `pnpm check:architecture`，以确保更全面的导入循环和架构边界检查在更快的本地检查之外也是绿色状态 +- 在 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，以确保打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在 +- 当你需要对发布候选版本执行完整的常规 CI 覆盖时，请在批准发布前运行手动 `CI` workflow。手动触发的 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 名称、有界属性以及内容/标识符脱敏，而无需 Opik、Langfuse 或其他外部收集器。 -- 在每次带标签发布前运行 `pnpm release:check` +- 在验证发布遥测时运行 `pnpm qa:otel:smoke`。它会通过本地 OTLP / HTTP 接收器运行 QA-lab，并验证导出的 trace span 名称、有界属性以及内容 / 标识符脱敏，而不需要 Opik、Langfuse 或其他外部收集器。 +- 在每次带标签的发布之前运行 `pnpm release:check` - 发布检查现在在单独的手动 workflow 中运行： `OpenClaw Release Checks` -- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock parity gate，以及实时 Matrix 和 Telegram QA 通道。实时通道使用 `qa-live-shared` 环境；Telegram 还会使用 Convex CI 凭证租约。 -- 跨操作系统的安装和升级运行时验证由私有调用方 workflow 调度： +- `OpenClaw Release Checks` 还会在批准发布之前运行 QA Lab mock parity gate 以及实时 Matrix 和 Telegram QA 通道。实时通道使用 `qa-live-shared` 环境；Telegram 还会使用 Convex CI 凭证租约。 +- 跨操作系统的安装和升级运行时验证由私有调用方 workflow 触发： `openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`， 它会调用可复用的公开 workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- 这种拆分是有意为之：让真正的 npm 发布路径保持简短、确定性强并聚焦于产物，而较慢的实时检查留在独立通道中，这样它们就不会拖慢或阻塞发布 -- 发布检查必须从 `main` workflow ref 或 `release/YYYY.M.D` workflow ref 发起，这样 workflow 逻辑和密钥才能保持受控 +- 这种拆分是有意设计的：让真正的 npm 发布路径保持简短、可预测并聚焦于产物，而较慢的实时检查则保留在自己的通道中，以免拖慢或阻塞发布 +- 发布检查必须从 `main` workflow ref 或 `release/YYYY.M.D` workflow ref 触发，以便 workflow 逻辑和密钥保持受控 - 该 workflow 接受现有发布标签，或当前完整的 40 字符 workflow 分支提交 SHA -- 在提交 SHA 模式下，它只接受当前 workflow 分支的 HEAD；对于较旧的发布提交，请使用发布标签 -- `OpenClaw NPM Release` 的仅验证预检也接受当前完整的 40 字符 workflow 分支提交 SHA，而不要求已有推送的标签 +- 在提交 SHA 模式下，它只接受当前 workflow 分支的 HEAD；对于较早的发布提交，请使用发布标签 +- `OpenClaw NPM Release` 的仅验证预检也接受当前完整的 40 字符 workflow 分支提交 SHA，而无需已推送的标签 - 该 SHA 路径仅用于验证，不能提升为真实发布 -- 在 SHA 模式下，该 workflow 仅为包元数据检查合成 `v`；真实发布仍然需要真实的发布标签 -- 这两个 workflow 都将真实发布和提升路径保留在 GitHub 托管 runner 上，而非变更型验证路径则可以使用更大的 Blacksmith Linux runner -- 该 workflow 运行 +- 在 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 secrets + 并同时使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` workflow 密钥 - npm 发布预检不再等待单独的发布检查通道 -- 在批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - （或对应的 beta/修正标签） -- 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_*` 环境变量凭证。 -- 维护者也可以通过 GitHub Actions 中手动触发的 `NPM Telegram Beta E2E` workflow 运行同样的发布后检查。它有意仅限手动运行，不会在每次合并时执行。 -- 维护者发布自动化现在使用“先预检，再提升”的流程： + （或对应的 beta / 修正版版本），以在全新的临时前缀中验证已发布的 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` + 以便针对已发布的 npm 包验证已安装包的新手引导、Telegram 设置以及真实的 Telegram E2E，使用共享的租赁 Telegram 凭证池。本地维护者的一次性检查可以省略 Convex 变量，改为直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭证。 +- 维护者也可以通过 GitHub Actions 中的手动 `NPM Telegram Beta E2E` workflow 运行同样的发布后检查。它有意仅支持手动运行，不会在每次合并时执行。 +- 维护者发布自动化现在采用“先预检，再提升”的方式： - 真实 npm 发布必须通过成功的 npm `preflight_run_id` - - 真实 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支发起 - - stable npm 发布默认目标为 `beta` + - 真实 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 发布 + 以增强安全性，因为 `npm dist-tag add` 仍然需要 `NPM_TOKEN`，而公开仓库保持仅使用 OIDC 发布 - 公开的 `macOS Release` 仅用于验证 - - 真实的私有 mac 发布必须通过成功的私有 mac + - 真正的私有 mac 发布必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id` - - 真实发布路径会提升已准备好的产物，而不是再次重新构建它们 -- 对于像 `YYYY.M.D-N` 这样的 stable 修正发布，发布后验证器还会检查从 `YYYY.M.D` 升级到 `YYYY.M.D-N` 的同一临时前缀升级路径，这样发布修正就不会悄悄让旧的全局安装仍停留在基础 stable 负载上 -- npm 发布预检默认失败关闭，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 负载，这样我们就不会再次发布一个空的浏览器仪表盘 -- 发布后验证还会检查已发布的注册表安装是否在根级 `dist/*` 布局下包含非空的内置插件运行时依赖。若发布缺少这些依赖负载或其内容为空，则发布后验证器会失败，并且该版本不能被提升到 `latest`。 + - 真实发布路径会提升已准备好的产物，而不是再次重新构建 +- 对于像 `YYYY.M.D-N` 这样的 stable 修正版发布，发布后验证器还会检查相同临时前缀下从 `YYYY.M.D` 到 `YYYY.M.D-N` 的升级路径，以确保发布修正不会悄悄让较旧的全局安装继续停留在基础 stable 载荷上 +- npm 发布预检默认采用封闭失败策略，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 内容，否则不会通过，这样我们就不会再次发布一个空的浏览器仪表板 +- 发布后验证还会检查已发布的 registry 安装是否在根级 `dist/*` 布局下包含非空的内置插件运行时依赖。若发布时缺少这些依赖载荷或其内容为空，则发布后验证器会失败，且该版本不能被提升到 `latest`。 - `pnpm test:install:smoke` 还会对候选更新 tarball 的 npm pack `unpackedSize` 预算进行强制检查，因此安装器 e2e 能在发布路径之前捕获意外的打包膨胀 -- 如果此次发布工作涉及 CI 规划、扩展时序清单或扩展测试矩阵，请在批准前重新生成并审查来自 `.github/workflows/ci.yml` 的、由规划器负责的 `checks-node-extensions` workflow 矩阵输出，这样发布说明就不会描述一个过时的 CI 布局 -- stable macOS 发布就绪还包括更新器相关界面： - - GitHub release 最终必须带有打包后的 `.zip`、`.dmg` 和 `.dSYM.zip` +- 如果发布工作涉及 CI 规划、扩展时序清单或扩展测试矩阵，请在批准前重新生成并审查 `.github/workflows/ci.yml` 中由 planner 管理的 `checks-node-extensions` workflow 矩阵输出，以确保发布说明不会描述过时的 CI 布局 +- Stable macOS 发布就绪还包括更新器相关界面： + - GitHub release 最终必须包含打包后的 `.zip`、`.dmg` 和 `.dSYM.zip` - 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip - - 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建底线的 `CFBundleVersion` + - 打包后的应用必须保留非调试 bundle id、非空的 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion` ## NPM workflow 输入 `OpenClaw NPM Release` 接受以下由操作人员控制的输入： -- `tag`：必填发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 - `v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前完整的 +- `tag`：必填的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 + `v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前完整的 40 字符 workflow 分支提交 SHA，用于仅验证的预检 -- `preflight_only`：`true` 表示仅验证/构建/打包，`false` 表示真实发布路径 -- `preflight_run_id`：真实发布路径中必填，以便 workflow 复用成功预检运行中准备好的 tarball -- `npm_dist_tag`：发布路径的 npm 目标标签；默认值为 `beta` +- `preflight_only`：`true` 表示仅执行验证 / 构建 / 打包，`false` 表示真实发布路径 +- `preflight_run_id`：真实发布路径中必填，以便 workflow 复用成功预检运行准备好的 tarball +- `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta` `OpenClaw Release Checks` 接受以下由操作人员控制的输入： -- `ref`：现有发布标签，或从 `main` 发起时当前完整的 40 字符 `main` 提交 - SHA；若从发布分支发起，请使用现有发布标签，或当前完整的 40 字符发布分支提交 - SHA +- `ref`：现有发布标签，或从 `main` 触发时用于验证的当前完整 40 字符 `main` 提交 SHA；从发布分支触发时，请使用现有发布标签或当前完整 40 字符发布分支提交 SHA 规则： - Stable 和修正标签可以发布到 `beta` 或 `latest` - Beta 预发布标签只能发布到 `beta` -- 对于 `OpenClaw NPM Release`，完整提交 SHA 输入只在 - `preflight_only=true` 时允许 -- `OpenClaw Release Checks` 始终仅用于验证，同时也接受当前 workflow 分支提交 SHA -- 发布检查的提交 SHA 模式还要求该 SHA 必须是当前 workflow 分支 HEAD +- 对于 `OpenClaw NPM Release`，只有在 `preflight_only=true` 时才允许输入完整提交 SHA +- `OpenClaw Release Checks` 始终仅用于验证，并且也接受当前 workflow 分支提交 SHA +- 发布检查的提交 SHA 模式还要求该 SHA 是当前 workflow 分支 HEAD - 真实发布路径必须使用与预检期间相同的 `npm_dist_tag`；workflow 会在继续发布前验证该元数据 ## Stable npm 发布顺序 -在切 stable npm 发布时： +切一个 stable npm 发布时： -1. 运行 `OpenClaw NPM Release`，设置 `preflight_only=true` - - 在标签尚不存在时，你可以使用当前完整的 workflow 分支提交 - SHA，对预检 workflow 进行仅验证的 dry run -2. 对于正常的 beta 优先流程，选择 `npm_dist_tag=beta`；只有在你有意直接发布 stable 时，才选择 `latest` -3. 当你希望得到完整的常规 CI 覆盖，而不是智能范围限制的合并覆盖时，在发布 ref 上运行手动 `CI` workflow -4. 当你希望得到实时 prompt cache、QA Lab parity、Matrix 和 Telegram 覆盖时，单独使用相同的标签或完整的当前 workflow 分支提交 SHA 运行 `OpenClaw Release Checks` - - 之所以故意分开，是为了让实时覆盖保持可用，而不把长时间运行或不稳定的检查重新耦合回发布 workflow +1. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true` + - 在标签尚不存在之前，你可以使用当前完整 workflow 分支提交 SHA，对预检 workflow 进行仅验证的演练 +2. 在正常的 beta 优先流程中选择 `npm_dist_tag=beta`；只有当你明确要直接发布 stable 时才选择 `latest` +3. 当你希望获得完整的常规 CI 覆盖，而不是智能范围限定的合并覆盖时，在发布 ref 上运行手动 `CI` workflow +4. 使用相同标签，或相同的当前完整 workflow 分支提交 SHA，单独运行 `OpenClaw Release Checks`，以获得实时 prompt cache、QA Lab parity、Matrix 和 Telegram 覆盖 + - 之所以单独拆分，是为了让实时覆盖持续可用，而不必再次将长时间运行或可能不稳定的检查耦合回发布 workflow 5. 保存成功的 `preflight_run_id` -6. 再次运行 `OpenClaw NPM Release`，设置 `preflight_only=false`，并使用相同的 - `tag`、相同的 `npm_dist_tag` 以及保存的 `preflight_run_id` -7. 如果该发布先落在 `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` - workflow，将该 stable 版本从 `beta` 提升到 `latest` -8. 如果该发布有意直接发布到 `latest`，并且 `beta` - 也应立即跟进同一个 stable 构建，请使用同一个私有 workflow 将两个 dist-tag 都指向该 stable 版本，或者让其计划中的自愈同步稍后推动 `beta` + workflow 将该 stable 版本从 `beta` 提升到 `latest` +8. 如果该发布是有意直接发布到 `latest`，并且 `beta` 也应立即跟随同一 stable 构建，请使用同一个私有 workflow 将两个 dist-tag 都指向该 stable 版本，或者让其计划中的自愈同步稍后再更新 `beta` -dist-tag 变更之所以放在私有仓库中，是出于安全考虑，因为它仍然 -需要 `NPM_TOKEN`，而公开仓库保持仅使用 OIDC 发布。 +出于安全原因，dist-tag 变更位于私有仓库中，因为它仍然需要 +`NPM_TOKEN`，而公开仓库保持仅使用 OIDC 发布。 -这样既让直接发布路径有文档可查、操作可见，也让 beta 优先的提升路径同样如此。 +这样可以让直接发布路径和 beta 优先的提升路径都具备文档说明，并且对操作人员可见。 -如果维护者必须回退到本地 npm 身份验证，任何 1Password -CLI（`op`）命令都只能在专用 tmux 会话中运行。不要直接从主 agent shell 调用 `op`；把它限制在 tmux 内，可以让提示、告警和 OTP 处理保持可观察，并防止重复的主机告警。 +如果维护者必须回退到本地 npm 认证，请仅在专用 tmux 会话中运行任何 1Password +CLI（`op`）命令。不要直接在主智能体 shell 中调用 `op`；将其放在 tmux 中可以让提示、告警和 OTP 处理保持可观察，并防止重复的主机告警。 ## 公开参考资料 @@ -168,7 +162,7 @@ CLI（`op`）命令都只能在专用 tmux 会话中运行。不要直接从主 维护者会使用私有发布文档 [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) -作为实际运行手册。 +作为实际的操作手册。 ## 相关内容