Headroom：让 LLM Agent 的 Token 消耗直接砍掉 60%-95%

发表于 分类于 ，
Headroom 跑在应用和 LLM 之间的"上下文压缩层"，6 种压缩器识别 JSON/AST/代码/日志，code search 砍 92%，SRE 日志砍 92%，答案不变、可逆回溯、本地优先。

Headroom：让 LLM Agent 的 Token 消耗直接砍掉 60%-95%

一、一个问题：你的 Agent 账单还好吗？

如果你正在用 Claude Code、Cursor、Codex 或者自己搭的 LangGraph / Agno 跑 AI Agent，账单曲线大概是这样的 —— 上线第一天觉得真便宜，运行一周后看到 Anthropic 或 OpenAI 的消费提醒开始沉默，运行一个月后开始认真思考” 是不是该把 RAG 召回的 chunk 数量从 20 砍到 5”。

这不是错觉。一次真实的 Agent 对话经常吃掉 100K+ token，而其中绝大多数都是重复的、冗余的、对最终答案毫无贡献的” 上下文噪音”：tool 返回的巨大 JSON、长串 stack trace、RAG 检索回来的整段文档、文件读取后的源码…… 这些内容塞进上下文窗口，模型要付钱，我们要付钱，但模型其实只需要其中一小段就能给出正确答案。

有没有办法在” 送到 LLM 之前” 就把这些噪音挤掉？Headroom 就是干这个的 —— 今天 GitHub Trending 上单日新增 4,000+ stars 的项目，本文带你把它看明白。

二、项目背景：Context Optimization Layer

Headroom（github.com/chopratejas/headroom）的定位是” 上下文优化层”（Context Optimization Layer），它跑在你的应用和 LLM 提供商之间。Agent 准备好要送给模型的 prompt、tool 输出、日志、RAG 结果、文件内容，Headroom 会先用对应的策略做压缩，再把压缩后的版本发到 Anthropic / OpenAI / Bedrock。

它的几个核心承诺：

  • 压缩率 60%–95%：在真实 Agent 工作负载上，code search 92%、SRE 事故日志 92%、GitHub issue triage 73%、代码库探索 47%。
  • 答案不变：GSM8K、TruthfulQA、SQuAD v2、BFCL 等基准上压缩前后准确率几乎无差异（GSM8K 0.870 vs 0.870）。
  • 可逆压缩：被压掉的内容不是真的丢了，模型可以通过 headroom_retrieve 工具按需拉回全文。
  • 本地优先：默认在本地运行，原始数据不出你的机器；通过 headroom learn 还能从失败会话里挖经验，自动写回 CLAUDE.md / AGENTS.md / GEMINI.md。

如果用一句话总结：它是 LLM 时代的 gzip，但能识别 JSON、AST、代码结构和自然语言，并知道哪些字节可以丢、哪些必须留。

三、核心功能：6 种压缩器 + 3 种接入方式

Headroom 的内部架构是一个三段式管道：CacheAligner → ContentRouter → CCR（Compression Content Router）。CCR 会根据内容类型把数据分发给三套压缩器之一：

  1. SmartCrusher：针对 JSON 的结构化压缩，能识别出重复键、长数组、冗余字段，把 {"a":1,"a":1,"a":1,...} 这种噪声打掉。
  2. CodeCompressor：基于 AST 的源码压缩，删掉注释、空行、无用 import，但保留语法正确性。
  3. Kompress-base：基于 Hugging Face 模型训练的通用文本压缩器，处理自然语言段落。

对用户来说，更直观的接口有三种：

  • 作为库调用：from headroom import compress，直接处理 messages 列表。
  • 作为本地代理：headroom proxy --port 8787，启动一个 OpenAI 兼容的 HTTP 端点，把 base_url 指过去就能用。
  • 作为 MCP 服务器：headroom mcp install，把 headroom_compress / headroom_retrieve / headroom_stats 三个工具挂到 Claude Desktop、Cursor 等客户端里。

另外，Headroom 还提供 headroom wrap 命令，可以一键包装 Claude Code、Codex、Cursor、Aider、Copilot CLI 等主流 Agent CLI；以及 headroom learn --verbosity，从历史会话里” 学” 你的简洁偏好，自动控制输出 token（因为 Opus 这类模型输出成本是输入的 5×）。

四、实战示例：30 秒接到 LangGraph

最省事的接入方式是用代理。下面这个例子里，我们让一个 LangGraph Agent 通过 Headroom 调用 OpenAI，统计一次真实问答的 token 消耗。

第一步：安装并启动代理

1
2
3
pip install headroom
export OPENAI_API_KEY=sk-...
headroom proxy --port 8787

