AI Agent 的「省 token 神器」：Headroom 压缩实测

Agent 每次调用工具都返回一堆东西，大部分是冗余的。Headroom 做的事：在内容进入 LLM 之前自动压缩 60-95%，答案质量不变。

---

一、问题：Agent 太费 token 了

用 AI Agent 写过代码的人都经历过：让 Agent 搜个东西，它 grep 返回 50 条结果，每条带文件名、行号、代码片段。然后 Agent 把这 50 条全部喂给 LLM。

一次搜索几千 token，十次交互几万 token——钱花在让 LLM 看重复信息上。

Headroom 解决的就是这个问题。它在 Agent 和 LLM 之间加了一个压缩层：

tool 输出 → Headroom 压缩 → LLM

---

二、Headroom 是什么

一句话：AI Agent 的上下文压缩中间件。

GitHub 37,000+ Star，Apache 2.0 开源，纯 Python。三种使用方式：

# 1. 库模式——代码里一行调用
from headroom import compress
result = compress(messages)

# 2. 代理模式——零代码改动
headroom proxy --port 8787
ANTHROPIC_BASE_URL=http://localhost:8787 claude

# 3. 包装模式——一行命令
headroom wrap claude

核心思路：不是无脑删东西，而是理解内容类型后做针对性压缩。

---

三、实测：它的 ContentRouter 有多聪明

我在本地装了一套，用各种内容测试它的行为：

我喂给它的内容	Headroom 怎么做	原因
用户发的消息	不压缩	用户意图不能丢
错误堆栈	不压缩	Agent 需要完整错误信息
刚 grep 出来的代码	不压缩	上下文一致性
JSON API 响应（8 条用户记录）	去空白（节省 12%）	纯格式化冗余
重复文本 30 遍	不触发（判定 noop）	内容无信息量不值得压

这比「粗暴截断」聪明太多了。它知道哪些该压、哪些该保护。

但注意：库模式 compress() 非常保守，大部分时候走 noop。真正的 60-95% 大压缩发生在代理模式——代理能看到完整上下文（系统提示、历史对话、tool 输出），做出更精准的压缩决策。

---

四、三层压缩引擎

Headroom 内部有三个压缩器，ContentRouter 自动选：

ContentRouter（识别内容类型）
  ├─ SmartCrusher    → JSON 去空白、截断长列表（~12%）
  ├─ CodeCompressor  → AST 语义级代码压缩
  └─ Kompress        → HuggingFace ML 模型语义摘要（60-95%）

SmartCrusher 是结构化的——它知道 JSON 的空白没意义，直接去掉。

CodeCompressor 是语法级的——它用 tree-sitter 解析代码 AST，保留签名去掉实现细节。

Kompress 是语义级的——一个专门训练的模型（Kompress-v2-base），读一段文本后生成压缩版，保留关键信息丢弃冗余。

三者配合，官方的基准数据：

场景	压缩前	压缩后	节省
代码搜索 100 条结果	17,765 token	1,408 token	92%
SRE 事故调试日志	65,694 token	5,118 token	92%
GitHub Issue 分类	54,174 token	14,761 token	73%

而且准确率不受影响——GSM8K 数学题 ±0.000，TruthfulQA 甚至略微提高。

---

五、两个很妙的设计

CCR 可逆压缩

Headroom 的压缩是「可逆」的——原始内容存在本地缓存里。如果 LLM 觉得压缩版不够，可以主动调用 headroom_retrieve 工具取回原文。相当于「先看摘要，需要再看全文」。

Prompt 缓存友好

每次压缩可能导致 prompt 前缀变化，让提供商的 KV Cache 失效。Headroom 有个 CacheAligner 模块，专门对齐前缀保证缓存命中——省钱又提速。

---

六、主流产品怎么做？和 Headroom 的对比

Headroom 这套「后处理压缩」思路在 Agent 领域其实很新。主流产品走的是完全不同的路线。

Claude Code

Claude Code 没有用 ML 模型压缩 tool 输出。它的 token 优化是「输入侧」的：

