OpenClaw 测试性能诊断工具 - 一键分析 CPU/RSS/堆增长 - AI技能教程

一、技能概述

该技能在 OpenClaw 测试性能出现瓶颈时使用——无论是整体测试套件运行缓慢、插件检查器加载过重，还是内存占用（RSS）过高甚至有 OOM 风险。它提供了一套系统化的性能工程工作流：建立基准 → 定位根因 → 修复根本问题 → 重新基准并量化收益，确保每一次优化都有数据支撑。

核心原则：证据优先，修复根因而非症状。不靠猜测调整运行器参数，而是通过精准的指标采集和根因分析从源头消除性能瓶颈。

二、核心功能

1. 建立性能基准（Baseline）

修改代码前，必须先采集可靠的性能基准：

命令	用途
`pnpm test:perf:groups --full-suite --allow-failures --output`	全量测试套件分组排名，识别最慢的组
`/usr/bin/time -l pnpm test <file> --maxWorkers=1 --reporter=verbose`	采集单文件测试的墙时与最大 RSS（Linux/macOS）
`OPENCLAW_VITEST_IMPORT_DURATIONS=1 OPENCLAW_VITEST_PRINT_IMPORT_BREAKDOWN=1 pnpm test`	分解每个测试文件的导入耗时，定位 barrel/runtime 加载热点
`pnpm test:extensions:batch <group>`	插件批处理范围测试，用于定位特定插件组的性能问题

2. 多维度指标采集

技能定义了完整的性能指标矩阵：

指标	用途	采集方式
墙时（Wall Time）	用户感知的套件总耗时	`/usr/bin/time -l`、Testbox 运行时间
Vitest 内部时长	测试体执行与导入成本	Vitest 按文件/shard 输出
导入时长	宽泛的 barrel / 运行时加载	`OPENCLAW_VITEST_IMPORT_DURATIONS=1`
最大 RSS	内存压力与 OOM 风险	`/usr/bin/time -l`、`test:extensions:memory`
CPU / user / sys	CPU 密集型 vs I/O 等待	`/usr/bin/time -l`、Testbox job timing
堆快照	真实泄漏 vs 模块图保留	`openclaw-test-heap-leaks` 工作流

3. 常见根因模式（Built‑in Pattern Library）

技能预置了 OpenClaw 项目中已知的性能陷阱，帮助快速定位：

完整打包的 channel/plugin runtime 被加载仅为了获取静态数据（应改用轻量级 manifest 或静态 helper）
getChannelPlugin() fallback 被用于本可用已加载 fixture 或纯 parser 的场景（应直接注入依赖）
宽泛的 api.ts、runtime-api.ts、test-api.ts 或 plugin-sdk barrel 被拉入热测试路径（应使用精确子路径导入）
SDK root 别名或 package barrel 将聚焦的子路径拉回宽泛的 plugin graph（应优化导出结构）
Plugin‑inspector 仅为了渲染 metadata/reports/CI policy scores 而加载 runtime 代码（应将静态数据与运行时分离）
打包插件捕获复用了真实 config/home 状态而非合成/脱敏/隔离状态（应使用测试专用 fixture）
vi.resetModules() + 每次测试循环中的新导入（应复用模块缓存或使用隔离容器）
每个测试都启动 gateway/server/client，而状态重置本已足够（应复用套件级实例）
并行 Vitest 运行共享 node_modules/.experimental-vitest-cache 而未使用不同的 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH（应为每个 worker 分配独立缓存路径）

4. 修复策略（Actionable Fixes）

根据根因类型，技能提供针对性的修复策略：

静态 metadata/parsing → 移至轻量级 helper 或 manifest artifact，供完整 runtime 和 fast path 复用
运行时加载过多 → 使用依赖注入、仅加载插件的查找、显式 fixture 和纯 helper，而非宽泛 mock
重复启动 server/client → 复用套件级 server/client（当 fresh handshake 不相关时）
scheduler/background loops → 除非测试证明调度，否则保持关闭
插件路径 → 将静态 metadata 移至 manifest/轻量级 artifact，runtime plugin 加载保持在显式执行边界之后

5. 插件套件专项优化

当性能工作涉及打包插件、插件检查器、SDK barrel、包边界测试或扩展套件时：

