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-20 14:17:45 +00:00
parent 3b918471b9
commit 85baaa0209
4 changed files with 527 additions and 527 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,76 +1,77 @@
---
read_when:
- 你需要了解某个 CI 作业为什么运行了或没有运行
- 你需要了解为什么某个 CI 作业运行了或没有运行
- 你正在调试失败的 GitHub Actions 检查
summary: CI 作业图、作用域门槛，以及本地等效命令
summary: CI 作业图、作用域门禁，以及本地等效命令
title: CI 流水线
x-i18n:
generated_at: "2026-04-20T12:57:37Z"
generated_at: "2026-04-20T14:13:24Z"
model: gpt-5.4
provider: openai
source_hash: b128a0112dbaa6449b4f2ace018939f552f99929044732d18d5bea8b46695815
source_hash: dd4ffb6986739ee6f4fca6e8b1f40baee7e47a8387e8d06c722881ebe78b4766
source_path: ci.md
workflow: 15
---
# CI 流水线
CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能作用域判断，在只有不相关区域发生变更时跳过高开销作业。
CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能作用域判断，在仅有无关区域变更时跳过高开销作业。
## 作业概览
| 作业 | 用途 | 运行时机 |
| ------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------- |
| `preflight` | 检测是否仅有文档变更、已变更的作用域、已变更的扩展，并构建 CI 清单 | 在所有非草稿推送和 PR 上始终运行 |
| `security-fast` | 私钥检测、通过 `zizmor` 进行工作流审计、生产依赖审计 | 在所有非草稿推送和 PR 上始终运行 |
| `build-artifacts` | 构建 `dist/` 和 Control UI 一次，并上传供下游作业复用的构建产物 | 与 Node 相关的变更 |
| `checks-fast-core` | 快速 Linux 正确性检查路径，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 |
| `checks-node-extensions` | 针对扩展套件运行完整的 bundled-plugin 测试分片 | 与 Node 相关的变更 |
| `checks-node-core-test` | Core Node 测试分片，不包括 channel、bundled、contract 和 extension 路径 | 与 Node 相关的变更 |
| `extension-fast` | 仅针对已变更 bundled plugin 的聚焦测试 | 检测到 extension 变更时 |
| `check` | CI 中的主要本地门槛：`pnpm check` 加 `pnpm build:strict-smoke` | 与 Node 相关的变更 |
| `check-additional` | 架构、边界、导入环守卫，以及 Gateway 网关 watch 回归测试 | 与 Node 相关的变更 |
| `build-smoke` | 已构建 CLI 的冒烟测试和启动内存冒烟测试 | 与 Node 相关的变更 |
| `checks` | 其余 Linux Node 路径：channel 测试以及仅在 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-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 |
| `android` | Android 构建和测试矩阵 | 与 Android 相关的变更 |
| 作业 | 用途 | 运行时机 |
| ------------------------ | ---------------------------------------------------------------------------------------- | ------------------------ |
| `preflight` | 检测是否仅为文档变更、变更的作用域、变更的扩展，并构建 CI 清单 | 在所有非草稿推送和 PR 中始终运行 |
| `security-fast` | 私钥检测、通过 `zizmor` 进行工作流审计、生产依赖审计 | 在所有非草稿推送和 PR 中始终运行 |
| `build-artifacts` | 构建 `dist/` 和 Control UI 一次，并上传供下游作业复用的构建产物 | 与 Node 相关的变更 |
| `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 |
| `checks-node-extensions` | 针对整个扩展套件运行完整的 bundled-plugin 测试分片 | 与 Node 相关的变更 |
| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、bundled、contract 和扩展通道 | 与 Node 相关的变更 |
| `extension-fast` | 仅针对已变更 bundled 插件的聚焦测试 | 检测到扩展变更时 |
| `check` | CI 中的主要本地门禁：`pnpm check`、`pnpm check:test-types` 和 `pnpm build:strict-smoke` | 与 Node 相关的变更 |
| `check-additional` | 架构、边界、导入环守卫，以及 Gateway 监视回归测试 harness | 与 Node 相关的变更 |
| `build-smoke` | 已构建 CLI 的 smoke 测试以及启动内存 smoke 测试 | 与 Node 相关的变更 |
| `checks` | 剩余的 Linux Node 通道：渠道测试和仅在推送时运行的 Node 22 兼容性 | 与 Node 相关的变更 |
| `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` | Android 构建和测试矩阵 | 与 Android 相关的变更 |
## 快速失败顺序
作业的排列顺序经过设计，让低成本检查先失败，再决定是否运行高成本作业：
作业的排序方式是让低成本检查先失败，再运行高成本作业：
1. `preflight` 决定哪些路径会实际存在。`docs-scope` 和 `changed-scope` 逻辑是该作业内部的步骤，不是独立作业。
1. `preflight` 决定究竟存在哪些通道。`docs-scope` 和 `changed-scope` 逻辑是该作业中的步骤，不是独立作业。
2. `security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而不会等待更重的构建产物和平台矩阵作业。
3. `build-artifacts` 会与快速 Linux 路径并行，这样下游使用方可以在共享构建就绪后立即启动。
4. 更重的平台和运行时路径随后展开：`checks-fast-core`、`checks-node-extensions`、`checks-node-core-test`、`extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。
3. `build-artifacts` 会与快速 Linux 通道并行运行，这样下游消费者可以在共享构建就绪后立即开始。
4. 更重的平台和运行时通道随后展开：`checks-fast-core`、`checks-node-extensions`、`checks-node-core-test`、`extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。
作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。
单独的 `install-smoke` 工作流也通过它自己的 `preflight` 作业复用同一个作用域脚本。它根据更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/安装冒烟测试只会在安装、打包和容器相关变更时运行。
独立的 `install-smoke` 工作流通过其自己的 `preflight` 作业复用同一个作用域脚本。它会根据更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/安装 smoke 仅会在与安装、打包和容器相关的变更时运行。
在 push 上，`checks` 矩阵会添加仅在 push 时运行的 `compat-node22` 路径。在拉取请求上，该路径会被跳过，矩阵会保持聚焦于常规测试/channel 路径。
在推送时，`checks` 矩阵会增加仅在推送时运行的 `compat-node22` 通道。在拉取请求中，该通道会被跳过，矩阵会聚焦于常规测试/渠道通道。
## 运行器
| 运行器 | 作业 |
| 运行器 | 作业 |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `blacksmith-16vcpu-ubuntu-2404` | `preflight`、`security-fast`、`build-artifacts`、Linux 检查、文档检查、Python Skills、`android` |
| `blacksmith-32vcpu-windows-2025` | `checks-windows` |
| `macos-latest` | `macos-node`、`macos-swift` |
| `blacksmith-16vcpu-ubuntu-2404` | `preflight`、`security-fast`、`build-artifacts`、Linux 检查、文档检查、Python Skills、`android` |
| `blacksmith-32vcpu-windows-2025` | `checks-windows` |
| `macos-latest` | `macos-node`、`macos-swift` |
## 本地等效命令
```bash
pnpm check # 快速本地门槛：project-reference tsgo + 分片 lint + 并行快速守卫
pnpm check:timed # 相同门槛，但带有各阶段耗时
pnpm check # 快速本地门禁：生产 tsgo + 分片 lint + 并行快速守卫
pnpm check:test-types
pnpm check:timed # 相同门禁，但带有各阶段耗时
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test # vitest 测试
pnpm test:channels
pnpm check:docs # 文档格式 + lint + 失效链接
pnpm build # 当 CI 的 artifact/build-smoke 路径相关时，构建 dist
pnpm build # 当 CI 构建产物 / build-smoke 通道相关时，构建 dist
```

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

