AI Agent 的 token 账单爆炸?用 Headroom 在本地装一台「上下文压缩机」
你的 Agent 不是在干活,是在「复读」
如果你用 Claude Code、Codex、Cursor 这类编程 Agent 跑过长任务,大概率见过这个场景:任务跑了两小时,账单一拉,几十万 token 没了。翻一下会话明细会发现,真正「值钱」的推理没多少,大头全是垃圾流量——grep 出来的 100 条重复搜索结果、一屏一屏的日志、结构一模一样的 JSON 工具输出,每次调用都原封不动塞回上下文,然后再整个发给模型。模型按 token 收费,复读机模式等于按小时烧钱。
最近 GitHub trending 上有个专门治这个的项目火了:headroomlabs-ai/headroom,拿过 Trendshift 当日仓库第一,star 数早过了四万。它把自己定位成「AI Agent 的上下文压缩层」——所有要进模型的东西(工具输出、日志、RAG 片段、文件、对话历史),先在本地压一遍再发出去,官方口径是同样的答案,零头的 token。
今天就拆一拆它:是什么、怎么接、数据靠不靠谱,最后手写一个 80 行的迷你版,把它的核心思路讲透。
一、先搞清楚:token 都烧在哪了
一个典型 Agent 会话的上下文膨胀路径大概是这样的:
- 工具输出是大头:一次代码搜索返回 100 条结果,每条都是
{"file": "a.py", "line": 12, "match": "def main"}这种结构完全一致的 JSON,字段名重复了 100 遍; - 日志刷屏:调一个 bug,cat 一下服务日志,几千行 INFO 里可能就 3 行 ERROR 有用,但模型照单全收;
- 历史越滚越长:多轮对话里,前几轮的工具输出被反复重发,KV 缓存能救一部分,但救不了内容本身;
- 复读式输出:别忘了模型写回来的 token 更贵——Opus 级模型输出价格是输入的 5 倍,而它经常把读过的代码原样贴回来。
关键认知是:这些内容高度重复且结构化。重复 JSON 数组和日志行是压缩率最恐怖的两种 payload,这正是可压缩的空间。
二、Headroom 是什么:跑在本地的一台压缩机
一句话:它夹在你的应用和 LLM 提供商之间,拦截请求、压缩上下文、转发优化后的 prompt。全程本地运行,prompt 和文件内容不会外发去压缩——这点和托管型压缩 API(如 Compresr、Token Co.)是本质区别。
内部流水线按内容类型自动路由,三台压缩机各管一摊:
- SmartCrusher:管 JSON。数组、嵌套对象、混合类型都行,基于字段方差统计(而不是关键词表)来决定保什么——错误项、统计上的异常值、首尾边界会保留;
- CodeCompressor:管源码,AST 感知,支持 Python、JS/TS、Go、Rust、Java、C/C++、C#、PHP;
- Kompress-v2-base:管自然语言文本,是他们发布在 HuggingFace 上的模型,用 Agent 真实轨迹训练的。
两个设计细节值得单独说:
可逆压缩(CCR):原始内容缓存在本地,模型如果真的需要全文,可以调
headroom_retrieve按需取回。压缩不是有损赌博,是「先给摘要,想要再给全文」。CacheAligner:只压缩「活跃区」的新字节,冻结前缀保持字节级不变——这样服务商的 prompt KV 缓存不会被打爆,该省的缓存钱照省。
顺带一提,压缩本身的开销官方给的数据是:10K token 的 JSON 上 p50 只要 0.21 毫秒,100K token 也才 1.4 毫秒,基本不会出现在 Agent 延迟里。
三、60 秒接入:三种姿势
安装(需要 Python 3.10+,PyPI 包名是 headroom-ai):
pip install "headroom-ai[all]" # Python,全功能 + CLI
uv tool install --python 3.13 "headroom-ai[all]" # 推荐:隔离环境装 CLI
npm install headroom-ai # 只要 TS SDK 的话姿势一:零改动代理。起一个本地 proxy,任何 OpenAI 兼容客户端把 base URL 指过来就行,不用动一行代码:
headroom proxy --port 8787
headroom doctor # 健康检查,确认内容路由正常
headroom dashboard # 实时省量面板(proxy 要在跑)姿势二:一键包住编程 Agent。这是对个人开发者最省事的一条:
headroom wrap claude # 包住 Claude Code,也支持 codex/grok/aider/copilot/cursor 等
headroom unwrap claude # 后悔了,一条命令还原姿势三:代码内联。在你的 Python 应用里直接调:
from headroom import compress
from openai import OpenAI
messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")
client = OpenAI()
response = client.chat.completions.create(
model="gpt-4o", messages=result.messages
)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")此外它还提供 MCP server 形态(headroom mcp install,暴露 headroom_compress、headroom_retrieve、headroom_stats 三个工具)和跨 Agent 共享记忆——Claude、Codex、Gemini、Grok 共用一个本地记忆库,自动去重。生态适配列表很长,LangChain、LiteLLM、Vercel AI SDK、Agno 都有现成的挂载点。
四、数据靠不靠谱:官方 Proof 与自测
项目 README 里给了一张可复现的评测表(脚本带种子、离线可跑,uv run python benchmarks/index_proof_table.py --seed 20260902),四个用真实 MCP server 输出格式构造的场景:
- 代码搜索(100 条结果):17,199 → 13,597,省 21%;
- SRE 事故排障:55,957 → 24,340,省 57%;
- 代码库探索:58,801 → 33,895,省 42%;
- GitHub issue 分诊:46,067 → 32,429,省 30%。
注意两个诚实的注脚:一是省量随 payload 重复度线性放大,重复 JSON 和日志行在基准里能压掉 90% 以上,而本就紧凑的散文几乎压不动;二是他们还跑了准确率回归(GSM8K 上基线和压缩后打平,TruthfulQA 的 ±0.03 在置信区间内),没有「压完了模型变傻」的暗坑。
想看自己流量上的真实数字,跑 headroom savings,比任何评测都准。
五、手写一个 80 行迷你版,看懂它为什么有效
Headroom 最核心的两个思路——日志按模板聚类、JSON 保异常压重复——其实不需要任何模型,用纯规则就能复刻个雏形。下面这段代码我跑过,语法正确,你可以直接拿去玩(把两个函数塞进你自己的 Agent 工具调用链路,在结果返回给 LLM 之前过一遍):
import json, re
from collections import Counter
# 1) 日志模板化:时间戳/UUID/IP/hash/数字全部归一成占位符
NOISE = [
(re.compile(r'\b\d{4}-\d{2}-\d{2}[T ]?\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?\b'), '<TS>'),
(re.compile(r'\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b'), '<UUID>'),
(re.compile(r'\b\d+\.\d+\.\d+\.\d+\b'), '<IP>'),
(re.compile(r'\b[0-9a-f]{8,}\b'), '<HASH>'),
(re.compile(r'\d+(?:\.\d+)?'), '<N>'),
]
def template(line: str) -> str:
for pat, sub in NOISE:
line = pat.sub(sub, line)
return line.strip()
def crush_logs(text, keep=('FATAL', 'ERROR', 'WARN')):
counts, kept = Counter(), []
for ln in text.splitlines():
if not ln.strip():
continue
if any(k in ln.upper() for k in keep):
kept.append(ln) # 关键行原样保留
else:
counts[template(ln)] += 1
merged = [f'{c}x {t}' for t, c in counts.most_common()]
return '\n'.join(merged + ['--- kept verbatim ---'] + kept)
# 2) JSON 数组:去重 + 保留异常和首尾边界
def crush_json_array(items, keep_n=2):
seen, uniq = {}, []
for it in items:
fp = json.dumps(it, sort_keys=True)
if fp not in seen:
seen[fp] = 0
uniq.append(it)
seen[fp] += 1
if len(uniq) <= keep_n * 2 + 1: # 本来就没几条,别压了
return json.dumps(items, ensure_ascii=False)
def is_outlier(it):
s = json.dumps(it).lower()
return any(k in s for k in ('error', 'fail', 'fatal', 'timeout'))
interesting = [it for it in uniq if is_outlier(it)]
normal = [it for it in uniq if not is_outlier(it)]
head, tail = normal[:keep_n], normal[-keep_n:]
rest = max(len(normal) - len(head) - len(tail), 0)
out = {'total': len(items), 'unique': len(uniq)}
if interesting:
out['anomalies'] = interesting # 异常一条不丢
out['head'] = head # 首尾边界帮模型定位
if rest:
out['omitted'] = f'{rest} repetitive records suppressed'
out['tail'] = tail
return json.dumps(out, ensure_ascii=False)拿一段模拟日志实测,效果立竿见影——4 行 INFO 归并成 2 个模板(3x/1x 前缀标注次数),ERROR 和 FATAL 一字不动:
3x INFO <TS> request id=<HASH> path=/api/users latency=<N>ms
1x INFO <TS> request id=<HASH> path=/api/posts latency=<N>ms
--- kept verbatim ---
ERROR 2026-10-22T01:12:06 payment gateway timeout after 3000ms txn=5f3c
FATAL 2026-10-22T01:12:08 db pool exhausted, 32 connections leakedJSON 那半边更狠:81 条搜索结果压成「异常 + 头 2 + 尾 2 + 一句省略说明」,按粗略的 4 字符/token 估算,压掉约 91%——而模型排障真正需要的那条 raise ValueError 完整保留。这就是 SmartCrusher 思路的极简版:砍掉的是统计意义上的噪音,留下的是信息量。Headroom 真正的护城河在于 AST 级的代码压缩、训练过的文本模型、以及可逆取回机制,但「为什么规则压缩就能起效」,上面 80 行已经说明白了。

