diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 30d5df98a..b809dac59 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -2,92 +2,92 @@ read_when: - 你需要了解某个 CI 作业为什么会运行或没有运行 - 你正在调试失败的 GitHub Actions 检查 -summary: CI 作业图、作用域门禁以及本地等效命令 +summary: CI 作业图、作用域门控，以及本地命令等价项 title: CI 流水线 x-i18n: - generated_at: "2026-04-23T13:33:19Z" + generated_at: "2026-04-23T13:56:16Z" model: gpt-5.4 provider: openai - source_hash: 730bba64e0867f41b47e4896f8255b6d23e6530bb91d349abb25b35a43152e9e + source_hash: c5a8ea0d8e428826169b0e6aced1caeb993106fe79904002125ace86b48cae1f source_path: ci.md workflow: 15 --- # CI 流水线 -CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能作用域划分，在只改动无关区域时跳过高开销作业。 +CI 会在每次推送到 `main` 以及每个拉取请求上运行。它使用智能作用域划分，在只改动了不相关区域时跳过高成本作业。 -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` environment，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 advisory 执行无依赖的生产 lockfile 审计 | 始终在非草稿推送和 PR 上运行 | -| `security-fast` | 快速安全作业的必需聚合作业 | 始终在非草稿推送和 PR 上运行 | -| `build-artifacts` | 构建 `dist/`、Control UI、内置产物检查，以及可供下游复用的产物 | 与 Node 相关的变更 | -| `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/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 相关的变更 | -| `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 相关的变更 | +| `checks-node-extensions` | 针对整个扩展套件执行完整的内置 plugin 测试分片 | 与 Node 相关的变更 | +| `checks-node-core-test` | Core Node 测试分片，不含渠道、内置、契约和扩展通道 | 与 Node 相关的变更 | +| `extension-fast` | 仅针对已变更的内置 plugin 执行聚焦测试 | 带有扩展变更的拉取请求 | +| `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 相关的变更 | ## 快速失败顺序 -作业按顺序排列，以便让便宜的检查先失败，再运行昂贵的检查： +作业按顺序排列，以便让低成本检查先失败，再决定是否运行高成本作业： -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 工作流表面；无关的源码、插件、install-smoke 和仅测试变更仍保留在 Linux Node 通道中，这样就不会为了正常测试分片已经覆盖的内容而占用一个 16 vCPU 的 Windows worker。 -独立的 `install-smoke` 工作流通过它自己的 `preflight` 作业复用同一个作用域脚本。它根据更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/install smoke 会在安装、打包、与容器相关的变更、内置扩展生产变更，以及 Docker smoke 作业所覆盖的 core plugin/channel/Gateway 网关/Plugin SDK 表面变更时运行。仅测试和仅文档编辑不会占用 Docker worker。它的 QR 包 smoke 会强制 Docker `pnpm install` 层重新运行，同时保留 BuildKit pnpm store cache，因此仍然会验证安装流程，而不必在每次运行时重新下载依赖。它的 gateway-network e2e 会复用该作业前面已构建的运行时镜像，因此在不增加另一轮 Docker 构建的情况下，增加了真实的容器到容器 WebSocket 覆盖。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像，以及一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，然后在 `OPENCLAW_SKIP_DOCKER_BUILD=1` 下并行运行 live/E2E smoke 通道；默认并发数为 4，可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整。对启动或 provider 敏感的通道会在并行池之后独占运行。可复用的 live/E2E 工作流也遵循共享镜像模式：在 Docker 矩阵之前先构建并推送一个带 SHA 标签的 GHCR Docker E2E 镜像，然后在矩阵中以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。QR 和安装器 Docker 测试保留各自以安装为重点的 Dockerfile。另有一个单独的 `docker-e2e-fast` 作业，会在 120 秒命令超时下运行受限的内置插件 Docker 配置：setup-entry 依赖修复，以及 synthetic bundled-loader 故障隔离。完整的 bundled update/channel 矩阵仍然是手动/完整套件，因为它会反复执行真实的 npm update 和 doctor 修复流程。 +CI 工作流编辑会校验 Node CI 作业图以及工作流 lint，但它们本身不会强制触发 Windows、Android 或 macOS 原生构建；这些平台通道仍然只对平台源码变更生效。 +Windows Node 检查的作用域限定在 Windows 专用的进程/路径包装器、npm/pnpm/UI 运行器辅助代码、包管理器配置，以及会执行该通道的 CI 工作流表面；不相关的源码、plugin、安装 smoke 和纯测试改动会继续留在 Linux Node 通道上，这样就不会为了 Linux 正常测试分片已经覆盖的内容而占用一个 16-vCPU 的 Windows worker。 +独立的 `install-smoke` 工作流通过其自己的 `preflight` 作业复用同一个作用域脚本。它会根据更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/安装 smoke 会在安装、打包、容器相关变更、内置扩展生产代码变更，以及 Docker smoke 作业会覆盖到的核心 plugin/channel/Gateway 网关/插件 SDK 表面变更时运行。纯测试和纯文档编辑不会占用 Docker worker。它的 QR 包 smoke 会强制 Docker `pnpm install` 层重新运行，同时保留 BuildKit 的 pnpm store 缓存，因此仍然能覆盖安装流程，而不需要每次运行都重新下载依赖。它的 gateway-network e2e 会复用该作业前面构建好的运行时镜像，因此在不增加另一次 Docker 构建的情况下，增加了真实的容器到容器 WebSocket 覆盖。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像，以及一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，然后以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 并行运行 live/E2E smoke 通道；可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整默认并发数 4。默认情况下，本地聚合作业会在首次失败后停止调度新的池化通道，并且每个通道都有 120 分钟超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖。对启动或提供商敏感的通道会在并行池之后独占运行。可复用的 live/E2E 工作流也采用同样的共享镜像模式：先在 Docker 矩阵之前构建并推送一个带 SHA 标签的 GHCR Docker E2E 镜像，然后在矩阵中以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。定时 live/E2E 工作流会每天运行完整的发布路径 Docker 套件。QR 和安装器 Docker 测试保留各自专注安装流程的 Dockerfile。另有一个独立的 `docker-e2e-fast` 作业，会在 120 秒命令超时限制下运行受限的内置 plugin Docker 配置：setup-entry 依赖修复，以及合成的 bundled-loader 失败隔离。完整的内置更新/渠道矩阵仍然是手动/完整套件，因为它会反复执行真实的 npm update 和 Doctor 修复流程。 -本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界方面比宽泛的 CI 平台作用域更严格：core 生产变更会运行 core 生产 typecheck 加 core 测试，core 仅测试变更只会运行 core 测试 typecheck/测试，扩展生产变更会运行扩展生产 typecheck 加扩展测试，而扩展仅测试变更只会运行扩展测试 typecheck/测试。公开的 Plugin SDK 或 plugin-contract 变更会扩大到扩展验证，因为扩展依赖这些 core 契约。仅有发布元数据的版本号变更会运行有针对性的版本/配置/root 依赖检查。未知的 root/配置变更会以安全优先方式落到所有通道。 +本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，由 `scripts/check-changed.mjs` 执行。这个本地门控在架构边界方面比广义的 CI 平台作用域更严格：核心生产代码变更会运行核心生产 typecheck 加核心测试，核心纯测试变更只运行核心测试 typecheck/测试，扩展生产代码变更会运行扩展生产 typecheck 加扩展测试，而扩展纯测试变更只运行扩展测试 typecheck/测试。公共插件 SDK 或 plugin-contract 变更会扩展到扩展校验，因为扩展依赖这些核心契约。仅包含发布元数据的版本变更会运行有针对性的版本/配置/根依赖检查。未知的根目录/配置变更会以保守方式退回到所有通道。 -在 push 上，`checks` 矩阵会增加仅 push 运行的 `compat-node22` 通道。在拉取请求中，该通道会被跳过，矩阵则保持聚焦于常规测试/渠道通道。 +在 push 上，`checks` 矩阵会增加仅在 push 运行的 `compat-node22` 通道。在拉取请求上，该通道会被跳过，矩阵只聚焦于常规测试/渠道通道。 -最慢的 Node 测试族已被拆分或平衡，以保持每个作业都足够小：渠道契约把 registry 和 core 覆盖拆成总共六个带权重的分片，内置插件测试在六个扩展 worker 之间平衡，自动回复以三个平衡 worker 运行而不是六个很小的 worker，而 agentic Gateway 网关/plugin 配置会分散到现有的仅源码 agentic Node 作业中，而不是等待已构建产物。宽泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。宽泛的智能体通道使用共享的 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。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试通道仍会带着 SMS/通话日志 BuildConfig 标志编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行一个 debug APK 打包作业。 -`extension-fast` 仅在 PR 上运行，因为 push 运行已经会执行完整的内置插件分片。这样可以为代码审查提供已变更插件的反馈，同时不会在 `main` 上为 `checks-node-extensions` 已经覆盖的内容额外占用一个 Blacksmith worker。 +最慢的 Node 测试族已被拆分或均衡，以保持每个作业规模较小：渠道契约将 registry 和核心覆盖拆为总计六个加权分片，内置 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 的编译/canary 工作放在一起，并将运行时拓扑架构与 gateway watch 覆盖拆开；边界守卫分片会在一个作业内部并发运行其小型独立守卫。Gateway watch、渠道测试和核心 support-boundary 分片会在 `build-artifacts` 中于 `dist/` 和 `dist-runtime/` 已构建完成后并发运行，从而在保留旧检查名称作为轻量校验作业的同时，避免再增加两个 Blacksmith worker 和第二个产物消费者队列。 +Android CI 会运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；它的单元测试通道仍会带着 SMS/通话日志 BuildConfig 标志编译该 flavor，同时避免在每次与 Android 相关的 push 上重复进行 debug APK 打包作业。 +`extension-fast` 仅在 PR 上运行，因为 push 运行已经会执行完整的内置 plugin 分片。这样可以在代码评审时为变更过的 plugin 提供反馈，而不会在 `main` 上为 `checks-node-extensions` 已经覆盖的内容额外占用一个 Blacksmith worker。 -当同一 PR 或 `main` ref 上有更新的 push 到来时，GitHub 可能会将被替代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则请将其视为 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、自动响应；`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 测试分片、内置 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-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 changed:lanes # 检查针对 origin/main...HEAD 的本地 changed-lane 分类器 +pnpm check:changed # 智能本地门控：按边界通道运行变更相关的 typecheck/lint/测试 +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 @@ -95,6 +95,6 @@ pnpm test # vitest 测试 pnpm test:channels pnpm test:contracts:channels pnpm check:docs # 文档格式化 + lint + 失效链接检查 -pnpm build # 当 CI 产物/build-smoke 通道相关时，构建 dist +pnpm build # 当 CI 的产物构建/build-smoke 通道相关时，构建 dist node scripts/ci-run-timings.mjs # 汇总总耗时、排队时间和最慢的作业 ``` diff --git a/docs/zh-CN/reference/test.md b/docs/zh-CN/reference/test.md index 7254ebc6d..d4745f00b 100644 --- a/docs/zh-CN/reference/test.md +++ b/docs/zh-CN/reference/test.md @@ -4,48 +4,48 @@ read_when: summary: 如何在本地运行测试（vitest），以及何时使用 force/coverage 模式 title: 测试 x-i18n: - generated_at: "2026-04-23T13:33:17Z" + generated_at: "2026-04-23T13:56:15Z" model: gpt-5.4 provider: openai - source_hash: 2897f6a58720b43c749dc7ea410369a529bb8f72c50f8d9e55f114bf39ccb1a9 + source_hash: e0bcecb0868b3b68361e5ef78afc3170f2a481771bda8f7d54200b1d778d044a source_path: reference/test.md workflow: 15 --- # 测试 -- 完整测试工具包（测试套件、实时、Docker）：[测试](/zh-CN/help/testing) +- 完整测试工具包（测试套件、实时测试、Docker）：[测试](/zh-CN/help/testing) -- `pnpm test:force`：终止任何仍占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，这样服务器测试就不会与正在运行的实例冲突。当先前的 Gateway 网关运行导致端口 `18789` 仍被占用时，请使用此命令。 -- `pnpm test:coverage`：使用 V8 覆盖率运行单元测试套件（通过 `vitest.unit.config.ts`）。这是一个针对已加载文件的单元覆盖率门禁，而不是整个仓库所有文件的覆盖率。阈值为：行数 / 函数 / 语句 70%，分支 55%。由于 `coverage.all` 为 false，该门禁会统计被单元覆盖率套件加载的文件，而不是将每个拆分测试通道中的源文件都视为未覆盖。 -- `pnpm test:coverage:changed`：仅针对自 `origin/main` 以来发生变更的文件运行单元覆盖率。 -- `pnpm test:changed`：当差异只涉及可路由的源文件 / 测试文件时，会将变更过的 git 路径展开为有范围限制的 Vitest 通道。配置 / 设置变更仍会回退到原生根项目运行方式，因此在需要时，接线层修改会触发更广泛的重跑。 -- `pnpm changed:lanes`：显示相对于 `origin/main` 的差异所触发的架构通道。 -- `pnpm check:changed`：针对相对于 `origin/main` 的差异运行智能变更门禁。它会将核心改动与核心测试通道一起运行，将扩展改动与扩展测试通道一起运行，将仅测试改动限制为测试类型检查 / 测试本身，将公开的插件 SDK 或插件契约变更扩展为扩展验证，并将仅发布元数据的版本号变更限制在有针对性的版本 / 配置 / 根依赖检查上。 -- `pnpm test`：通过有范围限制的 Vitest 通道来路由显式指定的文件 / 目录目标。未指定目标的运行会使用固定的分片组，并展开到叶子配置，以便在本地并行执行；扩展组始终会展开为按扩展划分的分片配置，而不是单个巨大的根项目进程。 -- 完整测试和扩展分片运行会更新 `.artifacts/vitest-shard-timings.json` 中的本地计时数据；后续运行会使用这些计时信息来平衡慢分片和快分片。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地计时产物。 -- 部分 `plugin-sdk` 和 `commands` 测试文件现在会通过专用轻量通道进行路由，这些通道只保留 `test/setup.ts`，而运行时负载较重的用例仍保留在原有通道中。 -- 部分 `plugin-sdk` 和 `commands` 辅助源文件也会将 `pnpm test:changed` 映射到这些轻量通道中的显式同级测试，因此对小型辅助文件的修改可以避免重跑依赖重型运行时的测试套件。 -- `auto-reply` 现在也拆分为三个专用配置（`core`、`top-level`、`reply`），因此 reply 测试框架不会拖慢较轻量的顶层状态 / token / helper 测试。 -- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用了共享的非隔离运行器。 +- `pnpm test:force`：终止任何仍在占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，避免服务器测试与正在运行的实例发生冲突。当之前的 Gateway 网关运行遗留端口 `18789` 被占用时，请使用此命令。 +- `pnpm test:coverage`：使用 V8 覆盖率运行单元测试套件（通过 `vitest.unit.config.ts`）。这是基于已加载文件的单元覆盖率门禁，而不是整个仓库的全文件覆盖率。阈值为 70% 的行数 / 函数 / 语句覆盖率，以及 55% 的分支覆盖率。由于 `coverage.all` 为 false，该门禁会统计被单元覆盖率套件加载的文件，而不是将所有拆分 lane 的源文件都视为未覆盖。 +- `pnpm test:coverage:changed`：仅对自 `origin/main` 以来发生变更的文件运行单元覆盖率。 +- `pnpm test:changed`：当 diff 只涉及可路由的源文件 / 测试文件时，将变更的 git 路径展开为有范围限制的 Vitest lanes。配置 / 设置变更仍会回退到原生根项目运行，以便在需要时对接线类修改进行更广泛的重跑。 +- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 触发了哪些架构 lanes。 +- `pnpm check:changed`：对相对于 `origin/main` 的 diff 运行智能变更门禁。它会将核心代码与核心测试 lanes 一起运行，将扩展工作与扩展测试 lanes 一起运行，仅测试变更则只运行测试类型检查 / 测试；将公开插件 SDK 或插件契约变更扩展到扩展验证；并让仅包含发布元数据的版本变更保持在有针对性的版本 / 配置 / 根依赖检查范围内。 +- `pnpm test`：通过有范围限制的 Vitest lanes 路由显式的文件 / 目录目标。未指定目标的运行会使用固定的分片组，并展开为叶子配置以便在本地并行执行；扩展组始终会展开为按扩展划分的分片配置，而不是一个巨大的根项目进程。 +- 完整运行和扩展分片运行会将本地耗时数据更新到 `.artifacts/vitest-shard-timings.json`；后续运行会使用这些耗时数据来平衡慢分片和快分片。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地耗时工件。 +- 部分 `plugin-sdk` 和 `commands` 测试文件现在会通过专用的轻量 lanes 路由，这些 lanes 仅保留 `test/setup.ts`，而运行时较重的用例仍保留在原有 lanes 上。 +- 部分 `plugin-sdk` 和 `commands` 辅助源文件也会将 `pnpm test:changed` 映射到这些轻量 lanes 中显式的同级测试，因此小型辅助函数改动无需重跑较重的、依赖运行时的测试套件。 +- `auto-reply` 现在也拆分为三个专用配置（`core`、`top-level`、`reply`），这样 reply harness 就不会压制较轻量的顶层状态 / token / helper 测试。 +- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用了共享的非隔离 runner。 - `pnpm test:channels` 运行 `vitest.channels.config.ts`。 -- `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 `：对已路由的 changed 模式路径与原生根项目运行进行基准比较，两者使用相同的已提交 git 差异。 -- `pnpm test:perf:changed:bench -- --worktree`：对当前工作区的变更集进行基准比较，无需先提交。 +- `pnpm test:extensions` 和 `pnpm test extensions` 运行所有扩展 / 插件分片。重量级渠道扩展和 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 模式路径与原生根项目运行进行基准对比。 +- `pnpm test:perf:changed:bench -- --worktree`：对当前工作树变更集进行基准测试，无需先提交。 - `pnpm test:perf:profile:main`：为 Vitest 主线程写入 CPU profile（`.artifacts/vitest-main-profile`）。 -- `pnpm test:perf:profile:runner`：为单元测试运行器写入 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。 +- `pnpm test:perf:profile:runner`：为单元 runner 写入 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。 - Gateway 网关集成：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 选择性启用。 -- `pnpm test:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS/HTTP/node 配对）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false` 与自适应 worker；可通过 `OPENCLAW_E2E_WORKERS=` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。 -- `pnpm test:live`：运行提供商实时测试（minimax/zai）。需要 API key，并且需要设置 `LIVE=1`（或提供商专用的 `*_LIVE_TEST=1`）来取消跳过。 -- `pnpm test:docker:all`：先各构建一次共享的实时测试镜像和 Docker E2E 镜像，然后默认以并发数 4 运行 Docker 冒烟测试通道，并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`。可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM=` 调整。对启动流程或提供商更敏感的通道会在并行池之后独占运行。每个通道的日志会写入 `.artifacts/docker-tests//`。 -- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的实时模型 key（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并且不像常规单元 / e2e 测试套件那样预期具有 CI 稳定性。 -- `pnpm test:docker:mcp-channels`：启动一个已注入种子数据的 Gateway 网关容器，以及第二个会生成 `openclaw mcp serve` 的客户端容器，然后通过真实的 stdio bridge 验证路由会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该冒烟测试反映的是 bridge 实际发出的内容。 +- `pnpm test:e2e`：运行 Gateway 网关端到端 smoke 测试（多实例 WS/HTTP/节点配对）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false`，并采用自适应 workers；可通过 `OPENCLAW_E2E_WORKERS=` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 获取详细日志。 +- `pnpm test:live`：运行提供商实时测试（minimax/zai）。需要 API keys 和 `LIVE=1`（或提供商专用的 `*_LIVE_TEST=1`）才能取消跳过。 +- `pnpm test:docker:all`：构建共享的实时测试镜像和 Docker E2E 镜像各一次，然后默认以并发数 4、并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 Docker smoke lanes。可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM=` 调整。除非设置了 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，否则 runner 会在首次失败后停止调度新的池化 lanes；每个 lane 默认有 120 分钟超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖。对启动或提供商敏感的 lanes 会在并行池之后以独占方式运行。每个 lane 的日志会写入 `.artifacts/docker-tests//`。 +- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的实时模型 key（例如在 `~/.profile` 中配置的 OpenAI），会拉取外部 Open WebUI 镜像，并不像常规单元 / e2e 测试套件那样预期具备 CI 稳定性。 +- `pnpm test:docker:mcp-channels`：启动一个已注入种子数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后验证经路由的会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及通过真实 stdio bridge 传输的 Claude 风格渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP frames，因此该 smoke 测试反映的是 bridge 实际发出的内容。 ## 本地 PR 门禁 -在本地执行 PR 合并 / 门禁检查时，请运行： +对于本地 PR 合并 / 门禁检查，请运行： - `pnpm check:changed` - `pnpm check` @@ -54,12 +54,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） +## 模型延迟基准（本地 keys） 脚本：[`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) @@ -69,12 +69,12 @@ x-i18n: - 可选环境变量：`MINIMAX_API_KEY`、`MINIMAX_BASE_URL`、`MINIMAX_MODEL`、`ANTHROPIC_API_KEY` - 默认提示词：“用一个单词回复：ok。不要使用标点或额外文本。” -最近一次运行（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) @@ -99,15 +99,15 @@ 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 采集使用的是同一个测试框架。 +输出内容包括每个命令的 `sampleCount`、平均值、p50、p95、最小值 / 最大值、exit-code / signal 分布，以及最大 RSS 汇总。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profiles，从而让耗时与 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` 会将目标 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： @@ -117,19 +117,19 @@ x-i18n: ## 新手引导 E2E（Docker） -Docker 是可选的；只有在需要容器化新手引导冒烟测试时才需要它。 +Docker 是可选项；仅在需要容器化新手引导 smoke 测试时才需要。 -在干净的 Linux 容器中执行完整冷启动流程： +在一个干净的 Linux 容器中执行完整的冷启动流程： ```bash scripts/e2e/onboard-docker.sh ``` -该脚本会通过 pseudo-tty 驱动交互式向导，验证 config/workspace/session 文件，然后启动 Gateway 网关并运行 `openclaw health`。 +该脚本会通过 pseudo-tty 驱动交互式向导，验证配置 / 工作区 / 会话文件，然后启动 Gateway 网关并运行 `openclaw health`。 -## QR 导入冒烟测试（Docker） +## QR 导入 smoke 测试（Docker） -确保 `qrcode-terminal` 能在受支持的 Docker Node 运行时下加载（默认 Node 24，兼容 Node 22）： +确保 `qrcode-terminal` 能在受支持的 Docker Node 运行时中加载（默认 Node 24，兼容 Node 22）： ```bash pnpm test:docker:qr