Headroom实战测评：烧钱Agent的救星与避坑指南
先说说我为什么盯上这个项目。
手头有个内部用的SRE排查agent，逻辑其实挺糙的：告警进来，它去捞最近五分钟的日志，查几个相关服务的指标，再调一下trace，最后让Claude给出“大概是哪儿炸了”的判断。听起来挺优雅，是不是？跑起来才发现，最大的成本根本不在模型思考，而在“喂料”。一次排查动不动就塞进去六七万token，里面80%是日志，重复的stack trace糊了一大片，JSON里同一个字段在不同对象里出现一千次。Claude看完每次都特别有耐心地告诉我：“根据日志显示，xxxx服务出现了OOM”——废话，我知道是OOM，我想知道的是为什么OOM。
那一周对账，光这一个agent就烧了三百多块。老板倒是没说什么，但自己心里慌得很。
巧的是，那两天GitHub Trending上有个叫chopratejas/headroom的项目蹭蹭涨星，README里直接挂着一行字：“把你的Agent上下文压缩92%，精度不掉”。就这一行，我就去翻了它的代码。
它到底是个啥？一句话讲明白
很多上下文压缩方案是“让模型自己总结历史”，听起来挺聪明，但实际运行中等于多调一次LLM，省了输入又花了输出，还可能把关键信息总结没了。Headroom的思路完全是另一套——它根本不让LLM干这个活。
它在agent和LLM之间插了一个本地压缩层。这层的工作流程是这样的：先看一眼内容是什么——是JSON、是源码、是日志、还是普通文本？然后路由给对应的压缩器——JSON走SmartCrusher，源码走AST压缩，文本用自己训的小模型。该删的删、该折叠的折叠、该去重的去重，原文在本地留底。LLM看到的是瘦身版，但如果它真的需要某个细节，它能反向调用一个工具把原文捞回来——这一点是整个项目里最让人欣赏的设计，后面会单独展开。
下面这张架构图凑合看一下：
整个流程跑在本地，数据不出机器，对于合规要求苛刻的场景来说相当友好。
四种接法，怎么舒服怎么来
这是它最讨人喜欢的地方——不强迫你改代码。
把这四种用法挨个看了一遍，结合SRE agent的形态，最后选了proxy模式——因为那玩意儿是Go写的，懒得动它。
1. Wrap模式：一行命令，最适合Claude Code/Cursor这类CLI
headroom wrap claude
headroom wrap cursor
headroom wrap aider
headroom wrap copilot
包完之后正常用Claude Code，它背后的所有上下文都会先过一遍Headroom，你完全无感。这是写README的人在炫技——他知道大部分用户根本不想学新东西。
2. Proxy模式：开个端口，谁都能接
headroom proxy --port 8787
然后把agent里的OPENAI_BASE_URL或ANTHROPIC_BASE_URL改成http://localhost:8787，齐活。Go、Rust、Ja va、PHP，不挑语言。
3. Library模式：要嵌进自己的逻辑里
from headroom import compress
compressed = compress(messages, model="claude-sonnet-4-5")
或者更优雅地用它的SDK Wrapper，连compress都不用自己调：
from headroom import withHeadroom
from anthropic import Anthropic
client = withHeadroom(Anthropic())
# 之后所有 client.messages.create 都自动压
4. MCP Server模式
挂成MCP，让其他支持MCP的客户端把它当成“压缩工具”调用，适合多agent系统里做共享中间件。
它具体怎么压的？拆开看不复杂
比较好奇的是：到底是怎么做到92%压缩还不掉精度的？翻了一圈代码和它附的几篇paper引用，大致是这么三层活：
第一层：ContentRouter——内容分诊台
这块是它的灵魂。任何一段输入进来，先做一次“这是啥”的判定：
| 内容类型 | 路由去向 | 典型场景 |
|---|---|---|
| JSON数组/对象 | SmartCrusher | tool返回值、API response |
| 源代码 | CodeCompressor（AST感知） | 代码库探索、补全上下文 |
| 日志、纯文本 | Kompress-base（自训小模型） | 日志、文档、RAG片段 |
| 历史对话 | HistoryCompressor | 多轮对话回看 |
判错了怎么办？它内部有打分机制，评估压缩前后的语义保留度，过低就退回原文。这个fallback比那些“一压到底”的方案靠谱多了。
第二层：六个专用压缩器
- SmartCrusher：JSON专用。识别结构、合并重复字段、把数组同构对象列成“列式”格式。SRE agent调监控接口拿到的指标JSON，最直接受益。
- CodeCompressor：基于AST，支持Python/JS/Go/Rust/Ja va/C。能区分函数体和注释、签名和实现，根据当前问题决定保留哪一层。
- Kompress-base：作者自己在HuggingFace上训的一个小模型，专门干文本压缩。没去复现训练，但人家放了模型权重，可信度比“我们用GPT总结一下”高得多。
- LogCompressor：日志去重和模板提取，把“用户X登录失败”这种重复行折叠成一行加计数。
- HistoryCompressor：对话历史专用。
- 基础降重/截断器：兜底用。
第三层：CCR（Reversible Compression）——可逆压缩
这是它真正让人决定要在生产用的原因。普通压缩工具压完就压完了，丢了的细节再也回不来。Headroom不一样：原文留在本地，压缩版的内容里会带一个引用句柄，比如[ref: log_chunk_a3f]。LLM在推理过程中如果觉得“这块好像有信息我需要看”，它可以主动调一个headroom_retrieve工具，把原文展开。这就让“压缩”这件事从“破坏性操作”变成了“惰性加载”。看到这个设计的瞬间就知道，作者做过生产系统——只有生产里被坑过，才会提前把后悔药备好。
第四层（彩蛋）：CacheAligner
这块比较细。Anthropic/OpenAI都有prompt cache，缓存命中价格能差几倍。Headroom在压缩的时候会刻意保持前缀稳定，让缓存更容易命中。压缩加上缓存命中双重buff，账单上的反应就更明显了。
官方实测+个人的“演练”
光看README数字没意思，把官方benchmark拉出来对比，再结合SRE agent的实际形态，估一下能省多少。
官方公开的实测数据
| 工作负载 | 压缩前Token | 压缩后Token | 节省 |
|---|---|---|---|
| 代码搜索（100条结果） | 17,765 | 1,408 | 92% |
| SRE故障排查 | 65,694 | 5,118 | 92% |
| GitHub Issue分类 | 54,174 | 14,761 | 73% |
| 代码库探索 | 78,502 | 41,254 | 47% |
而且作者很有职业道德，把“压缩之后会不会变蠢”也单独跑了benchmark：
| 评测集 | 压缩前 | 压缩后 | 备注 |
|---|---|---|---|
| GSM8K（数学推理） | 87% | 87% | 完全一致 |
| TruthfulQA（事实问答） | 53% | 56% | 反而涨了3分 |
| SQuAD v2（阅读理解） | 97% | 97% | 同时压了19% |
| BFCL（工具调用） | 97% | 97% | 同时压了32% |
注意TruthfulQA那一行——压完反而变准了。猜测原因是噪声本身就在干扰模型，把噪声去掉模型反而清醒。这个观察跟平时调prompt的经验是吻合的：很多时候不是上下文不够，而是上下文太脏。
套到SRE agent上
那个agent的输入大致是：30%日志（重复严重）、25%监控指标JSON（重复严重）、20% trace信息（半结构化）、15%历史告警上下文、10%系统prompt和用户输入。按Headroom各类压缩器的官方平均压缩比往这个分布上一套，估算的总节省大概在80%左右。换算回之前一晚上三百块的账单，理论上能压到六十块。
自己估完都觉得有点夸张，专门去翻了它issue区有没有人吐槽“实际没那么神”——翻了大概三十条issue，主要的负面反馈集中在两类：第一次冷启动有点慢，Kompress-base模型加载需要十几秒，这个能理解；AST压缩对小众语言（比如Elixir、Haskell）支持不到位，会退化成普通文本压缩，也合理。没有看到“压完答错了”这种致命吐槽，这个口碑在5k star的新项目里算很干净了。
上手成本和踩坑预判
如果想接进自己项目，把会卡住人的几个点提前列出来：
装它
# Python（推荐，特性最全）
pip install "headroom-ai[all]"
# Node.js
npm install headroom-ai
# Docker（生产推荐）
docker pull ghcr.io/chopratejas/headroom:latest
[all]会把所有子模块一起装，包括proxy/mcp/ml/code/memory。如果只用proxy，可以装[proxy]减小体积。Python要3.10，老版本会报奇怪的类型错误。
配LLM厂商
它的proxy默认朝Anthropic转。如果用的是OpenAI兼容的端点（包括国内一堆袋里），需要在配置里指明upstream，否则启动会卡住没报错。这个issue区有人翻过车。
CCR（可逆压缩）的工具注册
如果想让LLM用headroom_retrieve反查原文，得在agent工具列表里把这个工具暴露出去。Wrap模式自动帮你做了，proxy模式需要自己注册。这点README写得不算清楚，要看docs才能搞明白。
跨agent共享记忆
from headroom import SharedContext
ctx = SharedContext()
ctx.put("这个项目的数据库连接串是 xxx")
# 在另一个 agent 里
db_url = ctx.get("数据库连接串")
# 自动去重、自动关联
这个蹲了一下，本质是用本地SQLite当KV，再做嵌入检索。简洁，没炫技，但对多agent协作场景很实用。
Headroom Learn——它会自己学
headroom learn --agent claude --source ./sessions/
把过去的对话扔进去，它会找出agent频繁犯的错，写进CLAUDE.md/AGENTS.md，下次自动加载。这功能介于“花活”和“实用”之间，个人会先观察两周再决定要不要用。
它适合谁？不适合谁？
适合的场景
- agent输入里有大量重复/结构化噪声：日志多、JSON多、tool output长，提升立竿见影。
- 多轮对话堆很长的：HistoryCompressor是亲妈。
- 生产环境怕信息丢：CCR让你能放心用，丢不了关键信息。
- 多agent系统：proxy+SharedContext，统一压、统一记。
- 预算敏感的中小团队：账单减60%，老板看见报表会笑。
不适合的场景
- 输入本身就很短：每次1k token以内的，加压缩层反而引入额外延迟（虽然不多，但有）。
- 内容主要是非英文非中文的小语种：Kompress-base主要在英文上训，中文够用，但小语种可能拉胯。
- 极致追求延迟（毫秒级SLA）：路由+压缩有几十毫秒开销，对话场景无感，但如果做的是实时语音那种就别加了。
- agent本来就用了厂商的官方prompt cache且做得很到位：收益会被吃掉一部分，得自己评估。
总结评价
审视GitHub项目的口味比较挑，喜欢那种“作者明显被坑过、知道自己在解什么”的项目。Headroom完全是这类。它身上有几个非常成熟的判断：不让LLM干压缩——成本和不确定性双双省下来；按内容类型分诊——而不是一刀切；可逆——CCR的设计是对生产环境的尊重；多种接入——wrap/proxy/library/MCP，作者懂用户懒；前缀稳定——主动迎合prompt cache，是只有真正做过推理优化的人才会想到的细节。
要说不足，也老实讲：文档分散——README、docs site、几篇paper引用，新手摸索成本中等偏上；小语种/小众文件类型支持有限——现阶段以英文和主流编程语言为主；生态还在长——MCP模式、Learn模式都偏新，可能会改API；作者背景偏Netflix工程口味，能感觉到它特别擅长高并发、长文本场景，轻量场景可能有点“杀鸡用牛刀”。
但综合起来，会推荐任何在生产里跑agent的团队都至少试一下proxy模式——零代码改动、零风险、跑一周拉账单看效果。这种买卖太划算了。