Headroom：当压缩变成 LLM 的中间件，失败会话成了自学教材

一个反直觉的数字

10,144 → 1,260 tokens。

同样的 FATAL 错误被找到了，同样的修复方案被提出了，但你的 LLM 只读了原来 12% 的上下文。这不是一个 benchmark 场景，这是 headroomlabs-ai/headroom 在真实 coding agent 会话中的日常输出。

过去两年，LLM 领域的优化方向几乎全在模型侧：更长的上下文窗口、更快的推理、更便宜的 token 价格。Headroom 提出的问题是：如果模型读的东西本身就有 80% 是冗余的，为什么要让模型去读？

压缩不是预处理，是中间件

大多数 token 压缩工具的工作方式是"预处理"——在发送前把文本截断、摘要、或者去掉一些行。Headroom 的设计更像一个中间件层，它坐在你的 agent 和 LLM provider 之间，做三件传统压缩工具不做的事。

第一，内容路由。 Headroom 的 ContentRouter 会先检测输入的内容类型——JSON、源代码、还是自然语言文本——然后选择不同的压缩器。JSON 走 SmartCrusher（60-95% 压缩率），代码走 CodeCompressor（基于 AST 的结构压缩），文本走 Kompress-v2-base（HuggingFace 上的压缩模型）。这比一刀切的摘要要精确得多，因为 JSON 的冗余在结构（重复的 key、嵌套层级），代码的冗余在模式（import 语句、样板代码），文本的冗余在语义（重复表述）。

第二，缓存对齐。 CacheAligner 做的事情更微妙——它会标记"易变内容"（volatile content）。LLM provider 的 KV-cache 是基于前缀匹配的：如果你的 prompt 前缀没变，cache 命中，推理快且便宜；前缀一变，cache 失效，重新计算。传统压缩工具不知道这一点，可能把一个稳定的前缀压缩成一个完全不同的字符串，导致 cache 全部失效。CacheAligner 会识别哪些内容变动频繁（比如时间戳、计数器），在压缩时保持这些部分的相对位置稳定，从而保住 KV-cache 前缀。

第三，可逆压缩（CCR）。 原始内容被缓存在本地，模型可以通过 headroom_retrieve 工具按需取回完整文本。这意味着压缩不是"有损"的——如果模型判断压缩后的信息不足以做决策，它可以主动请求原始内容。这是一个"先压缩、后按需展开"的架构，而不是"压了就压了"的单向操作。

headroom learn：让失败会话变成自学教材

这是 Headroom 最有意思的功能，也是之前很少有人讨论的角度。

每个 coding agent 都会失败。Claude Code 跑了 20 轮，最后报错了。Codex 改了 15 次代码，测试还是没过。这些失败会话通常被直接丢弃——它们消耗了 token，没产生结果，看起来没有价值。

headroom learn 做的事情是挖掘失败会话，找出"模型在哪里走错了路"，然后把修正写进项目级别的指令文件——CLAUDE.local.md（默认，gitignored）、CLAUDE.md、AGENTS.md、GEMINI.md 或 GROK.md。

这本质上是一种经验驱动的 prompt 工程。传统的 prompt 工程是人工写的："不要用 var，用 const"、"测试要覆盖边界条件"。headroom learn 是自动从失败中提取的："在这个项目的这个模块，你上次尝试用 X 方法失败了，正确的方法是 Y。"

关键区别在于：这些修正是项目特定的。通用的 coding 指令（"写干净的代码"）对具体项目的帮助有限，因为失败往往发生在项目特定的上下文里——某个 API 的调用方式、某个配置文件的格式、某个测试框架的 quirk。headroom learn 捕获的正是这种项目特定的知识。

跨 Agent 记忆：Claude 学到的，Gemini 也能用

Headroom 的另一个被低估的功能是跨 Agent 共享记忆。当你用 headroom wrap 包装多个 coding agent（Claude Code、Codex、Gemini、Grok）时，它们共享同一个本地压缩存储，并且自动去重。

这意味着什么？如果 Claude Code 在一个项目中工作了 2 小时，读了 50 个文件，压缩后的上下文已经积累了大量项目知识。当你切换到 Codex 继续工作时，Codex 不需要从头读这些文件——Headroom 的共享存储已经有了压缩版本，可以直接使用。

这解决了一个实际问题：不同 agent 之间的上下文迁移。传统做法是手动复制粘贴上下文，或者导出会话日志再导入。Headroom 把这个过程自动化了，而且通过压缩大幅减少了迁移的数据量。

数据说话

Headroom 的 README 给出了几个场景的压缩数据：

• Coding agents：20% token 减少（这类场景的文本已经是代码，冗余度较低）
• JSON 处理：60-95% token 减少（JSON 的结构冗余极高）
• RAG chunks：取决于内容类型，通常 40-70%

20% 对 coding agent 来说意味着什么？如果你每天花 $100 在 Claude API 上，20% 就是 $20/天，$600/月。对于一个 5 人团队，每月省 $3000。而 Headroom 的安装成本是 pip install "headroom-ai[all]"，运行在本地，不发送任何数据到第三方。

架构的启示

Headroom 的架构给了一个更深的启示：LLM 的输入层正在变成一个独立的工程领域。

过去，"给 LLM 什么内容"是由应用层决定的——RAG 系统决定检索什么，agent 框架决定读哪些文件，工具决定返回什么格式。Headroom 在这些和应用层之间插入了一个"内容优化层"，专门处理"如何让同样的信息用更少的 token 传达"。

这个层的三个组件——ContentRouter（分类）、CacheAligner（缓存感知）、CCR（可逆压缩）——构成了一个完整的中间件架构。它不修改你的 prompt，不改变你的 agent 逻辑，不替换你的 LLM provider。它只做一件事：让模型读到的每一个 token 都更有信息密度。

当 LLM 的上下文窗口从 4K 涨到 200K，再涨到 1M，"能不能塞进去"已经不是问题了。"塞进去的东西有多少是噪声"成了新问题。Headroom 的回答是：用中间件思维，而不是更大的窗口，来解决这个问题。

项目地址：headroomlabs-ai/headroom
文档：headroomlabs.ai