别再把 Token 节省当魔法：Caveman 用可恢复压缩替 AI Coding Agent 瘦身

# 别再把 Token 节省当魔法：Caveman 用可恢复压缩替 AI Coding Agent 瘦身 ## 先讲结论 Caveman 不是另一个 coding agent，而是一层放在既有 agent 与模型供应商之间的本机工具。它把「减少 token」拆成两条不同路径：用 skill 让 agent 少写一点赘词，或用 Engine 与 local proxy 压缩 agent 反复送进模型的 logs、JSON、diff、HTML、搜寻结果与工具输出。 真正值得注意的不是「把文字变短」本身，而是它把压缩设计成可回复的资料管线：先把可能遗失资讯的原始 bytes 存进 Caveman Context Recovery（CCR），再把较小的表示与 recovery handle 交给模型；解析失败、结果没有变小、CCR 写入失败或安全条件不明时，就退回原文。 这个设计让 Caveman 比单纯的 prompt 技巧更像一个 context middleware。不过，它也不是无条件省钱工具：官方文件明确承认 skill 会增加输入 token、HTML benchmark 可能退步、local estimate 不是帐单数字，而且本机 CCR 可能保存敏感原文。 ## Caveman 解决的是哪一段成本？ 一个长时间工作的 AI coding agent，通常会重复把几类内容送回模型：测试输出、编译器错误、JSON、git diff、搜寻结果、工具 schema、浏览器 accessibility tree，以及先前对话留下的 context。这些资料不一定需要逐 byte 保留在模型可见内容里，但又不能只靠粗暴截断。 Caveman 的产品模型把系统拆成数层： - **Skill、hooks、plugins：** 影响 agent 的输出风格，保留程式码、命令、识别字与技术细节。 - **CLI：** 安装元件、启动 agent、管理本机命令与整合。 - **Engine：** 判断输入类型、选择 compressor、计算估计 token，并保存 recovery data。 - **Local proxy：** 透过 loopback 接住 provider request，把选定的 input transform 套上去，再转送给原本的模型供应商。 - **MCP、memory、browser、shrink：** 把恢复、长输出、浏览器结构与本机记忆做成 agent 可使用的工具。 - **SDK：** 让应用程式直接接上 context assembly、provider routing、tracing 与 eval 能力。 这种分层的好处是可以只采用最小必要路径。只想让回答少一点赘词，可以只装 skill；需要处理长 logs 与工具输出，才启用 local runtime；要把自己的应用程式接进去，则改用 SDK 或 provider base URL。 ## 两条路径：缩短回答，或缩短输入 ### 1. Response skill：让 agent 少说废话 Caveman skill 是一份会被 agent 载入的规则，要求它缩短常见的冗余表达，并在较强的模式下允许片段式回答。它不应改写程式码、错误讯息、命令、路径或安全警告。 这条路径的优点是安装成本低，也不需要把 request 经过代理。不过规则本身会占用 input token，所以短问题可能反而变贵。官方 `HONEST-NUMBERS.md` 也指出，skill 并不压缩 context 或 model thinking tokens；是否有净节省，必须用同一任务的 provider usage 做 A/B 比较。 ### 2. Engine + proxy：让 agent 少读重复资料 第二条路径才是 Caveman 的核心工程。Engine 会先做 detection，再把资料送给对应的 compressor。官方目前列出的自动辨识类型包含 JSON、terminal output、diff、HTML、tabular data、source code、logs、search results、configuration text 与一般文字；TOON、accessibility tree 与 tool-schema 等较特殊的 transform 则不是一般 detection 自动选择。 Local proxy 透过 base URL 或环境设定包住既有 agent，并不取代 agent loop。它可为 Claude Code、Codex、Gemini CLI、Aider、Hermes、OpenClaw、opencode 等目标建立 launch profile，也能让 Anthropic、OpenAI、Google Gen AI、Vercel AI SDK、LangChain、LiteLLM、CrewAI、Pydantic AI 与 OpenAI Agents SDK 等应用使用整合配方。 ## 最重要的设计：压缩必须可恢复 Caveman Engine 的 pipeline 可以简化成以下流程： ```plain text 输入 bytes ↓ Detect：判断资料形状 ↓ Select：选择 compressor ↓ Transform：产生较小表示 ↓ 是否更小且通过安全检查？──否──→ 传回原始 bytes ↓ 是 是否需要 recovery？──否──→ 输出 compact bytes ↓ 是 把完整原始 bytes 写入 CCR ↓ 写入成功？──否──→ 传回原始 bytes ↓ 是 输出 compact bytes + recovery handle ``` 这里有几个实务上很重要的判断： 1. **变小不是唯一条件。** 解析错误、未知 mode、没有合适 compressor 或输出反而更大，都会 pass-through。 1. **Lossy output 要先保存原文。** 如果 recovery store 不存在或写入失败，就不应把压缩结果交给模型。 1. **Handle 不是品质保证。** 它只能让 agent 在需要时取回原始资料，不能保证模型一定会主动要求缺失内容。 1. **失败不应伪造成功。** Proxy 的 transform failure 会保持原始 provider traffic，而不是回传一个看似成功的假结果。 Engine 文件把 `Compress`、`Retrieve`、`Detect`、`Stats` 列为稳定核心操作，另外提供不提交正常 runtime side effect 的 `Simulate`。压缩器本身是纯 byte transform，网路、储存与 token accounting 由 Engine 外层控制，这让失败边界比较容易测试与审查。 ## 从 CLI 到 MCP：不只是一个 proxy Caveman 的 CLI 主要操作可以分成几类： ```bash caveman claude # 持续启用整合并启动 agent caveman wrap codex # 单次、暂时性的 wrapped session caveman tools compress < input.txt caveman tools retrieve caveman tools shrink -- go test ./... caveman tools mem remember "project uses PostgreSQL" caveman tools mem recall "database" caveman tools browse https://example.com "pricing" ``` 其中值得分开看的是三个本机工具： - **MCP server：** 提供 compress、retrieve、stats、TOON encode、TOON decode 等工具。Agent 何时呼叫由 host 决定，权限应限制在必要范围。 - **Cavemem：** 以 SQLite 保存 durable facts，使用本机 BM25 做 recall；它是持久化记忆，不是模型训练，资料也可能过时或错误。 - **Browser bridge：** 透过 Chrome DevTools Protocol 取得 accessibility tree，按查询过滤后回传元素 reference，必要时仍可 recovery 原始内容。它能 click 或执行 JavaScript，因此 read 与 write 权限必须分开管理。 Output shrinker 则是很直接的入口：把测试、编译或搜寻的长输出送进 shrinker，保留错误类型、exit status、重要路径与 recovery handle。文件特别提醒，不能用「只剩一段摘要」取代完整 debugging context。 ## Benchmark 应该怎么读？ Caveman 的 `WRAP-BENCHMARK.md` 报告一组固定的 agent-shaped tool-output workload：六种 fixture、每个 arm 三次、总共 18 组 direct/Caveman pairs。文件报告 Caveman 端使用 591,673 个 provider-reported input tokens，直接使用 Claude Code 则为 885,793，并且两边都是 18/18 exact-answer checks 通过。 这个结果可以支持一个窄化的结论：在该版本、该 provider、该固定 fixture 与该 recovery 方法下，Caveman 对这组大型工具输入有明显 input reduction。它不能直接推导成所有 coding session 都会省相同比例，原因包括： - benchmark 是固定的大型工具输出，不是开放式实际专案。 - dashboard HTML 是负面案例，压缩没有生效时连 skill overhead 都算进去，结果反而增加 9.9%。 - 公开 repository 有报告与 provenance hash，但没有一并提供原始 harness 与 run artifacts，因此文件自己把它标成 pinned report，而不是从 checkout 即可独立重现的 benchmark。 - Engine 本机 token 数通常是 `inferred`，来自 offline tokenizer 或 fallback estimate，不等于 provider invoice。 这种把负面结果、品质 gate、测量 basis 与不可重现边界一起写出的方式，比只放一个「省了 X%」更值得参考。使用者真正应该做的是在自己的 workload 上跑同一任务、同一模型、同一 provider，对照帐单或 provider usage，再决定是否保留某个 transform。 ## 安全与隐私：本机不等于没有资料风险 Caveman 的本机层不需要 Caveman account，但 request 仍会送到你选定的模型 provider。更重要的是，CCR 会保存可恢复的完整原文；官方安全文件指出，这些内容可能包含 prompts、credentials embedded in content 与 tool results，应把 `~/.caveman/ccr.db` 视为敏感资料。 还有几个部署前必看的边界： - Standalone proxy 预设绑定 `127.0.0.1:8787`，loopback 模式接受所有 inbound request；不要把它暴露到 LAN、container bridge 或 public interface。 - Shared deployment 需要 `CAVEMAN_AUTH_TOKEN`，并应放在 private network、在前方终止 TLS；健康检查与 metrics endpoint 仍可能未验证。 - SSRF protection 预设封锁 private、loopback、link-local 等不安全目的地；若需要 self-hosted provider，应设定精确的 `CAVE_SSRF_ALLOWLIST`，不要开过大的网段。 - CLI anonymous telemetry 预设开启，但第一次互动命令会显示揭露；可用 `caveman telemetry off` 或 `DO_NOT_TRACK=1` 关闭。官方列出的 telemetry 是无内容的使用事件与 token aggregate，不包含 prompt、completion body、档案路径或 provider credentials。 - Browser bridge 可执行 JavaScript、click、表单提交甚至可能触发购买；它不应被当成单纯的 read-only scraper。 因此，部署 Caveman 的思考方式应接近「安装 coding agent 或本机 proxy」，而不是把它当作无风险的文字格式化工具。 ## 安装与使用建议 官方 README 提供 skill-only 与 runtime 两种入口。实际采用时，可以按这个顺序降低风险： 1. 先阅读 pinned release 的 `INSTALL.md`、`SECURITY.md` 与 license 边界，不要直接把未审查的远端安装脚本 pipe 进 shell。 1. 只想测试回答风格时，先采用 skill path，并用短任务与长任务各做一次 A/B。 1. 要启用 runtime 时，先用 `caveman setup` 检查元件，再从单一 agent 的 `caveman wrap ` 开始，不要一开始就改动所有全域整合。 1. 在敏感专案中确认 `~/.caveman/` 的权限、CCR retention 与 telemetry 设定；不要把 secrets 写进 YAML、benchmark fixture、prompt 或 command history。 1. 先使用 record/pass-through mode 验证既有流程，再逐一开启 JSON、logs、diff 或 browser 等 transform。 1. 用 provider-reported usage 与品质结果验证，若自己的 workload 变差，直接停用该路径。 ## License 与采用范围 这个 repository 不是单一 license。Skill、CLI、SDK 与部分 adoption surface 采 MIT；Engine、proxy、rewriter、browser、MCP、shrink、Cavemem Go core 与 shared platform 等 Engine-linked 元件采 BSL-1.1，并有 first-party self-hosted production 的 Additional Use Grant。若你要把 Engine-linked 功能提供给第三方服务，必须先读 `LICENSING.md` 与对应的 BSL 条款。 这个区分会直接影响架构选择：个人或团队内部自架，和把压缩 runtime 包进对外提供的 SaaS，并不是同一种授权情境。文章可以介绍它的设计，但不能把整个 repository 简化成「MIT 开源 proxy」。 ## 结语：值得研究，但先量自己的资料 Caveman 最有价值的地方，不是把 AI agent 变成更会讲电报文，而是把 context compression 做成一个有 detection、recovery、fail-safe、usage basis 与 evidence labels 的本机系统。它让「压缩」从 prompt trick 变成可以被拆解、测量与停用的 middleware。 但它的正确使用方式也很清楚：从最小 layer 开始，保留原始资料的复原能力，分清 inferred estimate 与 provider usage，完整评估本机 CCR、telemetry、SSRF、browser permission 与 license 边界，最后用自己的 coding workload 做 A/B。 如果你的 agent 大量反复阅读 logs、JSON、diff 与测试输出，Caveman 是值得深入研究的实作；如果你的工作主要是短问答、按 request 计费，或每个输入 byte 都必须直接可见，先不要假设它会带来净收益。 ## 参考资料 - [Caveman GitHub repository](https://github.com/JuliusBrussee/caveman) - [Product model](https://github.com/JuliusBrussee/caveman/blob/main/docs/technical/product-model.md) - [Architecture](https://github.com/JuliusBrussee/caveman/blob/main/docs/technical/architecture.md) - [Compression Engine](https://github.com/JuliusBrussee/caveman/blob/main/docs/technical/engine.md) - [Local tools](https://github.com/JuliusBrussee/caveman/blob/main/docs/technical/local-tools.md) - [Security and privacy](https://github.com/JuliusBrussee/caveman/blob/main/docs/technical/security-and-privacy.md) - [Honest Numbers](https://github.com/JuliusBrussee/caveman/blob/main/docs/HONEST-NUMBERS.md) - [Wrap benchmark](https://github.com/JuliusBrussee/caveman/blob/main/docs/WRAP-BENCHMARK.md) - [Repository SECURITY.md](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md) - [Repository LICENSE](https://github.com/JuliusBrussee/caveman/blob/main/LICENSE)