Caveman 测试体系与基准实践：从多语言测试矩阵到可复现的 Token 基准报告规范

本文以仓库文档 docs/technical/testing-and-benchmarks.md 为主线，系统讲解 Caveman 的测试与基准体系：如何按语言选择最小相关的测试命令再逐层放大到发布门禁、verify_repo.py 仓库不变量验证器的十一组检查、五类基准（Engine 夹具、Browser、缓存语料、Subagent Tax、Wrap）各自的报告规范，以及公开基准结果必须包含的十项要素与故障测试清单。读完本篇，你可以直接按命令清单验证 Caveman 各子系统的行为，并掌握一份“证据先于结论”的基准报告该长什么样。

Caveman 是一个同时由 Go、TypeScript/JavaScript 和 Python 编写的多包仓库：Go 侧是单模块（见 go.mod，模块名 github.com/JuliusBrussee/caveman），JS 侧是 pnpm workspace，Python 侧主要是 SDK 与测试工具。测试策略的核心原则是文档开篇给出的：先跑最小的相关命令，再在发布前跑更宽的门禁（smallest relevant command first, then broader gates before release）。

核心测试命令

Go：引擎、代理与全部 Go 包

go test ./...
go vet ./...
go build ./...

这三条命令覆盖 Go 模块内的 Engine、proxy、memory、browser bridge、cache planner、rewriter 等全部 Go 包。从 go.mod 的依赖声明可以看到其技术栈：chromedp（浏览器自动化）、go-tree-sitter（代码解析）、tiktoken-go/tokenizer（token 计数）、modernc.org/sqlite（纯 Go SQLite，无 cgo 依赖）、go-json-experiment/json（实验性 JSON 库）等——这些正是 Engine 压缩、CCR 恢复存储和 browse 基准的底层依赖。

TypeScript 与 JavaScript：workspace 全量与单包窄门

workspace 级别使用：

pnpm install --frozen-lockfile
pnpm -r build
pnpm -r test

单个包暴露更窄的脚本，日常调试时应优先使用：

pnpm --dir packages/cli test
pnpm --dir packages/agent test
npm --prefix extension test
pnpm --dir packages/shared/contracts test

文档特别提示：以各包自己的 manifest（package.json）为准确认精确脚本名，不要凭记忆拼命令。根目录 package.json 本身就是一例：它的 test 脚本是 node --test --test-force-exit tests/installer/*.test.mjs tests/hooks/*.test.mjs，即 Node 内置 test runner 跑安装器与 hook 测试；engines 要求 Node >= 18，packageManager 锁定 pnpm@10.14.0。

Python

python -m pytest -q packages/sdk/python

仓库级验证：verify_repo.py

python tests/verify_repo.py

验证器检查的是普通单元测试覆盖不到的仓库不变量，包括生成物与打包预期。文档明确强调：一旦编辑了 src/hooks/ 下任何文件，就必须重新生成 src/hooks/checksums.sha256，验证器会逐条比对摘要（digest by digest）。

从 tests/verify_repo.py 源码看，main() 中注册了 11 组检查，远不止 checksum 这一项：

检查组	验证内容
verify_license_boundaries	engine、proxy、cacheengine、rewriter、browse、mcp、shrink、mem、shared/platform 九个 BSL 目录各自持有与 LICENSE.BSL 逐字节一致的 LICENSE，且根安装器保持 MIT
verify_untrusted_git_invocations	扫描 proxy 与 packages/cli 全部源码，禁止对不受信工作目录裸调 git -C，只允许走两个加固包装器（proxy/internal/gitsafe 与 packages/cli/src/git-safe.ts），且包装器必须携带 core.fsmonitor=false、core.hooksPath=、protocol.ext.allow=never 三个覆写
verify_shipped_skills_are_documented	skills/*/SKILL.md 中每个技能必须在 README.md 或 CLAUDE.md 的代码片段（code span）中具名，防止未文档化的技能被静默分发到所有用户的技能列表
verify_skill_frontmatter_upload_compatibility	五个核心技能的 frontmatter description 不得包含 XML 式尖括号
verify_synced_files	plugins/ 下的技能镜像、agent 镜像、dist/caveman.skill zip 包与源文件逐字节一致，且 zip 内容集合与磁盘双向对账（既查缺失也查过期残留）
verify_manifests_and_syntax	各 JSON manifest 可解析；plugin.json 不得声明 agents 字段（源码注释记录了该数组形式在特定 Claude Code 版本会加载 0 个 agent 的实测事故）；hook 目录文件集合与 checksums.sha256 清单完全一致且逐摘要比对；所有 JS 过 node --check、shell 过 bash -n
verify_package_contents	npm pack --dry-run 审计发布 tarball：必需文件齐全、不得泄漏 __pycache__/.pyc 等 Python 缓存产物
verify_powershell_static	对 sh/ps1/js 三端 statusline 做静态奇偶校验：会话目录名、.mode 文件扩展名、session id 白名单（字母表加长度上限）、TTY 守卫、有界 stdin 读取、bash 3.2 兼容性等，全部在三个移植间 grep 对账
verify_compress_fixtures	对 tests/caveman-compress/ 下全部 .original.md 夹具对运行压缩校验与可压缩性探测
verify_compress_cli	压缩 CLI 的 skip 路径退出码 0 且输出检测信息、缺失文件路径退出码 1
verify_hook_install_flow	在临时 HOME/CLAUDE_CONFIG_DIR 沙箱中跑真实的 install/uninstall/activate/mode-tracker/statusline 全流程，验证幂等安装、卸载还原既有 settings、外部 hook 保留、--force 重装不覆盖首个 .bak 等场景

