AI 编程工具 token 越来越不够用？这个本地压缩层让我把账单省了 20%——Headroom 实测

你有没有这种感觉：AI 编程工具跑着跑着，token 消耗就开始失控——上下文窗口越来越长，账单越来越厚，但输出质量并没有明显提升？

这不是你的错觉。AI 编程工具天生就是一个「token 黑洞」：每次工具调用返回的日志、每个 RAG 检索回来的段落、每段对话历史，全都要塞进上下文窗口。模型越大、对话越久，消耗越凶。

我最近发现了一个开源工具叫 Headroom，它做的事情很简单——在内容进入 LLM 之前，先给它「瘦个身」。

它是怎么工作的？

Headroom 是一个本地运行的上下文压缩层，夹在你的 AI 编程工具和 LLM provider 之间。架构大概是这样的：

你的 Agent（Claude Code / Cursor / Codex...）
    ↓ prompts · tool outputs · logs · RAG results
┌─────────────────────────────────────────┐
│         Headroom（本地运行）             │
│  ContentRouter → SmartCrusher/CodeCompressor/Kompress-v2 │
└─────────────────────────────────────────┘
    ↓ 压缩后的 prompt
LLM Provider

它内置了三种压缩器：

• SmartCrusher：压缩 JSON 数据，60-95% token 减少
• CodeCompressor：基于 AST 的代码压缩
• Kompress-v2-base：HuggingFace 上的文本压缩模型，通用场景 15-20% token 减少

实测效果怎么样？

官方给了一个 live demo：原始 10,144 tokens 压缩到 1,260 tokens，LLM 仍然找到了同样的 FATAL 错误。换句话说——压缩后的上下文仍然能回答对的问题。

对于代码场景，官方说能减少 15-20% tokens。对于 JSON 这类结构化数据，减少幅度更大，能到 60-95%。

安装和使用有多简单？

# 一行命令安装
uv tool install --python 3.13 "headroom-ai[all]"

# 直接包装你的编程工具
headroom wrap claude   # Claude Code
headroom wrap cursor   # Cursor
headroom wrap codex    # Codex

# 或者当 MCP server 用
headroom_compress   # 压缩工具
headroom_retrieve   # 解压工具

它还支持 headroom learn——从失败的 session 里学习，自动写纠正到 CLAUDE.local.md，下次不再犯同样的错。

还有几个细节值得说：

1. CacheAligner：它会检测那些「可能让 provider KV cache 前缀失效」的内容，避免因为 cache miss 白白多花 token
2. CCR（可逆压缩）：原始内容会缓存到本地，如果模型需要可以随时调回来，不是「有损压缩」
3. 跨 Agent 记忆：Claude、Codex、Gemini、Grok 之间可以共享压缩后的上下文，避免重复读相同内容
4. Output token reduction：不只压缩输入，还压缩模型的输出——会去掉那些重复说过的代码、跳过长任务里不重要的「thinking」

我的判断：值得先用起来

对于长期跑大项目的团队来说，token 成本是一个真实的问题。Headroom 的核心价值在于它不需要你改任何代码——就是一个本地 proxy，零侵入，undo 也只要一行命令。

现在还处于早期阶段，压缩模型 Kompress-v2-base 只有 1B 参数，如果你的上下文窗口已经非常大了，压缩质量可能会有损失。但作为第一版，这个思路和效果已经值得认真测试了。

下一步： 如果你在用 Claude Code 或者 Cursor，可以跑一遍 headroom wrap claude 试两周，看看账单有没有变化。GitHub 上有 500+ stars，今天刚更新，值得关注。