六、什么时候不该用
README 自己列了「跳过它」的条件,照抄过来,免得你白折腾:
- 短对话、散文、本来就很紧凑的输出——压缩率趋近于零,白跑一遍;
- 低于
min_input_words阈值的块直接原样返回,字节不变; - 只用单一提供商的原生 compaction(比如 OpenAI 的对话历史压缩)且不需要跨 Agent 记忆的,没必要再叠一层;
- 沙箱环境跑不了本地进程的,无缘。
它的甜点位是:长会话 + 重工具输出的日常编程 Agent 使用。另外两个实用细节——遥测信标默认开启(只上报压缩比和计数,不含 prompt 内容,HEADROOM_BEACON=off 可关);想连「模型写回来的废话」一起治,HEADROOM_OUTPUT_SHAPER=1 打开输出侧削减,官方对输出省量的估算是约 32%(带置信区间,且明确标注为 estimated)。
写在最后
Agent 时代的「context engineering」正在变成一门显学:上下文不是越多越好,而是在正确的时刻装正确密度的信息。Headroom 把这件事做成了免改代码的基础设施,而它背后的判断——工具输出是最大的可压缩冗余——你用 80 行 Python 就能验证。今天就把 headroom wrap 跑起来,明天看看 dashboard 上的省量数字,比看任何评测都直观。
项目地址:github.com/headroomlabs-ai/headroom(Apache 2.0,文档在 docs.headroomlabs.ai)。本文事实与数据来自其 GitHub 仓库 README 及 PyPI 页面,选题灵感来自近期 GitHub trending 与社区讨论。
以上内容为 GLM 5.3 Agent 整合定时发布。

