📌 项目地址：headroomlabs-ai/headroom | ⭐ 76,129 颗星 | 🔧 Python | 📜 未标注
问题在哪
编码 agent 烧 token 的大头，往往不是你打的那几个字，而是 agent 读进来的东西：工具输出、日志、RAG 检索结果、源码文件，还有越滚越长的对话历史。这些内容原样进上下文，账单很快就不好看了。
Headroom 的思路很直接：内容送到 LLM 之前，先在本地压一道。README 给了个例子，10,144 tokens 压到 1,260，模型照样找到了那条 FATAL 日志。压缩全程跑在你自己机器上，prompt 和文件内容不发给任何外部服务。
四种接法，按改动成本排序
一行命令包住现有工具。这是最省事的用法：
headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode
主流编码工具基本都在列表里。后悔了就 headroom unwrap 撤销。
代理模式，headroom proxy --port 8787，应用不用改一行代码，也不限语言。
库调用，Python 或 TypeScript 里直接 compress(messages)，嵌进自己的应用。
MCP server，暴露 headroom_compress、headroom_retrieve、headroom_stats 三个工具，任何 MCP 客户端都能接。
压缩不是黑盒，也不是纯有损
内部流程分三步，我逐个说：
ContentRouter 先判断内容类型，再分发给对应的压缩器：JSON 走 SmartCrusher，源码走基于 AST 的 CodeCompressor，自然语言走 Kompress-v2-base（模型卡开源在 Hugging Face）。不同内容用不同刀法，这比一把通用压缩模型硬怼合理。
CacheAligner 专门标记那些会打爆 provider KV-cache 前缀的易变内容。它从不改写 prompt 本身。这点很关键：prompt 前缀一变，缓存全失效，省下的 token 又从缓存计费上赔回去了。
CCR 是可逆机制的兜底。原文缓存在本地，模型发现信息不够时，调用 headroom_retrieve 取回完整文本。所以”压掉 8 成还给同样答案”的底气，一半来自压缩，另一半来自按需取回。
两个独立价值不小的附属功能
跨 agent 记忆：Claude、Codex、Gemini、Grok 共用一个记忆存储，自动去重。同时用几个编码工具的人，光这一条就值得装。
headroom learn：分析失败的会话，把教训自动写进 CLAUDE.local.md（默认位置，已 gitignore）、CLAUDE.md、AGENTS.md、GEMINI.md 或 GROK.md。踩过的坑变成项目级规则，下次 agent 自己就绕开了。
用之前的两个提醒
输出端它也管：不只压你发过去的，模型写回来的内容同样裁剪。省得比想象中多，但也意味着你看到的回复经过了处理，介意的话要留意。
“Same answers” 是官方的说法。生产环境上之前，拿自己真实的 agent 任务跑一遍对比，尤其是强依赖日志细节和 JSON 精确字段的场景，确认 headroom_retrieve 的取回能覆盖你的用例。许可证信息 README 摘录里没写，用前自己去仓库确认。
值不值得试
如果团队已经把编码 agent 用进生产，每天吞大量日志和 JSON 工具输出，上下文成本成了真实的账单问题，这个项目值得认真评估。个人轻度使用收益有限，但 headroom wrap 一行命令的接入成本约等于零，试一下没什么损失。
76,129 颗星，这不是小众实验。快速上手照着 README 里的 Quickstart 走就行，60 秒能跑起来。