技术	做法
Prompt Caching	系统提示、工具定义固定前缀，多次调用共享 KV Cache
/compact	手动触发，让 Claude 自己总结对话历史替代全文
子代理隔离	每次 delegate 新建上下文，不污染主会话
Skills 压缩	技能指令写的短小精悍，但不会后处理压缩
Todo 结构化	用 todo list 替代长篇思考输出

一句话：Claude Code 优化输入结构，Headroom 压缩已有内容。两条路。

Codex (OpenAI)

和 Claude Code 类似——靠 prompt caching + 结构化输出 + 子代理隔离，没有后处理压缩这一层。OpenAI 的 prompt caching 是自动的，开发者不用管。

Cursor

比较特殊，有自己的模型做上下文管理。但思路是语义检索——从代码库挑最相关的片段喂给模型，而不是压缩工具输出。更像 codebase-memory-mcp 的路线。

GitHub Copilot

完全依赖 embedding + 语义搜索——不是压缩，而是挑。面对整个代码库，只选最相关的几段。

对比总结

产品	Token 优化思路	有后处理压缩？	有专用压缩模型？
Headroom	ML 模型 + 结构化 + 代理	✅	✅ Kompress-v2
Claude Code	Prompt caching + 对话摘要	❌	❌
Codex	Prompt caching + 子代理隔离	❌	❌
Cursor	语义检索 + 自有模型	❌	❌
Copilot	Embedding 语义搜索	❌	❌

为什么主流产品不这么做？

后处理压缩有个核心风险：万一删错了关键信息，Agent 行为会异常。Claude Code 团队显然选择了更保守的路线——宁可多花 token，也不冒险丢信息。

Headroom 用 CCR（可逆压缩）来解决——原文缓存在本地，LLM 觉得不够可以主动取回。这套机制很聪明，但需要时间验证稳定性。目前 Headroom 是这个方向上唯一的成熟产品，37k Star 也说明社区对这个需求认可度很高。

---

七、和 codebase-memory-mcp 的配合

上一篇文章介绍了 codebase-memory-mcp——把代码库索引成知识图谱，让 Agent 用结构化查询替代 grep。

这两个工具解决的是同一件事的两个环节：

传统方式：
  Agent grep → 50 条结果 → 全量喂入 LLM
  耗时：数十次 tool call，几十万 token

codebase-memory-mcp：
  Agent 结构化查询 → 精确结果（毫秒） → LLM
  减少「找」的开销

Headroom：
  Agent grep → 50 条结果 → 压缩到精髓 → LLM
  减少「读」的开销

两者组合：
  Agent 结构化查询 → 精确结果 → 压缩 → LLM
  「找得准 + 读得少」→ token 优化到极致

---

八、安装与踩坑

安装不算轻松：

pip install "headroom-ai[all]"   # Python 3.10+

实际遇到的问题：

1. macOS 系统 Python 是 3.9——需要 Python 3.10+，得用 venv
2. 依赖链极长——litellm → tokenizers → huggingface-hub → httpx[http2] → h2 → …
3. [ml] 额外包有版本冲突——pip install headroom-ai[ml] 会把主包降级到 0.2.2
4. Kompress 模型 ~500MB——需要单独下载
5. 网络不好的话要装很久——依赖和模型下载可能需要十几分钟

建议的安装顺序：

python3.11 -m venv headroom-venv
source headroom-venv/bin/activate
pip install headroom-ai        # 先装核心
pip install "headroom-ai[proxy]"  # 再装代理
pip install "headroom-ai[ml]>=0.26.0"  # 最后装模型

---

九、总结

Headroom 解决了一个非常具体的问题：Agent 看到太多无用信息，浪费 token。

它的几个设计值得学习：

• 不无脑压缩——ContentRouter 区分 6+ 种内容类型，保护关键信息
• 可逆压缩——LLM 可以取回原文，不丢信息
• 多层压缩——结构化 + 语法级 + 语义级，分场景选用
• 对 Agent 透明——代理模式下零代码改动

对日常用 AI Agent 开发的工程师来说，这是一个「装了就省钱」的工具。

---

参考

• GitHub: https://github.com/chopratejas/headroom
• 文档: https://headroom-docs.vercel.app/docs
• 模型: https://huggingface.co/chopratejas/kompress-v2-base