File diff suppressed because it is too large Load Diff

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

@ -5,19 +5,19 @@ read_when:
summary: 公开发布渠道、版本命名和发布节奏
title: 发布策略
x-i18n:
generated_at: "2026-04-20T12:30:01Z"
generated_at: "2026-04-20T14:13:22Z"
model: gpt-5.4
provider: openai
source_hash: 1ce04bd255ae5f13ff5088414c87e865fe56a8a0d0bf6ef6d8d84cb07ef65f18
source_hash: 281b3fd1764c60cb35a25a12c338595020d7c04bcb662e96c4131193a0607537
source_path: reference/RELEASING.md
workflow: 15
---
# 发布策略
OpenClaw 有三个公开发布渠道：
OpenClaw 有三个公开发布通道：
- stable：带标签的发布版本，默认发布到 npm `beta`，或者在明确指定时发布到 npm `latest`
- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确要求时发布到 npm `latest`
- beta：预发布标签，发布到 npm `beta`
- dev：`main` 的持续更新头部版本
@ -29,113 +29,115 @@ OpenClaw 有三个公开发布渠道：
- 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 构建提升过去
- 每个 OpenClaw 发布都会同时交付 npm 包和 macOS 应用
## 发布节奏
- 发布采用 beta 优先流程
- 只有在最新 beta 验证通过后，才会跟进 stable
- 详细发布流程、审批、凭证和恢复说明仅对维护者开放
- 只有在最新 beta 完成验证后，才会跟进 stable
- 详细的发布流程、审批、凭证和恢复说明仅面向维护者
## 发布前检查
- 在进行发布前检查之前运行 `pnpm check:architecture`，以确保更全面的导入环和架构边界检查在更快的本地 gate 之外也是绿色状态
- 在运行 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，以确保打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在
- 每次带标签的发布之前都要运行 `pnpm release:check`
- 发布检查现在在一个独立的手动工作流中运行：
- 在发布前检查前运行 `pnpm check:test-types`，以便在更快的本地 `pnpm check` 门禁之外，仍然覆盖测试 TypeScript
- 在发布前检查前运行 `pnpm check:architecture`，以便在更快的本地门禁之外，确保更广泛的导入环和架构边界检查通过
- 在 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，以便打包校验步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在
- 每次带标签发布前都要运行 `pnpm release:check`
- 发布检查现在在单独的手动工作流中运行：
`OpenClaw Release Checks`
- 跨操作系统的安装和升级运行时验证由私有调用方工作流分发：
- 跨操作系统的安装与升级运行时验证由私有调用方工作流分发：
`openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`，
它会调用可复用的公开工作流
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 这种拆分是有意的：让真正的 npm 发布路径保持简短、确定性强且聚焦产物，同时将较慢的实时检查保留在独立渠道中，这样它们不会拖慢或阻塞发布
- 发布检查必须从 `main` 工作流 ref 发起，这样工作流逻辑和 secrets 才能保持为规范来源
- 该工作流接受现有发布标签，或当前完整的 40 字符 `main` commit SHA
- 在 commit SHA 模式下，它只接受当前 `origin/main` HEAD；较早的发布提交请使用发布标签
- `OpenClaw NPM Release` 的仅验证预检查也接受当前完整的 40 字符 `main` commit SHA，而无需已推送的标签
- 这种拆分是有意为之：让真实的 npm 发布路径保持简短、可预测且聚焦产物，而较慢的在线检查则留在各自的通道中，避免拖慢或阻塞发布
- 发布检查必须从 `main` 工作流引用发起，这样工作流逻辑和密钥才能保持规范一致
- 该工作流接受已有的发布标签，或当前完整的 40 字符 `main` 提交 SHA
- 在提交 SHA 模式下，它只接受当前 `origin/main` 的 HEAD；对于较旧的发布提交，请使用发布标签
- `OpenClaw NPM Release` 的仅验证预检查也接受当前完整的 40 字符 `main` 提交 SHA，而不要求已推送标签
- 该 SHA 路径仅用于验证，不能提升为真实发布
- 在 SHA 模式下，工作流仅为包元数据检查合成 `v<package.json version>`；真实发布仍然需要真实的发布标签
- 两个工作流都会将真实发布和提升路径保留在 GitHub-hosted runners 上，而非变更型验证路径则可以使用更大的 Blacksmith Linux runners
- 该工作流会运行
- 在 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` 两个工作流 secret
- npm 发布前检查不再等待独立的发布检查渠道完成
- 在审批之前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
（或对应的 beta/修正版标签）
并使用 `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/修正版版本），以在全新的临时前缀中验证已发布的 registry 安装路径
- 维护者发布自动化现在使用“先预检查再提升”的流程：
（或对应的 beta / 修正版版本），以在全新的临时前缀中验证已发布注册表安装路径
- 维护者发布自动化现在采用“先预检查，再提升”的流程：
- 真实 npm 发布必须通过成功的 npm `preflight_run_id`
- stable npm 发布默认目标为 `beta`
- stable npm 发布可以通过工作流输入明确指定目标为 `latest`
- 基于 token 的 npm dist-tag 变更现在位于
- 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` 这样的 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` 预算进行强制检查，因此安装器 e2e 可以在发布路径之前捕获意外的打包膨胀
- 如果发布工作涉及 CI 规划、扩展时序清单或扩展测试矩阵，请在审批前重新生成并审查来自 `.github/workflows/ci.yml` 的、由 planner 管理的 `checks-node-extensions` 工作流矩阵输出，以免发布说明描述过时的 CI 布局
- stable 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` 预算，因此安装器 e2e 会在发布路径之前捕获意外的打包膨胀
- 如果发布工作涉及 CI 规划、扩展时序清单或扩展测试矩阵，请在审批前重新生成并审查来自 `.github/workflows/ci.yml` 的、由规划器拥有的 `checks-node-extensions` 工作流矩阵输出，以免发布说明描述过时的 CI 布局
- stable macOS 发布就绪还包括更新器相关界面：
- GitHub 发布最终必须包含打包后的 `.zip`、`.dmg` 和 `.dSYM.zip`
- 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip
- 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed URL，以及不低于该发布版本规范 Sparkle build floor 的 `CFBundleVersion`
- 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion`
## NPM 工作流输入
`OpenClaw NPM Release` 接受以下由操作人员控制的输入：
- `tag`：必填发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或
`v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前完整的
40 字符 `main` commit SHA，用于仅验证的预检查
- `preflight_only`：`true` 表示仅进行验证/构建/打包，`false` 表示执行真实发布路径
- `preflight_run_id`：在真实发布路径中必填，以便工作流复用成功预检查运行中准备好的 tarball
- `npm_dist_tag`：发布路径的 npm 目标标签；默认值为 `beta`
`v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前
完整的 40 字符 `main` 提交 SHA，用于仅验证的预检查
- `preflight_only`：`true` 表示仅执行验证 / 构建 / 打包，`false` 表示
真实发布路径
- `preflight_run_id`：在真实发布路径中为必填，这样工作流会复用成功预检查运行中准备好的 tarball
- `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta`
`OpenClaw Release Checks` 接受以下由操作人员控制的输入：
- `ref`：用于验证的现有发布标签，或当前完整的 40 字符 `main` commit
- `ref`：要验证的现有发布标签，或当前完整的 40 字符 `main` 提交
SHA
规则：
- Stable 和修正版标签可以发布到 `beta` 或 `latest`
- stable 和修正标签可以发布到 `beta` 或 `latest`
- beta 预发布标签只能发布到 `beta`
- 只有在 `preflight_only=true` 时才允许使用完整 commit SHA 输入
- 发布检查的 commit SHA 模式还要求输入当前 `origin/main` HEAD
- 真实发布路径必须使用与预检查相同的 `npm_dist_tag`；工作流会在继续发布前验证该元数据
- 只有在 `preflight_only=true` 时才允许使用完整提交 SHA 输入
- 发布检查的提交 SHA 模式还要求当前 `origin/main` HEAD
- 真实发布路径必须使用与预检查期间相同的 `npm_dist_tag`；工作流会在发布继续前验证该元数据
## Stable npm 发布顺序
在进行 stable npm 发布时：
在切 stable npm 发布时：
1. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true`
- 在标签尚不存在之前，你可以使用当前完整的 `main` commit SHA，对预检查工作流进行一次仅验证的演练
2. 对于正常的 beta 优先流程，选择 `npm_dist_tag=beta`；只有在你有意直接发布 stable 时才选择 `latest`
3. 单独运行 `OpenClaw Release Checks`，使用相同的标签，或者在你想要实时 prompt cache 覆盖时使用当前完整的 `main` commit SHA
- 这样刻意分离，是为了让实时覆盖保持可用，而不会再次将长时间运行或可能不稳定的检查与发布工作流重新耦合
1. 运行 `OpenClaw NPM Release`，设置 `preflight_only=true`
- 在标签尚不存在时，你可以使用当前完整的 `main` 提交 SHA，对预检查工作流执行仅验证的演练
2. 对于正常的 beta 优先流程，选择 `npm_dist_tag=beta`；只有在你明确希望直接发布 stable 时，才选择 `latest`
3. 使用相同的标签单独运行 `OpenClaw Release Checks`，或者在你希望获得在线 prompt cache 覆盖时使用当前完整的 `main` 提交 SHA
- 这样刻意保持独立，是为了让在线覆盖持续可用，而不必把长时间运行或不稳定的检查重新耦合回发布工作流
4. 保存成功的 `preflight_run_id`
5. 再次运行 `OpenClaw NPM Release`，并设置 `preflight_only=false`，同时使用相同的 `tag`、相同的 `npm_dist_tag` 和已保存的 `preflight_run_id`
6. 如果该发布落在 `beta`，使用私有工作流
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`
将该 stable 版本从 `beta` 提升到 `latest`
7. 如果该发布有意直接发布到 `latest`，并且 `beta`
也应立即跟进同一 stable 构建，请使用同一个私有工作流将两个 dist-tag 都指向该 stable 版本，或者让其计划中的自愈同步稍后再移动 `beta`
工作流，将该 stable 版本从 `beta` 提升到 `latest`
7. 如果该发布是有意直接发布到 `latest`，并且希望 `beta` 立即跟随同一个 stable 构建，使用同一个私有工作流将两个 dist-tag 都指向该 stable 版本，或者让其计划任务自愈同步稍后再移动 `beta`
dist-tag 变更位于私有仓库中以增强安全性，因为它仍然需要
`NPM_TOKEN`，而公开仓库保留仅使用 OIDC 的发布方式。
dist-tag 变更之所以位于私有仓库，是出于安全考虑，因为它仍然
需要 `NPM_TOKEN`，而公开仓库保持仅使用 OIDC 发布。
这样既让直接发布路径有文档记录，也让 beta 优先的提升路径同样清晰且对操作人员可见。
这样既记录了直接发布路径，也记录了 beta 优先的提升路径，并且两者对操作人员都可见。
## 公开参考资料
## 公开参考
- [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml)
- [`.github/workflows/openclaw-release-checks.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-release-checks.yml)
@ -144,6 +146,6 @@ dist-tag 变更位于私有仓库中以增强安全性，因为它仍然需要
- [`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)
作为实际操作手册。

