几十万 token 压到几千，Agent 省钱的秘密开源了。
大家好，今天 GitHub 上翻到一个项目，值得聊聊。 headroomlabs-ai/headroom |Stars：58,582 ｜ Forks：4,330 ｜ License：Apache-2.0 ｜ Language：Python| | --- |  Agent 越智能，每一步往上下文里塞的东西就越多。日志、代码搜索结果、RAG 片段、文件内容、历史消息……模型真正仔细看完的，可能还不到一小半。 headroom 想在这中间加一道筛子。  ## 1. 它到底是什么 headroom 说白了，就是给 AI Agent 配的一层上下文压缩器。 它夹在 Agent 和模型中间，工具输出、日志、RAG 片段、文件内容，全部先过它一道，压完了再送给大模型。 而且它不是只做一个函数就完事。 README 里入口给得很全：Python / TypeScript 库、本地代理、MCP server，还有 `headroom wrap claude|codex|cursor|aider|opencode|cline` 这种——把你用的 Agent 包一层再启动。 我觉得它聪明的地方在于：不是让你选一种用法，而是你习惯怎么用，它就有那个入口。 简单说，headroom 想解决的不是「怎么调模型」，而是「Agent 每步往上下文塞东西的时候，怎么少塞点，但别丢关键线索」。  ## 2. 它解决什么麻烦 现在 Agent 用起来贵，不光是模型本身贵。 一次代码搜索、一次日志排查、一次 RAG 查询，工具能给你返回几千行。模型真正需要的，其实没那么多——结构、异常、边界，几条有代表性的就够了。 headroom 就是在这些东西进模型之前先过一遍。 比如一个 JSON 数组，它会扫一眼字段分布、哪些值重复、有没有异常、边界在哪。日志里要是有错误，它会把错误保住。原始内容先存本地缓存，后面模型万一真需要，再通过 `headroom_retrieve` 拿回来。 这个点对编码 Agent 来说特别直接——不是每次 `rg`、`cat`、API 返回都得原样往里塞。  ## 3. 核心看点 headroom 有几个地方我觉得值得看。 **第一，入口铺得很宽。** 代码里直接调 `compress(messages)` 也行，开个 `headroom proxy --port 8787` 也行，OpenAI、Anthropic、Codex 这些客户端走代理也能用上。本地跑着压缩服务，不用动现有代码。 **第二，它还搞了 MCP。** MCP server 暴露了 `headroom_compress`、`headroom_retrieve`、`headroom_stats`。Agent 看到大块内容，完全可以自己决定要不要打个压缩。 **第三，它不会一刀切全压了。** 用户消息不压，系统提示词内容留着，普通代码默认不动，短内容直接放过去。它更像一个路由器，先看内容类型再决定怎么处理。这比直接搞摘要靠谱多了。 **第四，它还做了缓存对齐，压完的东西能还原回来。** 原始内容能用 hash 找回——这个设计比"压完就丢"让人放心不少。  ## 4. 为什么值得看 headroom 的文档里给了几个挺实在的压测结果。 一个生产日志测试，原始输入 10,144 tokens，压缩完 1,260 tokens，让模型找错误、错误码、修复方式和影响数量，结果 4/4 全对。 文档里的真实工作负载也很直观： - code search：17,765 tokens → 1,408 tokens - SRE incident debugging：65,694 tokens → 5,118 tokens - GitHub issue triage：54,174 tokens → 14,761 tokens - codebase exploration：78,502 tokens → 41,254 tokens 这些数字不一定你本地也能省这么多，但指向的方向很明显——它最适合那些工具输出很长、结构重复很多的 Agent 场景。 说句实话，现在大家都在研究怎么让模型吃更多，headroom 在想的是怎么让它吃得更精。我觉得这个方向反而更值钱。  ## 5. 怎么用起来 想最快试，Python 这条路最直接： ``` uv tool install "headroom-ai[all]" headroom wrap codex ``` 走代理模式也行： ``` pip install "headroom-ai[proxy]" headroom proxy --port 8787 ``` 然后把兼容 OpenAI 或 Anthropic 的客户端指到本地代理。 要是用 MCP 客户端，可以只装 MCP： ``` pip install "headroom-ai[mcp]" headroom mcp install ``` 文档里还提醒了两个容易踩的坑。 一个是 npm 包 `headroom-ai` 主要是 TypeScript SDK，不带 `headroom` CLI——CLI 来自 PyPI 的包。装之前先看清自己走的是哪条路。 另一个是 Codex 或其他 MCP host 有时候拿不到 shell 里的 PATH。这时候得用 `command -v headroom` 找到绝对路径，再写进 MCP 配置。  ## 6. 适合谁，以及先注意什么 主要三类人值得先看看。 一类是重度用编码 Agent 的。经常读大文件、跑测试、查日志、扫 issue，headroom 有机会在这些场景里帮你降低上下文噪声。 一类是做 RAG 或搜索应用的。检索结果多、重复字段多、异常项又不能丢——这种场景正好对上它的 SmartCrusher。 一类是自己维护内部 Agent 平台的人。代理、MCP、SDK 三种入口都给了，往现有链路里试比较方便。 不过有几件事得提前知道。 它不是万能药，不是所有东西塞进去都能变短。文档里的 benchmark 也显示，grep 结果和 Python 源码可能是 0% 压缩——因为这些内容本来就不该动。 代理模式还会多一层本地服务。接到团队工具链之前，最好拿自己的日志、搜索结果和真实任务跑一遍。 压缩这事，关键其实是知道什么时候不该压。headroom 至少在这点上想得挺明白的。  有正在被 Agent 上下文塞满困扰的同学，装一个试试，欢迎留言区说说你实际省了多少。 今天就先聊到这里。我们下期再见！
