From 95d25edc5371dfe5b6734d56cfd52dbc6d9737a0 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 26 Apr 2026 21:59:40 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/ci.md | 108 +++++++++++++++++------------------ docs/zh-CN/reference/test.md | 94 +++++++++++++++--------------- 2 files changed, 101 insertions(+), 101 deletions(-) diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 34fbc1e6b..ae91c3597 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-26T21:31:09Z" + generated_at: "2026-04-26T21:58:26Z" model: gpt-5.4 provider: openai - source_hash: 2b60445c01b9cc30be075c37c04ae827f68f9b08550abc3bfde498f8660c6fc2 + source_hash: 3332c240435650af6f2cfe898d47bd7da8bdc58edb8dc8544699a741625d9b27 source_path: ci.md workflow: 15 --- -CI 会在每次推送到 `main` 以及每个拉取请求上运行。它使用智能范围控制，在仅有不相关区域发生变更时跳过昂贵作业。 +CI 会在每次推送到 `main` 以及每个拉取请求上运行。它使用智能范围界定，在只改动无关区域时跳过高开销作业。 -QA Lab 在主智能范围控制工作流之外有专用的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更和手动触发时运行；它会构建私有 QA 运行时，并比较 mock GPT-5.5 和 Opus 4.6 agentic packs。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，也可手动触发；它会将 mock parity gate、实时 Matrix 通道和实时 Telegram 通道作为并行作业扇出运行。实时作业使用 `qa-live-shared` 环境，而 Telegram 通道使用 Convex leases。`OpenClaw Release Checks` 也会在发布批准前运行同样的 QA Lab 通道。 +QA Lab 在主智能范围工作流之外有专门的 CI 车道。`Parity gate` 工作流会在匹配的 PR 变更和手动触发时运行；它会构建私有 QA 运行时，并比较 mock GPT-5.5 和 Opus 4.6 agentic packs。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，也可手动触发；它会将 mock parity gate、实时 Matrix 车道和实时 Telegram 车道并行展开为多个作业。实时作业使用 `qa-live-shared` environment，而 Telegram 车道使用 Convex leases。`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` 上一次成功的、非机器人触发的 push CI 运行可以触发它，也可以通过手动触发直接运行。工作流运行触发的调用会在 `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` 上一次成功的、非机器人触发的 push CI 运行可以触发它，但如果当天 UTC 已有另一次由工作流运行触发的调用已经运行或正在运行，它就会跳过。手动触发会绕过这个按天统计的活动门禁。该车道会构建完整测试套件分组的 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,85 +34,85 @@ gh workflow run duplicate-after-merge.yml \ | 作业 | 用途 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | 检测是否仅为文档变更、变更范围、变更的扩展，并构建 CI 清单 | 在所有非草稿 push 和 PR 上始终运行 | +| `preflight` | 检测是否仅文档改动、已变更范围、已变更扩展，并构建 CI 清单 | 在所有非草稿 push 和 PR 上始终运行 | | `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 在所有非草稿 push 和 PR 上始终运行 | -| `security-dependency-audit` | 针对 npm advisories 执行无依赖的生产 lockfile 审计 | 在所有非草稿 push 和 PR 上始终运行 | +| `security-dependency-audit` | 针对 npm advisories 进行无需依赖安装的生产 lockfile 审计 | 在所有非草稿 push 和 PR 上始终运行 | | `security-fast` | 快速安全作业的必需聚合作业 | 在所有非草稿 push 和 PR 上始终运行 | -| `build-artifacts` | 构建 `dist/`、Control UI、已构建产物检查，以及供下游复用的产物 | 与 Node 相关的变更 | -| `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 | +| `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 相关的变更 | -| `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-extensions` | 对整个扩展套件执行完整的内置插件测试分片 | 与 Node 相关的变更 | +| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、内置、契约和扩展车道 | 与 Node 相关的变更 | +| `extension-fast` | 仅针对已变更内置插件的聚焦测试 | 具有扩展变更的拉取请求 | +| `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 相关的变更 | | `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 | -| `android` | 两种 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的变更 | -| `test-performance-agent` | 在可信活动后，每日执行一次 Codex 慢测试优化 | 主 CI 成功后或手动触发 | +| `android` | 两个 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的变更 | +| `test-performance-agent` | 在可信活动之后进行的每日 Codex 慢测试优化 | `main` CI 成功后或手动触发 | ## 快速失败顺序 -作业的顺序经过安排，以便让低成本检查先失败，再决定是否运行昂贵作业： +作业按顺序排列，以便让低成本检查先失败，避免高成本作业继续运行： -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 原生构建；这些平台通道仍然仅针对平台源代码变更进行范围控制。 -仅涉及 CI 路由的编辑、部分低成本 core-test fixture 编辑，以及狭窄的插件契约辅助工具/测试路由编辑，会使用快速的仅 Node 清单路径：preflight、安全检查，以及单个 `checks-fast-core` 任务。对于仅限于该快速任务可直接覆盖的路由或辅助工具表面的变更，这一路径会跳过构建产物、Node 22 兼容性、渠道契约、完整 core 分片、内置插件分片以及附加守卫矩阵。 -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/包表面、内置插件包/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 run 都有单独的上限。完整路径则保留 QR 包安装和安装器 Docker/update 覆盖，用于每夜定时运行、手动触发、workflow-call 发布检查，以及确实触及安装器/包/Docker 表面的拉取请求。推送到 `main`，包括 merge commit，不会强制走完整路径；当 changed-scope 逻辑在 push 上请求完整覆盖时，工作流会保留快速 Docker smoke，并将完整 install smoke 留给夜间或发布验证。较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独门控；它会在夜间调度和发布检查工作流中运行，手动触发 `install-smoke` 时也可选择启用，但拉取请求和 `main` 推送不会运行它。QR 和安装器 Docker 测试保留各自专注于安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像和一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，然后使用加权调度器和 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 live/E2E smoke 通道；默认主池插槽数为 10，可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整；对提供商更敏感的尾池插槽数也默认为 10，可通过 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整。重型通道上限默认分别为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，这样 npm install 和多服务通道就不会过度占用 Docker，而较轻的通道仍能填满可用插槽。默认情况下，各通道启动会错开 2 秒，以避免本地 Docker 守护进程在创建时发生风暴；可使用 `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 工作流会构建并推送一个带 SHA 标签的 GHCR Docker E2E 镜像，然后以最多三个分块作业运行发布路径 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` 以及每个通道的重跑命令。工作流的 `docker_lanes` 输入会针对准备好的镜像运行选定通道，而不是运行这三个分块作业；这样可以把失败通道调试限制在一个有针对性的 Docker 作业中；如果选定通道是 live Docker 通道，则该定向作业会为这次重跑在本地构建 live-test 镜像。当在发布路径套件中请求 Open WebUI 时，它会在 plugins/integrations 分块内运行，而不是额外占用第四个 Docker worker；只有 openwebui-only 触发时，Open WebUI 才保留独立作业。定时的 live/E2E 工作流每天运行完整的发布路径 Docker 套件。内置更新矩阵按更新目标拆分，因此重复的 npm update 和 doctor repair 过程可以与其他内置检查一起分片运行。 +CI 工作流编辑会校验 Node CI 图和工作流 lint，但它们本身不会强制触发 Windows、Android 或 macOS 原生构建；这些平台车道仍然只针对对应平台源码变更进行范围界定。 +仅涉及 CI 路由的编辑、选定的低成本核心测试夹具编辑，以及窄范围的插件契约辅助工具 / 测试路由编辑，会使用快速的仅 Node 清单路径：preflight、安全检查，以及单个 `checks-fast-core` 任务。当前变更文件仅限于该快速任务可直接覆盖的路由或辅助工具表面时，这一路径会避开构建产物、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片，以及额外的守卫矩阵。 +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`。对于 pull request，Docker/包表面、内置插件包 / manifest 变更，以及 Docker smoke 作业会覆盖到的核心插件 / 渠道 / Gateway 网关 / 插件 SDK 表面，会运行快速路径。仅源码层面的内置插件变更、纯测试编辑和纯文档编辑不会占用 Docker worker。快速路径会构建根目录 Dockerfile 镜像一次，检查 CLI，运行 agents delete shared-workspace CLI smoke，运行容器 gateway-network e2e，验证一个内置扩展 build arg，并在总命令超时 240 秒的限制下运行有界的内置插件 Docker profile，同时每个场景的 Docker run 也分别受限。完整路径则保留 QR 包安装以及安装器 Docker / 更新覆盖，用于每晚定时运行、手动触发、workflow-call 发布检查，以及确实触及安装器 / 包 / Docker 表面的 pull request。推送到 `main`（包括 merge commit）不会强制走完整路径；当 changed-scope 逻辑会在 push 上请求完整覆盖时，工作流仍保留快速 Docker smoke，而把完整 install smoke 留给夜间任务或发布校验。较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独门控；它会在夜间计划任务和发布检查工作流中运行，手动触发 `install-smoke` 时也可以选择启用，但 pull request 和 `main` push 不会运行它。QR 和安装器 Docker 测试保持各自专注安装流程的 Dockerfile。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像，以及两个共享的 `scripts/e2e/Dockerfile` built-app 镜像：一个 bare 镜像供安装器 / 更新 / 插件依赖车道使用，另一个 functional 镜像会预先准备内置插件运行时依赖，供常规功能车道使用。调度器会通过 `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=6`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，从而避免 npm 安装和多服务车道过度占用 Docker，同时让较轻的车道继续填满可用槽位。车道启动默认错开 2 秒，以避免本地 Docker daemon 出现 create 风暴；可以通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合运行会先对 Docker 做 preflight，移除陈旧的 OpenClaw E2E 容器，输出活跃车道状态，持久化车道耗时以支持“最长优先”排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 进行调度器检查。默认情况下，它会在首次失败后停止调度新的池化车道，并且每个车道都有 120 分钟的后备超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；某些实时 / 尾部车道使用更紧的单车道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确指定的调度器车道，包括仅发布使用的车道（如 `install-e2e`）以及拆分的内置更新车道（如 `bundled-channel-update-acpx`），同时跳过 cleanup smoke，以便智能体复现某个失败车道。可复用的 live/E2E 工作流会构建并推送一个带 SHA 标签的 bare GHCR Docker E2E 镜像，以及一个带 SHA 标签的 functional GHCR Docker E2E 镜像，然后以最多三个分块作业运行发布路径 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`、阶段耗时以及每个车道的重跑命令。工作流输入 `docker_lanes` 会让所选车道针对已准备好的镜像运行，而不是运行这三个分块作业；这能把失败车道调试限制在一个有针对性的 Docker 作业中；如果选中的车道是实时 Docker 车道，那么该定向作业会为这次重跑在本地构建 live-test 镜像。当在发布路径套件中请求 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 生产 typecheck 加 core 测试，core 仅测试变更只运行 core 测试 typecheck/测试，扩展生产变更会运行扩展生产 typecheck 加扩展测试，而扩展仅测试变更只运行扩展测试 typecheck/测试。公开的插件 SDK 或插件契约变更会扩展到扩展验证，因为扩展依赖这些 core 契约。仅发布元数据的版本号变更会运行有针对性的 version/config/root-dependency 检查。未知的根目录/配置变更会以安全优先方式落到所有通道。 +本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界方面比宽泛的 CI 平台范围更严格：核心生产变更会运行核心生产 typecheck 加核心测试，核心纯测试变更只运行核心测试 typecheck / tests，扩展生产变更会运行扩展生产 typecheck 加扩展测试，而扩展纯测试变更只运行扩展测试 typecheck / tests。公开的插件 SDK 或插件契约变更会扩展到扩展校验，因为扩展依赖这些核心契约。仅发布元数据的版本号变更会运行有针对性的版本 / 配置 / 根依赖检查。未知的根目录 / 配置变更会以安全优先方式退化为运行所有车道。 -在 push 上，`checks` 矩阵会增加仅 push 运行的 `compat-node22` 通道。在拉取请求上，该通道会被跳过，矩阵保持聚焦于常规测试/渠道通道。 +在 push 上，`checks` 矩阵会额外添加仅在 push 上运行的 `compat-node22` 车道。在 pull request 上，该车道会被跳过，矩阵仍然聚焦于常规测试 / 渠道车道。 -最慢的 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 分片会在 `build-artifacts` 内部并发运行，此时 `dist/` 和 `dist-runtime/` 已经构建完成，这样既保留了它们原有的检查名称作为轻量验证作业，又避免了额外两个 Blacksmith worker 和第二个产物消费者队列。 -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试通道仍会使用 SMS/call-log BuildConfig 标志编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行一个 debug APK 打包作业。 -`extension-fast` 仅在 PR 上运行，因为 push 已经会执行完整的内置插件分片。这样既能为评审提供已变更插件的反馈，又不会在 `main` 上为了 `checks-node-extensions` 已经覆盖的内容额外占用一个 Blacksmith worker。 +最慢的 Node 测试家族会被拆分或平衡，以便每个作业都保持较小规模，同时避免过度预留 runner：渠道契约会作为三个加权分片运行，内置插件测试会在六个扩展 worker 之间平衡，小型核心单元车道会成对组合，自动回复会运行在四个平衡的 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 分片一起运行，以避免共享运行时分片承担尾部。基于 include-pattern 的分片会使用 CI 分片名称记录耗时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置与过滤分片。`check-additional` 会把包边界 compile / canary 工作保留在一起，并把运行时拓扑架构与 gateway watch 覆盖分开；边界守卫分片会在一个作业内部并发运行其小型独立守卫。Gateway watch、渠道测试以及核心 support-boundary 分片会在 `build-artifacts` 内部并发运行，此时 `dist/` 和 `dist-runtime/` 已构建完成，从而在保留旧检查名称作为轻量校验作业的同时，避免再增加两个 Blacksmith worker 和第二条产物消费者队列。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试车道仍会在启用 SMS / call-log BuildConfig 标志的情况下编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行 debug APK 打包作业。 +`extension-fast` 仅在 PR 上运行，因为 push 运行已经会执行完整的内置插件分片。这使得评审时能获得已变更插件的反馈，同时不会在 `main` 上额外占用一个 Blacksmith worker 去覆盖 `checks-node-extensions` 已经包含的内容。 -当同一 PR 或 `main` 引用上有更新的 push 落地时，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 矩阵就能更早开始排队 | +| `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` | `macos-node`，用于 `openclaw/openclaw`；fork 会回退到 `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift`，用于 `openclaw/openclaw`；fork 会回退到 `macos-latest` | +| `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/测试 -pnpm check # 快速本地门控：生产 tsgo + 分片 lint + 并行快速守卫 +pnpm check:changed # 智能本地门禁：按边界车道运行 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 的 artifact/build-smoke 通道相关时，构建 dist +pnpm check:docs # 文档格式 + lint + 损坏链接检查 +pnpm build # 当 CI 构建产物 / 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 # 汇总总耗时、排队耗时和最慢的作业 +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/test.md b/docs/zh-CN/reference/test.md index ff46164c2..aea131f91 100644 --- a/docs/zh-CN/reference/test.md +++ b/docs/zh-CN/reference/test.md @@ -1,54 +1,54 @@ --- read_when: - 运行或修复测试 -summary: 如何在本地运行测试（vitest），以及何时使用 force / coverage 模式 +summary: 如何在本地运行测试（`vitest`），以及何时使用 force / coverage 模式 title: 测试 x-i18n: - generated_at: "2026-04-26T09:32:01Z" + generated_at: "2026-04-26T21:58:25Z" model: gpt-5.4 provider: openai - source_hash: 24eb2d122c806237bd4b90dffbd293479763c11a42cfcd195e1aed59efc71a5b + source_hash: cc575df6f7a6edd72fe5db766b140587e16c2daf887bb3ce3f9d273a0e7cf311 source_path: reference/test.md workflow: 15 --- - 完整测试工具包（测试套件、live、Docker）：[测试](/zh-CN/help/testing) -- `pnpm test:force`：终止任何仍在占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，以避免服务器测试与正在运行的实例冲突。当之前的 Gateway 网关运行导致端口 `18789` 仍被占用时，使用此命令。 -- `pnpm test:coverage`：通过 `vitest.unit.config.ts` 使用 V8 覆盖率运行单元测试套件。这是一个针对已加载文件的单元覆盖率检查，而不是整个仓库的全文件覆盖率。阈值为：行 / 函数 / 语句 70%，分支 55%。由于 `coverage.all` 为 false，该检查衡量的是被单元覆盖率套件加载到的文件，而不是把每个拆分测试 lane 中的源文件都视为未覆盖。 -- `pnpm test:coverage:changed`：仅针对自 `origin/main` 以来发生变更的文件运行单元覆盖率。 -- `pnpm test:changed`：当 diff 只涉及可路由的源文件 / 测试文件时，会将变更的 Git 路径扩展为带作用域的 Vitest lane。配置 / setup 变更仍会回退到原生根项目运行，因此接线类修改在需要时会触发更广泛的重跑。 -- `pnpm test:changed:focused`：用于内部循环的变更测试运行。它只会根据直接修改的测试文件、同级 `*.test.ts` 文件、显式源文件映射以及本地导入图运行精确目标。广泛的 / 配置 / package 变更会被跳过，而不会扩展到完整的 changed-test 回退运行。 -- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 所触发的架构 lane。 -- `pnpm check:changed`：对相对于 `origin/main` 的 diff 运行智能变更检查。它会为核心代码运行核心测试 lane，为扩展代码运行扩展测试 lane，仅测试改动则只运行测试类型检查 / 测试，并将公开的 Plugin SDK 或插件契约变更扩展为一次扩展验证，同时把仅发布元数据的版本提升限制在定向的版本 / 配置 / 根依赖检查上。 -- `pnpm test`：通过带作用域的 Vitest lane 路由显式文件 / 目录目标。未指定目标的运行会使用固定分片组，并扩展到叶子配置以进行本地并行执行；扩展组始终会扩展为每个扩展 / 插件的分片配置，而不是一个庞大的根项目进程。 -- 完整、扩展以及 include-pattern 分片运行会更新 `.artifacts/vitest-shard-timings.json` 中的本地耗时数据；后续的整配置运行会利用这些耗时来平衡慢分片和快分片。include-pattern CI 分片会将分片名称附加到耗时键名，这样就能在不覆盖整配置耗时数据的情况下保留过滤后分片的耗时信息。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地耗时产物。 -- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会路由到专用的轻量 lane，只保留 `test/setup.ts`，而运行时较重的用例仍保留在现有 lane 中。 -- 具有同级测试的源文件会优先映射到该同级测试，然后才回退到更宽泛的目录 glob。`test/helpers/channels` 和 `test/helpers/plugins` 下的辅助文件编辑会使用本地导入图来运行导入它们的测试，而不是在依赖路径明确时广泛运行每个分片。 -- `auto-reply` 现在也拆分为三个专用配置（`core`、`top-level`、`reply`），这样 reply harness 就不会主导较轻量的顶层状态 / token / helper 测试。 -- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用共享的非隔离 runner。 +- `pnpm test:force`：终止任何仍在占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，避免服务端测试与正在运行的实例发生冲突。当之前的 Gateway 网关运行导致端口 `18789` 仍被占用时，请使用此命令。 +- `pnpm test:coverage`：通过 `vitest.unit.config.ts` 运行带有 V8 覆盖率的单元测试套件。这是一个基于已加载文件的单元测试覆盖率门禁，不是整个仓库的全文件覆盖率。阈值为 70% 的行数 / 函数 / 语句覆盖率，以及 55% 的分支覆盖率。由于 `coverage.all` 为 false，该门禁会统计被单元测试覆盖率套件加载的文件，而不是将每个拆分测试通道中的源文件都视为未覆盖。 +- `pnpm test:coverage:changed`：仅针对自 `origin/main` 以来变更的文件运行单元测试覆盖率。 +- `pnpm test:changed`：当 diff 只涉及可路由的源文件 / 测试文件时，会将变更的 Git 路径展开为有范围限制的 Vitest 测试通道。配置 / 设置变更仍会回退到原生根项目运行，以便在需要时对接线变更进行更广泛的重跑。 +- `pnpm test:changed:focused`：用于内循环的变更测试运行。它只运行由直接测试编辑、同级 `*.test.ts` 文件、显式源文件映射以及本地导入图精确定位的目标。广泛的 / 配置 / package 变更会被跳过，而不是扩展为完整的变更测试回退运行。 +- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 所触发的架构测试通道。 +- `pnpm check:changed`：针对相对于 `origin/main` 的 diff 运行智能变更门禁。它会将核心变更与核心测试通道一起运行，将扩展变更与扩展测试通道一起运行，将仅测试变更限制为只跑测试类型检查 / 测试，把公共 Plugin SDK 或插件契约变更扩展为一次扩展验证，并在仅版本发布元数据变更时保持在有针对性的版本 / 配置 / 根依赖检查范围内。 +- `pnpm test`：通过有范围限制的 Vitest 测试通道来路由显式的文件 / 目录目标。未指定目标的运行会使用固定的分片组，并扩展到叶子配置以进行本地并行执行；扩展组总是展开为按扩展划分的分片配置，而不是一个巨大的根项目进程。 +- 完整测试、扩展测试和 include-pattern 分片运行会将本地耗时数据更新到 `.artifacts/vitest-shard-timings.json`；之后的整配置运行会使用这些耗时数据来平衡慢分片与快分片。include-pattern CI 分片会将分片名称附加到耗时键名上，这样可在不覆盖整配置耗时数据的情况下保留过滤分片的耗时信息。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地耗时产物。 +- 部分 `plugin-sdk` 和 `commands` 测试文件现在会路由到专用的轻量通道，这些通道仅保留 `test/setup.ts`，而运行时较重的用例仍保留在现有通道中。 +- 具有同级测试的源文件会优先映射到该同级测试，然后才回退到更宽泛的目录 glob。`test/helpers/channels` 和 `test/helpers/plugins` 下的辅助文件编辑会使用本地导入图来运行导入它们的测试，而不是在依赖路径足够精确时宽泛地重跑所有分片。 +- `auto-reply` 现在还拆分为三个专用配置（`core`、`top-level`、`reply`），因此 reply harness 不会再主导较轻量的顶层状态 / token / helper 测试。 +- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用了共享的非隔离运行器。 - `pnpm test:channels` 运行 `vitest.channels.config.ts`。 -- `pnpm test:extensions` 和 `pnpm test extensions` 运行全部扩展 / 插件分片。较重的渠道插件、browser 插件以及 OpenAI 会作为专用分片运行；其他插件组仍保持批量运行。对单个内置插件 lane，使用 `pnpm test extensions/`。 -- `pnpm test:perf:imports`：启用 Vitest 导入时长 + 导入拆解报告，同时仍对显式文件 / 目录目标使用带作用域的 lane 路由。 -- `pnpm test:perf:imports:changed`：相同的导入分析，但仅针对自 `origin/main` 以来发生变更的文件。 -- `pnpm test:perf:changed:bench -- --ref `：对同一已提交 Git diff 的 changed-mode 路径与原生根项目运行进行基准对比。 -- `pnpm test:perf:changed:bench -- --worktree`：无需先提交，直接对当前工作树的变更集进行基准测试。 +- `pnpm test:extensions` 和 `pnpm test extensions` 会运行所有扩展 / 插件分片。较重的渠道插件、浏览器插件以及 OpenAI 会作为专用分片运行；其他插件组仍保持批处理。对某个内置插件通道可使用 `pnpm test extensions/`。 +- `pnpm test:perf:imports`：启用 Vitest 导入耗时 + 导入明细报告，同时对显式文件 / 目录目标继续使用有范围限制的通道路由。 +- `pnpm test:perf:imports:changed`：相同的导入性能分析，但仅针对自 `origin/main` 以来变更的文件。 +- `pnpm test:perf:changed:bench -- --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`：为单元测试 runner 写入 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。 -- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行每个完整测试套件的 Vitest 叶子配置，并写入分组耗时数据以及每个配置对应的 JSON / 日志产物。Test Performance Agent 会将其作为尝试修复慢测试之前的基线。 -- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：在以性能为重点的变更之后比较分组报告。 +- `pnpm test:perf:profile:runner`：为单元测试运行器写入 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。 +- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行每个完整测试套件的 Vitest 叶子配置，并写入分组耗时数据以及按配置划分的 JSON / 日志产物。Test Performance Agent 会将其作为尝试修复慢测试之前的基线。 +- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：对比性能优化相关变更前后的分组报告。 - 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=` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。 -- `pnpm test:live`：运行提供商 live 测试（minimax / zai）。需要 API keys，并设置 `LIVE=1`（或特定提供商的 `*_LIVE_TEST=1`）才能取消跳过。 -- `pnpm test:docker:all`：一次性构建共享的 live-test 镜像和 Docker E2E 镜像，然后通过加权调度器在设置 `OPENCLAW_SKIP_DOCKER_BUILD=1` 的情况下运行 Docker 冒烟测试 lane。`OPENCLAW_DOCKER_ALL_PARALLELISM=` 控制进程槽位，默认值为 10；`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=` 控制对提供商敏感的尾部池，默认值也为 10。重型 lane 上限默认分别为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；提供商上限默认是每个提供商一个重型 lane，对应 `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`、`OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` 和 `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`。对于配置更高的主机，可使用 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。为避免本地 Docker 守护进程在创建容器时出现风暴，lane 启动默认会错开 2 秒；可通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=` 覆盖。该运行器默认会预检 Docker、清理过期的 OpenClaw E2E 容器、每 30 秒输出活动 lane 状态、在兼容 lane 之间共享提供商 CLI 工具缓存、默认对瞬时 live-provider 失败重试一次（`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=`），并将 lane 耗时存储在 `.artifacts/docker-tests/lane-timings.json` 中，以便后续运行按最长优先排序。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可仅打印 lane 清单而不运行 Docker，使用 `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=` 可调整状态输出频率，使用 `OPENCLAW_DOCKER_ALL_TIMINGS=0` 可禁用耗时复用。使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` 可只运行确定性的 / 本地 lane，使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` 可只运行 live-provider lane；package 别名分别为 `pnpm test:docker:local:all` 和 `pnpm test:docker:live:all`。仅 live 模式会将主 live lane 和尾部 live lane 合并为一个按最长优先排序的池，从而让提供商桶可以将 Claude、Codex 和 Gemini 工作打包在一起。除非设置 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，否则运行器会在首次失败后停止调度新的池化 lane；每个 lane 都有一个 120 分钟的后备超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；部分选定的 live / tail lane 使用更严格的单 lane 上限。CLI 后端 Docker 设置命令有独立超时，通过 `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` 控制（默认 180）。每个 lane 的日志会写入 `.artifacts/docker-tests//`。 -- `pnpm test:docker:browser-cdp-snapshot`：构建一个基于 Chromium 的 source E2E 容器，启动原始 CDP 和一个隔离的 Gateway 网关，运行 `browser doctor --deep`，并验证 CDP 角色快照包含链接 URL、由光标提升的可点击元素、iframe 引用以及 frame 元数据。 -- CLI 后端 live Docker 探测可以作为聚焦 lane 运行，例如 `pnpm test:docker:live-cli-backend:codex`、`pnpm test:docker:live-cli-backend:codex:resume` 或 `pnpm test:docker:live-cli-backend:codex:mcp`。Claude 和 Gemini 也有对应的 `:resume` 和 `:mcp` 别名。 -- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的 live 模型 key（例如 `~/.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:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS / HTTP / 节点配对）。默认在 `vitest.e2e.config.ts` 中使用 `threads` + `isolate: false` 和自适应 worker；可通过 `OPENCLAW_E2E_WORKERS=` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。 +- `pnpm test:live`：运行提供商 live 测试（minimax / zai）。需要 API 密钥以及 `LIVE=1`（或特定提供商的 `*_LIVE_TEST=1`）才能取消跳过。 +- `pnpm test:docker:all`：一次性构建共享的 live-test 镜像以及两个 Docker E2E 镜像，然后通过加权调度器并配合 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 Docker 冒烟测试通道。基础镜像（`OPENCLAW_DOCKER_E2E_BARE_IMAGE`）用于安装器 / 更新 / 插件依赖测试通道；功能镜像（`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`）会为正常功能测试通道预先准备内置插件的运行时依赖。`OPENCLAW_DOCKER_ALL_PARALLELISM=` 控制进程槽位，默认值为 10；`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=` 控制对提供商敏感的尾部池，默认值也为 10。重型通道上限默认分别为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；提供商上限默认每个提供商一个重型通道，具体为 `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`、`OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` 和 `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`。对于更强的主机，可使用 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。为避免本地 Docker daemon 因同时创建容器而出现风暴，通道启动默认错开 2 秒；可通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=` 覆盖。该运行器默认会对 Docker 进行预检查、清理过期的 OpenClaw E2E 容器、每 30 秒输出一次活跃通道状态、在兼容通道之间共享提供商 CLI 工具缓存、默认对临时性的 live 提供商失败重试一次（`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=`），并将通道耗时保存到 `.artifacts/docker-tests/lane-timings.json`，以便后续运行按最长优先排序。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可只打印通道清单而不运行 Docker，使用 `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=` 可调整状态输出频率，或使用 `OPENCLAW_DOCKER_ALL_TIMINGS=0` 禁用耗时复用。使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` 可只运行确定性 / 本地通道，或使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` 只运行 live 提供商通道；对应的 package 别名为 `pnpm test:docker:local:all` 和 `pnpm test:docker:live:all`。仅 live 模式会将主 live 通道和尾部 live 通道合并为一个按最长优先排序的池，以便提供商桶能够将 Claude、Codex 和 Gemini 的工作一起打包。除非设置了 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，否则在首次失败后，运行器会停止调度新的池化通道；每个通道都有一个 120 分钟的后备超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；部分 live / 尾部通道使用更严格的每通道上限。CLI 后端 Docker 设置命令还有单独的超时，由 `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` 控制（默认 180）。每个通道的日志以及 `summary.json` 阶段耗时会写入 `.artifacts/docker-tests//`。 +- `pnpm test:docker:browser-cdp-snapshot`：构建一个基于 Chromium 的源码 E2E 容器，启动原始 CDP 以及一个隔离的 Gateway 网关，运行 `browser doctor --deep`，并验证 CDP 角色快照包含链接 URL、被光标提升的可点击元素、iframe 引用以及 frame 元数据。 +- CLI 后端 live Docker 探针可作为聚焦测试通道运行，例如 `pnpm test:docker:live-cli-backend:codex`、`pnpm test:docker:live-cli-backend:codex:resume` 或 `pnpm test:docker:live-cli-backend:codex:mcp`。Claude 和 Gemini 也有对应的 `:resume` 和 `:mcp` 别名。 +- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的 live 模型密钥（例如 `~/.profile` 中的 OpenAI），会拉取外部的 Open WebUI 镜像，并不像常规 unit / e2e 测试套件那样预期具备 CI 稳定性。 +- `pnpm test:docker:mcp-channels`：启动一个带有种子数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后验证路由会话发现、转录读取、附件元数据、live 事件队列行为、出站发送路由，以及通过真实 stdio 桥接传递的 Claude 风格渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该冒烟测试反映的是桥接实际发出的内容。 -## 本地 PR 检查门 +## 本地 PR 门禁 -对于本地 PR 合入 / 检查，运行： +对于本地 PR 合入 / 门禁检查，请运行： - `pnpm check:changed` - `pnpm check` @@ -57,12 +57,12 @@ x-i18n: - `pnpm test` - `pnpm check:docs` -如果 `pnpm test` 在高负载主机上出现偶发失败，在将其视为回归之前先重跑一次，然后使用 `pnpm test ` 进行隔离。对于内存受限的主机，使用： +如果 `pnpm test` 在高负载主机上出现偶发失败，请先重跑一次，再将其视为回归问题；之后可用 `pnpm test ` 进行隔离。对于内存受限的主机，可使用： - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` -## 模型延迟基准（本地 keys） +## 模型延迟基准测试（本地密钥） 脚本：[`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) @@ -72,12 +72,12 @@ x-i18n: - 可选环境变量：`MINIMAX_API_KEY`、`MINIMAX_BASE_URL`、`MINIMAX_MODEL`、`ANTHROPIC_API_KEY` - 默认提示词：“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） -## CLI 启动基准 +## CLI 启动基准测试 脚本：[`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts) @@ -102,17 +102,17 @@ 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`、平均值、p50、p95、最小 / 最大值、exit-code / signal 分布，以及最大 RSS 汇总。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，因此计时和 profile 捕获使用的是同一套 harness。 +输出包含每个命令的 `sampleCount`、avg、p50、p95、min/max、exit-code / signal 分布，以及最大 RSS 汇总。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，因此耗时统计和 profile 采集使用的是同一套 harness。 保存输出约定： -- `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` -- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1` 刷新已提交的基线 fixture，路径为 `test/fixtures/cli-startup-bench.json` +- `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` +- `pnpm test:startup:bench:update` 会以 `runs=5` 和 `warmup=1` 刷新已检入的基线 fixture：`test/fixtures/cli-startup-bench.json` -已提交的 fixture： +已检入的 fixture： - `test/fixtures/cli-startup-bench.json` - 使用 `pnpm test:startup:bench:update` 刷新 @@ -120,7 +120,7 @@ x-i18n: ## 新手引导 E2E（Docker） -Docker 是可选的；只有在需要容器化的新手引导冒烟测试时才需要它。 +Docker 是可选的；只有在运行容器化的新手引导冒烟测试时才需要。 在干净的 Linux 容器中运行完整的冷启动流程： @@ -128,11 +128,11 @@ Docker 是可选的；只有在需要容器化的新手引导冒烟测试时才 scripts/e2e/onboard-docker.sh ``` -该脚本会通过 pseudo-tty 驱动交互式向导，验证配置 / 工作区 / 会话文件，然后启动 Gateway 网关并运行 `openclaw health`。 +该脚本会通过伪 TTY 驱动交互式向导，验证配置 / workspace / 会话文件，然后启动 Gateway 网关并运行 `openclaw health`。 ## 二维码导入冒烟测试（Docker） -确保维护中的二维码运行时辅助程序能够在受支持的 Docker Node 运行时中加载（默认 Node 24，兼容 Node 22）： +确保受支持的 Docker Node 运行时（默认 Node 24，兼容 Node 22）下能够加载受维护的二维码运行时辅助工具： ```bash pnpm test:docker:qr @@ -141,4 +141,4 @@ pnpm test:docker:qr ## 相关内容 - [测试](/zh-CN/help/testing) -- [实时测试](/zh-CN/help/testing-live) +- [live 测试](/zh-CN/help/testing-live)