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。三种使用方式：
bash
# 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+实际遇到的问题：
- macOS 系统 Python 是 3.9------需要 Python 3.10+，得用 venv
- 依赖链极长------litellm → tokenizers → huggingface-hub → httpxhttp2 → h2 → ...
- ml 额外包有版本冲突 ------
pip install headroom-ai[ml]会把主包降级到 0.2.2 - Kompress 模型 ~500MB------需要单独下载
- 网络不好的话要装很久------依赖和模型下载可能需要十几分钟
建议的安装顺序：
bash
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 开发的工程师来说，这是一个「装了就省钱」的工具。