启动后访问 http://localhost:8787/stats 能看到实时面板：累计请求数、节省的 token、命中率。

第二步：让 Agent 走代理

1
2
3
4
5
6
7
8
9
10
11
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

llm = ChatOpenAI(
    model="gpt-4o",
    base_url="http://localhost:8787/v1",   # 指向 Headroom
    api_key="dummy",                       # Headroom 会用环境变量里的真实 key
)

agent = create_react_agent(llm, tools=[...])
result = agent.invoke({"messages": [("user", "总结我刚发的那 50 条 GitHub issue")]})

不需要改任何业务代码 —— 所有 RAG 召回的 chunk、tool 的 JSON 返回、文件读取结果，Headroom 都会在转发到 OpenAI 之前自动压一遍。

第三步：让模型” 取回” 原文

Headroom 的关键设计是可逆。它不会把数据真删掉，而是给模型一个引用 + 一个 headroom_retrieve 工具。模型如果发现” 这里信息不够”，可以自己拉全文：

1
2
3
4
5
6
7
8
9
10
# Headroom 自动注入的 tool schema
{
  "name": "headroom_retrieve",
  "description": "按 cache_key 取回被压缩的原始内容",
  "parameters": {
    "cache_key": {"type": "string"},
    "offset":    {"type": "integer"},
    "limit":     {"type": "integer"}
  }
}

这种” 先压、要看再拉” 的模式，是它能在保留答案质量的前提下做到 90%+ 压缩率的根本原因。

第四步：观察效果

跑完一个会话后：

1
headroom stats --last 1h

典型输出：

1
2
3
input_tokens_saved: 412,338  (78.2%)
output_tokens_saved: 89,201   (measured, 0.95 CI)
top_compressor: CodeCompressor (52%), SmartCrusher (33%)

五、适用场景与限制

最值得用 Headroom 的场景：

  • 跑 Claude Code、Cursor、Codex 等长任务 Agent，账单肉眼可见地降。
  • RAG 应用召回量大、上下文窗口吃紧，需要在送进 LLM 之前做一层无损 / 近无损压缩。
  • 多 Agent 系统（Claude + Codex + 自建 agent）需要共享” 压缩记忆”——Headroom 自带跨 Agent 记忆。
  • SRE / 运维 Agent 处理长日志、stack trace、监控输出。
  • 想白嫖 Copilot CLI 订阅但希望降低上下文长度的开发者。

目前需要留意的限制：

  • macOS 上 Copilot CLI 的 keychain 鉴权已冒烟测试，Windows Credential Manager、Linux Secret Service 还在真实 OS 验证阶段。Docker / CI 场景建议显式传 GITHUB_COPILOT_TOKEN。
  • headroom learn --verbosity 节省的是” 输出 token”—— 这是反事实估计，Headroom 会明确标注 measured 还是 estimated 并给出置信区间，不会假装测过。
  • 对延迟极敏感的场景（< 50ms 首 token）需要先 benchmark，本地代理会增加几毫秒开销。
  • Reddit 社区上有开发者指出” 任何上下文压缩都不能保证得到和原文完全一样的答案”——Headroom 用 benchmark 论证” 足够接近”，但具体业务场景请自己跑回归。

六、和同类项目的差异

维度 Headroom llmlingua / LLMLingua-2 自建摘要层
触发位置 透明代理 /wrap/ MCP 库调用 业务代码内
内容识别 JSON / AST / 文本分路压缩 统一文本压缩 取决于实现
可逆性 ✅ cache + retrieve 工具 ❌ 一次性 ❌ 一次性
跨 Agent 共享记忆 ✅ ❌ ❌
接入成本 改 base_url 即可 需重写调用层 改业务代码

核心差异在于：Headroom 把” 压缩” 做成了网络协议层和 MCP 工具，而不是一个 Python 函数。这让它在不动业务代码的前提下，能同时压输入和压输出、能跨 Agent 共享压缩记忆、能在主流程里无缝介入。

七、总结

Headroom 的爆火（单日 4K+ stars）背后是一个真实痛点：Agent 的成本曲线在失控，单纯靠减小 RAG 召回数、缩短 tool 输出只是治标。它用” 内容感知 + 可逆压缩 + 透明代理” 的组合拳，给出了一个工程化、可观测、可回滚的解决方案 —— 这是和” 再写一个 LLMlingua 包装” 完全不同的产品形态。

如果你的 Agent 已经在跑、账单已经在涨，建议先花 10 分钟跑一下 headroom proxy，打开 dashboard 看一眼实际压缩率 —— 大概率你会立刻决定把它留下来。

项目地址：github.com/chopratejas/headroom
协议：Apache 2.0
趋势数据：单日 +4,005 stars，38,728 total stars