如何压缩上下文还保留错误现场：Caveman JSON 压缩器的完整指南

如何压缩上下文还保留错误现场：Caveman JSON 压缩器的完整指南

【免费下载链接】caveman🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman

在 AI Agent 的实际使用中，工具返回的 JSON 往往是 Token 消耗的大户。Caveman 是一个面向 Claude Code 等编码 Agent 的技能工具，它的核心卖点是用"原始人式精简"的思路为模型上下文瘦身，官方宣称可削减 65% 的 Token。其中真正干活的，是位于 engine/compressors/ 目录下的Caveman JSON 压缩器：它专门处理工具输出里的 JSON 负载，一边折叠重复数组，一边原样保留 error/message 子树，做到"瘦身不丢关键信息"。

为什么 JSON 值得单独压缩

Agent 跑任务时，一次工具调用动辄返回几十上百条记录：订单列表、API 响应、日志事件……这些 JSON 有两个共同点：

1. 数组高度重复——绝大多数元素是同一"形状"的重复记录；
2. 关键信号藏在少数元素里——报错的那一条、异常值的那一条，恰恰不能丢。

所以 JSON 压缩器（json.go）的设计目标很明确：折叠重复的，保留有信号的，丢掉的还要能找回。整个策略分为三条规则。

规则一：error/message 子树原样保留

压缩器内置了一个正则（json.go 第32行），匹配这些键名：

error、errors、message、msg、stack、stacktrace、exception、reason、details、warning等

递归遍历 JSON 时，只要某个对象的键命中这个正则，它下面的整棵子树都会被标记为preserve（json.go 第110-136行）——子树内的数组再长也不折叠，逐条原样保留。

这解释了压缩器测试用例里的场景（json_test.go）：data数组的 12 条记录被折叠，而error.items里的 12 个元素一个不少地留下。对 Agent 来说，"压缩后的输出里错误信息必须逐字可读"是硬约束。

规则二：长数组只留"有信号的元素"

没被保护、且长度超过阈值（默认 8 个元素）的数组，会进入selectArray的筛选流程（json.go 第141行）。哪些元素会被强制保留？按优先级：

全部判定都是确定性的——没有随机数、没有向量嵌入，同一输入永远得到同一输出（这对前缀缓存很关键）。

被丢掉的元素不会凭空消失，而是每段连续丢失区生成一个省略标记：

{"__caveman_elided__": 10, "__caveman_invariants__": "status: ok×10"}

标记既告诉模型"这里省了多少条"，又附带从这批元素里计算出的事实摘要（invariants.go），比如恒定字段、状态分布计数、数值区间——但摘要只陈述"验证过的事实"，绝不猜测。

规则三：压缩是"有损"的，但可恢复

JSON 压缩器被归为 S4 安全级别（有损）。这意味着压缩前，引擎会先把原始字节存入本地CCR（上下文恢复存储）（engine/ccr/store.go），并在压缩后的负载里附带恢复句柄；Agent 需要完整原始数据时，随时可以取回逐字原文。

反过来，以下情况压缩器会直接放弃、原样透传（json.go 第81-104行）：

• JSON 解析失败、或包含多个顶层值；
• 一个元素都没折叠掉——光重新序列化不构成"压缩"，不能冒领功绩。

进阶：Best-of 策略模式

如果引擎的 TOON 标志位设为 best-of，JSON 内容类型会改用jsonStrategy（json_strategy.go）：它把TOON 编码（对模型无损）和数组省略（有损）各跑一遍，用真实 Token 计数器比较结果，只采用省 Token 更多的那个；两个都不省就整体放弃。

上手与延伸阅读

• 安装后通过 CLI 启动 Agent 即可自动生效：npm i -g @caveman-ai/cli，再caveman claude（详见 engine/README.md）；
• 压缩器完整行为说明与默认参数：json.go、json_test.go；
• 省略标记的不变量摘要机制：invariants.go；
• 上下文恢复（CCR）实现：engine/ccr/store.go；
• 缓存规划与轨迹重写等配套机制：docs/technical/cache-and-rewriter.md。

一句话总结：Caveman JSON 压缩器 = error/message 子树原样保留 + 长数组按"首尾/错误/异常/变化点/相关性"筛选保留 + 省略标记附带事实摘要 + 原文本地可恢复。四条规则叠起来，才是它敢在 Agent 上下文里做有损压缩的底气。

【免费下载链接】caveman🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman