diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index e144e9b4a..8c2659863 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -1,75 +1,75 @@ --- read_when: - - 你需要了解 CI 作业为什么运行或未运行 + - 你需要了解某个 CI 作业为什么运行或没有运行 - 你正在调试一个失败的 GitHub Actions 检查 - - 你正在协调发布验证运行或重新运行 + - 你正在协调发布验证的运行或重新运行 summary: CI 作业图、范围门禁、发布总括流程和本地命令等效项 title: CI 流水线 x-i18n: - generated_at: "2026-05-01T23:10:03Z" + generated_at: "2026-05-01T23:38:35Z" model: gpt-5.5 provider: openai - source_hash: 4475dd906e2a7b7675a01ec72e7782f75ccbb4769bd0333c3f56acea9f343893 + source_hash: e3aeba9260d2eb6b65f1775d457f3dd7c5470ba628e9234409e3a8483a453b48 source_path: ci.md workflow: 16 --- -OpenClaw CI 会在每次推送到 `main` 以及每个拉取请求上运行。`preflight` 作业会对差异进行分类，并在仅不相关区域发生变化时关闭高成本流水线。手动 `workflow_dispatch` 运行会有意绕过智能范围限定，并为发布候选和广泛验证展开完整图。Android 流水线通过 `include_android` 保持选择性启用。仅发布使用的插件覆盖位于单独的 [`Plugin Prerelease`](#plugin-prerelease) 工作流中，并且只会从 [`Full Release Validation`](#full-release-validation) 或显式手动调度运行。 +OpenClaw CI 会在每次推送到 `main` 和每个拉取请求时运行。`preflight` 作业会对差异进行分类，并在仅有无关区域发生变化时关闭昂贵的执行路线。手动 `workflow_dispatch` 运行会有意绕过智能作用域，并为发布候选版本和广泛验证展开完整图。Android 路线通过 `include_android` 保持选择加入。仅发布用的插件覆盖位于单独的 [`插件预发布`](#plugin-prerelease) 工作流中，并且只会从 [`完整发布验证`](#full-release-validation) 或显式手动派发运行。 ## 流水线概览 | 作业 | 目的 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | 检测仅文档变更、变更范围、变更的扩展，并构建 CI 清单 | 始终在非草稿推送和 PR 上运行 | +| `preflight` | 检测仅文档变更、变更范围、变更扩展，并构建 CI 清单 | 始终在非草稿推送和 PR 上运行 | | `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 始终在非草稿推送和 PR 上运行 | -| `security-dependency-audit` | 针对 npm 公告执行无需安装依赖的生产 lockfile 审计 | 始终在非草稿推送和 PR 上运行 | -| `security-fast` | 快速安全作业所需的聚合项 | 始终在非草稿推送和 PR 上运行 | -| `check-dependencies` | 生产 Knip 仅依赖检查，以及未使用文件 allowlist 保护 | Node 相关变更 | -| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查，以及可复用下游产物 | Node 相关变更 | -| `checks-fast-core` | 快速 Linux 正确性流水线，例如内置/插件契约/协议检查 | Node 相关变更 | -| `checks-fast-contracts-channels` | 带稳定聚合检查结果的分片渠道契约检查 | Node 相关变更 | -| `checks-node-core-test` | Core Node 测试分片，不包括渠道、内置、契约和扩展流水线 | Node 相关变更 | -| `check` | 分片主本地门禁等效项：生产类型、lint、保护、测试类型和严格冒烟 | Node 相关变更 | -| `check-additional` | 架构、边界、扩展表面保护、包边界和 gateway-watch 分片 | Node 相关变更 | -| `build-smoke` | 已构建 CLI 冒烟测试和启动内存冒烟 | Node 相关变更 | -| `checks` | 构建产物渠道测试验证器 | Node 相关变更 | -| `checks-node-compat-node22` | Node 22 兼容性构建和冒烟流水线 | 发布用手动 CI 调度 | -| `check-docs` | 文档格式化、lint 和断链检查 | 文档变更 | -| `skills-python` | Python 支持的 Skills 的 Ruff + pytest | Python Skill 相关变更 | -| `checks-windows` | Windows 专属进程/路径测试，以及共享运行时导入说明符回归 | Windows 相关变更 | -| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试流水线 | macOS 相关变更 | +| `security-dependency-audit` | 针对 npm 安全公告进行无依赖的生产锁文件审计 | 始终在非草稿推送和 PR 上运行 | +| `security-fast` | 快速安全作业的必需聚合项 | 始终在非草稿推送和 PR 上运行 | +| `check-dependencies` | 仅生产 Knip 依赖检查，以及未使用文件 allowlist 守卫 | Node 相关变更 | +| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查和可复用的下游产物 | Node 相关变更 | +| `checks-fast-core` | 快速 Linux 正确性路线，例如内置/插件合约/协议检查 | Node 相关变更 | +| `checks-fast-contracts-channels` | 分片渠道合约检查，并提供稳定的聚合检查结果 | Node 相关变更 | +| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、内置、合约和扩展路线 | Node 相关变更 | +| `check` | 分片主本地门禁等价项：生产类型、lint、守卫、测试类型和严格 smoke | Node 相关变更 | +| `check-additional` | 架构、边界、扩展表面守卫、包边界和 gateway-watch 分片 | Node 相关变更 | +| `build-smoke` | 已构建 CLI smoke 测试和启动内存 smoke | Node 相关变更 | +| `checks` | 构建产物渠道测试的验证器 | Node 相关变更 | +| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke 路线 | 发布用手动 CI 派发 | +| `check-docs` | 文档格式、lint 和断链检查 | 文档变更 | +| `skills-python` | Python 支持的 Skills 的 Ruff + pytest | Python Skills 相关变更 | +| `checks-windows` | Windows 特定的进程/路径测试，以及共享运行时导入说明符回归测试 | Windows 相关变更 | +| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试路线 | macOS 相关变更 | | `macos-swift` | macOS 应用的 Swift lint、构建和测试 | macOS 相关变更 | -| `android` | 两种 flavor 的 Android 单元测试，以及一次 debug APK 构建 | Android 相关变更 | -| `test-performance-agent` | 在可信活动之后每日进行 Codex 慢测试优化 | Main CI 成功或手动调度 | +| `android` | 两个 flavor 的 Android 单元测试，以及一个 debug APK 构建 | Android 相关变更 | +| `test-performance-agent` | 受信活动后的每日 Codex 慢测试优化 | 主 CI 成功或手动派发 | ## 快速失败顺序 -1. `preflight` 决定哪些流水线会存在。`docs-scope` 和 `changed-scope` 逻辑是此作业中的步骤，而不是独立作业。 +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-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 +3. `build-artifacts` 会与快速 Linux 路线重叠运行，因此下游消费者可以在共享构建准备好后立即开始。 +4. 更重的平台和运行时路线会随后展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 -当同一 PR 或 `main` ref 上有较新的推送落地时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已被取代后继续排队。自动 CI 并发键带版本号（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸项无法无限期阻塞较新的 main 运行。手动全套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行的运行。 +当同一 PR 或 `main` ref 上有更新的推送落地时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则应将其视为 CI 噪音。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但在整个工作流已经被取代后不会继续排队。自动 CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 端旧队列组中的僵尸任务无法无限期阻塞较新的 main 运行。手动完整套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行的运行。 ## 范围和路由 -范围逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。手动调度会跳过 changed-scope 检测，并使 preflight 清单表现得像每个已限定范围的区域都发生了变化。 +范围逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。手动派发会跳过变更范围检测，并让 preflight 清单表现得像每个受作用域控制的区域都发生了变化。 -- **CI 工作流编辑**会验证 Node CI 图以及工作流 lint，但不会自行强制运行 Windows、Android 或 macOS 原生构建；这些平台流水线仍限定于平台源代码变更。 -- **仅 CI 路由编辑、选定的低成本 core-test fixture 编辑，以及窄范围插件契约辅助/测试路由编辑**使用快速 Node-only 清单路径：`preflight`、安全检查和单个 `checks-fast-core` 任务。当变更仅限于该快速任务直接覆盖的路由或辅助表面时，此路径会跳过构建产物、Node 22 兼容性、渠道契约、完整 core 分片、内置插件分片和附加保护矩阵。 -- **Windows Node 检查**限定于 Windows 专属进程/路径包装器、npm/pnpm/UI 运行器辅助工具、包管理器配置，以及执行该流水线的 CI 工作流表面；不相关的源代码、插件、install-smoke 和仅测试变更仍保留在 Linux Node 流水线上。 +- **CI 工作流编辑** 会验证 Node CI 图和工作流 lint，但本身不会强制运行 Windows、Android 或 macOS 原生构建；这些平台路线仍限定于平台源代码变更。 +- **仅 CI 路由编辑、选定的廉价核心测试 fixture 编辑，以及窄范围插件合约辅助/测试路由编辑** 使用快速的仅 Node 清单路径：`preflight`、安全检查和单个 `checks-fast-core` 任务。当变更仅限于该快速任务直接执行的路由或辅助表面时，此路径会跳过构建产物、Node 22 兼容性、渠道合约、完整核心分片、内置插件分片和额外守卫矩阵。 +- **Windows Node 检查** 限定于 Windows 特定的进程/路径 wrapper、npm/pnpm/UI runner 辅助工具、包管理器配置，以及执行该路线的 CI 工作流表面；无关源码、插件、安装 smoke 和仅测试变更会保留在 Linux Node 路线上。 -最慢的 Node 测试族会被拆分或平衡，使每个作业保持较小规模而不过度预留运行器：渠道契约作为三个加权分片运行，小型 core 单元流水线成对运行，auto-reply 作为四个平衡 worker 运行（reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片），agentic gateway/plugin 配置分布在现有仅源代码 agentic Node 作业中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用其专用 Vitest 配置，而不是共享插件总括项。include-pattern 分片使用 CI 分片名称记录计时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置和经过过滤的分片。`check-additional` 将 package-boundary 编译/canary 工作保持在一起，并将运行时拓扑架构与 gateway watch 覆盖分离；边界保护分片会在一个作业内并发运行其小型独立保护。Gateway watch、渠道测试和 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建后，在 `build-artifacts` 内并发运行。 +最慢的 Node 测试族会被拆分或均衡，让每个作业保持较小规模而不过度预留 runner：渠道合约作为三个加权分片运行，小型核心单元路线会配对，auto-reply 作为四个均衡 worker 运行（reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片），agentic gateway/插件配置会分散到现有的仅源码 agentic Node 作业中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享插件兜底配置。包含模式分片会使用 CI 分片名称记录计时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置和过滤后的分片。`check-additional` 将包边界编译/canary 工作放在一起，并将运行时拓扑架构与 gateway watch 覆盖分离；边界守卫分片会在一个作业内并发运行其小型独立守卫。Gateway 网关 watch、渠道测试和核心支持边界分片会在 `dist/` 和 `dist-runtime/` 已构建之后，在 `build-artifacts` 内并发运行。 -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。third-party flavor 没有单独的 source set 或 manifest；其单元测试流水线仍会使用 SMS/call-log BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关推送上重复执行 debug APK 打包作业。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；它的单元测试路线仍会使用 SMS/call-log BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关推送上重复执行 debug APK 打包作业。 -`check-dependencies` 分片会运行 `pnpm deadcode:dependencies`（生产 Knip 仅依赖检查，固定到最新 Knip 版本，并在 `dlx` 安装时禁用 pnpm 的最低发布年龄限制）和 `pnpm deadcode:unused-files`，后者会将 Knip 的生产未使用文件发现结果与 `scripts/deadcode-unused-files.allowlist.mjs` 比较。当 PR 添加新的未经审查的未使用文件，或留下过期 allowlist 条目时，未使用文件保护会失败，同时保留 Knip 无法静态解析的有意动态插件、生成内容、构建、live-test 和包桥接表面。 +`check-dependencies` 分片运行 `pnpm deadcode:dependencies`（仅生产 Knip 依赖检查，固定到最新 Knip 版本，并为 `dlx` 安装禁用 pnpm 的最小发布年龄）和 `pnpm deadcode:unused-files`，后者会将 Knip 的生产未使用文件发现结果与 `scripts/deadcode-unused-files.allowlist.mjs` 进行比较。当 PR 添加新的未经审查的未使用文件，或留下过期的 allowlist 条目时，未使用文件守卫会失败，同时保留 Knip 无法静态解析的有意动态插件、生成文件、构建、实时测试和包桥接表面。 -## 手动调度 +## 手动派发 -手动 CI 调度运行与普通 CI 相同的作业图，但会强制启用每个非 Android 范围流水线：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS 和 Control UI i18n。独立手动 CI 调度只有在 `include_android=true` 时才运行 Android；完整发布总控通过传入 `include_android=true` 启用 Android。插件预发布静态检查、仅发布的 `agentic-plugins` 分片、完整扩展批量扫查，以及插件预发布 Docker 流水线均不包含在 CI 中。Docker 预发布套件仅在 `Full Release Validation` 调度单独的 `Plugin Prerelease` 工作流并启用 release-validation 门禁时运行。 +手动 CI 派发运行与普通 CI 相同的作业图，但会强制启用所有非 Android 受作用域控制的路线：Linux Node 分片、内置插件分片、渠道合约、Node 22 兼容性、`check`、`check-additional`、构建 smoke、文档检查、Python Skills、Windows、macOS 和 Control UI i18n。独立手动 CI 派发只有在 `include_android=true` 时才运行 Android；完整发布总控会通过传递 `include_android=true` 来启用 Android。插件预发布静态检查、仅发布用的 `agentic-plugins` 分片、完整扩展批量扫描和插件预发布 Docker 路线会从 CI 中排除。Docker 预发布套件仅在 `Full Release Validation` 以启用发布验证门禁的方式派发单独的 `Plugin Prerelease` 工作流时运行。 -手动运行使用唯一的并发组，因此发布候选全套件不会被同一 ref 上的另一次推送或 PR 运行取消。可选的 `target_ref` 输入允许可信调用者在使用所选调度 ref 的工作流文件时，针对分支、标签或完整提交 SHA 运行该图。 +手动运行使用唯一的并发组，因此发布候选版本完整套件不会被同一 ref 上的另一个推送或 PR 运行取消。可选的 `target_ref` 输入允许受信调用方使用选定派发 ref 中的工作流文件，针对分支、标签或完整提交 SHA 运行该图。 ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -77,19 +77,19 @@ gh workflow run ci.yml --ref main -f target_ref= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -## 运行器 +## Runners -| 运行器 | 任务 | +| 运行器 | 作业 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`、快速安全任务和聚合任务（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速协议/契约/内置检查、分片渠道契约检查、除 lint 以外的 `check` 分片、`check-additional` 分片和聚合任务、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，因此 Blacksmith 矩阵可以更早排队 | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、较轻量的插件分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types` 和 `check-test-types` | +| `ubuntu-24.04` | `preflight`、快速安全作业和聚合项（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速协议/契约/内置检查、分片的渠道契约检查、除 lint 外的 `check` 分片、`check-additional` 分片和聚合项、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke 预检也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵可以更早排队 | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、较低权重的插件分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types` 和 `check-test-types` | | `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`（对 CPU 足够敏感，8 vCPU 的成本高于节省的时间）；install-smoke Docker 构建（32-vCPU 的排队时间成本高于节省的时间） | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`（对 CPU 足够敏感，8 vCPU 的成本高于节省的时间）；install-smoke Docker 构建（32 vCPU 的排队时间成本高于节省的时间） | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | | `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 回退到 `macos-latest` | | `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 回退到 `macos-latest` | -## 本地等效命令 +## 本地等价命令 ```bash pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD @@ -117,31 +117,31 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac ## 完整发布验证 -`Full Release Validation` 是用于“在发布前运行所有内容”的手动总括工作流。它接受分支、标签或完整 commit SHA，使用该目标分派手动 `CI` 工作流，分派 `Plugin Prerelease` 以进行仅发布相关的插件/包/静态/Docker 验证，并分派 `OpenClaw Release Checks` 以进行安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 通道。使用 `rerun_group=all` 和 `release_profile=full` 时，它还会针对发布检查中的 `release-package-under-test` 工件运行 `NPM Telegram Beta E2E`。发布后，传入 `npm_telegram_package_spec`，即可针对已发布的 npm 包重新运行同一个 Telegram 包通道。 +`Full Release Validation` 是“发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标调度手动 `CI` 工作流，为仅发布使用的插件/包/静态/Docker 证明调度 `Plugin Prerelease`，并为安装烟测、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 通道调度 `OpenClaw Release Checks`。使用 `rerun_group=all` 和 `release_profile=full` 时，它还会针对发布检查中的 `release-package-under-test` 制品运行 `NPM Telegram Beta E2E`。发布后，传入 `npm_telegram_package_spec`，即可针对已发布的 npm 包重新运行同一个 Telegram 包通道。 -请参阅[完整发布验证](/zh-CN/reference/full-release-validation)，了解阶段矩阵、确切工作流任务名称、配置文件差异、工件和聚焦重跑句柄。 +有关阶段矩阵、准确的工作流作业名称、配置文件差异、制品以及定向重跑句柄，请参见[完整发布验证](/zh-CN/reference/full-release-validation)。 -`release_profile` 控制传入发布检查的 live/提供商 覆盖范围。手动发布工作流默认使用 `stable`；只有在你有意需要更广的咨询型提供商/媒体矩阵时才使用 `full`。 +`release_profile` 控制传递给发布检查的 live/提供商覆盖范围。手动发布工作流默认使用 `stable`；仅当你有意需要广泛的建议性提供商/媒体矩阵时，才使用 `full`。 - `minimum` 保留最快的 OpenAI/核心发布关键通道。 - `stable` 添加稳定的提供商/后端集合。 -- `full` 运行更广的咨询型提供商/媒体矩阵。 +- `full` 运行广泛的建议性提供商/媒体矩阵。 -总括工作流会记录已分派的子运行 ID，最终的 `Verify full validation` 任务会重新检查当前子运行结论，并为每个子运行追加最慢任务表。如果某个子工作流被重跑并变为绿色，只需重跑父级验证器任务，即可刷新总括结果和耗时摘要。 +该总控会记录已调度子运行的 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流重跑后变绿，只需重新运行父验证器作业，即可刷新总控结果和耗时摘要。 -恢复时，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。对发布候选版本使用 `all`，仅对普通完整 CI 子流程使用 `ci`，仅对插件预发布子流程使用 `plugin-prerelease`，对每个发布子流程使用 `release-checks`，或在总括工作流中使用更窄的组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这样在进行聚焦修复后，失败的发布环境重跑会保持边界明确。 +对于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。对于发布候选使用 `all`，仅普通完整 CI 子项使用 `ci`，仅插件预发布子项使用 `plugin-prerelease`，每个发布子项使用 `release-checks`，也可以在总控上使用更窄的组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这样，在定向修复后，失败发布环境的重跑会保持有界。 -`OpenClaw Release Checks` 使用受信任的工作流 ref，将所选 ref 解析一次为 `release-package-under-test` tarball，然后把该工件传给 live/E2E 发布路径 Docker 工作流和包验收分片。这能让发布环境之间的包字节保持一致，并避免在多个子任务中重复打包同一个候选版本。 +`OpenClaw Release Checks` 使用受信任的工作流引用，将所选引用解析一次为 `release-package-under-test` tarball，然后将该制品传递给 live/E2E 发布路径 Docker 工作流和包验收分片。这会让发布环境之间的包字节保持一致，并避免在多个子作业中重复打包同一个候选版本。 -对于 `ref=main` 和 `rerun_group=all` 的重复 `Full Release Validation` 运行，会由较新的总括工作流取代较旧的总括工作流。父级监视器在父级被取消时，会取消它已经分派的任何子工作流，因此新的 main 验证不会被陈旧的两小时发布检查运行阻塞。发布分支/标签验证和聚焦重跑组会保持 `cancel-in-progress: false`。 +`ref=main` 且 `rerun_group=all` 的重复 `Full Release Validation` 运行会取代较早的总控。当父项被取消时，父监视器会取消它已调度的任何子工作流，因此较新的 main 验证不会被卡在陈旧的两小时发布检查运行之后。发布分支/标签验证和定向重跑组保留 `cancel-in-progress: false`。 ## Live 和 E2E 分片 -发布 live/E2E 子流程保留广泛的原生 `pnpm test:live` 覆盖，但它通过 `scripts/test-live-shard.mjs` 以命名分片运行，而不是作为一个串行任务运行： +发布 live/E2E 子项保留广泛的原生 `pnpm test:live` 覆盖，但它通过 `scripts/test-live-shard.mjs` 以具名分片运行，而不是作为单个串行作业运行： - `native-live-src-agents` - `native-live-src-gateway-core` -- 提供商过滤的 `native-live-src-gateway-profiles` 任务 +- 提供商过滤的 `native-live-src-gateway-profiles` 作业 - `native-live-src-gateway-backends` - `native-live-test` - `native-live-extensions-a-k` @@ -149,59 +149,61 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- 拆分的媒体音频/视频分片，以及提供商过滤的音乐分片 +- 拆分后的媒体音频/视频分片，以及提供商过滤的音乐分片 -这会保持相同的文件覆盖，同时让较慢的 live 提供商失败更容易重跑和诊断。聚合的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称仍可用于手动一次性重跑。 +这会保持相同的文件覆盖范围，同时让缓慢的 live 提供商失败更容易重跑和诊断。聚合 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称仍可用于手动一次性重跑。 -原生 live 媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预安装了 `ffmpeg` 和 `ffprobe`；媒体任务只会在设置前验证这些二进制文件。让 Docker 支撑的 live 套件继续在普通 Blacksmith 运行器上运行，容器任务并不适合启动嵌套 Docker 测试。 +原生 live 媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预安装 `ffmpeg` 和 `ffprobe`；媒体作业只在设置前验证这些二进制文件。将 Docker 支持的 live 套件保留在常规 Blacksmith 运行器上，容器作业并不适合启动嵌套 Docker 测试。 -Docker 支撑的 live 模型/后端分片会按所选 commit 使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:` 镜像。live 发布工作流会构建并推送该镜像一次，然后 Docker live 模型、按提供商分片的 Gateway 网关、CLI 后端、ACP bind 和 Codex harness 分片会使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。Gateway 网关 Docker 分片在脚本级携带显式 `timeout` 上限，低于工作流任务超时，因此卡住的容器或清理路径会快速失败，而不是耗尽整个发布检查预算。如果这些分片独立重建完整源码 Docker 目标，则说明发布运行配置错误，并会在重复镜像构建上浪费总耗时。 +Docker 支持的 live 模型/后端分片会为每个所选提交使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:` 镜像。live 发布工作流会构建并推送该镜像一次，然后 Docker live 模型、按提供商分片的 Gateway 网关、CLI 后端、ACP 绑定和 Codex harness 分片会以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。Gateway 网关 Docker 分片带有显式脚本级 `timeout` 上限，低于工作流作业超时，因此卡住的容器或清理路径会快速失败，而不是消耗整个发布检查预算。如果这些分片独立重建完整源 Docker 目标，则说明发布运行配置错误，并会在重复镜像构建上浪费实际耗时。 ## 包验收 -当问题是“这个可安装的 OpenClaw 包是否能作为产品正常工作？”时，使用 `Package Acceptance`。它不同于普通 CI：普通 CI 验证源码树，而包验收会通过用户安装或更新后实际使用的同一 Docker E2E harness 来验证单个 tarball。 +当问题是“这个可安装的 OpenClaw 包作为产品是否能工作？”时，使用 `Package Acceptance`。它不同于普通 CI：普通 CI 验证源代码树，而包验收会通过用户安装或更新后实际使用的同一个 Docker E2E harness 来验证单个 tarball。 -### 任务 +### 作业 -1. `resolve_package` 检出 `workflow_ref`，解析一个包候选项，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者作为 `package-under-test` artifact 上传，并在 GitHub 步骤摘要中打印来源、工作流 ref、包 ref、版本、SHA-256 和配置文件。 -2. `docker_acceptance` 调用 `openclaw-live-and-e2e-checks-reusable.yml`，并传入 `ref=workflow_ref` 和 `package_artifact_name=package-under-test`。可复用工作流会下载该 artifact，验证 tarball 清单，在需要时准备包摘要 Docker 镜像，并针对该包运行所选 Docker lane，而不是打包工作流检出内容。当某个配置文件选择多个定向 `docker_lanes` 时，可复用工作流会先准备一次包和共享镜像，然后将这些 lane 扇出为并行定向 Docker 作业，并使用唯一 artifact。 -3. `package_telegram` 可选择性调用 `NPM Telegram Beta E2E`。它会在 `telegram_mode` 不是 `none` 时运行，并在包验收已解析出包时安装相同的 `package-under-test` artifact；独立 Telegram 分发仍可安装已发布的 npm 规格。 -4. 如果包解析、Docker 验收或可选 Telegram lane 失败，`summary` 会使工作流失败。 +1. `resolve_package` 检出 `workflow_ref`，解析一个包候选，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者都作为 `package-under-test` 构件上传，并在 GitHub 步骤摘要中打印来源、工作流引用、包引用、版本、SHA-256 和配置文件。 +2. `docker_acceptance` 使用 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 调用 `openclaw-live-and-e2e-checks-reusable.yml`。这个可复用工作流会下载该构件，验证 tarball 清单，在需要时准备包摘要 Docker 镜像，并针对该包运行所选 Docker 通道，而不是打包工作流检出的内容。当某个配置文件选择多个目标 `docker_lanes` 时，可复用工作流会先准备一次包和共享镜像，然后将这些通道分发为并行的目标 Docker 作业，并生成唯一构件。 +3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时运行；如果包验收已解析出一个包，它会安装同一个 `package-under-test` 构件；独立 Telegram 分发仍可安装已发布的 npm 规格。 +4. `summary` 会在包解析、Docker 验收或可选 Telegram 通道失败时使工作流失败。 ### 候选来源 -- `source=npm` 只接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。将它用于已发布 beta/稳定版验收。 -- `source=ref` 会打包受信任的 `package_ref` 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支/标签，验证所选提交可从仓库分支历史或发布标签访问，在分离 worktree 中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。 -- `source=url` 下载 HTTPS `.tgz`；必须提供 `package_sha256`。 -- `source=artifact` 从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 是可选项，但对于外部共享 artifact 应提供它。 +- `source=npm` 仅接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta/稳定版验收。 +- `source=ref` 打包受信任的 `package_ref` 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支/标签，验证所选提交可从仓库分支历史或发布标签到达，在分离工作树中安装依赖，并用 `scripts/package-openclaw-for-docker.mjs` 打包。 +- `source=url` 下载 HTTPS `.tgz`；`package_sha256` 为必填。 +- `source=artifact` 从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 为可选，但外部共享构件应提供。 -保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的受信任工作流/测试框架代码。`package_ref` 是 `source=ref` 时会被打包的源提交。这样当前测试框架就可以验证较旧的受信任源提交，而无需运行旧的工作流逻辑。 +保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的受信任工作流/测试框架代码。`package_ref` 是 `source=ref` 时会被打包的源提交。这样当前测试框架就能验证较旧的受信任源提交，而无需运行旧的工作流逻辑。 ### 套件配置文件 - `smoke` — `npm-onboard-channel-agent`、`gateway-network`、`config-reload` - `package` — `npm-onboard-channel-agent`、`doctor-switch`、`update-channel-switch`、`upgrade-survivor`、`published-upgrade-survivor`、`plugins-offline`、`plugin-update` -- `product` — `package` 加上 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui` -- `full` — 包含 OpenWebUI 的完整 Docker 发布路径分块 +- `product` — `package` 加 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui` +- `full` — 带 OpenWebUI 的完整 Docker 发布路径分块 - `custom` — 精确的 `docker_lanes`；当 `suite_profile=custom` 时必填 -`package` 配置文件使用离线插件覆盖，因此已发布包验证不会被实时 ClawHub 可用性阻塞。可选 Telegram lane 会在 `NPM Telegram Beta E2E` 中复用 `package-under-test` artifact，并保留已发布 npm 规格路径用于独立分发。 +`package` 配置文件使用离线插件覆盖，因此已发布包验证不会受实时 ClawHub 可用性的限制。可选 Telegram 通道会在 `NPM Telegram Beta E2E` 中复用 `package-under-test` 构件，同时为独立分发保留已发布 npm 规格路径。 -有关专用的更新和插件测试策略，包括本地命令、Docker lane、包验收输入、发布默认值和失败分类，请参阅[更新和插件测试](/zh-CN/help/testing-updates-plugins)。 +有关专门的更新和插件测试策略，包括本地命令、 +Docker 通道、包验收输入、发布默认值和失败分诊， +请参阅[更新和插件测试](/zh-CN/help/testing-updates-plugins)。 -发布检查会使用 `source=artifact`、准备好的发布包 artifact、`suite_profile=custom`、`docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`、`published_upgrade_survivor_baselines=release-history`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai` 调用包验收。这会让包迁移、更新、过期插件依赖清理、离线插件、插件更新和 Telegram 证明都基于同一个已解析的包 tarball。跨 OS 发布检查仍会覆盖特定 OS 的新手引导、安装器和平台行为；包/更新产品验证应从包验收开始。`published-upgrade-survivor` Docker lane 每次运行验证一个已发布包基线。在包验收中，已解析的 `package-under-test` tarball 始终是候选项，而 `published_upgrade_survivor_baseline` 选择回退的已发布基线，默认值为 `openclaw@latest`；失败 lane 的重跑命令会保留该基线。设置 `published_upgrade_survivor_baselines=release-history` 可将该 lane 扩展到去重后的历史矩阵：最新六个稳定版本、`2026.4.23`，以及 `2026-03-15` 之前的最新稳定版本。设置 `published_upgrade_survivor_scenarios=reported-issues` 可将相同基线扩展到面向 issue 形态的 fixture，覆盖 Feishu 配置、保留的 bootstrap/persona 文件、波浪号日志路径，以及过期旧版插件依赖根。本地聚合运行可以通过 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 传入精确包规格，也可以通过 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 保持单个 lane，例如 `openclaw@2026.4.15`，或设置 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 以使用场景矩阵。已发布 lane 会使用内置的 `openclaw config set` 命令配方配置基线，在 `summary.json` 中记录配方步骤，并在 Gateway 网关启动后探测 `/healthz`、`/readyz` 以及 RPC Status。Windows 打包和安装器全新 lane 还会验证已安装的包可以从原始绝对 Windows 路径导入 browser-control override。OpenAI 跨 OS agent-turn 冒烟测试在设置时默认使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.5`，因此安装和 Gateway 网关证明会保持在首选的 GPT-5 测试模型上。 +发布检查会使用 `source=artifact`、已准备好的发布包构件、`suite_profile=custom`、`docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`、`published_upgrade_survivor_baselines=release-history`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai` 调用包验收。这会让包迁移、更新、过时插件依赖清理、离线插件、插件更新和 Telegram 证明都基于同一个已解析的包 tarball。跨操作系统发布检查仍覆盖特定操作系统的新手引导、安装程序和平台行为；包/更新产品验证应从包验收开始。`published-upgrade-survivor` Docker 通道每次运行验证一个已发布包基线。在包验收中，已解析的 `package-under-test` tarball 始终是候选包，而 `published_upgrade_survivor_baseline` 会选择回退的已发布基线，默认为 `openclaw@latest`；失败通道重跑命令会保留该基线。设置 `published_upgrade_survivor_baselines=release-history` 可将通道扩展到去重后的历史矩阵：最新六个稳定版本、`2026.4.23`，以及 `2026-03-15` 之前的最新稳定版本。设置 `published_upgrade_survivor_scenarios=reported-issues` 可将同一组基线扩展到问题形态的夹具，覆盖 Feishu 配置、保留的引导/人设文件、波浪号日志路径，以及过时旧版插件依赖根。单独的 `Update Migration` 工作流会在问题是穷尽式已发布更新清理，而不是常规完整发布 CI 广度时，使用带 `all-since-2026.4.23` 和 `plugin-deps-cleanup` 的 `update-migration` Docker 通道。本地聚合运行可以用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 传入精确包规格，也可以用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 保持单一通道，例如 `openclaw@2026.4.15`，或设置 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 来启用场景矩阵。已发布通道使用内置的 `openclaw config set` 命令配方配置基线，在 `summary.json` 中记录配方步骤，并在 Gateway 网关启动后探测 `/healthz`、`/readyz` 和 RPC Status。Windows 打包和安装程序全新安装通道还会验证，已安装的包可以从原始绝对 Windows 路径导入浏览器控制覆盖项。OpenAI 跨操作系统智能体回合冒烟测试在设置 `OPENCLAW_CROSS_OS_OPENAI_MODEL` 时默认使用该值，否则使用 `openai/gpt-5.5`，因此安装和 Gateway 网关证明会保持在首选的 GPT-5 测试模型上。 ### 旧版兼容窗口 -包验收为已发布包设置了有界旧版兼容窗口。直到 `2026.4.25` 的包，包括 `2026.4.25-beta.*`，都可以使用兼容路径： +包验收对已发布包有有界的旧版兼容窗口。直到 `2026.4.25` 的包，包括 `2026.4.25-beta.*`，可以使用兼容路径： -- `dist/postinstall-inventory.json` 中已知的私有 QA 条目可以指向 tarball 省略的文件； -- 当包没有公开 `gateway install --wrapper` 标志时，`doctor-switch` 可以跳过其持久化子用例； -- `update-channel-switch` 可以从 tarball 派生的假 git fixture 中剪除缺失的 `pnpm.patchedDependencies`，并可以记录缺失的持久化 `update.channel`； -- 插件冒烟测试可以读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化； -- `plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。 +- `dist/postinstall-inventory.json` 中已知的私有 QA 条目可以指向 tarball 中省略的文件； +- 当包未暴露 `gateway install --wrapper` 标志时，`doctor-switch` 可以跳过该持久化子用例； +- `update-channel-switch` 可以从基于 tarball 生成的伪 git 夹具中删减缺失的 `pnpm.patchedDependencies`，并可以记录缺失的持久化 `update.channel`； +- 插件冒烟测试可以读取旧版安装记录位置，或接受缺失的市场安装记录持久化； +- `plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重装行为保持不变。 -已发布的 `2026.4.26` 包也可能对已经发布的本地构建元数据戳文件发出警告。更晚的包必须满足现代契约；相同条件会失败，而不是警告或跳过。 +已发布的 `2026.4.26` 包也可以对已经发布的本地构建元数据戳文件发出警告。更晚的包必须满足现代契约；相同条件会失败，而不是警告或跳过。 ### 示例 @@ -244,152 +246,152 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -调试失败的包验收运行时，请从 `resolve_package` 摘要开始，确认包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker artifact：`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane 日志、阶段耗时和重跑命令。优先重跑失败的包配置文件或精确 Docker lane，而不是重跑完整发布验证。 +调试失败的包验收运行时，请先查看 `resolve_package` 摘要，确认包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker 构件：`.artifacts/docker-tests/**/summary.json`、`failures.json`、通道日志、阶段耗时和重跑命令。优先重跑失败的包配置文件或精确 Docker 通道，而不是重跑完整发布验证。 ## 安装冒烟测试 -独立的 `Install Smoke` 工作流通过自己的 `preflight` 作业复用相同的范围脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。 +单独的 `Install Smoke` 工作流会通过自己的 `preflight` 作业复用同一个范围脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。 -- **快速路径**会在 pull request 触及 Docker/包表面、内置插件包/清单变更，或 Docker 冒烟作业会覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面时运行。仅源代码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI 冒烟测试，运行容器 gateway-network e2e，验证内置 extension 构建参数，并在 240 秒聚合命令超时下运行有界内置插件 Docker 配置文件（每个场景的 Docker 运行分别设置上限）。 -- **完整路径**会为夜间计划运行、手动分发、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的 pull request 保留 QR 包安装和安装器 Docker/更新覆盖。在完整模式中，install-smoke 会准备或复用一个目标 SHA GHCR 根 Dockerfile 冒烟镜像，然后将 QR 包安装、根 Dockerfile/Gateway 网关冒烟测试、安装器/更新冒烟测试，以及快速内置插件 Docker E2E 作为单独作业运行，这样安装器工作就不会被根镜像冒烟测试阻塞。 +- **快速路径**会在拉取请求触及 Docker/包表面、内置插件包/清单变更，或 Docker 冒烟作业会执行的核心插件/渠道/Gateway 网关/插件 SDK 表面时运行。仅源代码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents 删除共享工作区 CLI 冒烟测试，运行容器 `gateway-network` e2e，验证内置扩展构建参数，并在 240 秒聚合命令超时内运行有界的内置插件 Docker 配置文件（每个场景的 Docker 运行会单独封顶）。 +- **完整路径**为夜间计划运行、手动分发、工作流调用发布检查，以及确实触及安装程序/包/Docker 表面的拉取请求保留 QR 包安装和安装程序 Docker/更新覆盖。在完整模式下，install-smoke 会准备或复用一个目标 SHA GHCR 根 Dockerfile 冒烟镜像，然后将 QR 包安装、根 Dockerfile/Gateway 网关冒烟测试、安装程序/更新冒烟测试，以及快速内置插件 Docker E2E 作为单独作业运行，因此安装程序工作不会等待根镜像冒烟测试完成。 -`main` 推送（包括合并提交）不会强制使用完整路径；当变更范围逻辑会在推送上请求完整覆盖时，工作流会保留快速 Docker 冒烟测试，并将完整安装冒烟测试留给夜间或发布验证。 +`main` 推送（包括合并提交）不会强制完整路径；当变更范围逻辑会在推送上请求完整覆盖时，工作流会保留快速 Docker 冒烟测试，并将完整安装冒烟测试留给夜间或发布验证。 -较慢的 Bun 全局安装 image-provider 冒烟测试由 `run_bun_global_install_smoke` 单独控制。它会在夜间计划和发布检查工作流中运行，手动 `Install Smoke` 分发也可以选择加入它，但 pull request 和 `main` 推送不会运行它。QR 和安装器 Docker 测试保留各自面向安装的 Dockerfile。 +较慢的 Bun 全局安装镜像提供商冒烟测试由 `run_bun_global_install_smoke` 单独控制。它会在夜间计划和发布检查工作流中运行，手动 `Install Smoke` 分发可以选择启用它，但拉取请求和 `main` 推送不会运行。QR 和安装程序 Docker 测试保留各自面向安装的 Dockerfile。 ## 本地 Docker E2E -`pnpm test:docker:all` 会预构建一个共享实时测试镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像： +`pnpm test:docker:all` 会预构建一个共享实时测试镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享 `scripts/e2e/Dockerfile` 镜像： -- 用于安装器/更新/插件依赖 lane 的裸 Node/Git runner； -- 将相同 tarball 安装到 `/app` 的功能镜像，用于正常功能 lane。 +- 用于安装程序/更新/插件依赖通道的裸 Node/Git runner； +- 一个功能镜像，它会将同一个 tarball 安装到 `/app`，用于常规功能通道。 -Docker lane 定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，runner 只执行所选计划。调度器使用 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每个 lane 选择镜像，然后通过 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 lane。 +Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，runner 只执行所选计划。调度器通过 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 按通道选择镜像，然后使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行通道。 ### 可调参数 -| 变量 | 默认值 | 用途 | -| -------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 普通执行通道的主池槽位数量。 | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | 对提供商敏感的尾池槽位数量。 | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | 并发实时执行通道上限，避免提供商限流。 | -| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 并发 npm install 执行通道上限。 | -| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 并发多服务执行通道上限。 | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | 执行通道启动之间的错峰间隔，用于避免 Docker 守护进程创建风暴；设置为 `0` 表示不使用错峰。 | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | 每个执行通道的兜底超时（120 分钟）；选定的实时/尾部执行通道使用更严格的上限。 | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | 未设置 | `1` 会打印调度器计划而不运行执行通道。 | -| `OPENCLAW_DOCKER_ALL_LANES` | 未设置 | 逗号分隔的精确执行通道列表；跳过清理冒烟测试，以便智能体复现单个失败的执行通道。 | +| 变量 | 默认值 | 用途 | +| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 普通泳道的主池槽位数。 | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | 对提供商敏感的尾池槽位数。 | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | 并发实时泳道上限，避免提供商限流。 | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 并发 npm 安装泳道上限。 | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 并发多服务泳道上限。 | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | 泳道启动之间的错峰间隔，用于避免 Docker 守护进程创建风暴；设置为 `0` 表示不使用错峰。 | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | 每泳道的回退超时（120 分钟）；选定的实时/尾部泳道使用更严格的上限。 | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | 未设置 | `1` 会打印调度器计划而不运行泳道。 | +| `OPENCLAW_DOCKER_ALL_LANES` | 未设置 | 逗号分隔的精确泳道列表；跳过清理冒烟测试，以便智能体复现某个失败泳道。 | -比其有效上限更重的执行通道仍可从空池启动，然后独占运行直到释放容量。本地聚合流程会预检 Docker，移除陈旧的 OpenClaw E2E 容器，输出活动执行通道 Status，持久化执行通道耗时以便按最长优先排序，并且默认在第一次失败后停止调度新的池化执行通道。 +超过其有效上限的泳道仍可从空池启动，然后独占运行，直到释放容量。本地聚合会预检 Docker、移除陈旧的 OpenClaw E2E 容器、发出活动泳道状态、持久化泳道耗时以便按最长优先排序，并且默认在第一次失败后停止调度新的池化泳道。 ### 可复用的实时/E2E 工作流 -可复用的实时/E2E 工作流会询问 `scripts/test-docker-all.mjs --plan-json` 需要哪些包、镜像种类、实时镜像、执行通道和凭证覆盖范围。随后 `scripts/docker-e2e.mjs` 会把该计划转换为 GitHub 输出和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，下载当前运行的包构件，或从 `package_artifact_run_id` 下载包构件；校验 tarball 清单；当计划需要已安装包的执行通道时，通过 Blacksmith 的 Docker 层缓存构建并推送带有包摘要标签的 bare/functional GHCR Docker E2E 镜像；并且在提供了 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或已有包摘要镜像时复用它们，而不是重新构建。Docker 镜像拉取会使用每次尝试 180 秒的有界超时进行重试，因此卡住的 registry/cache 流会快速重试，而不是消耗 CI 关键路径的大部分时间。 +可复用的实时/E2E 工作流会询问 `scripts/test-docker-all.mjs --plan-json` 需要哪些包、镜像类型、实时镜像、泳道和凭证覆盖范围。随后 `scripts/docker-e2e.mjs` 会把该计划转换为 GitHub 输出和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，下载当前运行的包构件，或从 `package_artifact_run_id` 下载包构件；验证 tarball 清单；当计划需要已安装包的泳道时，通过 Blacksmith 的 Docker 层缓存构建并推送带包摘要标签的裸/功能性 GHCR Docker E2E 镜像；并复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或现有的包摘要镜像，而不是重新构建。Docker 镜像拉取会在每次尝试时使用有界的 180 秒超时重试，因此卡住的注册表/缓存流会快速重试，而不会消耗 CI 关键路径的大部分时间。 ### 发布路径分块 -发布 Docker 覆盖使用更小的分块任务运行，并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`，这样每个分块只拉取它需要的镜像种类，并通过同一个加权调度器执行多个执行通道： +发布 Docker 覆盖运行更小的分块作业，并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`，因此每个分块只拉取其所需的镜像类型，并通过同一个加权调度器执行多个泳道： - `OPENCLAW_DOCKER_ALL_PROFILE=release-path` - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h` -当前发布 Docker 分块包括 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`，以及从 `plugins-runtime-install-a` 到 `plugins-runtime-install-h`。`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍然是聚合的插件/运行时别名。`install-e2e` 执行通道别名仍然是两个提供商安装器执行通道的聚合手动重跑别名。 +当前的发布 Docker 分块包括 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`，以及从 `plugins-runtime-install-a` 到 `plugins-runtime-install-h`。`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍是聚合的插件/运行时别名。`install-e2e` 泳道别名仍是两个提供商安装器泳道的聚合手动重跑别名。 -当完整发布路径覆盖请求 OpenWebUI 时，OpenWebUI 会折入 `plugins-runtime-services`，并且仅在只调度 OpenWebUI 时保留独立的 `openwebui` 分块。内置渠道更新执行通道会对临时 npm 网络失败重试一次。 +当完整的发布路径覆盖请求 OpenWebUI 时，OpenWebUI 会并入 `plugins-runtime-services`，并且只有在仅分发 OpenWebUI 时才保留独立的 `openwebui` 分块。内置渠道更新泳道会针对短暂的 npm 网络失败重试一次。 -每个分块都会上传 `.artifacts/docker-tests/`，其中包含执行通道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢执行通道表，以及每个执行通道的重跑命令。工作流 `docker_lanes` 输入会针对已准备好的镜像运行选定执行通道，而不是运行分块任务，这样可以把失败执行通道的调试限制在一个有针对性的 Docker 任务中，并为该次运行准备、下载或复用包构件；如果选定执行通道是实时 Docker 执行通道，则有针对性的任务会为该次重跑在本地构建实时测试镜像。生成的每个执行通道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和已准备好的镜像输入，因此失败的执行通道可以复用失败运行中的精确包和镜像。 +每个分块都会上传 `.artifacts/docker-tests/`，其中包含泳道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢泳道表，以及每泳道重跑命令。工作流的 `docker_lanes` 输入会针对已准备的镜像运行选定泳道，而不是运行分块作业，这使失败泳道调试限定在一个目标 Docker 作业内，并为该次运行准备、下载或复用包构件；如果选定泳道是实时 Docker 泳道，则目标作业会为该次重跑在本地构建实时测试镜像。生成的每泳道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和已准备的镜像输入，因此失败泳道可以复用失败运行中的确切包和镜像。 ```bash -pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands -pnpm test:docker:timings # slow-lane and phase critical-path summaries +pnpm test:docker:rerun # 下载 Docker 构件并打印组合/每泳道目标重跑命令 +pnpm test:docker:timings # 慢泳道和阶段关键路径摘要 ``` -计划的实时/E2E 工作流每天运行完整发布路径 Docker 套件。 +计划的实时/E2E 工作流每天运行完整的发布路径 Docker 套件。 ## 插件预发布 -`Plugin Prerelease` 是更昂贵的产品/包覆盖，因此它是由 `Full Release Validation` 或显式操作员调度的独立工作流。普通拉取请求、`main` 推送和单独的手动 CI 调度都会关闭该套件。它会在八个扩展 worker 之间平衡内置插件测试；这些扩展分片任务一次最多运行两个插件配置组，每组一个 Vitest worker，并使用更大的 Node 堆，因此导入密集型插件批次不会创建额外的 CI 任务。仅用于发布的 Docker 预发布路径会以小组批处理有针对性的 Docker 执行通道，避免为一到三分钟的任务预留几十个 runner。 +`Plugin Prerelease` 是成本更高的产品/包覆盖，因此它是一个单独的工作流，由 `Full Release Validation` 或明确的操作员触发。普通拉取请求、`main` 推送和独立的手动 CI 分发都不会启用该套件。它会在八个扩展工作器之间均衡内置插件测试；这些扩展分片作业一次最多运行两个插件配置组，每组使用一个 Vitest 工作器和更大的 Node 堆，这样导入密集的插件批次就不会创建额外的 CI 作业。仅发布的 Docker 预发布路径会把目标 Docker 泳道按小组批处理，以避免为一到三分钟的作业预留几十个运行器。 ## QA Lab -QA Lab 在主智能作用域工作流之外有专用 CI 执行通道。 +QA Lab 在主智能范围工作流之外有专用 CI 泳道。 -- `Parity gate` 工作流会在匹配的 PR 变更和手动调度时运行；它会构建私有 QA 运行时，并比较模拟 GPT-5.5 与 Opus 4.6 智能体包。 -- `QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，也可手动调度；它会将模拟 parity gate、实时 Matrix 执行通道，以及实时 Telegram 和 Discord 执行通道展开为并行任务。实时任务使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex leases。 +- `Parity gate` 工作流会在匹配的 PR 变更和手动分发时运行；它会构建私有 QA 运行时，并比较模拟 GPT-5.5 和 Opus 4.6 的智能体包。 +- `QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，也可手动分发；它会将模拟一致性门、实时 Matrix 泳道，以及实时 Telegram 和 Discord 泳道作为并行作业展开。实时作业使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex 租约。 -发布检查会使用确定性模拟提供商和符合模拟要求的模型（`mock-openai/gpt-5.5` 与 `mock-openai/gpt-5.5-alt`）运行 Matrix 与 Telegram 实时传输执行通道，从而将渠道契约与实时模型延迟和普通提供商插件启动隔离。实时传输 Gateway 网关会禁用记忆搜索，因为 QA parity 会单独覆盖记忆行为；提供商连接性由单独的实时模型、原生提供商和 Docker 提供商套件覆盖。 +发布检查会使用确定性模拟提供商和模拟限定模型（`mock-openai/gpt-5.5` 与 `mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram 实时传输泳道，因此渠道契约会与实时模型延迟和普通提供商插件启动隔离。实时传输 Gateway 网关会禁用记忆搜索，因为 QA 一致性会单独覆盖记忆行为；提供商连接性由单独的实时模型、原生提供商和 Docker 提供商套件覆盖。 -Matrix 在计划任务和发布门禁中使用 `--profile fast`，并且仅在检出的 CLI 支持时添加 `--fail-fast`。CLI 默认值和手动工作流输入仍然是 `all`；手动 `matrix_profile=all` 调度始终会把完整 Matrix 覆盖分片为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 任务。 +Matrix 在计划门和发布门中使用 `--profile fast`，并且仅当检出的 CLI 支持时才添加 `--fail-fast`。CLI 默认值和手动工作流输入仍为 `all`；手动 `matrix_profile=all` 分发始终会把完整 Matrix 覆盖分片为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。 -`OpenClaw Release Checks` 也会在发布批准前运行发布关键的 QA Lab 执行通道；它的 QA parity gate 会把候选包和基线包作为并行执行通道任务运行，然后把两个构件下载到一个小型报告任务中，用于最终 parity 比较。 +`OpenClaw Release Checks` 也会在发布批准前运行发布关键的 QA Lab 泳道；其 QA 一致性门会将候选包和基线包作为并行泳道作业运行，然后把两个构件下载到一个小型报告作业中，用于最终一致性比较。 -除非变更确实触及 QA 运行时、模型包 parity，或 parity 工作流拥有的表面，否则不要把 PR 落地路径置于 `Parity gate` 之后。对于普通渠道、配置、文档或单元测试修复，将其视为可选信号，并遵循作用域内 CI/检查证据。 +不要把 PR 落地路径置于 `Parity gate` 之后，除非该变更确实触及 QA 运行时、模型包一致性，或一致性工作流拥有的表面。对于普通渠道、配置、文档或单元测试修复，应将其视为可选信号，并遵循有范围的 CI/检查证据。 ## CodeQL -`CodeQL` 工作流有意作为狭窄的第一轮安全扫描器，而不是完整仓库扫描。每日、手动和非草稿拉取请求守护运行会扫描 Actions 工作流代码，以及最高风险的 JavaScript/TypeScript 表面，并使用过滤到高/严重 `security-severity` 的高置信安全查询。 +`CodeQL` 工作流有意作为一个窄范围的第一轮安全扫描器，而不是完整仓库扫描。每日、手动和非草稿拉取请求守护运行会扫描 Actions 工作流代码，以及最高风险的 JavaScript/TypeScript 表面，并使用高置信度安全查询过滤到高/关键 `security-severity`。 -拉取请求守护保持轻量：它只会在 `.github/actions`、`.github/codeql`、`.github/workflows`、`packages` 或 `src` 下发生变更时启动，并运行与计划工作流相同的高置信安全矩阵。Android 和 macOS CodeQL 不包含在 PR 默认项中。 +拉取请求守护保持轻量：它只会针对 `.github/actions`、`.github/codeql`、`.github/workflows`、`packages` 或 `src` 下的变更启动，并运行与计划工作流相同的高置信度安全矩阵。Android 和 macOS CodeQL 不在 PR 默认范围内。 ### 安全类别 | 类别 | 表面 | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-security-high/core-auth-secrets` | 认证、密钥、沙箱、cron 和 Gateway 网关基线 | -| `/codeql-security-high/channel-runtime-boundary` | 核心渠道实现契约，以及渠道插件运行时、Gateway 网关、插件 SDK、密钥、审计触点 | -| `/codeql-security-high/network-ssrf-boundary` | 核心 SSRF、IP 解析、网络防护、web-fetch，以及插件 SDK SSRF 策略表面 | -| `/codeql-security-high/mcp-process-tool-boundary` | MCP 服务器、进程执行 helper、出站投递，以及智能体工具执行门禁 | -| `/codeql-security-high/plugin-trust-boundary` | 插件安装、加载器、manifest、registry、包管理器安装、源码加载，以及插件 SDK 包契约信任表面 | +| `/codeql-security-high/core-auth-secrets` | 身份验证、密钥、沙箱、cron 和 Gateway 网关基线 | +| `/codeql-security-high/channel-runtime-boundary` | 核心渠道实现契约，以及渠道插件运行时、Gateway 网关、插件 SDK、密钥、审计接触点 | +| `/codeql-security-high/network-ssrf-boundary` | 核心 SSRF、IP 解析、网络保护、web-fetch 和插件 SDK SSRF 策略表面 | +| `/codeql-security-high/mcp-process-tool-boundary` | MCP 服务器、进程执行辅助工具、出站交付和智能体工具执行门 | +| `/codeql-security-high/plugin-trust-boundary` | 插件安装、加载器、清单、注册表、包管理器安装、源加载和插件 SDK 包契约信任表面 | ### 平台特定安全分片 -- `CodeQL Android Critical Security` — 计划运行的 Android 安全分片。在 workflow sanity 接受的最小 Blacksmith Linux runner 上为 CodeQL 手动构建 Android 应用。上传到 `/codeql-critical-security/android` 下。 -- `CodeQL macOS Critical Security` — 每周/手动 macOS 安全分片。在 Blacksmith macOS 上为 CodeQL 手动构建 macOS 应用，从上传的 SARIF 中过滤掉依赖构建结果，并上传到 `/codeql-critical-security/macos` 下。它保留在每日默认项之外，因为即使干净时，macOS 构建也会主导运行时间。 +- `CodeQL Android Critical Security` — 计划的 Android 安全分片。在工作流完整性检查接受的最小 Blacksmith Linux 运行器上，为 CodeQL 手动构建 Android 应用。上传到 `/codeql-critical-security/android`。 +- `CodeQL macOS Critical Security` — 每周/手动 macOS 安全分片。在 Blacksmith macOS 上为 CodeQL 手动构建 macOS 应用，从上传的 SARIF 中过滤掉依赖构建结果，并上传到 `/codeql-critical-security/macos`。它保留在每日默认范围之外，因为即使干净运行，macOS 构建也会主导运行时间。 ### 关键质量类别 -`CodeQL Critical Quality` 是对应的非安全分片。它只在较小的 Blacksmith Linux runner 上，对狭窄的高价值表面运行错误严重级别、非安全的 JavaScript/TypeScript 质量查询。它的拉取请求守护刻意小于计划配置文件：非草稿 PR 只会针对智能体命令/模型/工具执行和回复分发代码、配置 schema/迁移/IO 代码、认证/密钥/沙箱/安全代码、核心渠道和内置渠道插件运行时、Gateway 网关协议/服务器方法、记忆运行时/SDK 胶水、MCP/进程/出站投递、提供商运行时/模型目录、会话诊断/投递队列、插件加载器、插件 SDK/包契约，或插件 SDK 回复运行时变更，运行匹配的 `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract` 和 `plugin-sdk-reply-runtime` 分片。CodeQL 配置和质量工作流变更会运行全部十二个 PR 质量分片。 +`CodeQL Critical Quality` 是对应的非安全分片。它只在较小的 Blacksmith Linux 运行器上，对窄范围的高价值表面运行错误严重级别、非安全 JavaScript/TypeScript 质量查询。它的拉取请求守护有意比计划配置更小：非草稿 PR 只会针对智能体命令/模型/工具执行和回复分发代码、配置 schema/迁移/IO 代码、身份验证/密钥/沙箱/安全代码、核心渠道和内置渠道插件运行时、Gateway 网关协议/服务器方法、记忆运行时/SDK 胶水代码、MCP/进程/出站交付、提供商运行时/模型目录、会话诊断/交付队列、插件加载器、插件 SDK/包契约，或插件 SDK 回复运行时变更，运行匹配的 `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract` 和 `plugin-sdk-reply-runtime` 分片。CodeQL 配置和质量工作流变更会运行全部十二个 PR 质量分片。 -手动调度接受： +手动分发接受： ``` profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary ``` -狭窄配置文件是用于单独运行一个质量分片的教学/迭代钩子。 +窄配置是用于单独运行一个质量分片的教学/迭代钩子。 -| 类别 | 涉及范围 | -| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | 认证、密钥、沙箱、cron 和 Gateway 网关安全边界代码 | -| `/codeql-critical-quality/config-boundary` | 配置 schema、迁移、规范化和 IO 契约 | -| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway 网关协议 schema 和服务器方法契约 | -| `/codeql-critical-quality/channel-runtime-boundary` | 核心渠道和内置渠道插件实现契约 | -| `/codeql-critical-quality/agent-runtime-boundary` | 命令执行、模型/提供商分发、自动回复分发和队列，以及 ACP 控制平面运行时契约 | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP 服务器和工具桥接、进程监督辅助工具，以及出站投递契约 | -| `/codeql-critical-quality/memory-runtime-boundary` | 记忆宿主 SDK、记忆运行时门面、记忆插件 SDK 别名、记忆运行时激活胶合代码，以及记忆 Doctor 命令 | -| `/codeql-critical-quality/session-diagnostics-boundary` | 回复队列内部机制、会话投递队列、出站会话绑定/投递辅助工具、诊断事件/日志包表面，以及会话 Doctor CLI 契约 | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | 插件 SDK 入站回复分发、回复载荷/分块/运行时辅助工具、渠道回复选项、投递队列，以及会话/线程绑定辅助工具 | -| `/codeql-critical-quality/provider-runtime-boundary` | 模型目录规范化、提供商认证和设备发现、提供商运行时注册、提供商默认值/目录，以及 Web/搜索/获取/嵌入注册表 | -| `/codeql-critical-quality/ui-control-plane` | 控制 UI 引导、本地持久化、Gateway 网关控制流，以及任务控制平面运行时契约 | -| `/codeql-critical-quality/web-media-runtime-boundary` | 核心 Web 获取/搜索、媒体 IO、媒体理解、图像生成，以及媒体生成运行时契约 | -| `/codeql-critical-quality/plugin-boundary` | 加载器、注册表、公共表面，以及插件 SDK 入口点契约 | -| `/codeql-critical-quality/plugin-sdk-package-contract` | 已发布包侧插件 SDK 源码和插件包契约辅助工具 | +| 类别 | 表面 | +| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-critical-quality/core-auth-secrets` | 身份验证、密钥、沙箱、cron 和 Gateway 网关安全边界代码 | +| `/codeql-critical-quality/config-boundary` | 配置 schema、迁移、规范化和 IO 契约 | +| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway 网关协议 schema 和服务器方法契约 | +| `/codeql-critical-quality/channel-runtime-boundary` | 核心渠道和内置渠道插件实现契约 | +| `/codeql-critical-quality/agent-runtime-boundary` | 命令执行、模型/提供商调度、自动回复调度和队列，以及 ACP 控制平面运行时契约 | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP 服务器和工具桥接、进程监督辅助工具，以及出站投递契约 | +| `/codeql-critical-quality/memory-runtime-boundary` | 记忆主机 SDK、记忆运行时门面、记忆插件 SDK 别名、记忆运行时激活胶水代码，以及记忆 Doctor 命令 | +| `/codeql-critical-quality/session-diagnostics-boundary` | 回复队列内部机制、会话投递队列、出站会话绑定/投递辅助工具、诊断事件/日志包表面，以及会话 Doctor CLI 契约 | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | 插件 SDK 入站回复调度、回复载荷/分块/运行时辅助工具、渠道回复选项、投递队列，以及会话/线程绑定辅助工具 | +| `/codeql-critical-quality/provider-runtime-boundary` | 模型目录规范化、提供商身份验证和设备发现、提供商运行时注册、提供商默认值/目录，以及 Web/搜索/抓取/嵌入注册表 | +| `/codeql-critical-quality/ui-control-plane` | 控制 UI 引导、本地持久化、Gateway 网关控制流，以及任务控制平面运行时契约 | +| `/codeql-critical-quality/web-media-runtime-boundary` | 核心 Web 抓取/搜索、媒体 IO、媒体理解、图像生成和媒体生成运行时契约 | +| `/codeql-critical-quality/plugin-boundary` | 加载器、注册表、公开表面和插件 SDK 入口点契约 | +| `/codeql-critical-quality/plugin-sdk-package-contract` | 已发布包侧插件 SDK 源码和插件包契约辅助工具 | -质量与安全保持分离，这样质量发现项可以被排期、度量、禁用或扩展，而不会掩盖安全信号。只有在窄配置文件具备稳定的运行时和信号之后，才应将 Swift、Python 和内置插件 CodeQL 扩展作为有范围或分片的后续工作加回。 +质量与安全保持分离，这样质量发现可以被排期、度量、禁用或扩展，而不会掩盖安全信号。只有在窄范围配置文件拥有稳定运行时和信号之后，才应将 Swift、Python 和内置插件 CodeQL 扩展作为有作用域或分片的后续工作加回。 ## 维护工作流 ### Docs Agent -`Docs Agent` 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与最近落地的更改保持一致。它没有纯定时计划：`main` 上成功的非 bot 推送 CI 运行可以触发它，手动调度也可以直接运行它。当 `main` 已经前进，或过去一小时内创建了另一个未跳过的 Docs Agent 运行时，workflow-run 调用会跳过。运行时，它会审查从上一个未跳过的 Docs Agent 来源 SHA 到当前 `main` 的提交范围，因此每小时运行一次即可覆盖自上次文档检查以来累积的所有 main 更改。 +`Docs Agent` 工作流是一个事件驱动的 Codex 维护通道，用于让现有文档与近期落地的变更保持一致。它没有纯定时计划：`main` 上一次成功的非 bot push CI 运行可以触发它，也可以通过手动派发直接运行它。当 `main` 已经继续推进，或过去一小时内已创建另一个未跳过的 Docs Agent 运行时，workflow-run 调用会跳过。运行时，它会审查从上一个未跳过的 Docs Agent 来源 SHA 到当前 `main` 的提交范围，因此一次每小时运行可以覆盖自上次文档处理以来累积的所有 main 变更。 ### Test Performance Agent -`Test Performance Agent` 工作流是一个事件驱动的 Codex 维护通道，用于处理慢测试。它没有纯定时计划：`main` 上成功的非 bot 推送 CI 运行可以触发它，但如果当天 UTC 已经有另一个 workflow-run 调用运行过或正在运行，它会跳过。手动调度会绕过该每日活动门槛。该通道会构建完整套件分组 Vitest 性能报告，让 Codex 只做小范围且保持覆盖率的测试性能修复，而不是大规模重构；随后重新运行完整套件报告，并拒绝会降低通过基线测试数量的更改。如果基线存在失败测试，Codex 只能修复明显失败项，并且 agent 之后的完整套件报告必须通过，才会提交任何内容。当 `main` 在 bot 推送落地前前进时，该通道会 rebase 已验证的补丁，重新运行 `pnpm check:changed`，并重试推送；有冲突的过期补丁会被跳过。它使用 GitHub 托管的 Ubuntu，因此 Codex action 可以与文档 agent 保持相同的 drop-sudo 安全姿态。 +`Test Performance Agent` 工作流是一个事件驱动的 Codex 维护通道，用于处理慢测试。它没有纯定时计划：`main` 上一次成功的非 bot push CI 运行可以触发它，但如果同一 UTC 日已有另一个 workflow-run 调用运行过或正在运行，它会跳过。手动派发会绕过这个每日活动门禁。该通道会构建一份完整套件分组 Vitest 性能报告，让 Codex 只做保持覆盖率的小型测试性能修复，而不是大范围重构，然后重新运行完整套件报告，并拒绝会降低通过基线测试数量的变更。如果基线存在失败测试，Codex 只能修复明显失败，并且 agent 之后的完整套件报告必须通过后才会提交任何内容。当 `main` 在 bot push 落地前推进时，该通道会 rebase 已验证的补丁，重新运行 `pnpm check:changed`，并重试 push；冲突的过期补丁会被跳过。它使用 GitHub 托管的 Ubuntu，因此 Codex action 可以保持与 docs agent 相同的 drop-sudo 安全姿态。 ### 合并后的重复 PR -`Duplicate PRs After Merge` 工作流是一个手动维护者工作流，用于落地后的重复项清理。它默认 dry-run，并且仅在 `apply=true` 时关闭显式列出的 PR。在变更 GitHub 之前，它会验证已落地 PR 已合并，并且每个重复项要么共享引用的 issue，要么有重叠的变更 hunk。 +`Duplicate PRs After Merge` 工作流是一个面向维护者的手动工作流，用于落地后的重复项清理。它默认 dry-run，并且只有在 `apply=true` 时才关闭显式列出的 PR。在修改 GitHub 之前，它会验证已落地 PR 已合并，并验证每个重复项要么共享引用的 issue，要么存在重叠的变更 hunk。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -400,27 +402,27 @@ gh workflow run duplicate-after-merge.yml \ ## 本地检查门禁和变更路由 -本地变更通道逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。与宽泛 CI 平台范围相比，该本地检查门禁对架构边界更严格： +本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地检查门禁在架构边界上比宽范围 CI 平台作用域更严格： -- 核心生产更改运行核心生产和核心测试 typecheck，加上核心 lint/guard； -- 仅核心测试更改只运行核心测试 typecheck，加上核心 lint； -- 插件生产更改运行插件生产和插件测试 typecheck，加上插件 lint； -- 仅插件测试更改运行插件测试 typecheck，加上插件 lint； -- 公共插件 SDK 或插件契约更改会扩展到插件 typecheck，因为插件依赖这些核心契约（Vitest 插件扫查仍然是显式测试工作）； -- 仅发布元数据的版本号 bump 运行定向版本/配置/根依赖检查； -- 未知根目录/配置更改会安全失败到所有检查通道。 +- 核心生产代码变更会运行核心生产代码和核心测试 typecheck，以及核心 lint/guard； +- 仅核心测试变更只运行核心测试 typecheck 和核心 lint； +- 插件生产代码变更会运行插件生产代码和插件测试 typecheck，以及插件 lint； +- 仅插件测试变更会运行插件测试 typecheck 和插件 lint； +- 公开插件 SDK 或插件契约变更会扩展到插件 typecheck，因为插件依赖这些核心契约（Vitest 插件 sweep 仍然是显式测试工作）； +- 仅发布元数据的版本 bump 会运行定向版本/配置/root 依赖检查； +- 未知 root/配置变更会 fail safe 到所有检查通道。 -本地变更测试路由位于 `scripts/test-projects.test-support.mjs`，并且有意比 `check:changed` 更低成本：直接测试编辑会运行自身，源码编辑优先使用显式映射，然后是同级测试和导入图依赖项。共享 group-room 投递配置是显式映射之一：对群组可见回复配置、来源回复投递模式或 message-tool 系统提示词的更改，会通过核心回复测试加上 Discord 和 Slack 投递回归测试，因此共享默认值更改会在首次 PR 推送前失败。只有当更改影响整个 harness，以至于低成本映射集合不是可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 +本地 changed-test 路由位于 `scripts/test-projects.test-support.mjs`，并且有意比 `check:changed` 更便宜：直接测试编辑会运行自身，源码编辑优先使用显式映射，然后使用同级测试和导入图依赖项。共享群组房间投递配置是显式映射之一：对群组可见回复配置、来源回复投递模式或 message-tool 系统提示词的变更，会经由核心回复测试以及 Discord 和 Slack 投递回归测试，因此共享默认值变更会在第一次 PR push 前失败。只有当变更影响范围足够覆盖整个 harness，导致便宜的映射集合不是可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 ## Testbox 验证 -从仓库根目录运行 Testbox，并优先为宽泛证明使用新预热的 box。在把慢门禁花到一个被复用、已过期或刚报告异常大同步的 box 上之前，先在 box 内运行 `pnpm testbox:sanity`。 +从仓库根目录运行 Testbox，并优先为宽范围证明使用新预热的 box。在将慢门禁花到一个复用过、已过期或刚报告异常大同步的 box 上之前，先在 box 内运行 `pnpm testbox:sanity`。 -当必需的根文件（如 `pnpm-lock.yaml`）消失，或 `git status --short` 显示至少 200 个已跟踪删除时，完整性检查会快速失败。这通常意味着远程同步状态不是 PR 的可信副本；应停止该 box 并预热一个新的，而不是调试产品测试失败。对于有意的大规模删除 PR，在该完整性运行中设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。 +当所需根文件（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 显示至少 200 个已跟踪删除时，sanity check 会快速失败。这通常意味着远程同步状态不是 PR 的可信副本；停止该 box 并预热一个新的，而不是调试产品测试失败。对于有意的大规模删除 PR，请为该 sanity 运行设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。 -`pnpm testbox:run` 也会终止本地 Blacksmith CLI 调用：如果它在同步阶段停留超过五分钟且没有同步后输出。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该防护，或为异常大的本地 diff 使用更大的毫秒值。 +如果本地 Blacksmith CLI 调用在同步阶段停留超过五分钟且没有同步后输出，`pnpm testbox:run` 也会终止它。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该保护；对于异常大的本地 diff，也可以使用更大的毫秒值。 -当 Blacksmith 不可用，或更适合使用自有云容量时，Crabbox 是仓库自有的第二条远程 box Linux 证明路径。预热一个 box，通过项目工作流 hydrate 它，然后通过 Crabbox CLI 运行命令： +当 Blacksmith 不可用，或更偏好自有云容量时，Crabbox 是仓库自有的第二条远程 box Linux 证明路径。预热一个 box，通过项目工作流 hydrate 它，然后通过 Crabbox CLI 运行命令： ```bash pnpm crabbox:warmup -- --idle-timeout 90m @@ -429,7 +431,7 @@ pnpm crabbox:run -- --id --shell "OPENCLAW_TESTBOX=1 pnpm check:changed pnpm crabbox:stop -- ``` -`.crabbox.yaml` 负责提供商、同步和 GitHub Actions hydrate 默认值。它排除本地 `.git`，因此 hydrate 后的 Actions checkout 会保留自身的远程 Git 元数据，而不是同步维护者本地的 remote 和对象存储；它还排除永远不应传输的本地运行时/构建产物。`.github/workflows/crabbox-hydrate.yml` 负责 checkout、Node/pnpm 设置、`origin/main` 获取，以及后续 `crabbox run --id ` 命令会 source 的非密钥环境交接。 +`.crabbox.yaml` 负责提供商、同步和 GitHub Actions hydrate 默认值。它排除本地 `.git`，因此 hydrated Actions checkout 会保留自己的远程 Git 元数据，而不是同步维护者本地的远程和对象存储；它还排除绝不应传输的本地运行时/构建产物。`.github/workflows/crabbox-hydrate.yml` 负责 checkout、Node/pnpm 设置、`origin/main` fetch，以及后续 `crabbox run --id ` 命令会 source 的非 secret 环境交接。 ## 相关 diff --git a/docs/zh-CN/help/testing-updates-plugins.md b/docs/zh-CN/help/testing-updates-plugins.md index 88e72ae66..fa58f6129 100644 --- a/docs/zh-CN/help/testing-updates-plugins.md +++ b/docs/zh-CN/help/testing-updates-plugins.md @@ -1,34 +1,34 @@ --- read_when: - 更改 OpenClaw 更新、Doctor、软件包验收或插件安装行为 - - 准备或批准发布候选版 + - 准备或批准候选发布版本 - 调试包更新、插件依赖清理或插件安装回归问题 sidebarTitle: Update and plugin tests summary: OpenClaw 如何验证更新路径、软件包迁移以及插件安装/更新行为 title: 更新和插件测试 x-i18n: - generated_at: "2026-05-01T22:37:40Z" + generated_at: "2026-05-01T23:38:35Z" model: gpt-5.5 provider: openai - source_hash: dc3cfa7b6a1ede28dfb12940b56d34d3f8ca4d539c26fd818d663d7052f962a8 + source_hash: 4d4b52047b9b80273e2d93b97e647e5e9c93d93910828fdce010568f3ea81390 source_path: help/testing-updates-plugins.md workflow: 16 --- -这是更新和插件验证的专用清单。目标很简单：证明可安装包可以更新真实用户状态，通过 `doctor` 修复陈旧的旧版状态，并且仍能从受支持的来源安装、加载、更新和卸载插件。 +这是更新和插件验证的专用清单。目标很简单：证明可安装软件包可以更新真实用户状态，通过 `doctor` 修复陈旧的遗留状态，并且仍能从支持的来源安装、加载、更新和卸载插件。 -如需更完整的测试运行器地图，请参见 [测试](/zh-CN/help/testing)。如需实时提供商密钥和触网套件，请参见 [实时测试](/zh-CN/help/testing-live)。 +关于更广泛的测试运行器映射，请参见 [测试](/zh-CN/help/testing)。关于实时提供商密钥和会触网的套件，请参见 [实时测试](/zh-CN/help/testing-live)。 -## 我们保护什么 +## 我们保护的内容 -更新和插件测试保护以下契约： +更新和插件测试保护这些契约： -- 软件包 tarball 完整，包含有效的 `dist/postinstall-inventory.json`，并且不依赖未打包的仓库文件。 -- 用户可以从较旧的已发布包迁移到候选包，而不会丢失配置、智能体、会话、工作区、插件 allowlist 或渠道配置。 -- `openclaw doctor --fix --non-interactive` 负责旧版清理和修复路径。启动流程不应为陈旧的插件状态增加隐藏的兼容性迁移。 -- 插件安装可从本地目录、git 仓库、npm 包和 ClawHub 注册表路径正常工作。 -- 插件 npm 依赖会安装到托管 npm 根目录中，在信任前被扫描，并在卸载期间通过 npm 移除，避免提升的依赖残留。 -- 插件在无变更时更新保持稳定：安装记录、解析后的来源和启用状态保持不变。 +- 软件包 tarball 是完整的，包含有效的 `dist/postinstall-inventory.json`，并且不依赖未打包的仓库文件。 +- 用户可以从较旧的已发布软件包迁移到候选软件包，而不会丢失配置、智能体、会话、工作区、插件 allowlist 或渠道配置。 +- `openclaw doctor --fix --non-interactive` 负责遗留清理和修复路径。启动流程不应为陈旧插件状态增加隐藏的兼容性迁移。 +- 插件安装可从本地目录、git 仓库、npm 软件包和 ClawHub 注册表路径运行。 +- 插件 npm 依赖会安装到托管的 npm 根目录，在信任前进行扫描，并在卸载期间通过 npm 移除，避免提升的依赖残留。 +- 插件更新在没有变化时保持稳定：安装记录、解析后的来源和启用状态保持不变。 ## 开发期间的本地证明 @@ -40,41 +40,43 @@ pnpm check:changed pnpm test:changed ``` -对于插件安装、卸载、依赖或包清单变更，还要运行覆盖已编辑接缝的聚焦测试： +对于插件安装、卸载、依赖或软件包 inventory 变更，还要运行覆盖已编辑接缝的聚焦测试： ```bash pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts ``` -在任何包 Docker lane 使用 tarball 之前，先证明包产物： +在任何软件包 Docker lane 使用 tarball 之前，先证明软件包构件： ```bash pnpm release:check ``` -`release:check` 会运行配置/文档/API 漂移检查，写入包 dist 清单，运行 `npm pack --dry-run`，拒绝被禁止打包的文件，将 tarball 安装到临时前缀，运行 postinstall，并对内置渠道入口点做冒烟测试。 +`release:check` 会运行配置/文档/API 漂移检查，写入软件包 dist inventory，运行 `npm pack --dry-run`，拒绝禁止打包的文件，将 tarball 安装到临时前缀，运行 postinstall，并对内置渠道入口点做冒烟测试。 -## Docker lane +## Docker lanes -Docker lane 是产品级证明。它们会在 Linux 容器内安装或更新真实包，并通过 CLI 命令、Gateway 网关启动、HTTP 探测、RPC Status 和文件系统状态断言行为。 +Docker lanes 是产品级证明。它们在 Linux 容器内安装或更新真实软件包，并通过 CLI 命令、Gateway 网关启动、HTTP 探测、RPC 状态和文件系统状态断言行为。 -迭代时使用聚焦 lane： +迭代时使用聚焦 lanes： ```bash pnpm test:docker:plugins pnpm test:docker:plugin-update pnpm test:docker:upgrade-survivor pnpm test:docker:published-upgrade-survivor +pnpm test:docker:update-migration ``` -重要 lane： +重要 lanes： -- `test:docker:plugins` 验证插件安装冒烟、本地文件夹安装、带预安装依赖的本地文件夹、带包依赖的 git 安装、npm 包依赖安装、本地 ClawHub fixture 安装、市场更新行为，以及 Claude bundle 启用/检查。设置 `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` 可让 ClawHub 区块保持封闭/离线。 -- `test:docker:plugin-update` 验证未变更的已安装插件在 `openclaw plugins update` 期间不会重新安装或丢失安装元数据。 -- `test:docker:upgrade-survivor` 会把候选 tarball 安装到脏的旧用户 fixture 之上，运行包更新和非交互式 Doctor，然后启动 local loopback Gateway 网关并检查状态保留。 -- `test:docker:published-upgrade-survivor` 先安装已发布基线，通过烘焙的 `openclaw config set` 配方配置它，再更新到候选 tarball，运行 Doctor，检查旧版清理，启动 Gateway 网关，并探测 `/healthz`、`/readyz` 和 RPC Status。 +- `test:docker:plugins` 验证插件安装冒烟、本地文件夹安装、带预安装依赖的本地文件夹、带软件包依赖的 git 安装、npm 软件包依赖安装、本地 ClawHub fixture 安装、marketplace 更新行为，以及 Claude bundle 启用/检查。设置 `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` 可让 ClawHub 区块保持 hermetic/offline。 +- `test:docker:plugin-update` 验证未变化的已安装插件在 `openclaw plugins update` 期间不会重新安装或丢失安装元数据。 +- `test:docker:upgrade-survivor` 将候选 tarball 安装到脏的旧用户 fixture 之上，运行软件包更新和非交互式 Doctor，然后启动 local loopback Gateway 网关并检查状态保留。 +- `test:docker:published-upgrade-survivor` 首先安装已发布基线，通过内置的 `openclaw config set` 配方配置它，将其更新到候选 tarball，运行 Doctor，检查遗留清理，启动 Gateway 网关，并探测 `/healthz`、`/readyz` 和 RPC 状态。 +- `test:docker:update-migration` 是重清理的已发布更新 lane。它从已配置的 Discord/Telegram 风格用户状态开始，运行基线 Doctor，使已配置的插件依赖有机会实体化，为已配置的打包插件播种遗留插件依赖碎片，更新到候选 tarball，并要求更新后的 Doctor 移除遗留依赖根目录。 -有用的 published-upgrade survivor 变体： +有用的已发布升级幸存者变体： ```bash OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \ @@ -86,26 +88,37 @@ OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \ pnpm test:docker:published-upgrade-survivor ``` -可用场景包括 `base`、`feishu-channel`、`bootstrap-persona`、`tilde-log-path` 和 `versioned-runtime-deps`。在聚合运行中，`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` 会扩展为所有已报告问题形态的场景。 +可用场景包括 `base`、`feishu-channel`、`bootstrap-persona`、`plugin-deps-cleanup`、`tilde-log-path` 和 `versioned-runtime-deps`。在聚合运行中，`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` 会展开为所有已报告问题形态的场景。 + +完整更新迁移有意与 Full Release CI 分离。当发布问题是“从 2026.4.23 起的每个已发布稳定版本是否都能更新到此候选版本并清理插件依赖碎片？”时，使用手动 `Update Migration` 工作流： + +```bash +gh workflow run update-migration.yml \ + --ref main \ + -f workflow_ref=main \ + -f package_ref=main \ + -f baselines=all-since-2026.4.23 \ + -f scenarios=plugin-deps-cleanup +``` ## Package Acceptance -Package Acceptance 是 GitHub 原生的包门禁。它会将一个候选包解析为 `package-under-test` tarball，记录版本和 SHA-256，然后针对该精确 tarball 运行可复用的 Docker E2E lane。workflow harness ref 与包来源 ref 分离，因此当前测试逻辑可以验证较旧的受信任版本。 +Package Acceptance 是 GitHub 原生的软件包门禁。它将一个候选软件包解析为 `package-under-test` tarball，记录版本和 SHA-256，然后针对该精确 tarball 运行可复用的 Docker E2E lanes。工作流 harness ref 与软件包源 ref 分离，因此当前测试逻辑可以验证较旧的受信任发布版本。 候选来源： - `source=npm`：验证 `openclaw@beta`、`openclaw@latest` 或精确的已发布版本。 - `source=ref`：使用选定的当前 harness 打包受信任的分支、标签或提交。 -- `source=url`：验证需要 `package_sha256` 的 HTTPS tarball。 +- `source=url`：验证 HTTPS tarball，并要求 `package_sha256`。 - `source=artifact`：复用另一个 Actions 运行上传的 tarball。 -发布检查会用包/更新/插件集合调用 Package Acceptance： +发布检查使用软件包/更新/插件集合调用 Package Acceptance： ```text doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update ``` -它们还会传入： +它们还传递： ```text published_upgrade_survivor_baselines=release-history @@ -113,9 +126,11 @@ published_upgrade_survivor_scenarios=reported-issues telegram_mode=mock-openai ``` -这会让包迁移、更新渠道切换、陈旧插件依赖清理、离线插件覆盖、插件更新行为和 Telegram 包 QA 使用同一个已解析产物。 +这使软件包迁移、更新渠道切换、陈旧插件依赖清理、离线插件覆盖、插件更新行为和 Telegram 软件包 QA 都在同一个解析后的构件上运行。 -在发布前验证候选包时，手动运行包 profile： +`release-history` 是有边界的发布检查样本：最新六个稳定版本、`2026.4.23`，以及一个更早的日期前锚点。对于详尽的已发布更新迁移覆盖，请在单独的 Update Migration 工作流中使用 `all-since-2026.4.23`，而不是 Full Release CI。 + +在发布前验证候选版本时，手动运行软件包 profile： ```bash gh workflow run package-acceptance.yml \ @@ -129,27 +144,27 @@ gh workflow run package-acceptance.yml \ -f telegram_mode=mock-openai ``` -当发布问题包含 MCP 渠道、cron/subagent 清理、OpenAI web search 或 OpenWebUI 时，使用 `suite_profile=product`。仅在需要完整 Docker 发布路径覆盖时使用 `suite_profile=full`。 +当发布问题包括 MCP 渠道、cron/subagent 清理、OpenAI web 搜索或 OpenWebUI 时，使用 `suite_profile=product`。仅在需要完整 Docker 发布路径覆盖时使用 `suite_profile=full`。 -## 发布默认项 +## 发布默认值 -对于发布候选，默认证明栈是： +对于候选发布版本，默认证明栈是： -1. 针对源码级回归运行 `pnpm check:changed` 和 `pnpm test:changed`。 -2. 针对包产物完整性运行 `pnpm release:check`。 -3. 针对安装/更新/插件契约运行 Package Acceptance `package` profile 或发布检查自定义包 lane。 -4. 针对 OS 特定安装器、新手引导和平台行为运行跨 OS 发布检查。 -5. 仅当变更面触及提供商或托管服务行为时运行实时套件。 +1. `pnpm check:changed` 和 `pnpm test:changed` 用于源代码级回归。 +2. `pnpm release:check` 用于软件包构件完整性。 +3. Package Acceptance `package` profile 或 release-check 自定义软件包 lanes，用于安装/更新/插件契约。 +4. Cross-OS 发布检查，用于特定 OS 的安装器、新手引导和平台行为。 +5. 仅当变更表面触及提供商或托管服务行为时，运行实时套件。 -在维护者机器上，广范围门禁和 Docker/包产品证明应在 Testbox 中运行，除非明确要做本地证明。 +在维护者机器上，广泛门禁和 Docker/软件包产品证明应在 Testbox 中运行，除非明确执行本地证明。 -## 旧版兼容性 +## 遗留兼容性 -兼容性宽松范围很窄且有时间限制： +兼容性宽容范围很窄且有时间限制： -- 截至 `2026.4.25` 的包（包括 `2026.4.25-beta.*`）可以在 Package Acceptance 中容忍已发布的包元数据缺口。 -- 已发布的 `2026.4.26` 包可以对已发布的本地构建元数据戳文件发出警告。 -- 之后的包必须满足现代契约。相同缺口会失败，而不是警告或跳过。 +- 到 `2026.4.25` 为止的软件包，包括 `2026.4.25-beta.*`，可以在 Package Acceptance 中容忍已发布的软件包元数据缺口。 +- 已发布的 `2026.4.26` 软件包可以对已发布的本地构建元数据戳文件发出警告。 +- 后续软件包必须满足现代契约。相同缺口会失败，而不是警告或跳过。 不要为这些旧形态添加新的启动迁移。添加或扩展 Doctor 修复，然后用 `upgrade-survivor` 或 `published-upgrade-survivor` 证明它。 @@ -157,20 +172,20 @@ gh workflow run package-acceptance.yml \ 更改更新或插件行为时，在能因正确原因失败的最低层添加覆盖： -- 纯路径或元数据逻辑：源旁边的单元测试。 -- 包清单或已打包文件行为：`package-dist-inventory` 或 tarball 检查器测试。 +- 纯路径或元数据逻辑：在源码旁边添加单元测试。 +- 软件包 inventory 或打包文件行为：`package-dist-inventory` 或 tarball 检查器测试。 - CLI 安装/更新行为：Docker lane 断言或 fixture。 - 已发布版本迁移行为：`published-upgrade-survivor` 场景。 -- 注册表/包来源行为：`test:docker:plugins` fixture 或 ClawHub fixture 服务器。 +- 注册表/软件包来源行为：`test:docker:plugins` fixture 或 ClawHub fixture 服务器。 -让新的 Docker fixture 默认保持封闭。使用本地 fixture 注册表和假包，除非测试重点是实时注册表行为。 +默认保持新的 Docker fixtures hermetic。除非测试重点是实时注册表行为，否则使用本地 fixture 注册表和假软件包。 ## 失败分诊 -从产物身份开始： +从构件身份开始： -- Package Acceptance `resolve_package` 摘要：来源、版本、SHA-256 和产物名称。 -- Docker 产物：`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane 日志和重跑命令。 -- Upgrade survivor 摘要：`.artifacts/upgrade-survivor/summary.json`，包括基线版本、候选版本、场景、阶段耗时和配方步骤。 +- Package Acceptance `resolve_package` 摘要：来源、版本、SHA-256 和构件名称。 +- Docker 构件：`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane 日志和重跑命令。 +- 升级幸存者摘要：`.artifacts/upgrade-survivor/summary.json`，包括基线版本、候选版本、场景、阶段计时和配方步骤。 -优先使用相同包产物重跑失败的精确 lane，而不是重跑整个发布总括流程。 +优先使用相同的软件包构件重跑失败的精确 lane，而不是重跑整个发布总括流程。 diff --git a/docs/zh-CN/reference/RELEASING.md b/docs/zh-CN/reference/RELEASING.md index 1b555699b..4acab42eb 100644 --- a/docs/zh-CN/reference/RELEASING.md +++ b/docs/zh-CN/reference/RELEASING.md @@ -1,20 +1,20 @@ --- read_when: - 正在查找公开发布渠道定义 - - 运行发布验证或包验收 + - 运行发布验证或软件包验收 - 查找版本命名和发布节奏 -summary: 发布通道、操作员检查清单、验证环境、版本命名和发布节奏 +summary: 发布通道、操作员检查清单、验证环境、版本命名和节奏 title: 发布策略 x-i18n: - generated_at: "2026-05-01T23:10:00Z" + generated_at: "2026-05-01T23:38:40Z" model: gpt-5.5 provider: openai - source_hash: 89274e9cbd5546b718517053e37574ceae53d4031d6ec02a033d250908e93bfd + source_hash: e915840070324f7614c993d20490f0bf4c9b266c57ce74eddfc461e019d3dc07 source_path: reference/RELEASING.md workflow: 16 --- -OpenClaw 有三个公开发布通道： +OpenClaw 有三条公开发布通道： - stable：带标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest` - beta：预发布标签，发布到 npm `beta` @@ -28,124 +28,109 @@ OpenClaw 有三个公开发布通道： - Git 标签：`vYYYY.M.D-N` - Beta 预发布版本：`YYYY.M.D-beta.N` - Git 标签：`vYYYY.M.D-beta.N` -- 月份或日期不要补零 -- `latest` 表示当前已提升的稳定 npm 发布版本 +- 不要对月份或日期补零 +- `latest` 表示当前已推广的稳定 npm 发布版本 - `beta` 表示当前 beta 安装目标 -- 稳定发布和稳定修正发布默认发布到 npm `beta`；发布操作员可以明确指定 `latest`，或稍后提升已验证的 beta 构建 +- 稳定和稳定修正发布版本默认发布到 npm `beta`；发布操作员可以明确指定 `latest`，也可以稍后推广经过审查的 beta 构建 - 每个稳定 OpenClaw 发布版本都会同时交付 npm 包和 macOS 应用； - beta 发布通常先验证并发布 npm/包路径，除非明确请求，否则 - mac 应用构建/签名/公证仅保留给稳定版本 + beta 发布版本通常会先验证并发布 npm/包路径，mac 应用的构建/签名/公证会保留给稳定版本，除非明确请求 ## 发布节奏 - 发布按 beta 优先推进 -- 仅在最新 beta 通过验证后才发布稳定版本 -- 维护者通常从基于当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布版本， +- 只有在最新 beta 验证完成后才会推出稳定版本 +- 维护者通常会从当前 `main` 创建 `release/YYYY.M.D` 分支来切发布， 这样发布验证和修复不会阻塞 `main` 上的新开发 -- 如果 beta 标签已经推送或发布并且需要修复，维护者会切出 - 下一个 `-beta.N` 标签，而不是删除或重新创建旧 beta 标签 -- 详细的发布流程、审批、凭证和恢复说明 - 仅限维护者查看 +- 如果 beta 标签已经推送或发布且需要修复，维护者会切下一个 + `-beta.N` 标签，而不是删除或重新创建旧的 beta 标签 +- 详细发布流程、审批、凭证和恢复说明仅限维护者使用 -## 发布操作员检查清单 +## 发布操作员清单 -此检查清单是发布流程的公开形态。私有凭证、 -签名、公证、dist-tag 恢复和紧急回滚详情保留在 -仅限维护者查看的发布运行手册中。 +此清单是发布流程的公开形态。私有凭证、签名、公证、dist-tag 恢复和紧急回滚细节保留在仅限维护者使用的发布运行手册中。 -1. 从当前 `main` 开始：拉取最新代码，确认目标提交已推送， - 并确认当前 `main` CI 足够健康，可以从它创建分支。 -2. 使用 `/changelog` 根据真实提交历史重写顶部 `CHANGELOG.md` 章节， - 保持条目面向用户，提交它，推送它，并在创建分支前再次 rebase/pull。 -3. 检查 +1. 从当前 `main` 开始：拉取最新内容，确认目标提交已推送， + 并确认当前 `main` CI 的状态足够适合从它创建分支。 +2. 使用真实提交历史通过 `/changelog` 重写顶部 `CHANGELOG.md` 章节， + 保持条目面向用户，提交并推送，然后在创建分支前再 rebase/pull + 一次。 +3. 查看 `src/plugins/compat/registry.ts` 和 - `src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。仅当升级路径仍被覆盖时才移除过期兼容性，或记录为什么有意继续保留。 -4. 从当前 `main` 创建 `release/YYYY.M.D`；不要直接在 `main` 上进行常规发布工作。 -5. 为预期标签更新每个必需的版本位置，然后运行 - 本地确定性预检： + `src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。只有在升级路径仍然有覆盖时才移除过期兼容性，或者记录为何有意继续保留。 +4. 从当前 `main` 创建 `release/YYYY.M.D`；不要直接在 `main` 上做常规发布工作。 +5. 为目标标签更新所有必需的版本位置，然后运行本地确定性预检： `pnpm check:test-types`、`pnpm check:architecture`、 `pnpm build && pnpm ui:build` 和 `pnpm release:check`。 -6. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true`。在标签存在之前， - 允许使用完整的 40 字符发布分支 SHA 进行仅验证预检。保存成功的 `preflight_run_id`。 -7. 使用 `Full Release Validation` 为发布分支、标签或完整提交 SHA 启动所有预发布测试。 - 这是四个大型发布测试箱的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。 -8. 如果验证失败，在发布分支上修复，并重新运行能证明修复的最小失败 - 文件、通道、workflow job、包 profile、提供商或模型 allowlist。仅当变更表面使先前证据失效时， - 才重新运行完整总括流程。 -9. 对于 beta，标记 `vYYYY.M.D-beta.N`，使用 npm dist-tag `beta` 发布，然后针对已发布的 `openclaw@YYYY.M.D-beta.N` - 或 `openclaw@beta` 包运行发布后包验收。如果已推送或已发布的 beta 需要修复， - 切出下一个 `-beta.N`；不要删除或重写旧 beta。 -10. 对于稳定版本，仅在已验证的 beta 或发布候选版本具备所需验证证据后继续。 - 稳定 npm 发布会通过 `preflight_run_id` 复用成功的 - 预检产物；稳定 macOS 发布就绪还要求在 `main` 上具备打包后的 `.zip`、`.dmg`、`.dSYM.zip` 以及更新后的 +6. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签存在之前， + 可以使用完整的 40 字符发布分支 SHA 进行仅验证预检。保存成功的 + `preflight_run_id`。 +7. 对发布分支、标签或完整提交 SHA 使用 `Full Release Validation` 启动所有预发布测试。这是四个大型发布测试箱的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。 +8. 如果验证失败，在发布分支上修复，并重新运行能证明修复的最小失败文件、通道、工作流作业、包配置文件、提供商或模型 allowlist。只有在变更面使先前证据过期时，才重新运行完整总入口。 +9. 对于 beta，打标签 `vYYYY.M.D-beta.N`，使用 npm dist-tag `beta` 发布，然后针对已发布的 `openclaw@YYYY.M.D-beta.N` + 或 `openclaw@beta` 包运行发布后包验收。如果已推送或已发布的 beta 需要修复，切下一个 `-beta.N`；不要删除或重写旧 beta。 +10. 对于稳定版本，只有在经过审查的 beta 或发布候选版本具备所需验证证据后才继续。稳定 npm 发布会通过 `preflight_run_id` 复用成功的预检产物；稳定 macOS 发布就绪还要求打包好的 `.zip`、`.dmg`、`.dSYM.zip` 以及 `main` 上已更新的 `appcast.xml`。 -11. 发布后，运行 npm 发布后验证器，在需要发布后渠道证明时运行可选的独立 - published-npm Telegram E2E，在需要时进行 dist-tag 提升，根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub release/prerelease notes，并执行发布公告 - 步骤。 +11. 发布后，运行 npm 发布后验证器；在需要发布后渠道证明时，可选运行独立的已发布 npm Telegram E2E；按需进行 dist-tag 推广；根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub release/prerelease 说明；并执行发布公告步骤。 ## 发布预检 -- 在发布预检前运行 `pnpm check:test-types`，以便测试 TypeScript 在更快的本地 `pnpm check` 门禁之外也保持覆盖 -- 在发布预检前运行 `pnpm check:architecture`，以便更广泛的导入循环和架构边界检查在更快的本地门禁之外保持绿色 -- 在 `pnpm release:check` 前运行 `pnpm build && pnpm ui:build`，以便预期的 `dist/*` 发布产物和 Control UI 包存在，可供打包验证步骤使用 -- 在发布批准前运行手动 `Full Release Validation` 工作流，从一个入口点启动所有预发布测试箱。它接受分支、标签或完整提交 SHA，调度手动 `CI`，并调度 `OpenClaw Release Checks`，用于安装烟雾测试、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 通道。在 `release_profile=full` 和 `rerun_group=all` 时，它还会针对发布检查生成的 `release-package-under-test` 产物运行包 Telegram E2E。发布后，如果同一个 Telegram E2E 也应证明已发布的 npm 包，请提供 `npm_telegram_package_spec`。当私有证据报告应证明验证匹配某个已发布的 npm 包，但不强制运行 Telegram E2E 时，请提供 `evidence_package_spec`。 +- 在发布预检前运行 `pnpm check:test-types`，使测试 TypeScript 在更快的本地 `pnpm check` 门禁之外仍被覆盖 +- 在发布预检前运行 `pnpm check:architecture`，使更广泛的导入循环和架构边界检查在更快的本地门禁之外保持绿色 +- 在 `pnpm release:check` 前运行 `pnpm build && pnpm ui:build`，使预期的 `dist/*` 发布产物和 Control UI 包存在，供打包验证步骤使用 +- 在发布批准前运行手动 `Full Release Validation` 工作流，从一个入口点启动所有预发布测试盒。它接受分支、标签或完整提交 SHA，分派手动 `CI`，并分派 `OpenClaw Release Checks`，覆盖安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 线路。使用 `release_profile=full` 和 `rerun_group=all` 时，它还会针对发布检查中的 `release-package-under-test` 产物运行包 Telegram E2E。当同一个 Telegram E2E 也应验证已发布的 npm 包时，请在发布后提供 `npm_telegram_package_spec`。当私有证据报告应证明验证与已发布的 npm 包匹配、但不强制运行 Telegram E2E 时，请提供 `evidence_package_spec`。 示例： `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- 当你希望在发布工作继续进行时为包候选提供旁路证明，请运行手动 `Package Acceptance` 工作流。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 以当前 `workflow_ref` harness 打包受信任的 `package_ref` 分支/标签/SHA；对带有必需 SHA-256 的 HTTPS tarball 使用 `source=url`；或对另一个 GitHub Actions 运行上传的 tarball 使用 `source=artifact`。该工作流会将候选解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并且可通过 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一个 tarball 运行 Telegram QA。当选定的 Docker 通道包含 `published-upgrade-survivor` 时，包产物就是候选，`published_upgrade_survivor_baseline` 选择已发布的基线。 +- 当你希望在发布工作继续进行时，为包候选版本提供旁路证明，请运行手动 `Package Acceptance` 工作流。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 以当前 `workflow_ref` harness 打包受信任的 `package_ref` 分支/标签/SHA；对带有必需 SHA-256 的 HTTPS tarball 使用 `source=url`；或对另一个 GitHub Actions 运行上传的 tarball 使用 `source=artifact`。该工作流会将候选版本解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并可通过 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一 tarball 运行 Telegram QA。当选中的 Docker 线路包含 `published-upgrade-survivor` 时，包产物就是候选版本，`published_upgrade_survivor_baseline` 选择已发布基线。 示例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` - 常见配置文件： - - `smoke`：安装/渠道/智能体、Gateway 网关网络和配置重载通道 - - `package`：不含 OpenWebUI 或 live ClawHub 的产物原生包/更新/插件通道 - - `product`：package 配置文件加上 MCP 渠道、cron/子智能体清理、OpenAI Web 搜索和 OpenWebUI + 常用配置： + - `smoke`：安装/渠道/智能体、Gateway 网关网络和配置重载线路 + - `package`：不含 OpenWebUI 或 live ClawHub 的产物原生包/更新/插件线路 + - `product`：package 配置加 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI - `full`：带 OpenWebUI 的 Docker 发布路径分块 - `custom`：用于聚焦重跑的精确 `docker_lanes` 选择 -- 当你只需要发布候选的完整常规 CI 覆盖时，直接运行手动 `CI` 工作流。手动 CI 调度会绕过变更范围限定，并强制运行 Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建烟雾测试、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n 通道。 +- 当你只需要发布候选版本的完整常规 CI 覆盖时，直接运行手动 `CI` 工作流。手动 CI 分派会绕过变更范围限定，并强制执行 Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n 线路。 示例：`gh workflow run ci.yml --ref release/YYYY.M.D` -- 在验证发布遥测时运行 `pnpm qa:otel:smoke`。它通过本地 OTLP/HTTP 接收器执行 QA-lab，并验证导出的 trace span 名称、有界属性以及内容/标识符脱敏，而不需要 Opik、Langfuse 或其他外部采集器。 -- 每个带标签发布前运行 `pnpm release:check` -- 发布检查现在在单独的手动工作流中运行： +- 验证发布遥测时运行 `pnpm qa:otel:smoke`。它通过本地 OTLP/HTTP 接收器运行 QA-lab，并验证导出的 trace span 名称、有界属性以及内容/标识符脱敏，无需 Opik、Langfuse 或其他外部收集器。 +- 每个打标签发布前运行 `pnpm release:check` +- 发布检查现在运行在一个单独的手动工作流中： `OpenClaw Release Checks` -- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock parity 门禁，以及快速 live Matrix 配置文件和 Telegram QA 通道。live 通道使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭证租约。当你希望并行运行完整 Matrix 传输、媒体和 E2EE 清单时，请使用 `matrix_profile=all` 和 `matrix_shards=true` 运行手动 `QA-Lab - All Lanes` 工作流。 -- 跨 OS 安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用工作流 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- 这种拆分是有意的：保持真正的 npm 发布路径短小、确定且聚焦产物，同时较慢的 live 检查留在自己的通道中，避免拖慢或阻塞发布 -- 携带密钥的发布检查应通过 `Full Release Validation` 调度，或从 `main`/release 工作流 ref 调度，以便工作流逻辑和密钥保持受控 -- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，只要解析出的提交可从 OpenClaw 分支或发布标签到达 -- `OpenClaw NPM Release` 仅验证预检也接受当前完整 40 字符工作流分支提交 SHA，无需已推送标签 -- 该 SHA 路径仅用于验证，不能提升为真正发布 -- 在 SHA 模式下，工作流仅为包元数据检查合成 `v`；真正发布仍需要真实发布标签 -- 两个工作流都将真正发布和提升路径保留在 GitHub 托管 runner 上，而非变更性验证路径可以使用更大的 Blacksmith Linux runner -- 该工作流会使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 工作流密钥运行 - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` -- 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 发布后运行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`，以使用共享租约 Telegram 凭证池，针对已发布 npm 包验证已安装包的新手引导、Telegram 设置和真实 Telegram E2E。本地维护者一次性运行可以省略 Convex 变量，并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭证。 -- 维护者可以通过手动 `NPM Telegram Beta E2E` 工作流从 GitHub Actions 运行相同的发布后检查。它有意仅限手动运行，不会在每次合并时运行。 -- 维护者发布自动化现在使用先预检后提升： - - 真正的 npm 发布必须通过一次成功的 npm `preflight_run_id` - - 真正的 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支调度 - - 稳定 npm 发布默认使用 `beta` - - 稳定 npm 发布可以通过工作流输入显式指向 `latest` - - 基于 token 的 npm dist-tag 变更现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，以提升安全性，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布 - - 公开 `macOS Release` 仅用于验证；当标签只存在于发布分支上但工作流从 `main` 调度时，设置 `public_release_branch=release/YYYY.M.D` - - 真正的私有 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/` 载荷，这样我们就不会再次发布空的浏览器仪表盘 +- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock 一致性门禁，以及快速 live Matrix 配置和 Telegram QA 线路。live 线路使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭证租约。当你希望并行获得完整 Matrix 传输、媒体和 E2EE 清单时，请使用 `matrix_profile=all` 和 `matrix_shards=true` 运行手动 `QA-Lab - All Lanes` 工作流。 +- 跨操作系统安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用工作流 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- 这种拆分是有意的：保持真实 npm 发布路径简短、确定且聚焦产物，同时较慢的 live 检查留在自己的线路中，避免拖慢或阻塞发布 +- 带密钥的发布检查应通过 `Full Release Validation` 分派，或从 `main`/release 工作流引用分派，以便工作流逻辑和密钥保持受控 +- 只要解析出的提交可从 OpenClaw 分支或发布标签访问，`OpenClaw Release Checks` 就接受分支、标签或完整提交 SHA +- `OpenClaw NPM Release` 仅验证预检也接受当前完整 40 字符工作流分支提交 SHA，而不需要已推送标签 +- 该 SHA 路径仅用于验证，不能提升为真实发布 +- 在 SHA 模式下，工作流仅为包元数据检查合成 `v`；真实发布仍需要真实发布标签 +- 两个工作流都将真实发布和提升路径保留在 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 发布预检不再等待单独的发布检查线路 +- 在批准前运行 `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 发布后，运行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`，使用共享租约 Telegram 凭证池，针对已发布的 npm 包验证已安装包的新手引导、Telegram 设置和真实 Telegram E2E。本地维护者的一次性运行可以省略 Convex 变量，直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭证。 +- 维护者可以通过手动 `NPM Telegram Beta E2E` 工作流，从 GitHub Actions 运行相同的发布后检查。它有意仅限手动，不会在每次合并时运行。 +- 维护者发布自动化现在使用预检后提升： + - 真实 npm 发布必须通过成功的 npm `preflight_run_id` + - 真实 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支分派 + - stable npm 发布默认指向 `beta` + - stable npm 发布可通过工作流输入显式指向 `latest` + - 基于 token 的 npm dist-tag 变更现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，以保证安全，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布 + - 公开 `macOS Release` 仅用于验证；当标签只存在于发布分支上、但工作流从 `main` 分派时，设置 `public_release_branch=release/YYYY.M.D` + - 真实私有 mac 发布必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id` + - 真实发布路径会提升已准备好的产物，而不是再次重新构建它们 +- 对于像 `YYYY.M.D-N` 这样的 stable 修正发布，发布后验证器也会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径，因此发布修正不会悄悄让旧的全局安装停留在基础 stable 载荷上 +- 除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 载荷，否则 npm 发布预检会失败关闭，避免我们再次发布空的浏览器仪表板 - 发布后验证还会检查已发布插件入口点和包元数据是否存在于已安装的 registry 布局中。缺少插件运行时载荷的发布会导致 postpublish 验证器失败，且不能提升到 `latest`。 -- `pnpm test:install:smoke` 还会对候选更新 tarball 强制执行 npm pack `unpackedSize` 预算，因此安装器 e2e 能在发布路径前捕获意外的打包膨胀 -- 如果发布工作触及 CI 规划、插件计时清单或插件测试矩阵，请在批准前重新生成并审查 planner 拥有的 `plugin-prerelease-extension-shard` 矩阵输出，来源为 `.github/workflows/plugin-prerelease.yml`，以便发布说明不会描述过期的 CI 布局 -- 稳定 macOS 发布就绪还包括更新器表面： - - GitHub release 最终必须包含打包后的 `.zip`、`.dmg` 和 `.dSYM.zip` - - 发布后，`main` 上的 `appcast.xml` 必须指向新的稳定 zip - - 打包后的应用必须保留非调试 bundle id、非空 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion` +- `pnpm test:install:smoke` 还会对候选更新 tarball 强制执行 npm pack `unpackedSize` 预算，因此安装器 e2e 会在发布路径发布前捕获意外的包体积膨胀 +- 如果发布工作触及 CI 规划、插件 timing manifest 或插件测试矩阵，请在批准前重新生成并审查由 planner 拥有的 `plugin-prerelease-extension-shard` 矩阵输出，来源为 `.github/workflows/plugin-prerelease.yml`，避免发布说明描述过时的 CI 布局 +- stable macOS 发布就绪还包括更新器表面： + - GitHub 发布必须最终包含打包后的 `.zip`、`.dmg` 和 `.dSYM.zip` + - 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip + - 打包后的应用必须保留非 debug bundle id、非空 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion` -## 发布测试箱 +## 发布测试盒 -`Full Release Validation` 是操作员从一个入口点启动所有预发布测试的方式。从受信任的 `main` 工作流 ref 运行它，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入： +`Full Release Validation` 是操作员从一个入口点启动所有预发布测试的方式。从受信任的 `main` 工作流引用运行它，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入： ```bash gh workflow run full-release-validation.yml \ @@ -157,17 +142,17 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -该工作流会解析目标 ref，使用 `target_ref=` 调度手动 `CI`，调度 `OpenClaw Release Checks`，并在 `release_profile=full` 且 `rerun_group=all` 时，或在设置 `npm_telegram_package_spec` 时，调度独立的包 Telegram E2E。随后 `OpenClaw Release Checks` 会扇出安装烟雾测试、跨 OS 发布检查、live/E2E Docker 发布路径覆盖、带 Telegram 包 QA 的 Package Acceptance、QA Lab parity、live Matrix 和 live Telegram。只有当 `Full Release Validation` 摘要显示 `normal_ci` 和 `release_checks` 成功时，完整运行才可接受。在 full/all 模式下，`npm_telegram` 子项也必须成功；在 full/all 之外，除非提供了已发布的 `npm_telegram_package_spec`，否则会跳过它。最终验证器摘要包含每个子运行的最慢作业表，因此发布经理无需下载日志即可看到当前关键路径。 -请参阅 [完整发布验证](/zh-CN/reference/full-release-validation)，了解完整阶段矩阵、精确工作流作业名称、stable 与 full 配置文件差异、产物以及聚焦重跑句柄。 -子工作流从运行 `Full Release Validation` 的受信任 ref 调度，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签也是如此。没有单独的 Full Release Validation 工作流 ref 输入；通过选择工作流运行 ref 来选择受信任的 harness。 +该工作流会解析目标引用，使用 `target_ref=` 分派手动 `CI`，分派 `OpenClaw Release Checks`，并在 `release_profile=full` 且 `rerun_group=all` 时，或设置了 `npm_telegram_package_spec` 时，分派独立包 Telegram E2E。随后 `OpenClaw Release Checks` 会扩展运行安装冒烟、跨操作系统发布检查、live/E2E Docker 发布路径覆盖、带 Telegram 包 QA 的 Package Acceptance、QA Lab 一致性、live Matrix 和 live Telegram。只有当 `Full Release Validation` 摘要显示 `normal_ci` 和 `release_checks` 成功时，完整运行才可接受。在 full/all 模式下，`npm_telegram` 子项也必须成功；在 full/all 之外，除非提供了已发布的 `npm_telegram_package_spec`，否则会跳过它。最终验证器摘要包含每个子运行的最慢作业表，因此发布经理无需下载日志即可看到当前关键路径。 +请参阅 [完整发布验证](/zh-CN/reference/full-release-validation)，了解完整阶段矩阵、精确工作流作业名称、stable 与 full 配置差异、产物和聚焦重跑句柄。 +子工作流会从运行 `Full Release Validation` 的受信任引用分派，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签。没有单独的 Full Release Validation 工作流引用输入；通过选择工作流运行引用来选择受信任的 harness。 -使用 `release_profile` 选择 live/提供商覆盖范围： +使用 `release_profile` 选择 live/provider 广度： - `minimum`：最快的发布关键 OpenAI/core live 和 Docker 路径 -- `stable`：minimum 加上用于发布批准的稳定提供商/后端覆盖 -- `full`：stable 加上广泛的 advisory 提供商/媒体覆盖 +- `stable`：minimum 加上用于发布批准的 stable provider/backend 覆盖 +- `full`：stable 加上广泛的 advisory provider/media 覆盖 -`OpenClaw Release Checks` 使用受信任的工作流 ref，将目标 ref 一次性解析为 `release-package-under-test`，并在 release-path Docker 检查和 Package Acceptance 中复用该构件。这会让所有面向软件包的检查项使用相同字节，并避免重复构建软件包。跨 OS 的 OpenAI 安装冒烟测试会在设置了仓库/组织变量时使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.5`，因为该通道验证的是软件包安装、新手引导、Gateway 网关启动和一次实时智能体轮次，而不是对最慢的默认模型做基准测试。更广泛的实时提供商矩阵仍然是覆盖特定模型的地方。 +`OpenClaw Release Checks` 使用受信任的工作流 ref，将目标 ref 一次性解析为 `release-package-under-test`，并在发布路径 Docker 检查和 Package Acceptance 中复用该产物。这会让所有面向软件包的 boxes 使用相同字节，并避免重复构建软件包。跨 OS OpenAI 安装冒烟在设置了 repo/org 变量时使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.5`，因为这条 lane 证明的是软件包安装、新手引导、Gateway 网关启动和一次实时智能体轮次，而不是对最慢的默认模型做基准测试。更广泛的实时提供商矩阵仍然负责模型特定覆盖。 根据发布阶段使用这些变体： @@ -199,22 +184,22 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -不要把完整总括流程用作聚焦修复后的第一次重跑。如果某个检查项失败，请使用失败的子工作流、作业、Docker 通道、软件包配置、模型提供商或 QA 通道作为下一次验证。只有当修复更改了共享发布编排，或让早先的全检查项证据过期时，才再次运行完整总括流程。总括流程的最终验证器会重新检查记录的子工作流运行 ID，因此在子工作流成功重跑后，只重跑失败的 `Verify full validation` 父作业。 +不要把完整 umbrella 作为定向修复后的首次重跑。如果某个 box 失败，下一次证明应使用失败的子工作流、job、Docker lane、软件包 profile、模型提供商或 QA lane。只有当修复更改了共享发布编排，或让之前的全 box 证据过期时，才再次运行完整 umbrella。umbrella 的最终验证器会重新检查记录的子工作流运行 id，所以在子工作流成功重跑后，只重跑失败的 `Verify full validation` 父 job。 -对于有边界的恢复，请向总括流程传入 `rerun_group`。`all` 是真正的候选发布运行，`ci` 只运行普通 CI 子流程，`plugin-prerelease` 只运行仅发布使用的插件子流程，`release-checks` 运行每个发布检查项，更窄的发布分组是 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 和 `npm-telegram`。聚焦的 `npm-telegram` 重跑需要 `npm_telegram_package_spec`；带有 `release_profile=full` 的 full/all 运行会使用 release-checks 软件包构件。 +对于有界恢复，向 umbrella 传入 `rerun_group`。`all` 是真正的候选发布运行，`ci` 只运行普通 CI 子项，`plugin-prerelease` 只运行仅发布用插件子项，`release-checks` 运行每个发布 box，更窄的发布组包括 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 和 `npm-telegram`。定向 `npm-telegram` 重跑需要 `npm_telegram_package_spec`；带有 `release_profile=full` 的 full/all 运行使用 release-checks 软件包产物。 ### Vitest -Vitest 检查项是手动 `CI` 子工作流。手动 CI 会有意绕过变更范围限制，并对候选发布强制执行普通测试图：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n。 +Vitest box 是手动 `CI` 子工作流。手动 CI 会有意绕过 changed 范围限定，并为候选发布强制运行常规测试图：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n。 -用这个检查项回答“源代码树是否通过了完整的普通测试套件？”它与 release-path 产品验证不同。需要保留的证据： +使用这个 box 来回答“源码树是否通过了完整的常规测试套件？”它与发布路径产品验证不同。需要保留的证据： -- `Full Release Validation` 摘要，显示已派发的 `CI` 运行 URL -- `CI` 在精确目标 SHA 上为绿色 -- 调查回归时来自 CI 作业的失败或较慢分片名称 -- 当某次运行需要性能分析时，保留 Vitest 计时构件，例如 `.artifacts/vitest-shard-timings.json` +- `Full Release Validation` 摘要，显示已调度的 `CI` 运行 URL +- `CI` 在精确目标 SHA 上变绿 +- 调查回归时来自 CI jobs 的失败或较慢分片名称 +- 当运行需要性能分析时，保留 Vitest 计时产物，例如 `.artifacts/vitest-shard-timings.json` -只有当发布需要确定性的普通 CI，而不需要 Docker、QA Lab、实时、跨 OS 或软件包检查项时，才直接运行手动 CI： +只有当发布需要确定性的常规 CI，但不需要 Docker、QA Lab、实时、跨 OS 或软件包 boxes 时，才直接运行手动 CI： ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -222,51 +207,51 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Docker 检查项位于 `OpenClaw Release Checks` 中，通过 `openclaw-live-and-e2e-checks-reusable.yml` 以及 release-mode `install-smoke` 工作流执行。它通过已打包的 Docker 环境验证候选发布，而不只是源代码级测试。 +Docker box 位于 `OpenClaw Release Checks` 中，通过 `openclaw-live-and-e2e-checks-reusable.yml` 以及发布模式的 `install-smoke` 工作流运行。它通过打包后的 Docker 环境验证候选发布，而不只是源码级测试。 发布 Docker 覆盖包括： -- 启用较慢 Bun 全局安装冒烟的完整安装冒烟 -- 按目标 SHA 准备/复用根 Dockerfile 冒烟镜像，并将 QR、root/gateway 和 installer/Bun 冒烟作业作为单独的 install-smoke 分片运行 -- 仓库 E2E 通道 -- release-path Docker 分块：`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g` 和 `plugins-runtime-install-h` -- 请求时，在 `plugins-runtime-services` 分块内覆盖 OpenWebUI -- 拆分的内置插件安装/卸载通道，从 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23` -- 当发布检查包含实时套件时，覆盖 live/E2E 提供商套件和 Docker 实时模型 +- 启用慢速 Bun 全局安装冒烟的完整安装冒烟 +- 按目标 SHA 准备/复用根 Dockerfile 冒烟镜像，其中 QR、root/gateway 和 installer/Bun 冒烟 jobs 作为独立 install-smoke 分片运行 +- 仓库 E2E lanes +- 发布路径 Docker chunks：`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g` 和 `plugins-runtime-install-h` +- 请求时在 `plugins-runtime-services` chunk 内进行 OpenWebUI 覆盖 +- 拆分的内置插件安装/卸载 lanes，从 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23` +- 当发布检查包含实时套件时，运行实时/E2E 提供商套件和 Docker 实时模型覆盖 -重跑前先使用 Docker 构件。release-path 调度器会上传 `.artifacts/docker-tests/`，其中包含通道日志、`summary.json`、`failures.json`、阶段计时、调度计划 JSON 和重跑命令。对于聚焦恢复，请在可复用 live/E2E 工作流上使用 `docker_lanes=`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含先前的 `package_artifact_run_id` 和已准备 Docker 镜像输入，因此失败通道可以复用同一个 tarball 和 GHCR 镜像。 +重跑前先使用 Docker 产物。发布路径调度器会上传 `.artifacts/docker-tests/`，其中包含 lane 日志、`summary.json`、`failures.json`、阶段计时、调度器计划 JSON 和重跑命令。对于定向恢复，在可复用实时/E2E 工作流上使用 `docker_lanes=`，而不是重跑所有发布 chunks。生成的重跑命令会在可用时包含之前的 `package_artifact_run_id` 和已准备 Docker 镜像输入，因此失败 lane 可以复用相同 tarball 和 GHCR 镜像。 ### QA Lab -QA Lab 检查项也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布门禁，与 Vitest 和 Docker 软件包机制分开。 +QA Lab box 也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布门禁，独立于 Vitest 和 Docker 软件包机制。 发布 QA Lab 覆盖包括： -- 使用 agentic parity pack，将 OpenAI 候选通道与 Opus 4.6 基线进行比较的 mock parity gate -- 使用 `qa-live-shared` 环境的快速实时 Matrix QA 配置 -- 使用 Convex CI 凭证租约的实时 Telegram QA 通道 -- 当发布遥测需要显式本地证明时运行 `pnpm qa:otel:smoke` +- mock parity gate，使用 agentic parity pack 将 OpenAI 候选 lane 与 Opus 4.6 基线对比 +- 使用 `qa-live-shared` 环境的快速实时 Matrix QA profile +- 使用 Convex CI 凭据租约的实时 Telegram QA lane +- 当发布遥测需要明确本地证明时，运行 `pnpm qa:otel:smoke` -用这个检查项回答“发布在 QA 场景和实时渠道流中表现是否正确？”批准发布时保留 parity、Matrix 和 Telegram 通道的构件 URL。完整 Matrix 覆盖仍然可以作为手动分片 QA-Lab 运行使用，而不是默认的发布关键通道。 +使用这个 box 来回答“发布在 QA 场景和实时渠道流中是否表现正确？”批准发布时保留 parity、Matrix 和 Telegram lanes 的产物 URL。完整 Matrix 覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认的发布关键 lane。 ### 软件包 -软件包检查项是可安装产品门禁。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支撑。解析器会将候选项标准化为 Docker E2E 使用的 `package-under-test` tarball，验证软件包清单，记录软件包版本和 SHA-256，并让工作流 harness ref 与软件包来源 ref 保持分离。 +软件包 box 是可安装产品门禁。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支撑。解析器会将候选规范化为供 Docker E2E 使用的 `package-under-test` tarball，验证软件包清单，记录软件包版本和 SHA-256，并将工作流 harness ref 与软件包源码 ref 分开。 支持的候选来源： -- `source=npm`：`openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本 -- `source=ref`：使用选定的 `workflow_ref` harness 打包受信任的 `package_ref` 分支、标签或完整提交 SHA +- `source=npm`：`openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本 +- `source=ref`：使用选定的 `workflow_ref` harness 打包受信任的 `package_ref` 分支、tag 或完整 commit SHA - `source=url`：下载需要 `package_sha256` 的 HTTPS `.tgz` - `source=artifact`：复用另一个 GitHub Actions 运行上传的 `.tgz` -`OpenClaw Release Checks` 使用 `source=artifact`、已准备的发布软件包构件、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`published_upgrade_survivor_baselines=release-history`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai` 运行 Package Acceptance。Package Acceptance 会针对同一个已解析 tarball 保持迁移、更新、陈旧插件依赖清理、离线插件 fixture、插件更新和 Telegram 软件包 QA。它是大多数软件包/更新覆盖的 GitHub 原生替代方案，这些覆盖以前需要 Parallels。跨 OS 发布检查对 OS 特定的新手引导、安装器和平台行为仍然重要，但软件包/更新产品验证应优先使用 Package Acceptance。 +`OpenClaw Release Checks` 使用 `source=artifact`、已准备的发布软件包产物、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`published_upgrade_survivor_baselines=release-history`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai` 运行 Package Acceptance。Package Acceptance 会让迁移、更新、过期插件依赖清理、离线插件 fixtures、插件更新和 Telegram 软件包 QA 使用同一个已解析 tarball。它是 GitHub 原生的替代方案，用于覆盖此前大多需要 Parallels 的软件包/更新验证。跨 OS 发布检查对于 OS 特定的新手引导、安装器和平台行为仍然重要，但软件包/更新产品验证应优先使用 Package Acceptance。 -更新和插件验证的规范清单是 [更新和插件测试](/zh-CN/help/testing-updates-plugins)。在决定哪个本地、Docker、Package Acceptance 或 release-check 通道能够证明插件安装/更新、Doctor 清理或已发布软件包迁移变更时，请使用它。 +更新和插件验证的标准清单是 [更新和插件测试](/zh-CN/help/testing-updates-plugins)。在判断哪条本地、Docker、Package Acceptance 或 release-check lane 能证明插件安装/更新、Doctor 清理或已发布软件包迁移变更时使用它。从每个稳定版 `2026.4.23+` 软件包进行的穷尽式已发布更新迁移是单独的手动 `Update Migration` 工作流，不属于 Full Release CI。 -旧版 package-acceptance 宽容路径有意设置了时间边界。截至 `2026.4.25` 的软件包可以对已发布到 npm 的元数据缺口使用兼容路径：tarball 中缺少私有 QA 清单条目、缺少 `gateway install --wrapper`、tarball 派生 git fixture 中缺少补丁文件、缺少持久化的 `update.channel`、旧版插件安装记录位置、缺少 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` 软件包可能会对已经发货的本地构建元数据戳文件发出警告。后续软件包必须满足现代软件包契约；相同缺口会导致发布验证失败。 +旧版 package-acceptance 宽松处理是有意限时的。直到 `2026.4.25` 的软件包可以对已发布到 npm 的元数据缺口使用兼容路径：tarball 中缺少私有 QA 清单条目、缺少 `gateway install --wrapper`、tarball 派生 git fixture 中缺少补丁文件、缺少持久化的 `update.channel`、旧版插件安装记录位置、缺少 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` 软件包可以对已经发布的本地构建元数据 stamp 文件发出警告。后续软件包必须满足现代软件包契约；相同缺口会导致发布验证失败。 -当发布问题涉及实际可安装软件包时，请使用更广泛的 Package Acceptance 配置： +当发布问题涉及实际可安装软件包时，使用更广泛的 Package Acceptance profiles： ```bash gh workflow run package-acceptance.yml \ @@ -278,73 +263,72 @@ gh workflow run package-acceptance.yml \ -f published_upgrade_survivor_baseline=openclaw@2026.4.26 ``` -常见软件包配置： +常用软件包 profiles： -- `smoke`：快速软件包安装/渠道/智能体、Gateway 网关网络和配置重载通道 -- `package`：不依赖实时 ClawHub 的安装/更新/插件软件包契约；这是 release-check 默认值 -- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI Web 搜索和 OpenWebUI -- `full`：带 OpenWebUI 的 Docker release-path 分块 -- `custom`：用于聚焦重跑的精确 `docker_lanes` 列表 +- `smoke`：快速软件包安装/渠道/智能体、Gateway 网关网络和配置重载 lanes +- `package`：不含实时 ClawHub 的安装/更新/插件软件包契约；这是 release-check 默认值 +- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI +- `full`：带 OpenWebUI 的 Docker 发布路径 chunks +- `custom`：用于定向重跑的精确 `docker_lanes` 列表 -对于软件包候选的 Telegram 证明，请在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该工作流会把已解析的 `package-under-test` tarball 传入 Telegram 通道；独立的 Telegram 工作流仍然接受已发布的 npm spec，用于发布后检查。 +对于软件包候选 Telegram 证明，在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该工作流会将已解析的 `package-under-test` tarball 传入 Telegram lane；独立 Telegram 工作流仍接受用于发布后检查的已发布 npm 规范。 ## NPM 工作流输入 -`OpenClaw NPM Release` 接受这些由操作者控制的输入： +`OpenClaw NPM Release` 接受这些操作员控制的输入： -- `tag`：必需的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 `v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前完整的 40 字符工作流分支提交 SHA，用于仅验证的 preflight -- `preflight_only`：`true` 表示只进行验证/构建/打包，`false` 表示真实发布路径 -- `preflight_run_id`：真实发布路径必填，这样工作流会复用成功 preflight 运行中准备好的 tarball -- `npm_dist_tag`：发布路径的 npm 目标标签；默认值为 `beta` +- `tag`：必需的发布 tag，例如 `v2026.4.2`、`v2026.4.2-1` 或 `v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前工作流分支的完整 40 字符 commit SHA，用于仅验证 preflight +- `preflight_only`：`true` 表示仅验证/构建/打包，`false` 表示真实发布路径 +- `preflight_run_id`：真实发布路径必需，这样工作流可复用成功 preflight 运行中准备好的 tarball +- `npm_dist_tag`：发布路径的 npm 目标 tag；默认为 `beta` -`OpenClaw Release Checks` 接受这些由操作者控制的输入： +`OpenClaw Release Checks` 接受这些操作员控制的输入： -- `ref`：要验证的分支、标签或完整提交 SHA。带有密钥的检查要求解析后的提交可从 OpenClaw 分支或发布标签访问。 +- `ref`：要验证的分支、tag 或完整 commit SHA。带密钥的检查要求解析出的 commit 可从 OpenClaw 分支或发布 tag 到达。 规则： -- 稳定版和修正版标签可以发布到 `beta` 或 `latest` -- Beta 预发布标签只能发布到 `beta` -- 对于 `OpenClaw NPM Release`，只有在 `preflight_only=true` 时才允许输入完整提交 SHA -- `OpenClaw Release Checks` 和 `Full Release Validation` 始终只用于验证 +- 稳定版和修正版 tag 可以发布到 `beta` 或 `latest` +- Beta 预发布 tag 只能发布到 `beta` +- 对于 `OpenClaw NPM Release`，只有在 `preflight_only=true` 时才允许完整 commit SHA 输入 +- `OpenClaw Release Checks` 和 `Full Release Validation` 始终只做验证 - 真实发布路径必须使用 preflight 期间使用的同一个 `npm_dist_tag`；工作流会在发布继续前验证该元数据 -## 稳定 npm 发布流程 +## 稳定版 npm 发布流程 -切稳定 npm 发布时： +切稳定版 npm 发布时： -1. 使用 `OpenClaw NPM Release` 并设置 `preflight_only=true` +1. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true` - 在标签存在之前，你可以使用当前完整工作流分支提交 - SHA，对预检工作流进行仅验证的 dry run -2. 为常规 beta 优先流程选择 `npm_dist_tag=beta`，仅在 - 你有意直接发布稳定版时才选择 `latest` -3. 当你希望从一个手动工作流获得常规 CI 以及实时 prompt cache、Docker、QA Lab、 - Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整 + SHA 对预检工作流执行一次仅验证的试运行 +2. 为常规 beta 优先流程选择 `npm_dist_tag=beta`，只有在你有意直接发布稳定版时才选择 `latest` +3. 当你希望通过一个手动工作流获得常规 CI，以及实时提示缓存、Docker、QA Lab、 + Matrix 和 Telegram 覆盖时，请在发布分支、发布标签或完整 提交 SHA 上运行 `Full Release Validation` -4. 如果你有意只需要确定性的常规测试图，请改为在发布引用上运行 +4. 如果你明确只需要确定性的常规测试图，请改为在发布引用上运行 手动 `CI` 工作流 5. 保存成功的 `preflight_run_id` 6. 再次运行 `OpenClaw NPM Release`，并设置 `preflight_only=false`、相同的 `tag`、相同的 `npm_dist_tag`，以及保存的 `preflight_run_id` 7. 如果发布落在 `beta` 上，请使用私有 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - 工作流，将该稳定版本从 `beta` 提升到 `latest` -8. 如果发布有意直接发布到 `latest`，且 `beta` + 工作流将该稳定版本从 `beta` 提升到 `latest` +8. 如果发布有意直接发布到 `latest`，并且 `beta` 应立即跟随同一个稳定构建，请使用同一个私有 - 工作流将两个 dist-tag 都指向该稳定版本，或让其定时的 - 自愈同步稍后移动 `beta` + 工作流将两个 dist-tags 都指向该稳定版本，或者让它的计划 + 自修复同步稍后移动 `beta` 出于安全原因，dist-tag 变更位于私有仓库中，因为它仍然 需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布。 -这让直接发布路径和 beta 优先提升路径都得到 -文档记录，并且对操作人员可见。 +这样会让直接发布路径和 beta 优先提升路径都 +有文档记录，并且对操作人员可见。 -如果维护者必须回退到本地 npm 身份验证，请仅在专用 tmux 会话内运行任何 1Password -CLI（`op`）命令。不要直接从主 agent shell 调用 `op`；将其放在 tmux 内可让提示、 +如果维护者必须回退到本地 npm 身份验证，请只在专用 tmux 会话中运行任何 1Password +CLI（`op`）命令。不要直接从主智能体 shell 调用 `op`；将它保留在 tmux 中可以让提示、 警报和 OTP 处理可观察，并防止重复的主机警报。 -## 公开参考 +## 公共参考资料 - [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml) - [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml) @@ -360,6 +344,6 @@ CLI（`op`）命令。不要直接从主 agent shell 调用 `op`；将其放在 [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) 中的私有发布文档作为实际运行手册。 -## 相关 +## 相关内容 - [发布渠道](/zh-CN/install/development-channels) diff --git a/docs/zh-CN/reference/test.md b/docs/zh-CN/reference/test.md index c66e8a7a7..cbedf7f1b 100644 --- a/docs/zh-CN/reference/test.md +++ b/docs/zh-CN/reference/test.md @@ -4,10 +4,10 @@ read_when: summary: 如何在本地运行测试（vitest），以及何时使用 force/coverage 模式 title: 测试 x-i18n: - generated_at: "2026-05-01T22:37:21Z" + generated_at: "2026-05-01T23:38:22Z" model: gpt-5.5 provider: openai - source_hash: 3dddc0a772a422264f52096a43c601897fa0109c600f26d45274409fe26c5184 + source_hash: b2bf9cf1024d78747d97b5f4fb41ae42fe6cba547db023b78f3d0dcd4ba5128d source_path: reference/test.md workflow: 16 --- @@ -15,47 +15,48 @@ x-i18n: - 完整测试工具包（套件、实时测试、Docker）：[测试](/zh-CN/help/testing) - 更新和插件包验证：[更新和插件测试](/zh-CN/help/testing-updates-plugins) -- `pnpm test:force`：终止任何仍占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整 Vitest 套件，避免服务器测试与正在运行的实例冲突。当先前的 Gateway 网关运行让端口 18789 被占用时使用此命令。 -- `pnpm test:coverage`：使用 V8 覆盖率运行单元套件（通过 `vitest.unit.config.ts`）。这是已加载文件的单元覆盖率门禁，不是整个仓库所有文件的覆盖率。阈值为行/函数/语句 70%，分支 55%。由于 `coverage.all` 为 false，该门禁衡量单元覆盖率套件加载的文件，而不是把每个拆分车道的源文件都视为未覆盖。 +- `pnpm test:force`：终止任何仍占用默认控制端口的 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整 Vitest 套件，避免服务器测试与正在运行的实例冲突。当先前的 Gateway 网关运行留下端口 18789 被占用时使用此命令。 +- `pnpm test:coverage`：使用 V8 coverage 运行单元套件（通过 `vitest.unit.config.ts`）。这是已加载文件的单元覆盖率门禁，不是整个仓库的全文件覆盖率。阈值为行/函数/语句 70%，分支 55%。由于 `coverage.all` 为 false，该门禁衡量的是单元覆盖率套件加载的文件，而不是把每个拆分 lane 的源文件都视为未覆盖。 - `pnpm test:coverage:changed`：仅对自 `origin/main` 以来更改的文件运行单元覆盖率。 -- `pnpm test:changed`：低成本的智能变更测试运行。它会从直接测试编辑、同级 `*.test.ts` 文件、显式源码映射以及本地导入图中运行精确目标。宽泛的配置/包更改会被跳过，除非它们映射到精确测试。 -- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`：显式宽泛变更测试运行。当测试 harness/配置/包编辑应回退到 Vitest 更宽泛的变更测试行为时使用。 -- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 触发的架构车道。 -- `pnpm check:changed`：针对相对于 `origin/main` 的 diff 运行智能变更检查门禁。它会为受影响的架构车道运行 typecheck、lint 和 guard 命令，但不会运行 Vitest 测试。使用 `pnpm test:changed` 或显式 `pnpm test ` 作为测试证明。 -- `pnpm test`：将显式文件/目录目标路由到有作用域的 Vitest 车道。无目标运行会使用固定分片组，并展开到叶子配置以便本地并行执行；扩展组始终展开到按扩展划分的分片配置，而不是一个巨大的根项目进程。 -- 测试包装器运行结束时会输出简短的 `[test] passed|failed|skipped ... in ...` 摘要。Vitest 自己的耗时行仍作为每个分片的细节保留。 +- `pnpm test:changed`：低成本的智能变更测试运行。它会从直接测试编辑、相邻 `*.test.ts` 文件、显式源映射以及本地导入图运行精确目标。广泛的配置/包变更会被跳过，除非它们映射到精确测试。 +- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`：显式的广泛变更测试运行。当测试 harness/配置/包编辑应回退到 Vitest 更广泛的变更测试行为时使用。 +- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 触发的架构 lane。 +- `pnpm check:changed`：针对相对于 `origin/main` 的 diff 运行智能变更检查门禁。它会为受影响的架构 lane 运行 typecheck、lint 和 guard 命令，但不会运行 Vitest 测试。使用 `pnpm test:changed` 或显式 `pnpm test ` 获取测试证明。 +- `pnpm test`：将显式文件/目录目标路由到有作用域的 Vitest lane。无目标运行会使用固定分片组，并展开为 leaf config 以便本地并行执行；extension 组始终展开为按扩展分片的配置，而不是一个巨大的根项目进程。 +- 测试 wrapper 运行结束时会有简短的 `[test] passed|failed|skipped ... in ...` 摘要。Vitest 自身的耗时行仍然保留为每个分片的细节。 - 共享 OpenClaw 测试状态：当测试需要隔离的 `HOME`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`、配置 fixture、工作区、智能体目录或 auth-profile 存储时，在 Vitest 中使用 `src/test-utils/openclaw-test-state.ts`。 -- 进程 E2E helper：当 Vitest 进程级 E2E 测试需要运行中的 Gateway 网关、CLI 环境、日志捕获和集中清理时，使用 `test/helpers/openclaw-test-instance.ts`。 -- Docker/Bash E2E helper：source `scripts/lib/docker-e2e-image.sh` 的车道可以把 `docker_e2e_test_state_shell_b64