openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-23 05:29:09 +00:00
parent a29b175e64
commit a313a4b290
3 changed files with 568 additions and 586 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
docs/zh-CN/ci.md
View File

@ -1,81 +1,81 @@
---
read_when:
- 你需要了解为什么某个 CI 作业运行了或没有运行。
- 你正在调试失败的 GitHub Actions 检查。
summary: CI 作业图、作用域门禁，以及本地等效命令
- 你需要了解某个 CI 作业为什么会运行，或者为什么没有运行
- 你正在调试失败的 GitHub Actions 检查
summary: CI 作业图、范围门禁，以及本地等效命令
title: CI 流水线
x-i18n:
generated_at: "2026-04-23T05:14:57Z"
generated_at: "2026-04-23T05:24:47Z"
model: gpt-5.4
provider: openai
source_hash: b3c2cf85b45405fdd5cc1d74c7cc07c4f16c3d9dcf8ca93286a0ba78ba4b6dd1
source_hash: 5c89c66204b203a39435cfc19de7b437867f2792bbfa2c3948371abde9f80e11
source_path: ci.md
workflow: 15
---
# CI 流水线
CI 会在每次推送到 `main` 以及每个拉取请求上运行。它使用智能作用域划分，在只有不相关区域发生变更时跳过高开销作业。
CI 会在每次推送到 `main` 以及每个拉取请求上运行。它使用智能范围控制，在仅有不相关区域发生变更时跳过高开销作业。
QA Lab 在主智能作用域工作流之外还有两条专用的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更、`main` 上的每夜运行以及手动触发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.4 和 Opus 4.6 智能体包。`QA-Lab - Live Telegram, Live Frontier` 工作流会在 `main` 上每夜运行以及手动触发时运行；它使用 `qa-live-shared` 环境，并为实时 Telegram 通道使用 Convex 租约。`OpenClaw Release Checks` 也会在发布批准前运行这两条 QA Lab 通道。
QA Lab 在主智能范围工作流之外拥有专用的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更和手动触发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.4 和 Opus 4.6 智能体包。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，也支持手动触发；它会将模拟 parity gate、实时 Matrix 通道和实时 Telegram 通道作为并行作业展开。实时作业使用 `qa-live-shared` 环境，而 Telegram 通道使用 Convex 租约。`OpenClaw Release Checks` 也会在发布批准前运行同样的 QA Lab 通道。
## 作业概览
| 作业 | 目的 | 运行时机 |
| 作业 | 用途 | 运行时机 |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ |
| `preflight` | 检测仅文档变更、变更作用域、变更的扩展，并构建 CI 清单 | 在所有非草稿推送和 PR 上始终运行 |
| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 在所有非草稿推送和 PR 上始终运行 |
| `security-dependency-audit` | 针对 npm 安全通告执行无依赖的生产锁文件审计 | 在所有非草稿推送和 PR 上始终运行 |
| `security-fast` | 快速安全作业的必需聚合作业 | 在所有非草稿推送和 PR 上始终运行 |
| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查，以及可复用的下游构建产物 | 与 Node 相关的变更 |
| `checks-fast-core` | 快速 Linux 正确性通道，例如内置/plugin-contract/protocol 检查 | 与 Node 相关的变更 |
| `preflight` | 检测是否仅为文档变更、变更范围、变更的扩展，并构建 CI 清单 | 始终在非草稿推送和 PR 上运行 |
| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 始终在非草稿推送和 PR 上运行 |
| `security-dependency-audit` | 针对 npm 安全公告执行无需安装依赖的生产锁文件审计 | 始终在非草稿推送和 PR 上运行 |
| `security-fast` | 快速安全作业的必需聚合作业 | 始终在非草稿推送和 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 相关的变更 |
| `checks-node-extensions` | 覆盖整个扩展套件的完整 bundled-plugin 测试分片 | 与 Node 相关的变更 |
| `checks-node-core-test` | 核心 Node 测试分片，不包含渠道、bundled、契约和扩展通道 | 与 Node 相关的变更 |
| `extension-fast` | 仅针对发生变更的 bundled plugins 的聚焦测试 | 带有扩展变更的拉取请求 |
| `check` | 分片后的主要本地门禁等效项：生产类型、lint、守卫、测试类型以及严格 smoke | 与 Node 相关的变更 |
| `check-additional` | 架构、边界、扩展表面守卫、包边界以及 gateway-watch 分片 | 与 Node 相关的变更 |
| `build-smoke` | 已构建 CLI 的 smoke 测试以及启动内存 smoke | 与 Node 相关的变更 |
| `checks` | 已构建构件渠道测试的验证器，以及仅推送时启用的 Node 22 兼容性 | 与 Node 相关的变更 |
| `check-docs` | 文档格式、lint 和坏链检查 | 文档发生变更 |
| `skills-python` | 面向 Python 支持的 Skills 的 Ruff + pytest | 与 Python Skills 相关的变更 |
| `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 相关的变更 |
| `macos-node` | 使用共享已构建产物的 macOS TypeScript 测试通道 | 与 macOS 相关的变更 |
| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 |
| `android` | 两种 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的变更 |
| `android` | 两个 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 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`、仅 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`、仅 PR 运行的 `extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。
作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。
CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但它们本身不会强制触发 Windows、Android 或 macOS 原生构建；这些平台通道仍然只针对平台源码变更启用。
Windows Node 检查的作用域限定在 Windows 专用的进程/路径包装器、npm/pnpm/UI 运行器辅助工具、包管理器配置，以及执行该通道的 CI 工作流表面；不相关的源码、插件、安装 smoke 和仅测试变更仍然留在 Linux Node 通道中，因此不会为了已由常规测试分片覆盖的内容占用一个 16 vCPU 的 Windows worker。
单独的 `install-smoke` 工作流会通过它自己的 `preflight` 作业复用同一个作用域脚本。它会基于更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/安装 smoke 会在安装、打包、与容器相关的变更、内置扩展生产变更，以及 Docker smoke 作业所覆盖的 core plugin/channel/Gateway 网关/插件 SDK 表面发生变化时运行。仅测试和仅文档编辑不会占用 Docker worker。它的 QR 包 smoke 会强制 Docker `pnpm install` 层重新运行，同时保留 BuildKit 的 pnpm store 缓存，因此仍会覆盖安装流程，而不必在每次运行时重新下载依赖。它的 gateway-network e2e 会复用该作业前面构建的运行时镜像，因此增加了真实的容器到容器 WebSocket 覆盖，而无需再增加一次 Docker 构建。本地 `test:docker:all` 会预构建一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，并在 E2E 容器 smoke 运行器之间复用；可复用的 live/E2E 工作流也采用同样的模式，在 Docker 矩阵之前先构建并推送一个带 SHA 标签的 GHCR Docker E2E 镜像，然后以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行矩阵。QR 和 installer Docker 测试保留各自以安装为重点的 Dockerfile。单独的 `docker-e2e-fast` 作业会在 120 秒命令超时限制下运行有界的内置插件 Docker 配置：setup-entry 依赖修复加上合成的 bundled-loader 故障隔离。完整的内置更新/渠道矩阵仍然是手动/完整套件，因为它会执行多次真实的 npm update 和 doctor 修复流程。
范围逻辑位于 `scripts/ci-changed-scope.mjs` 中，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。
CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但仅凭这些编辑本身不会强制触发 Windows、Android 或 macOS 原生构建；这些平台通道仍然只会在对应平台源码发生变更时运行。
Windows Node 检查的范围仅限于 Windows 专用的进程/路径包装器、npm/pnpm/UI 运行器辅助工具、包管理器配置，以及执行该通道的 CI 工作流表面；不相关的源码、plugin、安装 smoke 和仅测试类变更仍然保留在 Linux Node 通道中，这样它们就不会为已经由常规测试分片覆盖的内容占用一个 16 vCPU 的 Windows worker。
独立的 `install-smoke` 工作流通过它自己的 `preflight` 作业复用同一个范围脚本。它根据更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/安装 smoke 会针对安装、打包、容器相关变更、bundled extension 生产代码变更，以及 Docker smoke 作业所覆盖的核心 plugin/channel/Gateway 网关/插件 SDK 表面运行。仅测试和仅文档编辑不会占用 Docker worker。它的 QR 包 smoke 会强制 Docker 的 `pnpm install` 层重新运行，同时保留 BuildKit 的 pnpm store 缓存，因此它仍然能测试安装过程，而不必在每次运行时重新下载依赖。它的 gateway-network e2e 会复用该作业中先前构建的运行时镜像，因此在不新增 Docker 构建的前提下增加了真实的容器到容器 WebSocket 覆盖。本地 `test:docker:all` 会预构建一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，并在 E2E 容器 smoke 运行器之间复用它；可复用的 live/E2E 工作流也遵循相同模式，在 Docker 矩阵之前构建并推送一个带 SHA 标签的 GHCR Docker E2E 镜像，然后在设置了 `OPENCLAW_SKIP_DOCKER_BUILD=1` 的情况下运行该矩阵。QR 和安装器 Docker 测试保留了它们各自以安装为重点的 Dockerfile。另一个独立的 `docker-e2e-fast` 作业会在 120 秒命令超时限制下运行受限的 bundled-plugin Docker 配置：setup-entry 依赖修复加上 synthetic bundled-loader 故障隔离。完整的 bundled 更新/渠道矩阵仍然保留为手动/完整套件，因为它会重复执行真实的 npm update 和 doctor 修复流程。
本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界方面比宽泛的 CI 平台作用域更严格：core 生产变更会运行 core 生产 typecheck 加 core 测试，core 仅测试变更只运行 core 测试 typecheck/测试，扩展生产变更会运行扩展生产 typecheck 加扩展测试，而扩展仅测试变更只运行扩展测试 typecheck/测试。公开的插件 SDK 或 plugin-contract 变更会扩大到扩展验证，因为扩展依赖这些核心契约。仅发布元数据的版本号变更会运行有针对性的版本/配置/root 依赖检查。未知的 root/配置变更会以保守方式回退到所有通道。
本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs` 中，并由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界方面比宽泛的 CI 平台范围更严格：核心生产代码变更会运行 core prod typecheck 加 core tests，核心仅测试类变更只会运行 core test typecheck/tests，扩展生产代码变更会运行 extension prod typecheck 加 extension tests，而扩展仅测试类变更只会运行 extension test typecheck/tests。公共插件 SDK 或 plugin-contract 变更会扩大到扩展验证，因为扩展依赖这些核心契约。仅包含发布元数据的版本号变更会运行有针对性的 version/config/root-dependency 检查。未知的根目录/配置变更会安全地退回到所有通道。
在推送时，`checks` 矩阵会增加仅推送启用的 `compat-node22` 通道。在拉取请求上，这个通道会被跳过，矩阵仍专注于常规测试/渠道通道。
在 push 上，`checks` 矩阵会增加仅在 push 上运行的 `compat-node22` 通道。在拉取请求上，这个通道会被跳过，矩阵只聚焦于常规测试/渠道通道。
最慢的 Node 测试家族已经被拆分或平衡，因此每个作业都保持较小规模：渠道契约将 registry 和 core 覆盖拆成总计六个加权分片，内置插件测试在六个扩展 worker 之间平衡，自动回复以三个平衡 worker 运行而不是六个很小的 worker，而 agentic Gateway 网关/plugin 配置会分散到现有的仅源码 agentic Node 作业中，而不是等待构建产物。广泛的 browser、QA、media 和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。宽泛的 agents 通道使用共享的 Vitest 文件级并行调度器，因为它主要受 import/调度影响，而不是由单个慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享 runtime 分片成为尾部瓶颈。`check-additional` 将 package-boundary compile/canary 工作保持在一起，并将 runtime topology 架构与 gateway watch 覆盖分开；边界守卫分片会在一个作业内部并发运行其体量较小且彼此独立的守卫。Gateway 网关 watch、渠道测试以及 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，在 `build-artifacts` 内部并发运行；这样既保留了它们原有的检查名称作为轻量级验证作业，又避免了额外两个 Blacksmith worker 和第二个构建产物消费者队列。
Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；它的单元测试通道仍会在启用 SMS/通话记录 BuildConfig 标志的情况下编译该 flavor，同时避免在每次与 Android 相关的推送中重复执行 debug APK 打包作业。
`extension-fast` 仅在 PR 上运行，因为 push 已经会执行完整的内置插件分片。这样可以在评审时保留已变更插件的反馈，同时避免在 `main` 上为 `checks-node-extensions` 已经覆盖的内容额外占用一个 Blacksmith worker。
最慢的 Node 测试族已被拆分或平衡，因此每个作业都保持较小规模：渠道契约将注册表和核心覆盖拆分为总计六个加权分片，bundled plugin 测试在六个扩展 worker 间平衡分布，auto-reply 以三个平衡 worker 运行，而不是六个过小的 worker，agentic Gateway 网关/plugin 配置则分散到现有的仅源码 agentic Node 作业中，而不是等待已构建产物。广泛的浏览器、QA、媒体和杂项 plugin 测试使用各自专用的 Vitest 配置，而不是共享的 plugin 通用配置。广泛的 agents 通道使用共享的 Vitest 文件并行调度器，因为它主要受导入/调度影响，而不是由某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片承担尾部耗时。`check-additional` 会把 package-boundary compile/canary 工作放在一起，并将运行时拓扑架构与 gateway watch 覆盖分开；边界守卫分片会在一个作业内并发运行其较小且彼此独立的守卫。Gateway 网关 watch、渠道测试以及 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，在 `build-artifacts` 内并发运行，保留它们原有的检查名称作为轻量校验作业，同时避免额外占用两个 Blacksmith worker 和第二个产物消费者队列。
Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。third-party flavor 没有单独的 source set 或 manifest；它的单元测试通道仍会使用 SMS/通话日志 BuildConfig 标志编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行 debug APK 打包作业。
`extension-fast` 仅在 PR 上运行，因为 push 已经会执行完整的 bundled plugin 分片。这样既能为评审提供已变更 plugin 的反馈，也不会在 `main` 上为 `checks-node-extensions` 已经覆盖的内容额外占用一个 Blacksmith worker。
当同一个 PR 或 `main` 引用上有较新的推送到达时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一引用上的最新运行也失败，否则应将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会正常报告分片失败，但不会在整个工作流已经被更新版本取代后继续排队。
CI 并发键带有版本号（`CI-v7-*`），这样 GitHub 端旧队列组中的僵尸任务就不会无限期阻塞新的 `main` 运行。
当同一个 PR 或 `main` 引用上有新的 push 到达时，GitHub 可能会将被替代的作业标记为 `cancelled`。除非同一引用的最新运行也失败，否则应将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已经被替代后继续排队。
CI 并发键已进行版本化（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸任务不会无限期阻塞较新的 main 运行。
## 运行器
| 运行器 | 作业 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 的排队时间成本高于节省 |
| `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 测试分片、bundled plugin 测试分片、`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它仍然对 CPU 足够敏感，以至于 8 vCPU 节省下来的成本不如带来的损失；`install-smoke` 的 Docker 构建，其中 32 vCPU 的排队时间带来的成本不如收益 |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 会回退到 `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 会回退到 `macos-latest` |
@ -83,18 +83,18 @@ CI 并发键带有版本号（`CI-v7-*`），这样 GitHub 端旧队列组中的
## 本地等效命令
```bash
pnpm changed:lanes # 检查本地针对 origin/main...HEAD 的 changed-lane 分类器
pnpm check:changed # 智能本地门禁：按边界通道运行变更范围内的 typecheck/lint/测试
pnpm changed:lanes # 检查针对 origin/main...HEAD 的本地 changed-lane 分类器
pnpm check:changed # 智能本地门禁：按边界通道运行变更范围内的 typecheck/lint/tests
pnpm check # 快速本地门禁：生产 tsgo + 分片 lint + 并行快速守卫
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:channels
pnpm test:contracts:channels
pnpm check:docs # 文档格式 + lint + 坏链检查
pnpm build # 当 CI 构建产物/build-smoke 通道相关时，构建 dist
node scripts/ci-run-timings.mjs <run-id> # 汇总总耗时、排队时间以及最慢的作业
pnpm check:docs # 文档格式 + lint + 失效链接
pnpm build # 当 CI 的 artifact/build-smoke 通道相关时，构建 dist
node scripts/ci-run-timings.mjs <run-id> # 汇总总耗时、排队时间和最慢的作业
```

