OpenClaw测试技能

一、技能概述

该技能用于在决定测试什么、调试失败、重跑 CI 或验证一个变更时使用。它提供了从本地聚焦测试到远程大规模测试的完整路由模型，帮助开发者用最少的成本获得最高的验证信心。

核心原则：先按源码信任度路由，再按验证规模路由。

二、核心功能

1. 测试路由模型（Routing Model）

技能根据变更的信任度和规模，自动选择最合适的验证路径：

验证类型	适用场景	执行方式
本地聚焦测试	可信源、少量聚焦测试、本地依赖已就绪	`node scripts/run-vitest.mjs <file>`
远程验证	变更门控、类型检查/lint 扇出、构建、Docker、打包、E2E、跨平台	Blacksmith Testbox 或 AWS Crabbox

可信维护者的重度验证默认使用 Blacksmith Testbox
不可信贡献者或 fork 代码必须使用无密钥的 fork CI 或经过清理的直接 AWS Crabbox

2. 变更分类命令

技能提供一系列命令来帮助分类变更和选择验证路径：

命令	用途
`pnpm changed:lanes --json`	回答“这个 diff 触及了哪些检查通道？”
`pnpm check:changed`	本地小规模计划或委托的重度计划（不含 Vitest）
`pnpm test:changed`	智能变更 Vitest 目标
`pnpm verify`	完整检查 + 完整 Vitest
`pnpm test <file>`	针对特定文件的聚焦测试

命令语义：

pnpm check 和 pnpm check:changed 不运行 Vitest 测试——它们只做类型检查、lint 和门控证明
pnpm test 和 pnpm test:changed 运行 Vitest 测试
pnpm verify 先运行 pnpm check，再运行 pnpm test

3. 测试目标解析器

技能定义了精准的测试目标选择规则：

直接测试编辑：运行自己
源码编辑：优先使用显式映射、兄弟 *.test.ts，然后是导入图依赖项
共享 harness/config/root 编辑：默认跳过（除非有精确映射的测试）
共享群组消息配置和源码回复提示编辑：有精确映射的测试——运行核心自动回复回归 + Discord/Slack 投递测试
公共 SDK 或契约编辑：不会自动运行所有插件测试——选择最小的代表性插件/契约 Vitest 证明

4. 远程验证后端

技能支持两种远程验证后端：

后端	说明	标识
Blacksmith Testbox	可信维护者的默认重度验证后端	`provider=blacksmith-testbox`，`tbx_...` ID
AWS Crabbox	直接 AWS 验证	`provider=aws`，`cbx_...` ID

远程验证启动：

懒加载后端——不要为预期的工作预热
第一次重度命令准备好运行时获取后端，保存其 ID，后续重度命令复用，交接前停止
单个重度命令可以保持一次性

不可信代码的 AWS Crabbox 要求：

CRABBOX_ENV_ALLOW=CI 必须替换仓库的 OPENCLAW_* allowlist
--no-hydrate 必须阻止认证配置文件注入
远程命令必须使用全新的临时 HOME
从干净的受信任 main checkout 启动已安装的受信任 Crabbox 二进制文件，用 --fresh-pr 获取 PR
取消设置 CRABBOX_AWS_INSTANCE_PROFILE 和所有 CRABBOX_TAILSCALE* 覆盖
上传受信任的 scripts/crabbox-untrusted-bootstrap.sh，它引导 Node 24 和仓库锁定的 pnpm

5. CI 调试

技能提供了高效的 CI 调试工作流：

gh run list --branch main --limit 10
gh run view <run> --json status,conclusion,headSha,url,jobs
gh run view <run> --job <job> --log

检查确切的 SHA，忽略更新的不相关 main
对于被取消的同分支运行，确认是否有更新的运行取代了它
只获取失败或相关 job 的完整日志
调试时优先使用 gh run view <run> --json jobs，而非 PR 汇总（汇总可能过时/有噪音）

6. Docker 测试

Docker 测试是昂贵的，技能提供了先检查再运行的工作流：

先做干跑（Dry Run）：

OPENCLAW_DOCKER_ALL_DRY_RUN=1 pnpm test:docker:all
OPENCLAW_DOCKER_ALL_LANES=install-e2e node scripts/test-docker-all.mjs --plan-json

运行单个失败通道（仅在明确要求或 GitHub 不可用时）：

OPENCLAW_DOCKER_ALL_LANES=<lane> \
OPENCLAW_DOCKER_ALL_BUILD=0 \
OPENCLAW_DOCKER_ALL_PREFLIGHT=0 \
OPENCLAW_SKIP_DOCKER_BUILD=1 \
pnpm test:docker:all

