你有没有过这种体验：让 AI 编程助手帮你查个 bug，它先 grep 一遍代码，再 cat 十几个文件，然后翻一堆日志——一个会话下来，十几万 token 没了，账单蹭蹭往上涨，可它真正用到的信息，可能还不到十分之一。
这不是你的错觉。AI Agent 真正”吃 token”的，往往不是你提的问题，而是它在工具调用里读进来的一大堆噪声。
今天聊一个专门治这个毛病、在 GitHub 上拿下 4.4 万 Star 的开源项目——headroom。
一个让开发者集体破防的问题
先说清楚问题到底有多大。
现在的 AI Agent 工作流，基本上是”模型 + 一堆工具”。模型每走一步，就调个工具拿点东西回来看：读文件、跑搜索、查数据库、拉 RAG 结果、翻日志。问题在于，这些工具返回的内容，冗余得惊人。
有技术分析专门做过拆解：JSON 工具输出里大半是重复的字段名和 null 值；日志 95% 是例行跑通的噪声，真正有用的就那几行报错；RAG 检索回来的片段，文档之间互相重复样板话；代码搜索更是离谱，明明只想要几个函数签名，它给你整文件整文件地塞。
结果就是，一次编程会话堆积出 15 万 token 的上下文，其中绝大部分是”废话”。上下文窗口被撑爆，响应变慢，成本翻倍——而模型还要在一堆噪声里费力找有用信息，准确率反而被拖累。
headroom 是什么
headroom 给自己的定位是：AI Agent 的上下文压缩层（context compression layer）。
一句话概括它干的事：在内容到达大模型之前，先把它”瘦身”一遍。工具输出、日志、文件、RAG 片段、对话历史，统统先过一道 headroom，能压则压，再喂给模型。官方宣称能减少 60%–95% 的 token，而且——关键来了——答案基本不变。
项目目前 Apache 2.0 开源，主力语言 Python（约 79%）配 Rust（约 17%，扛性能关键路径），还在快速迭代，截至发稿已经发了 156 个版本，最新是 2026 年 6 月中旬的 v0.26.0。
它怎么砍掉 90% token 的
headroom 的设计思路很清楚：拦截 + 路由 + 压缩。
它不是简单粗暴地”截断”，而是先判断这段内容是什么类型，再派给专门的压缩器处理，最后才发给模型。流水线大致是这样：内容进来 → CacheAligner 稳定前缀 → ContentRouter 识别类型并选压缩器 → CCR 缓存原文 → 压缩后的内容发给模型。
更实在的是它的接入方式，给了三种，几乎覆盖所有场景：
库模式：在 Python 或 TypeScript 里直接调 compress()，适合自己写应用的人。代理模式：跑一句 headroom proxy --port 8787，零代码改动，像个中间人挡在你和模型厂商之间，什么语言都能用。包裹模式：一行命令直接包裹 Claude Code、Codex、Cursor、Aider、Copilot CLI 这些现成的编程 agent，开箱即用。
对大多数人来说，包裹模式是最省心的——本来在用 Claude Code，套一层 headroom 就行，不用改任何代码。
不同内容，不同”刀法”
这是 headroom 比较聪明的地方：它知道不同内容该用不同刀法。
JSON：用统计分析，专门保留那些偏离常规的异常值和边界值。换句话说，它知道日志里那个”长得不一样”的字段往往才是 bug 线索，宁可留着。 源代码：AST 语法树级别的感知，保留函数签名和文档注释，折叠掉实现细节。支持 Python、JS、Go、Rust、Java、C++ 六种语言。 日志：保留失败和报错，丢掉成功跑通的噪声。 搜索结果：按相关性排序，只留 top 命中。 纯文本：用一个在 agent 轨迹上专门训练过的模型（Kompress-base）去冗余。 图片：用 ML 路由选最优的缩放和质量权衡。
各类型节省幅度也不一样：日志能省 80%–95%，JSON 70%–90%，代码 40%–70%，纯文本相对克制，30%–50%。这个差距其实很合理——越冗余、越结构化的内容越能压，纯自然语言本来就没多少水分。
最妙的一招：压缩还能”反悔”
如果只能压、不能还原，那谁敢在生产环境用？多步 Agent 工作流里，一次信息丢失会顺着后面的步骤不断累积，最后可能全盘跑偏。
headroom 解决这个的法宝叫 CCR（Compress-Cache-Retrieve）。它压完之后，原文并不会丢，而是缓存在本地。模型那边会拿到一个 headroom_retrieve 工具，发现压缩后的信息不够用了，随时可以把原文捞回来。
官方有句话说得挺到位：**”compression is aggressive but reversible”**——压得可以很狠，但永远能反悔。
正是因为有了这个”安全网”，headroom 才敢对内容下重手。这也是它和市面上不少同类工具最本质的区别：那些工具基本压完就回不去了。
不光省输入，连 AI 的话都帮你管
很多人只盯着输入 token，其实还有一笔账常被忽略。
在 Opus 这个级别的模型上，输出 token 的价格是输入的 5 倍。也就是说，模型啰里啰嗦写一大段，比它读一堆文件还贵。
headroom 顺手把这事也管了：它能在系统提示后面追加”话少点”的引导，还能在处理常规工具结果时调低模型的”思考预算”。官方给的数据是输出能省约 31.7%（带置信区间）。这个能力，目前其他开源工具还真没有。
效果到底怎样？看真实数据
光嘴说没用，直接上两组数。
真实负载的节省：
准确率有没有掉？ 这才是关键。在标准基准上：数学题 GSM8K 持平不变，事实问答 TruthfulQA 反而涨了 0.03，工具调用 BFCL 在压了 32% 的情况下还保持 97%。
最反直觉的是 TruthfulQA 那个上涨——分析认为，headroom 把那些冗长但具有误导性的上下文一起压掉了，相当于顺带做了”去噪”。压缩在这里不只是省钱，还顺手让模型更专注。
说句实话：它也不是万能的
吹了这么多，得泼点冷水，这项目自己也挺坦诚。
代码库探索只能省 47% ，这是”诚实的上限”：当 agent 需要理解一段全新代码的整体结构时，本来就没多少冗余可去。 跨 agent 记忆的完整栈要 Docker（Qdrant + Neo4j），不是那么轻量，对基础设施有要求。 ML 模型主要拿英文 agent 轨迹训练，非英文文本效果会打折扣，中文场景要有个心理预期。 压缩会吃点内存，内存紧张的小机器上跑 ML 部分会有压力（好在能关掉，纯网关模式啥额外资源都不要）。 CCR 缓存会过期，万一过期了模型检索不到，就只能拿到压缩版信息了。
这些不算致命，但说明它更适合”重日志、重工具调用、token 开销大”的团队，而不是所有场景都立竿见影。
三步上手
想试试的话，三步走：
# 1. 安装
pip install "headroom-ai[all]"
# 2. 选个模式（比如包裹 Claude Code）
headroom wrap claude
# 或者跑个零改动的代理
headroom proxy --port 8787
# 3. 看省了多少
headroom perf
要求 Python 3.10 以上，也支持 npm 和 Docker。运行时会自动拉 ONNX Runtime 和那个 Kompress 模型；如果只想要”纯网关”不压缩，这俩都不用下。
写在最后
AI Agent 这波浪潮里，大家都在卷”模型多聪明、工具多丰富”，但很少有人认真算”读进来这一堆到底有多少是废的”。headroom 捅破的就是这层窗户纸——它不让你换个更聪明的脑子，而是先把喂给脑子的东西筛干净。
可逆压缩这个设计尤其戳人：敢下狠手，又留了退路，这是敢用在生产环境的底气。
如果你最近也被 Agent 的账单和上下文窗口搞得头疼，不妨给它套一层试试。
最后聊两句：你平时用 AI 编程助手，有没有被 token 账单吓到过？评论区聊聊你的”烧钱”经历。觉得有用，点个赞、在看，顺手转给同样被账单折腾的朋友。
参考资料/来源
https://github.com/chopratejas/headroom https://headroom-docs.vercel.app
