openclaw-test-performance

OpenClaw 测试性能

以证据为先。目标是在保持覆盖率完整的前提下，真正提升 pnpm test、插件套件和插件检查器的速度与 RSS，而不是凭猜测调整运行器。

工作流

1. 编辑前，阅读相关的本地 AGENTS.md 文件：
   • src/agents/AGENTS.md，了解 Agent／导入热点。
   • src/channels/AGENTS.md 和 src/plugins/AGENTS.md，了解插件／渠道的延迟加载。
   • src/gateway/AGENTS.md，了解服务生命周期测试。
   • test/helpers/AGENTS.md 和 src/channels/plugins/contracts/test-helpers/AGENTS.md，了解共享契约辅助工具。
   • src/infra/outbound/AGENTS.md，了解出站／媒体／操作测试。
2. 修改代码前，先建立基线：
   • 完整套件排名优先使用 pnpm test:perf:groups --full-suite --allow-failures --output <file>。
   • 对于打包的插件覆盖范围，先运行最小相关的 pnpm test:extensions:batch <plugin[,plugin...]> 或插件检查器命令，再考虑运行完整扩展扫描。
   • 针对特定热点，使用： /usr/bin/time -l pnpm test <file-or-files> --maxWorkers=1 --reporter=verbose
   • 怀疑导入开销较大时，添加 OPENCLAW_VITEST_IMPORT_DURATIONS=1 OPENCLAW_VITEST_PRINT_IMPORT_BREAKDOWN=1。
3. 区分实际文件开销与墙钟时间／运行器噪声：
   • 对比 Vitest 耗时、测试主体耗时、导入明细、墙钟时间和最大 RSS。
   • 如果分组／完整套件的数字看起来过时或有噪声，重新单独运行相关文件。
   • 如果完整套件分组运行报告某个通道失败，但 JSON 显示测试通过，将其记录为测试框架／噪声问题，并直接验证可疑文件。
4. 按收益和风险选择下一步攻关方向：
   • 高收益：某个文件／测试占用了大量时间或 RSS，且根因明确。
   • 高杠杆：某个插件或 SDK 汇总入口导致每次插件检查器或扩展批处理运行都加载庞大的运行时。
   • 风险较低：静态描述符、目标解析、路由、认证绕过、设置提示、注册表 fixture 或测试服务生命周期。
   • 风险较高：真实内存／运行时行为、在线提供方、协议契约或大范围生产代码重构。
5. 修复根因，而非表象：
   • 将静态元数据／解析逻辑移至精简的辅助工具或轻量产物，并供完整运行时和快速路径复用。
   • 优先采用依赖注入、仅查询已加载插件、显式 fixture 和纯辅助函数，而非大范围 mock。
   • 如果无需重新握手，复用套件级服务／客户端。
   • 除非测试用于验证调度，否则不要启动调度器／后台循环。
   • 在插件路径中，将静态元数据移至清单／轻量产物，并将运行时插件加载限制在明确的执行边界内。
6. 保持覆盖范围形态：
   • 除非将完全相同的生产环境组合逻辑提取到具名辅助函数并经过测试，否则不要删除耗时较长的集成验证。
   • 如果跨组件连线很重要，保留一个开销低的集成冒烟测试。
   • 如有移除任何附带覆盖，请明确说明。
7. 修改后，用相同命令重新跑基准，并计算节省的秒数和百分比增幅。
8. 按要求更新持续维护的报告，或在线程正在跟踪报告时更新。包括修改前后的命令、产物、覆盖率说明、验证结果和下一步攻关顺序。
9. 将预期路径加入暂存区，使用标准 Git 提交；用户要求提交／推送时再推送。只暂存此次攻关修改的文件。

插件套件工作流

当性能工作涉及捆绑插件、plugin-inspector、SDK 桶文件、包边界测试或扩展套件时，使用本节。

