Caveman Wrap Benchmark：Caveman 如何在固定 Claude Code 环境里量化出 33.2% 的 provider 输入 token 削减

Caveman 的 Wrap benchmark 回答一个很具体的问题：把 Claude Code 用 Caveman 的压缩运行时包一层（wrap）之后，模型实际消耗多少更少的 provider 上报输入 token，同时答案质量是否不降。本文基于 docs/WRAP-BENCHMARK.md 完整继承其结果、逐案例明细、方法、验证链路与发布门槛，并结合仓库中的证据分级规范（docs/technical/accounting-and-evidence.md）与评估体系（evals/README.md、benchmarks/run.py）展开讲解。读完后你会掌握一套"配对受控基准 + 质量门 + 溯源哈希 + 发布门槛"的完整量化方法，并知道如何正确解读这类 benchmark_counterfactual 数字的适用边界。

结果总览：18 组配对运行，省 33.2% 输入 token

在 6 个确定性、agent 形态的工具输出（tool-output）工作负载上，Caveman-wrapped 的 Claude Code 比直接运行的 Claude Code 少 33.2% 的 provider 上报输入 token：18 组配对运行合计 591,673 vs 885,793 tokens，且 Caveman 通过了全部 18/18 项精确答案检查。按案例聚类的 95% 区间为 14.6% 到 48.5%。

三组对照臂的对比如下（源自 docs/WRAP-BENCHMARK.md 的 Result 表）：

臂	精确质量	held pairs 上的 provider 输入	相对直接运行的削减	案例聚类 95% 区间
Direct Claude Code	18/18	885,793	baseline	n/a
Caveman wrap + skill	18/18	591,673	33.2%	14.6% 到 48.5%
Headroom wrap	15/18	703,202（对匹配的直接运行）	6.7%	-0.7% 到 17.9%

Caveman 在 18 组配对中赢了 15 组。第三组对照臂 Headroom 有 3 个 YAML 运行没有通过精确答案门（exact-answer gate）——这些失败运行保留在报告里可见，而不是被剔除后去抬高削减率。这是理解这份报告方法论基调的起点：负结果与失败案例不被删除。

文档同时明确了声明依据（claim basis）：

Claim basis: benchmark_counterfactual。这是受控基准证据，不是生产流量、客户支出、provider 账单，也不是 Caveman 的 verified_savings。

逐案例结果：削减从何而来，回退又在哪里

每个案例在每个臂上各运行三次。逐案例明细如下：

Case	形状	Direct 输入	Caveman 输入	削减率	Caveman 质量
sre-log-needle	log	148,807	74,068	50.2%	3/3
deployment-json-drift	JSON	147,975	108,939	26.4%	3/3
fraud-csv-outlier	CSV	165,823	74,484	55.1%	3/3
test-output-failure	test output	150,377	108,514	27.8%	3/3
config-yaml-drift	YAML	132,124	71,027	46.2%	3/3
dashboard-html-alert	HTML	140,687	154,641	-9.9%	3/3

几个值得注意的点：

• 削减率跨度很大：CSV 类工作负载（fraud-csv-outlier）削减 55.1%，而测试输出（test-output-failure）只有 27.8%。这说明收益高度依赖工具输出的内容形态——结构化、可重复、可表格化的数据压缩空间大，自由文本小的多。
• HTML 案例是负收益（-9.9%），且被如实计入聚合。原文解释：HTML 上没有压缩变换（transform）被应用，但完整的 Caveman skill 开销仍然被计入了输入。换句话说，这个案例里 Caveman 只付了固定成本、没拿到压缩收益——而报告选择保留这个回退案例，让聚合数字仍然为正。
• no-op（压缩未生效）与不支持的输入保留在聚合中。这与 docs/HONEST-NUMBERS.md 的立场一致：skill 本身每轮会增加约 1–1.5k 输入 token（SKILL.md 规则约 5 KB 注入上下文），如果某工作负载省不回来，就是净亏损，文档明确告诉用户"如果你的 A/B 是净负，就关掉"。

这个负案例也解释了为什么"聚合削减为正"不等于"每个案例都赢"：6 个案例中 5 个正收益、1 个回退，加权后仍是 33.2%。

方法细节：54 次 agent 运行如何构成一个可信对比

方法部分（Method）定义了这次对比的所有受控条件，逐条继承如下：

