Headroom：给 AI Agent 装一个上下文压缩层

headroom 在 GitHub 上拿到了 52K Star。

这个工具专门解决一个问题：AI Agent 处理大量上下文时，token 消耗太高。它在数据到达 LLM 之前做一层压缩，工具输出、日志、RAG 结果、文件、对话历史，统统先压缩一遍。答案质量不变，token 消耗能砍掉六到九成。

1、 解决什么问题

用过 Claude Code、Cursor 或者 Codex 的人应该有体会。一个稍微复杂点的任务，上下文窗口很快就满了。不是模型不够聪明，是你喂给它的数据太冗余。

工具返回的 JSON 一大片，git log 输出几百行，RAG 检索回来的文档重复内容一堆。模型要从这些里面找有用信息，跟大海捞针一样。

Headroom 的做法是：在数据进入模型之前，先过一遍压缩管道。JSON 用 SmartCrusher 处理，代码用 CodeCompressor 走 AST 分析，普通文本用 Kompress-base 模型。压缩完还能还原，原始数据本地缓存，模型需要的时候可以调 headroom_retrieve 拿回来。

2、 支持哪些接入方式

这个工具的接入方式比较全：

库模式：Python 和 TypeScript 都支持，在代码里直接调 compress() 就行。

代理模式：一行命令 headroom proxy --port 8787 启动本地代理，不用改任何代码。

Agent 包装：headroom wrap claude、headroom wrap codex 这种，一条命令把你的 Agent 包起来。

MCP 服务：提供 headroom_compress、headroom_retrieve、headroom_stats 三个工具，任何 MCP 客户端都能用。

跨 Agent 记忆：Claude、Codex、Gemini 之间共享上下文存储，自动去重。

3、 实际效果

官方给了一组真实数据：

代码搜索 100 条结果，从 17,765 tokens 压到 1,408，省了 92%。

SRE 故障排查场景，从 65,694 压到 5,118，也是 92%。

GitHub issue 分类，从 54,174 压到 14,761，省了 73%。

准确率方面，GSM8K 数学测试基准线 0.870，压缩后还是 0.870。TruthfulQA 从 0.530 涨到 0.560，反而好了。SQuAD v2 和 BFCL 都保持在 97%。

4、 还能砍输出 token

除了压缩输入，Headroom 还能减少模型写回来的内容。

模型经常在回复开头加一堆"好的，让我来……“这种废话，或者把你看过的代码重新贴一遍。Headroom 会在系统提示末尾加一句"简洁回答，不要重复上下文”，模型就会收敛很多。

还有一个叫 Effort Routing 的机制。当模型只是在读完一个文件后继续工作，这种简单场景会自动降低思考深度。遇到新问题或者错误才开全力。

开启方式：

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

5、 安装

pip install "headroom-ai[all]"      # Python
npm install headroom-ai             # TypeScript

也可以按需装：pip install "headroom-ai[proxy,mcp,ml]"。

代理模式装完就能用：

headroom wrap claude                # 包装 Claude Code
headroom proxy --port 8787          # 或者启动代理
headroom perf                       # 看看省了多少

Python 要求 3.10 以上。

启动代理
headroom perf # 看看省了多少

Python 要求 3.10 以上。