Headroom 实测：给 AI Agent 的上下文做压缩，Token 省了 90%

Headroom 实测：给 AI Agent 的上下文做压缩，Token 省了 90%

直接上一组实测数据。用 Claude Code 跑一个中型项目的代码搜索，100 条结果一股脑塞进 prompt，总共 17765 个 token。换上 Headroom 压缩一下，只用了 1408 个 token。结果呢？目标函数找对了，修改建议也给得正确。省了 92% 的 token，账单直接砍到零头。

问题出在哪

AI coding agent 这两年进步确实快，但有一个顽疾始终没解决——上下文太臃肿了。

一次 grep 搜索命中 100 个文件，大部分是噪音；一次 git log 输出几千行，真正有用的就那么几条；一次数据库查询返回 50 行 JSON，关键时刻用到的字段可能只有 3 个。

这些东西全部原封不动塞进 prompt，模型照单全收，按 token 计费。Claude 3.5 Sonnet 的价格是 3 美元/百万 token，GPT-4o 是 2.5 美元/百万 token。一个 SRE 排障会话，光日志就能吃掉 65000 个 token——这还没算模型思考和回复的消耗。

之前的解决思路无非三种：

1. 截断——只取前 N 行，但关键信息可能恰好就在第 N+1 行。
2. 摘要——用另一个 LLM 先总结，但会引入 500ms 左右的延迟，而且总结本身就是有损的。
3. 加大上下文窗口——Gemini 直接给到 100 万 token，但问题不是能不能装下，而是钱&包能不能扛住。

Headroom 的思路另辟蹊径：先把上下文压缩，原件保留不动，模型觉得不够用再自己去取。

Headroom 是什么

一个开源的上下文压缩层，跑在本地，插在 agent 和 LLM 之间。GitHub 上已经超过 10k star，单周涨了 6000 多，热度很高。

核心流程大致如下：

你的 Agent（Claude Code / Cursor / Codex / 自研代码）
│
│ 工具输出、日志、文件内容、RAG 结果
▼
┌──────────────────────────────────────────┐
│ Headroom（本地运行，数据不出机器） │
│ │
│ CacheAligner → ContentRouter → 压缩器 │
│ ├─ SmartCrusher (JSON) │
│ ├─ CodeCompressor (AST) │
│ └─ Kompress-base (文本) │
│ │
│ CCR 存原件·跨 agent 记忆·MCP │
└──────────────────────────────────────────┘
│
│ 压缩后的 prompt + retrieve 工具
▼
LLM 提供商（Anthropic / OpenAI / Bedrock）

使用方式有三种：最简单的袋里模式（headroom proxy --port 8787，零代码改动），库模式（直接调用 compress(messages)），或者用一行命令包裹 agent（headroom wrap claude）。

压缩原理拆解

Headroom 不是简单粗暴地砍字数。它有三个专门的压缩器，由 ContentRouter 根据内容类型自动分发。

SmartCrusher：处理 JSON

agent 调用工具拿到的返回值通常是 JSON。比如一个 API 响应可能有几十条记录，每条都带着相同的 key 名：

[{"id": 1, "name": "Alice", "email": "alice@example.com", "role": "admin", "created_at": "2026-01-15", "last_login": "2026-06-03", "status": "active", "department": "engineering"},
{"id": 2, "name": "Bob", "email": "bob@example.com", "role": "user", "created_at": "2026-02-20", "last_login": "2026-06-01", "status": "active", "department": "marketing"},
{"id": 3, "name": "Carol", "email": "carol@example.com", "role": "admin", "created_at": "2026-03-10", "last_login": "2026-05-28", "status": "inactive", "department": "engineering"}]

50 条这样的记录，每个 key 名重复 50 次，冗余触目惊心。SmartCrusher 检测到数组加字典的结构后，把重复的 key 抽出来做成表头，值按行排列，类似于 JSON 转 CSV。但它更聪明——嵌套对象会递归处理，混合类型也能兼容。

CodeCompressor：处理代码

