Headroom：在智能体读取的工具输出、日志和文件进入大模型之前先做本地压缩，并可按需取回原文

headroomlabs-ai/headroom 是一个用 Python 写的开源项目，采用 Apache-2.0 许可，创建于 2026 年 1 月 7 日，最近一次推送是 10 月 13 日，截至发稿约有 75,257 个星标和 5,838 个分叉。它的定位只有一句话：在智能体读到的一切内容进入大模型之前先压缩，包括工具输出、日志、检索片段、文件和对话历史，“答案不变，词元只剩一小部分”。README 还强调压缩在本机进行，没有提示或文件内容会被发到别处去压缩。它要解决的是智能体使用中很常见的一种浪费：一次搜索返回上百条结果，一段日志里同一行重复上千次，这些内容进入上下文后既占窗口，又按词元计费。 它的架构由三个环节组成。ContentRouter 先判断内容类型并选择压缩器：SmartCrusher 处理 JSON，CodeCompressor 基于语法树处理源代码，Kompress-v2-base 处理普通文本；CacheAligner 则只负责标出会破坏供应商 KV 缓存前缀的易变内容，README 说它从不改写提示。最关键的是 CCR，即可逆压缩：原文缓存在本地，模型需要完整文本时可以调用 headroom_retrieve 取回。这个设计回应了压缩最常见的担忧，信息丢了怎么办。接入也灵活：既可以在代码里调用 compress(messages)，也可以用 headroom proxy 起一个代理，不用改应用代码，或者直接 headroom wrap claude、codex、cursor、aider 等一长串编程智能体，甚至作为 MCP 服务器暴露三个工具。

项目还提供几项相关功能。其一是跨智能体的共享记忆：在 Claude、Codex、Gemini 和 Grok 之间共用一个存储并自动去重。其二是 headroom learn，它会分析失败的会话，把纠正写到 CLAUDE.local.md（默认，且不入库）、CLAUDE.md、AGENTS.md、GEMINI.md 或 GROK.md 里。其三是输出词元削减：除了压缩发出去的内容，还从代理侧削减模型写回的内容，办法是“冗长度引导”，即在系统提示末尾加一小段“请简洁，不要重复上下文”的说明，使提示缓存仍能命中；以及“推理强度路由”，当某一轮只是模型在工具结果后继续工作时，降低思考强度，而新问题和错误保持完整强度。README 提到在 Opus 级模型上输出成本是输入的 5 倍，所以这一块有实际意义。 数据方面，README 的基准用四个由真实 MCP 服务器输出格式构造、种子固定的场景：代码搜索（100 个结果）17,199 降到 13,597，节省 21%；SRE 故障排查 55,957 降到 24,340，节省 57%；代码库探索 58,801 降到 33,895，节省 42%；GitHub 议题分诊 46,067 降到 32,429，节省 30%。项目说明节省比例取决于内容的重复程度：重复的 JSON 数组和日志行在延迟基准中可超过 90%，而文章和本来就很密的输出几乎压不动。压缩耗时很短，10K 词元的 JSON 搜索结果中位数 0.21 毫秒，100K 词元为 1.4 毫秒。准确率方面，样本数 100 的 GSM8K 基线和使用后都是 0.870，TruthfulQA 从 0.530 到 0.560，项目自己指出这在置信区间内，应理解为没有检测到差异。SQuAD v2 达到 97%（压缩 19%），BFCL 达到 97%（压缩 32%）。

怎么用才稳妥？第一，所有数字都是项目自述的基准，样本也不大，应当先用 headroom savings 在自己的真实流量上看节省比例，再决定是否上线；对已经很紧凑的输出，不要期待大的收益。第二，headroom wrap 并不只是“包一层”：它会启动本地代理，并给被包装的项目安装 Serena 做语义代码导航，对 Claude Code 是在 ~/.claude.json 里登记一个本地范围的 MCP 服务器；要撤销用 headroom unwrap，若不想要可以用参数跳过。第三，原文虽然在本地缓存，但压缩过的内容才是模型看到的，调试智能体行为时要记得这一点。总体上，它是一个思路清楚、可逆、容易试的成本优化工具，适合先在测试环境里评估。 再补充几个选型时容易忽略的点。一是缓存的取舍：压缩会改变发给模型的文本，如果你的供应商按前缀缓存计费，需要确认压缩结果在多轮对话里是稳定的，否则可能省了词元却丢了缓存命中，这正是项目专门设计 CacheAligner 的原因，但效果仍应以自己的账单为准。二是可观测性：先用 headroom perf 和 headroom dashboard 看几天真实的节省数据，再决定是否把代理放进团队共用的环境。三是适用范围：它最擅长处理大段重复的结构化输出，比如搜索结果、日志和事故排查；如果你的智能体主要读短小的自然语言，收益会明显变小。把这三点想清楚，再去试，会少走很多弯路。 最后值得一提的是数据去向与可审计性。README 强调压缩在本机完成，不会把提示或文件内容送去别处，这对处理内部代码和日志的团队很重要；同时，因为可以用 headroom_stats 查看节省统计、用 headroom_retrieve 取回原文，出了问题时能追溯模型当时看到的到底是什么。把这两点和前面的基准结合起来看，Headroom 更像一个可以先小范围接入、再逐步放开的基础设施组件。