1. 6 个不可变的 MCP fixtures，每个 60–95 KB：日志（logs）、部署 JSON、欺诈 CSV、测试输出、配置 YAML、仪表盘 HTML。fixture 通过 MCP 暴露给 agent，是"agent 形态"的输入——即真实 agent 工作流中会读到的大型工具输出。

2. 三组臂各 3 轮轮换重复：direct Claude Code、Caveman、Headroom，共 54 次 agent 运行、18 组 direct/Caveman 配对。

3. 固定运行时：Claude Code 2.1.223，模型 claude-sonnet-5。

4. 每臂恰好调用一次同一 fixture，并返回一个由精确语义 JSON oracle 校验的结构化答案。"exact-answer check"是质量门的判定机制——答案必须语义精确，18/18 通过才允许把该臂计入削减率比较。

5. token 计量来源统一为 Claude Code 的 modelUsage 计数器。主指标为：

   input_tokens + cache_read_input_tokens + cache_creation_input_tokens
   

   三个缓存桶直接相加，不做价格加权——这是刻意选择：主声明是 token 数而非美元成本，避免引入价格假设。文档还强调，wrapper 自带的 tokenizer 估算值不参与这次对比。这一点与 docs/technical/accounting-and-evidence.md 的证据规范吻合：provider 上报字段保持 provider 口径（provider_reported），不得用本地估算替换。

6. Recovery（恢复）的计费口径：只有当答案所需数据在可见的压缩内容中缺失时，才允许走恢复路径；恢复调用与后续 provider 输入依然被计入。也就是说，CCR（Caveman Context Recovery，见 docs/technical/agent-wrapping.md）"取回原文"产生的额外 token 没有从成本里豁免。

7. 完整 Caveman skill prompt 开销从第一次请求起就被计入——skill 规则注入的固定输入成本没有被排除。

8. 统计口径：聚合削减率 = Caveman 输入总和 ÷ 配对 direct 输入总和。95% 区间采用按案例聚类的确定性 10,000 次重采样百分位 bootstrap——按案例聚类是为了处理同一案例 3 次重复之间的相关性，避免把 18 次运行当作独立样本高估显著性。

这套设计与仓库里输出侧基准 benchmarks/run.py 和 evals/README.md 的防混淆原则同源：evals 用 __terse__ 对照臂隔离"skill 本身贡献了多少，多少只是'请简洁'这类通用指令的效果"；wrap benchmark 则用 direct 臂 + 精确 oracle 隔离"省 token 是否以质量为代价"。两个方向（输出 token 与输入 token）分别用受控臂对比，而不是单臂前后对比。

验证与溯源：发布前过掉的门禁

报告附有一组可机检的验证结果与溯源哈希，全部通过：

• 生成时间：2026-08-06T14:31:43Z
• Publication gate：passed
• 同一 provider usage 来源：54/54 次运行
• fixture 恰好被调用一次：54/54 次运行
• Caveman skill 已安装、已加载、已应用：18/18 次运行
• 观测到正向 proxy 压缩：15/18 Caveman 运行；no-op 运行保留计入
• 权限拒绝（permission denials）：0
• 溯源哈希：corpus SHA-256 9a400a6dc38591dc3ce59bc2e3fa6fc59d99e211dc9185b430979de78991760a；Caveman skill SHA-256 5e30bb56afbd0b01bd736f2da84180e76f18db4a64de8e124525d5c8dc2e8605；harness 源码 SHA-256 e6322a3a55cfdfa6c7942022a1be9adb49fa30c380352c819c99bbd4bff30cc4；fixture MCP 二进制 SHA-256 5c71768780582708c00fa1d6862a6a5b93fc33fc23655ff430b0edb8fee1e790；Claude 二进制 SHA-256 4163c57c719e27680336f323ebdcd2ba8aa48a683fdfa427240ec4b506a21e45
• Harness Git commit：630e157246b68b63559fb8baab29b87042db996b；执行时工作区 dirty：false

这些哈希把"报告数字 ↔ 语料 ↔ skill 版本 ↔ harness 代码 ↔ 二进制"全部钉死在同一个可复核状态上。这与 docs/technical/testing-and-benchmarks.md 中"写一份基准报告应包含：fixture 名称/来源/哈希、代码修订与日期、模型、精确命令、计数口径、基线/处理定义、质量检查、失败与排除、以及数据支持的窄结论"的十条清单一一对应。