863
docs/zh-CN/help/testing.md
View File

File diff suppressed because it is too large Load Diff

195
docs/zh-CN/reference/RELEASING.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 查找公开发布渠道的定义
- 查找版本命名和发布节奏
- 正在查找公开发布渠道的定义
- 正在查找版本命名和发布节奏
summary: 公开发布渠道、版本命名和发布节奏
title: 发布策略
x-i18n:
generated_at: "2026-04-23T05:14:53Z"
generated_at: "2026-04-23T05:24:49Z"
model: gpt-5.4
provider: openai
source_hash: edb86d97a37e400a4041f1e087c90d9a4f26087cc5da5c37d11f7ca58dba9404
source_hash: 979fd30ec717e107858ff812ef4b46060b9a00a0b5a3c23085d95b8fb81723b8
source_path: reference/RELEASING.md
workflow: 15
---
@ -17,170 +17,137 @@ x-i18n:
OpenClaw 有三个公开发布渠道：
- stable：带标签的发布，默认发布到 npm `beta`，或在明确指定时发布到 npm `latest`
- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest`
- beta：预发布标签，发布到 npm `beta`
- dev：`main` 的持续更新头部版本
## 版本命名
- 稳定版发布版本：`YYYY.M.D`
- stable 发布版本：`YYYY.M.D`
- Git 标签：`vYYYY.M.D`
- 稳定版修正版发布版本：`YYYY.M.D-N`
- stable 修正版发布版本：`YYYY.M.D-N`
- Git 标签：`vYYYY.M.D-N`
- Beta 预发布版本：`YYYY.M.D-beta.N`
- beta 预发布版本：`YYYY.M.D-beta.N`
- Git 标签：`vYYYY.M.D-beta.N`
- 月和日不要补零
- `latest` 表示当前已提升的稳定版 npm 发布
- 不要为月份或日期补零
- `latest` 表示当前已提升为正式版的 stable npm 发布
- `beta` 表示当前 beta 安装目标
- 稳定版和稳定版修正版默认发布到 npm `beta`；发布操作人员可以明确指定目标为 `latest`，或者稍后再将已验证的 beta 构建提升过去
- 每个稳定版 OpenClaw 发布都会同时交付 npm 包和 macOS 应用；
beta 发布通常会先验证并发布 npm/package 路径，而 mac 应用的构建 / 签名 / 公证则保留给稳定版，除非有明确要求
- stable 和 stable 修正版默认发布到 npm `beta`；发布操作人员可以显式指定 `latest`，或者在之后将经过验证的 beta 构建提升上去
- 每个 stable OpenClaw 发布都会同时交付 npm 包和 macOS 应用；
beta 发布通常会先验证并发布 npm/package 路径，而 mac 应用的构建 / 签名 / 公证默认保留给 stable，除非明确要求
## 发布节奏
- 发布先走 beta
- 只有在最新 beta 完成验证后，才会跟进 stable
- 发布采用 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 已存在
- 每次带标签的发布前都要运行 `pnpm release:check`
- 在发布前检查前运行 `pnpm check:test-types`，这样测试 TypeScript 仍然会被覆盖，而不只依赖更快的本地 `pnpm check` 门禁
- 在发布前检查前运行 `pnpm check:architecture`，这样更广泛的导入环和架构边界检查会在更快的本地门禁之外保持通过
- 在 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，这样打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 都会存在
- 每次带标签发布前都运行 `pnpm release:check`
- 发布检查现在在单独的手动工作流中运行：
`OpenClaw Release Checks`
- `OpenClaw Release Checks` 还会在发布审批前运行 QA Lab 模拟一致性门槛和实时
Telegram QA 通道。实时通道使用
`qa-live-shared` 环境和 Convex CI 凭证租约。
- 跨操作系统的安装和升级运行时验证由私有调用方工作流
`openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`
发起，该工作流会调用可复用的公开工作流
- `OpenClaw Release Checks` 还会在发布审批前运行 QA Lab mock 一致性门禁，以及实时的 Matrix 和 Telegram QA 通道。实时通道使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭证租约。
- 跨操作系统的安装与升级运行时验证由私有调用方工作流分发：
`openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`，
它会调用可复用的公开工作流
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 这种拆分是有意为之：让真实的 npm 发布路径保持简短、
可预测且聚焦产物，而较慢的实时检查保留在它们自己的通道中，
这样就不会拖慢或阻塞发布
- 发布检查必须从 `main` 工作流引用或
- 这种拆分是刻意设计的：让真实的 npm 发布路径保持简短、确定性强，并聚焦于产物；而较慢的实时检查放在各自独立的通道中，这样它们不会拖慢或阻塞发布
- 发布检查必须从 `main` 工作流引用，或从
`release/YYYY.M.D` 工作流引用发起，这样工作流逻辑和密钥才能保持受控
- 该工作流接受已有的发布标签，或当前完整的
40 字符工作流分支提交 SHA
- 在提交 SHA 模式下，它只接受当前工作流分支的 HEAD；较旧的发布提交请使用
发布标签
- `OpenClaw NPM Release` 的仅验证预检也接受当前完整的
40 字符工作流分支提交 SHA，无需先推送标签
- 该工作流接受现有发布标签，或当前完整的 40 位工作流分支提交 SHA
- 在提交 SHA 模式下，它只接受当前工作流分支的 HEAD；较旧的发布提交请使用发布标签
- `OpenClaw NPM Release` 的仅验证前检查也接受当前完整的 40 位工作流分支提交 SHA，而不要求已有推送的标签
- 该 SHA 路径仅用于验证，不能提升为真实发布
- 在 SHA 模式下，工作流只会为包元数据检查临时生成
`v<package.json version>`；真实发布仍然需要真实的发布标签
- 这两个工作流都会将真实发布和提升路径保留在 GitHub 托管的
runner 上，而非变更性的验证路径则可以使用更大的
Blacksmith Linux runner
- 在 SHA 模式下，工作流只会为包元数据检查合成 `v<package.json version>`；真实发布仍然需要真实的发布标签
- 两个工作流都会将真实发布和提升路径保留在 GitHub 托管的 runner 上，而不修改状态的验证路径则可以使用更大的 Blacksmith Linux runner
- 该工作流会运行
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
并同时使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 工作流密钥
- npm 发布预检不再等待单独的发布检查通道
并使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 两个工作流密钥
- npm 发布前检查不再等待单独的发布检查通道
- 在审批前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
（或对应的 beta / 修正版标签）
（或匹配的 beta / 修正标签）
- npm 发布后，运行
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
（或对应的 beta / 修正版版本），以在新的临时前缀中验证已发布的注册表安装路径
- 维护者发布自动化现在采用先预检后提升的方式：
- 真实 npm 发布必须通过成功的 npm `preflight_run_id`
- 真实 npm 发布必须从与成功预检运行相同的 `main` 或
`release/YYYY.M.D` 分支发起
- 稳定版 npm 发布默认使用 `beta`
- 稳定版 npm 发布可以通过工作流输入明确指定目标为 `latest`
（或匹配的 beta / 修正版本），以在全新的临时前缀中验证已发布的注册表安装路径
- 维护者发布自动化现在采用“先前检查，再提升”：
- 真实的 npm 发布必须通过成功的 npm `preflight_run_id`
- 真实的 npm 发布必须从与成功前检查运行相同的 `main` 或 `release/YYYY.M.D` 分支发起
- stable npm 发布默认使用 `beta`
- stable npm 发布可以通过工作流输入显式指定 `latest`
- 基于令牌的 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
`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/` 负载，
以避免我们再次发布空的浏览器仪表盘
- `pnpm test:install:smoke` 还会对候选更新 tarball 的 npm pack `unpackedSize` 预算执行强制检查，
这样安装器 e2e 就能在发布路径之前捕获意外的打包膨胀
- 如果发布工作涉及 CI 规划、扩展 timing 清单或
扩展测试矩阵，请在审批前重新生成并审查
来自 `.github/workflows/ci.yml` 的、由 planner 负责的
`checks-node-extensions` 工作流矩阵输出，
以避免发布说明描述的是过时的 CI 布局
- 稳定版 macOS 发布就绪还包括更新器相关界面：
- 真实发布路径会提升已准备好的产物，而不是再次重新构建它们
- 对于 `YYYY.M.D-N` 这样的 stable 修正版发布，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径，这样发布修正就不会悄悄让旧的全局安装仍停留在基础 stable 负载上
- npm 发布前检查采用默认失败关闭策略，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 载荷，这样我们就不会再次发布空的浏览器仪表板
- `pnpm test:install:smoke` 还会对候选更新 tarball 的 npm pack `unpackedSize` 预算进行强制检查，因此安装器端到端流程会在发布路径之前捕获意外的打包膨胀
- 如果本次发布工作涉及 CI 规划、扩展时序清单或扩展测试矩阵，请在批准前重新生成并审查来自 `.github/workflows/ci.yml` 的、由 planner 负责的 `checks-node-extensions` 工作流矩阵输出，这样发布说明就不会描述过时的 CI 布局
- stable macOS 发布准备情况还包括更新器相关表面：
- GitHub 发布最终必须包含打包后的 `.zip`、`.dmg` 和 `.dSYM.zip`
- 发布后，`main` 上的 `appcast.xml` 必须指向新的稳定版 zip
- 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed
URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion`
- 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip
- 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed URL，以及不低于该发布版本规范 Sparkle build 下限的 `CFBundleVersion`
## NPM 工作流输入
`OpenClaw NPM Release` 接受以下由操作人员控制的输入：
- `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`
- `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 Checks` 接受以下由操作人员控制的输入：
- `ref`：已有发布标签，或从 `main` 发起时要验证的当前完整
40 字符 `main` 提交 SHA；如果从发布分支发起，请使用已有的发布标签
或当前完整的 40 字符发布分支提交 SHA
- `ref`：现有发布标签，或从 `main` 发起时用于验证的当前完整 40 位 `main` 提交
SHA；如果从发布分支发起，则使用现有发布标签，或当前完整的 40 位发布分支提交
SHA
规则：
- 稳定版和修正版标签可以发布到 `beta` 或 `latest`
- Beta 预发布标签只能发布到 `beta`
- stable 和修正标签可以发布到 `beta` 或 `latest`
- beta 预发布标签只能发布到 `beta`
- 对于 `OpenClaw NPM Release`，只有在
`preflight_only=true` 时才允许使用完整提交 SHA 作为输入
- `OpenClaw Release Checks` 始终仅用于验证，也接受
当前工作流分支提交 SHA
- 发布检查的提交 SHA 模式还要求必须是当前工作流分支 HEAD
- 真实发布路径必须使用与预检期间相同的 `npm_dist_tag`；
工作流会在继续发布前验证该元数据
- `OpenClaw Release Checks` 始终仅用于验证，也接受当前工作流分支提交 SHA
- 发布检查的提交 SHA 模式也要求当前工作流分支 HEAD
- 真实发布路径必须使用与前检查相同的 `npm_dist_tag`；工作流会在继续发布前验证该元数据
## 稳定版 npm 发布顺序
## Stable npm 发布顺序
在切稳定版 npm 发布时：
切 stable npm 发布时：
1. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true`
- 在标签尚不存在时，你可以使用当前完整的工作流分支提交
SHA，对预检工作流进行仅验证的试运行
2. 按照正常的先 beta 后 stable 流程选择 `npm_dist_tag=beta`，或者仅在你有意直接发布稳定版时选择 `latest`
3. 单独运行 `OpenClaw Release Checks`，使用相同的标签，或者在你想获得实时 prompt cache、
QA Lab 一致性和实时 Telegram 覆盖时，使用当前完整的工作流分支提交 SHA
- 之所以刻意分离，是为了在不重新耦合长时间运行或不稳定检查到发布工作流的前提下，
仍然保留实时覆盖能力
- 在标签尚不存在时，你可以使用当前完整工作流分支提交
SHA，对前检查工作流进行仅验证的试运行
2. 选择 `npm_dist_tag=beta` 用于正常的 beta 优先流程；只有在你明确想直接发布 stable 时，才选择 `latest`
3. 单独运行 `OpenClaw Release Checks`，使用相同标签，或在你希望获得实时 prompt cache、
QA Lab 一致性、Matrix 和 Telegram 覆盖时，使用当前完整工作流分支提交 SHA
- 这样刻意拆开，是为了让实时覆盖保持可用，而不会将长时间运行或不稳定的检查重新耦合到发布工作流中
4. 保存成功的 `preflight_run_id`
5. 再次运行 `OpenClaw NPM Release`，并设置 `preflight_only=false`，同时使用相同的
`tag`、相同的 `npm_dist_tag`，以及已保存的 `preflight_run_id`
5. 再次运行 `OpenClaw NPM Release`，并设置 `preflight_only=false`、相同的
`tag`、相同的 `npm_dist_tag`，以及保存的 `preflight_run_id`
6. 如果该发布先落在 `beta`，请使用私有的
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
工作流，将该稳定版从 `beta` 提升到 `latest`
7. 如果该发布是有意直接发布到 `latest`，并且 `beta`
也应立即跟随同一个稳定版构建，请使用同一个私有工作流
将两个 dist-tag 都指向该稳定版，或者交由其定时
自愈同步稍后再推动 `beta`
工作流，将该 stable 版本从 `beta` 提升到 `latest`
7. 如果该发布有意直接发布到 `latest`，并且 `beta`
也应立即跟随同一个 stable 构建，请使用同一个私有工作流让两个 dist-tag 都指向该 stable 版本，或者让其计划中的自愈同步稍后移动 `beta`
dist-tag 变更之所以放在私有仓库中，是出于安全考虑，因为它仍然
需要 `NPM_TOKEN`，而公开仓库保留仅 OIDC 的发布方式。
出于安全原因，dist-tag 变更位于私有仓库中，因为它仍然
需要 `NPM_TOKEN`，而公开仓库保持仅使用 OIDC 发布。
这样既记录了直接发布路径，也记录了先 beta 再提升的路径，并且两者
都对操作人员可见。
这样可以让直接发布路径和 beta 优先提升路径都保持文档化，并且对操作人员可见。
## 公开参考
@ -193,4 +160,4 @@ dist-tag 变更之所以放在私有仓库中，是出于安全考虑，因为
维护者会使用私有发布文档
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
作为实际运行手册。
作为实际操作手册。