这个文件本身就是文档中“生成物与打包预期”一类的典型：它把“哪些东西会被自动分发给用户”当作不变量来守护。

Claude Code hooks：四道命令

npm test                                   # 包含 tests/hooks/*.test.mjs
node --test --test-force-exit tests/*.js
python -m unittest discover -s tests
bash tests/manual/session-mode-smoke.sh    # 端到端，使用一次性配置目录

烟雾脚本 tests/manual/session-mode-smoke.sh 用 Claude Code 实际下发的 JSON payload 驱动真实 hook 二进制，全程针对 mktemp -d 出的临时 CLAUDE_CONFIG_DIR，从不触碰用户的 ~/.claude。脚本头部注释自述其定位：覆盖“hook 二进制 → 文件系统 → statusline 徽章”这条没有单元测试覆盖的端到端路径。它验证的链路包括：会话启动写 per-session mode、stop caveman 存入持久 off、compaction/resume 不会复活已停用会话、双窗口模式互不串扰、traversal id 到不了任何文件等。

完整分层测试计划在 docs/testing-session-modes.md：三层，从最便宜开始——自动化套件、端到端烟雾、以及只有真实 Claude Code 进程才能暴露的检查（双窗口 statusline 徽章、/compact）。该文档同时给出了编辑 src/hooks/ 后重新生成 checksums.sha256 的 awk 命令，以及各测试套件分别钉住了什么行为的对照表。

平台覆盖与发布矩阵

CI 构建并测试 Go 与 JS 的原生路径，并为平台敏感的 launcher 行为提供 Windows 覆盖。仓库 .github/workflows 目录可对应看到这些门禁：ci.yml、engine-ci.yml、release-binaries.yml、release-packages.yml 等。原生发布工作流构建一个 36 个产物的操作系统 × 架构 × 二进制矩阵，然后发布带签名的校验和。

文档给出两条纪律：

• 单平台本地通过不能证明完整发布矩阵通过；
• 报告时必须给出确切的已测命令与环境。

五类基准及其报告规范

Engine fixtures：压缩器对比夹具

Engine 基准在已提交的夹具上对比原始表示与压缩表示，有效报告必须包含：所选压缩器、恢复（recovery）结果、字节或 token 计数器，以及任何不变量检查。

支撑这一类基准的实现在 engine/evals/harness.go。从源码结构看：夹具通过 //go:embed fixtures 嵌入二进制，Run() 读取 fixtures/manifest.yaml 清单后逐条回放；每个 Fixture 声明 payload 文件、可选的强制类型、compress/record 模式、相关性 query、保留探针（probes）与评分器（graders/quality_graders）。TransformResult 结构精确记录了 TokensBefore/TokensAfter/Ratio/Basis/PassedThrough/Recoverable/LosslessToModel 等字段——这正是“有效报告”要素在代码层面的落地。TransformRunner 接口还允许非 Caveman 系统走同一套夹具、质量与报告路径，保证对比口径一致。

Browser fixtures：可访问性树捕获与恢复

Browser 基准在录制页面上测量可访问性树捕获、query 聚焦、压缩与恢复四个维度，完整数据见 browse/BENCHMARK.md。该文件是一份“合格基准报告”的示范：

• 固定了测量环境：2026-08-10、Chrome 151.0.7922.108、锁定版本 @playwright/test 1.56.1、Caveman 离线 o200k_base 计数器，并声明每个数字都是单快照的 inferred 计数，不是 provider 用量或账单；
• 五次独立运行取中位数并附 [min–max] 区间，解释了随机 CDP node id 造成的微小抖动来源；
• 大表格页面：原始 Accessibility.getFullAXTree JSON 398,494 token，Caveman 聚焦结果（query ORD-0173）121 token，较原始 AX 少 99.97%；
• 小表单页面则诚实报告了负结果：Caveman 完整结果 157 token 是 Playwright 裸 ARIA 文本（67 token）的 2.34 倍——恢复句柄、精确计数器、honesty 元数据在小页面上比裸 ARIA 更贵；
• 给出了可复制命令（go test -tags=integration -run 'TestCDPQueryScales|TestCDPFullTokenEfficient' -count=5 -v ./browse 与 Playwright 基线脚本），并明确声明边界：Phase 1 只覆盖同源、可预测控件，OOPIF、对话框、下载与任意站点可操作性被推迟。

夹具即 browse/testdata/order_dashboard.html 与 browse/testdata/agent_checkout.html。

Cache corpus：能力与 fail-safe 门

缓存规划器语料测试施压能力门（capability gate）与 fail-safe 门。报告要求列出未支持与被拒绝的用例——原始通过率不构成市场排名结论。对应实现在 cacheengine（含 cachebench 子包、replay.go/simulate.go 与已提交的观测结果 cacheengine/cachebench/results/lmcache-agentic-traces-2026-08-10.json）。

Subagent tax：本地夹具，零 provider 请求

packages/subagent-tax 完全本地运行：一个本地 sink 伪装成 provider 端点，各已安装 harness 向其发送一次真实请求，工具报告前缀（系统提示 + 全部工具 schema）的构成。其 README.md 与 METHOD.md 明确：无 provider API 调用（--count-tokens 例外且是显式 opt-in）、无账号、数据不出本机；token 数一律标注 est（按 ~6.4 字符/token 校准、±8% 带宽、两位有效数字）或 exact（Anthropic count_tokens）；mcp 列的 - 表示未知而非零。文档对这一类结果的限定非常典型：反事实结论只适用于确切的夹具、装配方式与 token 计数器——换一台机器、换一套插件配置，数字就变，这正是该工具的设计意图。

Wrap report：一次录制的对比及其溯源

已发布的 wrap 基准 docs/WRAP-BENCHMARK.md 记录了 CaveBench 结果：在 6 个确定性、agent 形工具输出工作负载上，Caveman 包装的 Claude Code 比直连少 33.2% 的 provider 上报 input token（591,673 vs 885,793，18 对配对运行），18/18 通过精确答案检查，case-clustered 95% 区间 14.6%–48.5%。该文件是“报告十项要素”的完整范例：

• 声明 claim basis 为 benchmark_counterfactual，即受控基准证据，不是生产流量、客户账单或 verified_savings；
• 负结果保留在聚合中：dashboard-html-alert 用例回归 -9.9%（无压缩变换生效但技能开销仍被计数），明确说明原因；
• 方法细节：Claude Code 2.1.223、模型 claude-sonnet-5、每臂三次轮换重复、主指标为 input_tokens + cache_read_input_tokens + cache_creation_input_tokens 的求和（不按价格加权）、10,000 次重采样的 case 聚类百分位 bootstrap；
• 溯源：corpus、skill、harness 源码、MCP 二进制、Claude 二进制的 SHA-256、harness Git commit，以及“执行时工作树干净：false 则不得发布”这类门；
• 复现可用性声明：仓库只含报告与溯源哈希，不含原始 harness 与运行产物，因此应视为固定报告而非可独立复现的公开基准。

基准报告十项清单

文档要求每个公开结果都包含以下十项，缺一不可：

1. 被测试的问题；
2. 夹具名称、来源与哈希；
3. 代码修订号与日期；
4. 相关的硬件或 provider/model；
5. 确切命令；
6. 计数口径（count basis）与价格来源；
7. 基线（baseline）与处理组（treatment）的定义;
8. 恢复、解析与质量检查；
9. 失败、排除项与负向 delta；
10. 与数据匹配宽度的窄结论。

并给出三条防越界断言：fixture 级结果不是生产验证；本地 token 估算不是 provider 成本；检索成功不等于质量对等。benchmarks/run.py 的实现印证了第 7 条的严肃性：脚本内置了 NORMAL_SYSTEM = "You are a helpful assistant." 与 TERSE_SYSTEM = "Answer concisely." 两个控制臂——源码注释直言，没有控制臂就会把“任何‘说简短点’指令的收益”错误记账给技能本身。

故障测试清单

压缩与集成测试应覆盖以下失败面：

• 畸形输入；
• 重复或有歧义的 JSON；
• 空 payload 与边界尺寸 payload；
• 变换后比原始更大的输入；
• 已满或失败的恢复存储（recovery store）；
• 未知的 mode、provider、model、grader；
• 流中断（stream interruption）；
• 不安全端点与重定向；
• 携带密钥的 headers；
• 不受支持的平台或上游版本。

文档强调预期安全结果常常是原始输入或显式拒绝，测试应当断言这种安全行为，而不是只断言“压缩成功了”。这与 engine/evals 中“自定义空语料是配置错误，不得变绿”（engine/evals/harness.go 中 RunDir 的注释）同属一种设计哲学：失败路径的断言与成功路径同样是一等公民。

文档变更验证清单

文档变更需要过六关：

• 相对链接检查（relative-link check）；
• 命令与路径对照当前 help 输出和包结构树检查；
• 私有或内部引用扫描；
• 对照代码与已提交证据的过期声明扫描（stale claim scan）；
• 平实语言审读（plain-language review）；
• git diff --check。

最后一句边界提醒值得所有贡献者记住：通过文档检查只证明与当前 checkout 一致，不证明运行时行为或发布就绪（Passing documentation checks proves consistency with checkout, not runtime or release readiness）。

小结

Caveman 的测试与基准体系可以概括为四个层次：语言级最小命令（go test / pnpm -r test / pytest）、仓库不变量层（verify_repo.py 的 11 组检查，把 checksum 清单、打包内容、跨平台奇偶都变成可失败的门禁）、端到端烟雾层（沙箱化的 hook 流程驱动），以及基准证据层（五类基准各自绑定夹具、哈希、确切命令与明确的 claim 边界）。其贯穿性原则是：报告先于结论——负 delta 保留、计数口径声明、溯源哈希列全、复现可用性如实标注。对要在多语言 monorepo 中发布“省 token”这类量化声明的团队而言，这套“十项要素 + 故障面清单 + 文档六关”的组合比任何单一 benchmark 脚本都值得直接借鉴。