发布门槛：哪些条件下才允许发布这个数字

原文明确列出了该结果的发布（publication）前提，这是一份可直接复用的"基准发布 checklist"：

• 至少 6 个案例、每个案例至少 3 次重复；
• 每一次运行的 direct 与 Caveman 质量都必须 exact（精确答案通过）；
• 每次运行只调用一次 fixture；
• 所有运行使用同一 provider usage 来源；
• Caveman skill 处于激活状态；
• 至少观测到一次确凿的压缩；
• 聚合削减率为正；
• 95% 区间完全在零之上；
• 负收益与 no-op 案例不得被移除。

同时，文档对"能否从本仓库复现"给出了非常坦率的边界声明：

本仓库包含已发布的报告与溯源哈希，但不包含该结果的原始 harness 或运行 artifacts。在 harness 与原始 artifacts 发布到本仓库之前，无法从当前 checkout 独立复现。请把该结果视为 pinned report（钉住报告），而不是可公开复现的基准。

即：哈希让你能确认"报告与它声称的环境一致"，但不能让你重跑一遍——因为原始运行数据不在仓库里。这一自我限定是解读该数字时最容易被忽略、却最关键的一点。

如何正确解读这个数字：benchmark_counterfactual 不是 verified

Caveman 仓库对每个数字都打证据基础（evidence basis）标签，docs/technical/accounting-and-evidence.md 给出了完整分级表，与本基准直接相关的几档：

Basis	含义	不代表什么
provider_reported	由 provider usage 字段返回	独立账单核对
benchmark_counterfactual	受控 fixture 变体之间的差值	生产环境节省
verified	满足指定且被强制执行的验证方法	普遍质量或未来节省

本报告的 33.2% 属于 benchmark_counterfactual：它是"受控基准证据"，计量口径是 provider 上报的 token（这一点比很多本地 tokenizer 估算严格得多），但它不是生产流量上的节省承诺。结合原文 Boundaries 一节，适用边界有：

1. 工作负载是确定性的大块工具输出，不是开放式编码任务，也不是客户真实流量；
2. 结果只对"这个钉住的套件 + 这个运行时"（Claude Code 2.1.223 + claude-sonnet-5）成立，不是普适的节省承诺；
3. 隔离手段是本地主机上"每个臂运行前重置专用 Claude 配置"，不是密封容器，文档不声称文件系统或网络出口级别的精确隔离；
4. 成本、延迟、输出 token 差值都是次要指标，因为 agent 轨迹会不同；主声明是"在质量保持的前提下，配对的 provider 输入 token"。

再结合 docs/HONEST-NUMBERS.md 的提醒——skill 固定开销每轮约 1–1.5k 输入 token、简短任务可能净亏损、按请求计费的 agent（如 Copilot credits）根本不受输出长度影响——可以得出一个实操判断框架：wrap benchmark 证明的是"在大工具输出场景下 Caveman 压缩链路不亏且明显省"，而你的工作负载是否属于这个区间，需要用自己的 provider-billed A/B 去确认（例如用 caveman stats 或 /caveman-stats 读会话日志的实际计数）。

小结：一份可以当范本的基准报告

把 docs/WRAP-BENCHMARK.md 拆开看，它的结构本身就是一套可迁移的方法论：

1. 结果先行，claim basis 紧跟其后——33.2% 下面第一句就是"这是 benchmark_counterfactual，不是生产节省"；
2. 逐案例透明——包括那个 -9.9% 的 HTML 回退案例，且解释回退成因（无变换应用 + skill 固定开销计入）；
3. 口径钉死——token 来自 modelUsage 三个字段直接相加、不价格加权；恢复调用与 skill 开销都计费；
4. 质量门与统计门分离——18/18 exact-answer 是质量门，聚类 bootstrap 区间整体大于零是统计门，两者都要过；
5. 溯源哈希 + 明确的不可复现声明——报告可被验证一致性，但诚实标注"raw artifacts 不在仓库，尚不可独立复现"。

对使用方的实际含义：如果你的 agent 大量消费结构化、可压缩的工具输出（日志、CSV、JSON、YAML），Caveman wrap 的这条证据链支持"输入 token 显著下降且答案精确性不降"的结论；如果你的负载是短问答或按请求计费，docs/HONEST-NUMBERS.md 的规则很直接——固定开销可能超过收益，关掉即可。