1. 先梳理套件结构：
   • 源码测试：pnpm test extensions/<id> 或 pnpm test:extensions:batch <id>
   • 包边界：pnpm run test:extensions:package-boundary:canary 和 pnpm run test:extensions:package-boundary:compile
   • 所有捆绑插件的源码测试：pnpm test:extensions
   • 插件导入内存：pnpm test:extensions:memory -- --json .artifacts/test-perf/extensions-memory.json
   • plugin-inspector/报告工作：将报告原语保留在 plugin-inspector 中； 保持包装器轻量；如果命令支持，则收集峰值 RSS。
2. 从小范围开始，再扩大范围：
   • 单个插件发生变更：运行该插件的测试和 plugin-inspector 对应切片。
   • SDK/公共桶文件发生变更：添加具有代表性的提供方、通道、内存和 功能插件。
   • 加载器/运行时镜像发生变更：根据需要添加包边界检查以及构建/打包 证明。
   • 共享插件行为尚不明确：先运行 test:extensions:batch 各组，再运行 pnpm test:extensions。
3. 将 plugin-inspector 故障视为产品信号：
   • JSON 必须能够解析。
   • 警告/错误必须分类，不能隐藏。
   • 运行时捕获应无额外输出，并能容忍配置差异。
   • 命令输出应包含墙钟时间、退出代码和峰值 RSS（如果 可用）。
4. 主机选择请遵循 $openclaw-testing。在机器/负载条件相当时，可信源码基准 测试可以在本地运行。如果验证需要 干净打包、Linux/平台行为、隔离或明确的远程请求，请使用 $crabbox； 仅复用并清理所拥有的租约。
5. 如果插件性能对包构建产物敏感，请改用 release-openclaw-plugin-testing 和包验收，而不是 仅依赖源码计时结果。

指标收集

前后至少收集一个稳定指标。优先使用同一台机器和 同一条命令。进行 Testbox 比较时，尽可能使用同一个 tbx_... ID。

指标	用途	首选来源
墙钟时间	用户可见的套件成本	/usr/bin/time -l、测试包装器耗时、Testbox 运行时间
Vitest 耗时	测试主体/导入成本	Vitest 按文件/分片输出的结果
导入耗时	大范围桶文件/运行时加载	OPENCLAW_VITEST_IMPORT_DURATIONS=1
最大 RSS	内存压力和 OOM 风险	/usr/bin/time -l、pnpm test:extensions:memory、包装器内存摘要
CPU/用户/系统	CPU 受限与等待受限的区分	本地使用 /usr/bin/time -l；本地 CPU 噪声较大时使用 Testbox 作业计时
堆证据	实际泄漏与被保留的模块图之间的区别	openclaw-test-heap-leaks 工作流

本地定向命令（CPU/RSS）：

timeout 240 /usr/bin/time -l pnpm test <file> --maxWorkers=1 --reporter=verbose

插件导入内存剖析：

pnpm build
pnpm test:extensions:memory -- --top 20 --json .artifacts/test-perf/extensions-memory.json

定向插件导入内存：

pnpm test:extensions:memory -- --extension discord --extension telegram --skip-combined

堆/RSS 深入排查：

pnpm test:perf:groups \
  --config test/vitest/vitest.unit-fast.config.ts \
  --allow-failures \
  --output .artifacts/test-perf/unit-fast-memory.json
pnpm test:perf:profile:runner -- \
  --output-dir .artifacts/test-perf/vitest-runner-profile -- <file>

当 RSS 在各时间区间中持续增长、工作进程 发生 OOM，或可疑命令存在应用对象滞留时，使用 openclaw-test-heap-leaks。在快照或内存保留 对象提供佐证之前，不要将 RSS 增长称为泄漏。

常见根本原因