利用 tree-sitter 做 AST 解析，识别代码结构后，保留函数签名、类定义和关键注释，砍掉函数体里的具体实现。模型在做代码搜索时，大多数情况下只需要知道“这个函数接收什么参数、返回什么类型”，并不需要逐行读实现细节。

tree-sitter 需要下载二进制包，大约 50MB，目前支持 Python、Ja vaScript、Go、Rust、Ja va、C++ 六种语言。

Kompress-base：处理自然语言

这是 Headroom 自己训练的一个 HuggingFace 模型，专门针对 agent 交互场景的文本做压缩。训练数据来自大量真实的 agent trace（工具调用日志、对话历史、文档片段）。

与通用摘要模型的最大区别在于：Kompress-base 知道哪些信息对 agent 后续决策有用。比如错误日志里的堆栈信息会被保留，而重复的时间戳和进程 ID 则会被压缩掉。

CCR：压缩可逆

这是 Headroom 最关键的设计。CCR（Compressed Context with Retrieval）不会删除原始数据，而是将其存在本地的 LRU 缓存里。压缩后的 prompt 中附带一个 headroom_retrieve 工具——如果模型发现压缩版信息不够用，可以调用这个工具拿回原始内容。

作者在 Hacker News 上解释过这个设计思路：把“压缩”和“可检索”结合起来，既保留了信息的完整性，又大幅减少了每次调用时的 token 消耗。和截断相比，数据没有丢失；和摘要相比，不需要额外的 LLM 调用；和加大上下文窗口相比，token 确实省下来了。

实际跑一下

安装非常简单：

pip install "headroom-ai[all]"

方式一：袋里模式

最省事，无需修改现有代码。Headroom 启动一个 HTTP 袋里，拦截发往 LLM 的请求，对 context 做压缩后再转发。

headroom proxy --port 8787

然后把 agent 的 API endpoint 指向 http://localhost:8787，所有兼容 OpenAI 接口的客户端都能用。

方式二：wrap 模式

一行命令包裹现有的 coding agent：

headroom wrap claude # Claude Code
headroom wrap codex # Codex
headroom wrap cursor # Cursor（会打印一段配置，粘贴即可）
headroom wrap aider # 启动袋里 + 启动 aider

方式三：库调用

Python 里直接调用：

from headroom import compress

messages = [
{"role": "user", "content": "分析这段日志..."},
{"role": "assistant", "content": "...（长日志内容）..."}
]

compressed = compress(messages, model="claude-sonnet-4-20250514")
# compressed 可以直接传给 Anthropic SDK

TypeScript 也有对应的包：

import { compress } from 'headroom-ai';
const compressed = await compress(messages, { model: 'claude-sonnet-4-20250514' });

方式四：框架集成

主流的框架都有现成适配：

# Anthropic SDK
from headroom import withHeadroom
client = withHeadroom(Anthropic())

# LangChain
from headroom.integrations import HeadroomChatModel
model = HeadroomChatModel(your_llm)

# LiteLLM
import litellm
from headroom.integrations import HeadroomCallback
litellm.callbacks = [HeadroomCallback()]

CacheAligner：被忽视的细节

除了压缩，Headroom 还额外做了一件事：稳定 prompt 前缀。

Anthropic 和 OpenAI 的 API 都有 KV cache 机制——如果两次请求的 prompt 前缀相同，第二次可以复用缓存，速度更快，成本也更低（Anthropic 的 cache hit 价格只有普通输入的 10%）。

但在实际使用中，agent 每次调用工具后返回的内容会略有变化（时间戳不同、字段顺序不同），导致前缀频繁变化，cache 命中率很低。

CacheAligner 会把 prompt 中不变的部分（系统提示、历史对话）和变化的部分（工具输出）分开处理，确保不变部分的 token 序列保持稳定。这样一来，KV cache 的命中率会高很多。

这个优化是免费的，压缩的时候顺带就完成了。

Benchmark 数据

官方给出的测试数据（可自行复现，运行 python -m headroom.evals suite --tier 1）：

压缩率方面：