Docker 分块：发布路径将 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
openwebui

7. 发布验证工作流

技能提供了完整的发布验证工作流：

Full Release Validation（.github/workflows/full-release-validation.yml）是手动产品验证的总工作流。它在产品完整的、变更日志之前的 Code SHA 上运行完整的子矩阵：

node scripts/full-release-validation-at-sha.mjs \
  --sha <SHA> \
  --target-ref release/YYYY.M.PATCH

它分派以下子工作流：

CI：完整正常 CI 图（含 Android）
Plugin Prerelease：发布专用插件静态检查、扩展分片、agentic-plugins 分片和插件产品 Docker 通道
OpenClaw Release Checks：安装冒烟测试、跨操作系统发布检查、Live/E2E 检查、Docker 发布路径套件、OpenWebUI、QA Lab、快速 Matrix 和 Telegram 发布通道

rerun_group 支持：修复后，使用最窄的组覆盖失败的盒子：

all、ci、plugin-prerelease、release-checks、install-smoke、cross-os、live-e2e、package、qa、qa-parity、qa-live、npm-telegram

8. Package Acceptance

当问题是“这个可安装包作为产品能工作吗？”而非“这个源码 diff 能通过 Vitest 吗？”时，使用 Package Acceptance 工作流：

gh workflow run package-acceptance.yml --ref main \
  -f source=npm \
  -f workflow_ref=main \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f telegram_mode=mock-openai

Package 候选选择：

source=npm：只接受 openclaw@beta、openclaw@latest 或精确的 OpenClaw 发布版本
source=url：tarball URL + package_sha256
source=artifact：Actions tarball artifact
source=ref：未发布的源码候选（受信任 ref 或 SHA）

Profile：

smoke：快速信心验证——tarball 安装、能 onboard 一个通道、能运行一个 agent turn

9. 插件包验证

验证外部或官方插件包时，分开证明包形状和信任形状：

本地发布候选证明：打包插件并用 openclaw plugins install npm-pack:<path> --force 安装
官方信任证明：如果行为依赖于 bundled-plugin 或受信任官方插件状态，通过 catalog-backed 官方安装或已发布包路径进行第二次证明
本地 npm-pack: 证明不足以用于特权 helper 或受信任官方作用域处理

三、主要用途

变更后选择最便宜的验证路径
根据变更的信任度和规模，自动选择本地聚焦测试或远程验证，避免本能地跑全量套件
调试 CI 失败
通过 gh run view 获取精确的失败 job 日志，而非盲目重跑全量 CI
发布候选验证
在 Beta/Stable 发布前运行 Full Release Validation，验证所有产品维度
Docker E2E 测试
通过干跑先检查计划，再运行单个失败通道，避免昂贵的全量 Docker 构建
Package Acceptance 验证
验证已发布的 npm 包是否可作为产品正常工作
插件包验证
验证官方或外部插件包的形状和信任状态

四、重要原则

先证明接触面，不要本能地跑全量套件
按源码信任度路由，再按验证规模路由
可信源可在本地运行聚焦测试；不可信仓库工具****绝不在本地执行
不要为预期的工作预热后端——懒加载，第一次重度命令准备好时获取
重用后端时不要使用 --no-sync（除非有意重跑未变更的已同步树）
不要杀死不相关的进程或测试——如果其他东西在运行，视为用户或其他 agent 拥有
不要在 Codex worktree 或 linked/sparse checkout 中直接运行本地 pnpm test*——使用 node scripts/run-vitest.mjs 进行聚焦本地证明
pnpm test:changed 默认是廉价的——只有 harness/config/package 编辑真正需要时才用 OPENCLAW_TEST_CHANGED_BROAD=1
不要因为核心变更就运行扩展 sweep——如果核心编辑是针对特定插件 bug，显式运行该插件的测试
不可信贡献者或 fork 代码必须使用无密钥的 fork CI 或经过清理的直接 AWS Crabbox

总结：OpenClaw Testing 是 OpenClaw 项目测试验证的核心路由技能，通过“先按信任度路由、再按规模路由”的原则，帮助开发者和维护者用最少的成本获得最高的验证信心。它覆盖了从本地聚焦测试到远程 Blacksmith Testbox/AWS Crabbox 验证、从 CI 调试到 Full Release Validation、从 Docker E2E 到 Package Acceptance 的完整测试谱系，是 OpenClaw 开发流程中不可或缺的质量保障工具。