文章目录Headroom给 AI Agent 装一个上下文压缩层1、 解决什么问题2、 支持哪些接入方式3、 实际效果4、 还能砍输出 token5、 安装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 的机制。当模型只是在读完一个文件后继续工作这种简单场景会自动降低思考深度。遇到新问题或者错误才开全力。开启方式exportHEADROOM_OUTPUT_SHAPER1headroom proxy--port87875、 安装pipinstallheadroom-ai[all]# Pythonnpminstallheadroom-ai# TypeScript也可以按需装pip install headroom-ai[proxy,mcp,ml]。代理模式装完就能用headroom wrap claude# 包装 Claude Codeheadroom proxy--port8787# 或者启动代理headroom perf# 看看省了多少Python 要求 3.10 以上。启动代理headroom perf # 看看省了多少Python 要求 3.10 以上。