• 为静态数据加载完整的打包频道／插件运行时。
• 明明使用已加载的 fixture 或纯解析器就足够，却使用 getChannelPlugin() 回退方案。
• 在耗时较长的测试中引入宽泛的 api.ts、runtime-api.ts、test-api.ts 或 plugin-sdk 汇总模块。
• SDK 根别名或包汇总模块将针对性子路径重新引入宽泛的插件依赖图。
• plugin-inspector 仅为渲染元数据、报告或 CI 策略评分而加载运行时代码。
• 打包的插件捕获复用真实配置／主目录状态，而非合成、脱敏、隔离的状态。
• 使用 importActual() 围绕宽泛模块创建的部分真实模拟。
• 在逐个测试的循环中使用 vi.resetModules() 并重新导入。
• 在 beforeAll 中填充测试插件注册表，却在 afterEach 中重置运行时状态。
• 明明重置状态就足够，却为每个测试启动网关／服务／客户端。
• 闲置快照或 fixture 也承担运行时／默认模型／身份验证选择的开销。
• 在检查参数是否包含插件自有字段之前，就触发插件自有的媒体／操作发现。
• 并行运行 Vitest 时共用 node_modules/.experimental-vitest-cache，却未设置不同的 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH 值。

基准测试命令

指定文件：

timeout 240 /usr/bin/time -l pnpm test <file> --maxWorkers=1 --reporter=verbose

指定文件并显示导入明细：

timeout 240 /usr/bin/time -l env \
  OPENCLAW_VITEST_IMPORT_DURATIONS=1 \
  OPENCLAW_VITEST_PRINT_IMPORT_BREAKDOWN=1 \
  pnpm test <file> --maxWorkers=1 --reporter=verbose

分组测试套件：

pnpm test:perf:groups --full-suite --allow-failures \
  --output .artifacts/test-perf/<name>.json

扩展批次：

pnpm test:extensions:batch <plugin[,plugin...]> -- --reporter=verbose

所有扩展测试：

pnpm test:extensions

插件包边界检查：

pnpm run test:extensions:package-boundary:canary
pnpm run test:extensions:package-boundary:compile

复用现有的 Vitest JSON 报告：

pnpm test:perf:groups --report <vitest-json> \
  --output .artifacts/test-perf/<name>.json

验证

• 始终运行能够证明更改有效的目标测试范围。
• 源码更改：推送前运行针对性的本地测试及目标类型检查／lint／格式检查；pnpm check:changed 可选。PR CI 提供广泛验证。仅在 CI／本地存在缺口时使用 Testbox，并立即授权；选用后复用已预热的 Testbox。
• 对于仅更改测试的情况，运行 pnpm test:changed 或准确指定修改过的测试。
• 涉及延迟加载、打包产物、包边界、动态导入、构建输出或公共接口时，运行 pnpm build。
• 对于插件 SDK／汇总模块／运行时更改，如果公共 API 可能发生变化，请使用 pnpm plugin-sdk:api:diff -- --base <base-sha> --head <head-sha> 比较确切的提交。要提供 PR 本地验证，请将分支合并基点用作 <base-sha>，将经过确切测试的 HEAD 提交用作 <head-sha>。
• 对于插件套件性能修复，至少验证一个有代表性的插件批次及已更改的检查；如果问题仅存在于打包产物中，请使用 Package Acceptance。
• 如果依赖缺失或过期，请运行 pnpm install，并重试确切失败的命令一次。
• 使用以下报告格式：

| Metric         | Before |  After |          Gain |
| -------------- | -----: | -----: | ------------: |
| File wall time |   `Xs` |   `Ys` |  `-Zs` (`P%`) |
| Max RSS        |  `XMB` |  `YMB` | `-ZMB` (`P%`) |
| CPU user/sys   | `X/Ys` | `A/Bs` |       explain |

交接

最终内容保持简洁：

• 根本原因。
• 测试套件／插件范围。
• 修改的文件。
• 可用时提供前后对比的耗时、Vitest／导入、CPU 和 RSS 数值。
• 如果涉及内存，说明泄漏分类：真实泄漏、模块依赖图滞留，或无法确定。
• 保留的覆盖范围。
• 验证命令。
• 远程验证的 Testbox ID 或工作流 URL。
• 提交哈希和推送状态。