67
docs/zh-CN/reference/test.md
View File

@ -1,13 +1,13 @@
---
read_when:
- 运行或修复测试时
summary: 如何在本地运行测试（vitest），以及何时使用 force/coverage 模式
- 运行或修复测试
summary: 如何在本地运行测试（Vitest），以及何时使用 force / coverage 模式
title: 测试
x-i18n:
generated_at: "2026-04-07T08:14:21Z"
generated_at: "2026-04-20T14:13:21Z"
model: gpt-5.4
provider: openai
source_hash: f7c19390f7577b3a29796c67514c96fe4c86c9fa0c7686cd4e377c6e31dcd085
source_hash: 03c44e5e4fab11883d9af416141d3e8013360a46b7c201ad9ac7cee5e6b3d24e
source_path: reference/test.md
workflow: 15
---
@ -16,40 +16,41 @@ x-i18n:
- 完整测试套件（测试套件、live、Docker）：[测试](/zh-CN/help/testing)
- `pnpm test:force`：终止任何仍在占用默认控制端口的 Gateway 网关残留进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，以避免服务端测试与正在运行的实例发生冲突。当之前的 Gateway 网关运行遗留了对端口 18789 的占用时，请使用此命令。
- `pnpm test:coverage`：使用 V8 覆盖率运行单元测试套件（通过 `vitest.unit.config.ts`）。全局阈值为 70% 的行数/分支/函数/语句覆盖率。覆盖率排除了集成度较高的入口点（CLI 连接代码、gateway/telegram 桥接、webchat 静态服务器），以便将目标聚焦于可进行单元测试的逻辑。
- `pnpm test:coverage:changed`：仅针对自 `origin/main` 以来发生变更的文件运行单元覆盖率。
- `pnpm test:changed`：当 diff 只涉及可路由的源文件/测试文件时，将变更的 git 路径展开为有范围的 Vitest 通道。配置/设置变更仍会回退到原生根项目运行，因此在需要时，连接代码改动仍会触发更广泛的重新运行。
- `pnpm test`：通过有范围的 Vitest 通道路由显式的文件/目录目标。现在，未指定目标的运行会顺序执行 11 个分片配置（`vitest.full-core-unit-src.config.ts`、`vitest.full-core-unit-security.config.ts`、`vitest.full-core-unit-ui.config.ts`、`vitest.full-core-unit-support.config.ts`、`vitest.full-core-support-boundary.config.ts`、`vitest.full-core-contracts.config.ts`、`vitest.full-core-bundled.config.ts`、`vitest.full-core-runtime.config.ts`、`vitest.full-agentic.config.ts`、`vitest.full-auto-reply.config.ts`、`vitest.full-extensions.config.ts`），而不是使用一个巨大的根项目进程。
- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会通过专用的轻量通道进行路由，这些通道仅保留 `test/setup.ts`，而运行时较重的用例仍保留在原有通道中。
- 选定的 `plugin-sdk` 和 `commands` 辅助源文件现在也会将 `pnpm test:changed` 映射到这些轻量通道中的显式同级测试，因此对小型辅助函数的修改无需重新运行依赖较重运行时支持的测试套件。
- `auto-reply` 现在也拆分为三个专用配置（`core`、`top-level`、`reply`），这样 reply 测试框架就不会主导较轻量的顶层状态/token/辅助函数测试。
- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并且在整个仓库配置中启用了共享的非隔离运行器。
- `pnpm test:force`：会终止任何仍占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，以避免服务端测试与正在运行的实例发生冲突。当先前的 Gateway 网关运行导致端口 18789 仍被占用时，使用此命令。
- `pnpm test:coverage`：使用 V8 覆盖率运行单元测试套件（通过 `vitest.unit.config.ts`）。全局阈值为 70% 的行/分支/函数/语句覆盖率。覆盖率会排除集成较重的入口点（CLI 接线、gateway/telegram 桥接、webchat 静态服务器），以便将目标聚焦在适合单元测试的逻辑上。
- `pnpm test:coverage:changed`：仅对相较于 `origin/main` 已变更的文件运行单元测试覆盖率。
- `pnpm test:changed`：当 diff 只涉及可路由的源码/测试文件时，会将已变更的 git 路径展开为有范围限制的 Vitest 通道。配置/初始化变更仍会回退到原生根项目运行，以便在需要时更广泛地重新运行接线相关测试。
- `pnpm test`：会将显式指定的文件/目录目标路由到有范围限制的 Vitest 通道。未指定目标的运行现在会依次执行 11 个分片配置（`vitest.full-core-unit-src.config.ts`、`vitest.full-core-unit-security.config.ts`、`vitest.full-core-unit-ui.config.ts`、`vitest.full-core-unit-support.config.ts`、`vitest.full-core-support-boundary.config.ts`、`vitest.full-core-contracts.config.ts`、`vitest.full-core-bundled.config.ts`、`vitest.full-core-runtime.config.ts`、`vitest.full-agentic.config.ts`、`vitest.full-auto-reply.config.ts`、`vitest.full-extensions.config.ts`），而不是一个庞大的根项目进程。
- 部分 `plugin-sdk` 和 `commands` 测试文件现在会通过专用的轻量通道路由，这些通道只保留 `test/setup.ts`，而运行时较重的用例仍保留在现有通道中。
- 部分 `plugin-sdk` 和 `commands` 辅助源码文件也会将 `pnpm test:changed` 映射到这些轻量通道中的显式同级测试，因此小范围的辅助函数修改无需重新运行依赖重型运行时支持的测试套件。
- `auto-reply` 现在也拆分为三个专用配置（`core`、`top-level`、`reply`），这样 reply 测试框架就不会压过更轻量的顶层状态/token/辅助函数测试。
- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用共享的非隔离运行器。
- `pnpm test:channels` 运行 `vitest.channels.config.ts`。
- `pnpm test:extensions` 运行 `vitest.extensions.config.ts`。
- `pnpm test:extensions`：运行扩展/插件测试套件。
- `pnpm test:perf:imports`：启用 Vitest 导入耗时 + 导入明细报告，同时仍对显式文件/目录目标使用有范围的通道路由。
- `pnpm test:perf:imports:changed`：与导入性能分析相同，但仅针对自 `origin/main` 以来发生变更的文件。
- `pnpm test:perf:changed:bench -- --ref <git-ref>`：针对同一组已提交 git diff，将已路由的 changed 模式路径与原生根项目运行进行基准测试比较。
- `pnpm test:perf:changed:bench -- --worktree`：无需先提交，即可对当前工作区变更集进行基准测试。
- `pnpm test:perf:imports`：启用 Vitest 导入耗时 + 导入明细报告，同时仍对显式文件/目录目标使用有范围限制的通道路由。
- `pnpm test:perf:imports:changed`：与上面相同的导入性能分析，但仅针对相较于 `origin/main` 已变更的文件。
- `pnpm test:perf:changed:bench -- --ref <git-ref>`：针对同一组已提交 git diff，对路由后的 changed 模式路径与原生根项目运行进行基准对比。
- `pnpm test:perf:changed:bench -- --worktree`：无需先提交，即可对当前工作树变更集进行基准测试。
- `pnpm test:perf:profile:main`：为 Vitest 主线程写入 CPU profile（`.artifacts/vitest-main-profile`）。
- `pnpm test:perf:profile:runner`：为单元测试运行器写入 CPU + 堆 profiles（`.artifacts/vitest-runner-profile`）。
- Gateway 网关集成测试：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 选择启用。
- `pnpm test:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS/HTTP/节点配对）。默认在 `vitest.e2e.config.ts` 中使用 `threads` + `isolate: false` 和自适应 workers；可通过 `OPENCLAW_E2E_WORKERS=<n>` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。
- `pnpm test:perf:profile:runner`：为单元测试运行器写入 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。
- Gateway 网关集成测试：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 选择性启用。
- `pnpm test:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS/HTTP/节点配对）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false` 和自适应 worker；可通过 `OPENCLAW_E2E_WORKERS=<n>` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。
- `pnpm test:live`：运行提供商 live 测试（minimax/zai）。需要 API 密钥以及 `LIVE=1`（或提供商特定的 `*_LIVE_TEST=1`）才能取消跳过。
- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的 live 模型密钥（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并不预期像常规单元/e2e 测试套件那样具备 CI 稳定性。
- `pnpm test:docker:mcp-channels`：启动一个预置数据的 Gateway 网关容器和第二个客户端容器，后者会生成 `openclaw mcp serve`，然后通过真实的 stdio bridge 验证路由后的会话发现、转录读取、附件元数据、live 事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该冒烟测试反映的是 bridge 实际发出的内容。
- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的 live 模型密钥（例如 `~/.profile` 中的 OpenAI 密钥），会拉取外部 Open WebUI 镜像，也不像常规单元测试 / e2e 测试套件那样以 CI 稳定为目标。
- `pnpm test:docker:mcp-channels`：启动一个已预置数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后通过真实的 stdio 桥接验证路由后的会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及 Claude 风格的渠道和权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该冒烟测试能够反映桥接实际发出的内容。
## 本地 PR gate
对于本地 PR 提交/gate 检查，请运行：
对于本地 PR 落地 / gate 检查，请运行：
- `pnpm check`
- `pnpm check:test-types`
- `pnpm build`
- `pnpm test`
- `pnpm check:docs`
如果 `pnpm test` 在高负载主机上偶发失败，请先重跑一次，再将其视为回归问题，然后用 `pnpm test <path/to/test>` 进行隔离。对于内存受限的主机，请使用：
如果 `pnpm test` 在负载较高的主机上出现偶发失败，先重跑一次，再将其视为回归，然后用 `pnpm test <path/to/test>` 进行隔离。对于内存受限的主机，可使用：
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
@ -62,9 +63,9 @@ x-i18n:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- 可选环境变量：`MINIMAX_API_KEY`、`MINIMAX_BASE_URL`、`MINIMAX_MODEL`、`ANTHROPIC_API_KEY`
- 默认提示词：“回复一个单词：ok。不要使用标点，也不要添加额外文本。”
- 默认提示词：“Reply with a single word: ok. No punctuation or extra text.”
最近一次运行（2025-12-31，20 次）：
上次运行（2025-12-31，20 次）：
- minimax 中位数 1279ms（最小 1114，最大 2431）
- opus 中位数 2454ms（最小 1224，最大 3170）
@ -94,11 +95,11 @@ x-i18n:
- `startup`：`--version`、`--help`、`health`、`health --json`、`status --json`、`status`
- `real`：`health`、`status`、`status --json`、`sessions`、`sessions --json`、`agents list --json`、`gateway status`、`gateway status --json`、`gateway health --json`、`config get gateway.port`
- `all`：同时包含两个预设
- `all`：两个预设都包含
输出包括每个命令的 `sampleCount`、avg、p50、p95、min/max、exit-code/signal 分布以及最大 RSS 摘要。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，因此计时与 profile 捕获使用的是同一个测试框架。
输出会包含每个命令的 `sampleCount`、平均值、p50、p95、最小/最大值、exit-code/signal 分布，以及最大 RSS 摘要。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，这样计时和 profile 捕获就使用同一个测试框架。
保存输出约定：
已保存输出约定：
- `pnpm test:startup:bench:smoke` 会将目标冒烟产物写入 `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` 会使用 `runs=5` 和 `warmup=1` 将完整测试套件产物写入 `.artifacts/cli-startup-bench-all.json`
@ -112,19 +113,19 @@ x-i18n:
## 新手引导 E2E（Docker）
Docker 是可选的；只有在进行容器化新手引导冒烟测试时才需要它。
Docker 是可选的；只有在需要容器化的新手引导冒烟测试时才需要它。
在干净的 Linux 容器中的完整冷启动流程：
在全新的 Linux 容器中执行完整冷启动流程：
```bash
scripts/e2e/onboard-docker.sh
```
此脚本会通过 pseudo-tty 驱动交互式向导，验证 config/workspace/session 文件，然后启动 Gateway 网关并运行 `openclaw health`。
该脚本会通过伪终端驱动交互式向导，验证配置 / 工作区 / 会话文件，然后启动 Gateway 网关并运行 `openclaw health`。
## 二维码导入冒烟测试（Docker）
确保 `qrcode-terminal` 能在受支持的 Docker Node 运行时（默认 Node 24，兼容 Node 22）下加载：
确保 `qrcode-terminal` 能在受支持的 Docker Node 运行时下加载（默认 Node 24，兼容 Node 22）：
```bash
pnpm test:docker:qr