套件形态映射：先运行 pnpm test extensions/、pnpm test:extensions:batch、包边界检查（canary/compile）和插件导入内存分析
从窄到宽：先跑单个插件的测试和 plugin‑inspector slice，再逐步扩大到 SDK、channel、memory 和 feature 插件
Crabbox/Testbox 证明：在维护者机器上默认使用 Blacksmith Testbox 进行宽泛或包密集的插件证明
包制品敏感时：切换到 release-openclaw-plugin-testing 和 Package Acceptance，而非信任源码级时序

6. 覆盖率保持（Coverage Retention）

优化不能以牺牲测试覆盖率为代价：

不删除慢速集成证明，除非将精确的生产组合提取为命名的 helper 并测试
当跨组件连接重要时，保留一个廉价的集成冒烟测试
明确说明移除了哪些附带覆盖率（如有）

7. 验证检查清单（Verification Checklist）

修改完成后，必须运行以下验证：

源码变更：pnpm check:changed
仅测试变更：pnpm test:changed 或精确编辑的测试
触碰懒加载/打包 artifact/包边界/动态导入/build 输出：pnpm build
触碰 plugin SDK/barrel/runtime：pnpm plugin-sdk:api:check 或 pnpm plugin-sdk:api:gen
插件套件性能修复：至少验证一个代表性插件 batch + 变更的 gate
依赖缺失/过时：pnpm install 后重试一次

三、主要用途

整体测试套件性能优化 —— 当 pnpm test 运行过慢或 RSS 过高时，定位并消除瓶颈。
插件套件性能诊断 —— 当插件检查器、扩展批处理或打包插件测试运行缓慢时，系统化定位根因。
内存泄漏排查 —— 当 RSS 持续增长、worker OOM 或怀疑存在应用对象保留时，使用堆快照和 openclaw-test-heap-leaks 工作流诊断。
导入热点定位 —— 通过 OPENCLAW_VITEST_IMPORT_DURATIONS=1 识别宽泛 barrel 加载和 runtime 导入热点。
CI 性能回归预防 —— 在 PR 合并前通过基准对比，防止性能回归进入 main 分支。
Crabbox/Testbox 远程证明 —— 在维护者机器上使用 Blacksmith Testbox 进行隔离、可重复的性能验证。

四、标准工作流

1. 阅读相关的 AGENTS.md 文件（agent/import hotspots、plugin/channel laziness、gateway lifecycle、test helpers）
2. 建立基准（test:perf:groups 或 scoped /usr/bin/time -l）
3. 根据返回值和风险选择攻击点（高回报 > 高杠杆 > 低风险 > 高风险）
4. 修复根因（静态数据移至轻量级 artifact、依赖注入、复用套件级 server 等）
5. 保持覆盖率形状（不删除慢速集成证明）
6. 重新基准同一命令，计算秒数和百分比收益
7. 更新运行报告（before/after、artifacts、coverage notes、verification、next attack）
8. 用户要求时提交并推送（仅暂存本次攻击涉及的文件）

五、输出报告格式

技能要求最终报告必须包含：

Root cause（根因）
Suite/plugin scope（影响范围）
Files changed（变更文件）
Before/after wall, Vitest/import, CPU, and RSS numbers（量化收益）
Leak classification（如涉及内存：真实泄漏、保留模块图或不确定）
Coverage retained（覆盖率保持情况）
Verification commands（验证命令）
Testbox ID or workflow URL（远程证明，如有）
Commit hash and push status（提交状态）

六、重要原则

证据优先 —— 每一次优化都必须有基准数据支撑，不靠猜测。
修复根因而非症状 —— 不靠调整运行器参数（如 --maxWorkers）掩盖问题。
保持覆盖率 —— 不删除慢速集成证明，除非有等效的 named helper 覆盖。
从窄到宽 —— 先跑单文件/单插件，再逐步扩大范围。
Plugin‑inspector 失败是产品信号 —— JSON 必须可解析，warnings/errors 必须分类而非隐藏。
不将 RSS 增长称为泄漏 —— 直到堆快照或 retainers 分析支持该结论。

总结：OpenClaw Test Performance 是一个系统化的测试性能工程技能，通过建立基准、定位根因、修复问题、重新基准的闭环工作流，真实提升 OpenClaw 测试套件和插件套件的运行速度与内存效率，同时保持测试覆盖率。它预置了 OpenClaw 项目中常见的性能根因模式，提供了完整的指标采集矩阵和验证检查清单，是维护 OpenClaw 测试套件健康与响应速度的核心工具。

OpenClaw 测试性能诊断与优化

Uh oh!