场景	原始 token	压缩后	节省
代码搜索（100 条结果）	17,765	1,408	92%
SRE 事故排查	65,694	5,118	92%
GitHub Issue 分类	54,174	14,761	73%
代码库浏览	78,502	41,254	47%

准确率方面，几乎不受影响：

基准测试	类型	无压缩	有压缩	差异
GSM8K	数学	0.870	0.870	0
TruthfulQA	事实	0.530	0.560	+0.03
SQuAD v2	问答	—	97%	压缩 19%
BFCL	工具调用	—	97%	压缩 32%

代码搜索和 SRE 排障场景的压缩率最高，因为这两类输出的冗余特别严重——大量重复的文件路径、相似的日志格式。代码库浏览的压缩率相对低一些，因为代码本身的信息密度比较高。

TruthfulQA 的分数反而提高了 0.03。一个可能的解释：压缩去掉了无关信息后，模型的注意力分配更集中了。

踩坑和局限

试用下来有几个问题值得注意：

CodeCompressor 依赖 tree-sitter，安装时需要编译原生模块。在 M1 Mac 上没问题，但在某些 CI 环境里可能需要手动安装编译工具链。如果使用 [ml] extra 安装 Kompress-base 模型，首次启动还会因为下载模型而比较慢。如果只需要 JSON 压缩和袋里功能，可以用最小安装 pip install headroom-ai[proxy]，跳过 tree-sitter 和模型下载。

原始数据存在内存的 LRU 缓存里。长时间运行的 agent 会话，缓存可能会涨到几百 MB。可以通过配置限制缓存大小，但设太小了模型检索时可能找不到原文。作者建议的做法是设置合理的 TTL（生存时间），让过期的工具输出自动清理。

47% 的压缩率对比其他场景差了不少。代码的信息密度高，AST 压缩只能去掉函数体，如果 agent 需要的恰好是函数实现的细节，压缩反而会触发额外的 retrieve 调用。对于需要深度阅读代码的场景（代码审查、重构），建议关闭 CodeCompressor 或调低压缩强度。

官方表示支持 40-90% 的图片 token 缩减，但这个功能比较新，文档还不够完善。如果 agent 大量使用视觉能力，建议先在非生产环境试一下。

跟其他方案对比

市面上做类似事情的工具不算多：

• RTK
  ：只压缩 CLI 命令输出（git show、ls 这类），范围较窄。Headroom 内部实际集成了 RTK 作为 shell 输出的预处理。

• lean-ctx
  ：CLI + MCP 工具的上下文精简，跟 RTK 类似，但覆盖面更广一点。

• Compresr / Token Co.
  ：云端压缩 API。数据要传到第三方服务器，不适合隐私敏感的场景。

• OpenAI Compaction
  ：OpenAI 内置的对话历史压缩，只对自家 API 有效，且不可逆。

Headroom 的优势集中在两点：全品类覆盖（JSON、代码、文本、图片都能压缩），以及压缩可逆（原件还在本地，随时可取）。劣势是本地部署，依赖相对较重。

适合谁用

值得一试的场景：

• 每天大量使用 AI coding agent，token 账单是笔不小的开销
• 同时使用多个 agent（Claude Code + Cursor + Codex），需要跨 agent 共享记忆
• SRE/DevOps 场景，agent 需要处理大量日志
• RAG 应用，检索结果的冗余度比较高

不太适合的场景：

• 只用一家 provider，上下文窗口足够大，也不在乎成本
• 沙盒环境跑不了本地进程
• agent 调用频率很低，压缩带来的收益不明显

小结

Headroom 解决的问题非常实际：AI agent 的上下文太臃肿，浪费 token，浪费钱。三个压缩器分别处理 JSON、代码、文本，CCR 机制保证压缩可逆，CacheAligner 顺手优化了 KV cache 的命中率。

从 benchmark 来看，代码搜索和日志分析场景能省 90% 以上的 token，而准确率几乎没有损失。实际使用中，袋里模式是最省事的——一行命令就能套到现有 agent 上，几乎零成本接入。

项目地址：github.com/chopratejas/headroom，Apache 2.0 开源协议，PyPI 和 npm 都有包可以直接安装。