Token 节省 60% 到 95% 零侵入的压缩利器

在这篇文章讲了针对工具调用的压缩工具 content-mode：这个开源工具把 token 消耗节省了98%，

在大模型和工具调用的中间加了一层，让 AI 改用沙箱执行替代直接读文件，主要是读取文件，调用外部数据进行压缩后，再发送给LLM。

今天推荐这个奈飞的工程师开源的，更彻底、针对不同内容进行不同策略压缩的开源项目：Headroom。

定位

Headroom 是一个 LLM 上下文压缩层，在数据发往大模型之前，先压一遍，所有即将进入上下文的内容：包括工具输出、日志、RAG chunks、文件、对话历史。

而 context-mode 只覆盖工具返回的数据，Headroom 是在数据发往 LLM 之前，覆盖所有上下文，其中自然包括工具返回的部分。

三种接入方式

Headroom 提供三种接入方式。

第一种是 Library，把它当 Python 库直接调，适合开发 AI 应用的场景。

写代码调它的 compress 函数，传一段文本进去，拿到压缩后的结果。

第二种是 Proxy，最省事的方式。

启动一个本地监听 8787 端口的代理服务，再让 Claude Code 把请求发到这个端口。

代理收到请求后，把里面的工具输出、文件内容、日志全部压缩一遍，再转发给真正的大模型。

整个过程对 Claude Code 来说完全透明。

第三种是 MCP Server，作为 MCP 服务接入。

如果你用的是支持 MCP 的客户端，比如 Claude Desktop，可以直接把它当一个 MCP 工具挂上去。

三阶段压缩

Headroom 的压缩实现分为三阶段。

第一阶段：CacheAligner。

这一阶段稳定前缀。

大模型厂商都有缓存机制，对话的内容如果命中缓存，后面的请求会快很多、而且便宜。

但如果因为压缩，导致已经缓存的内容改了，缓存就失效了，反而更慢更贵。

所以只压缩所谓的 live zone，也就是最新一轮用户消息里的内容，历史消息冻结不动。

第二阶段：ContentRouter 加压缩器。

ContentRouter 检测内容类型，然后路由到对应的压缩器。

Headroom 按类型分派，针对性压缩，这是它和其他压缩工具的主要区别。

JSON 数组走 SmartCrusher，做统计采样。

保留头部约 30% 的样本作为 schema 参考，尾部约 15% 保证最近性，中间 55% 按重要性采样，所有 error 和 warning 无条件保留。

一段 100 条日志的 JSON，原本 3163 tokens，压完 297 tokens，省 90.6%。

代码走 CodeCompressor，用 tree-sitter 解析语法树。

识别出哪些是注释、哪些是空白、哪些是重复的样板代码，针对性地压缩。

支持 Python、JS、Go、Rust、Java、C++ 六种语言，默认不开，需要显式开启。

纯文本走 Kompress-base，这是一个 274 MB 的 ONNX 模型，托管在 HuggingFace，专门在 agent 轨迹上训练过。

它用模型判断哪些是冗余的、哪些必须保留，不是简单的正则截断。

另外还有 Search Compressor、Tabular Compressor、Log Compressor、Diff Compressor、HTML Compressor，每种内容类型都有专门的压缩路径。

第二阶段是管道的性能瓶颈，占 91% 到 98% 的开销，P50 约 12 毫秒，P90 约 259 毫秒。

第三阶段：Context Manager。

用 Rolling Window 或 Intelligent Context 做上下文拟合。

Intelligent Context 会给每条消息打六维评分，按重要性排序，超窗口的就丢弃。

被丢弃的消息存入 CCR 缓存。

CCR，可逆压缩

CCR 全称 Compress-Cache-Retrieve，是 reversible compression，可逆压缩。

因为Headroom 的压缩算法本身是有损的。

SmartCrusher 的统计采样丢了大部分中间数据，CodeCompressor 砍了注释和空白，Kompress-base 的模型压缩更是不可逆。

所以需要一个兜底机制，在万一需要还原的情况下，还能找出原文。

第一步：压缩并缓存。

工具输出被压缩前，原始内容先存进本地 SQLite 数据库，路径在 ~/.headroom/ccr_store.db。

压缩版生成一个 hash 标识，然后带着这个 hash 发给 LLM。

第二步：注入检索工具。

Headroom 给 LLM 暴露一个 headroom_retrieve 工具。

LLM 拿到压缩版之后，如果发现信息不够用，可以主动调这个工具，传 hash 进去，取回原始未压缩内容。

第三步：Response Handler 拦截。

LLM 如果调了 retrieve，Headroom 的代理层会拦截这个调用，从本地缓存里取原始数据，塞回上下文，再让 LLM 继续。

这一步开销约 1 毫秒。

第四步：Context Tracker 主动展开。

Headroom 会跟踪哪些压缩内容被 LLM 反复引用，如果判断某段压缩内容是当前任务的焦点，会在下一轮主动展开它，省得 LLM 来回调 retrieve。

所以 Headroom 的"可逆"是双存机制，压缩版发 LLM，原始版存本地，需要时按需取回。

原始内容只在配置的 TTL 内可检索，默认 1800 秒。

CCR 还支持 BM25 query 检索，LLM 可以传一个查询，只取回原始内容的子集，避免"取回等于白压"。

压缩策略

Headroom 的压缩策略如下：

代码内容，tree-sitter 解析语法树，识别注释、空白、样板代码，针对性压缩。

日志和搜索结果，专门的 Log Compressor 和 Search Compressor，识别重复模式和冗余字段。

表格数据，包括 CSV、TSV、Markdown 表格，转成 JSON records 再压。

电子表格，xlsx 和 xls 文件，直接读取每个 sheet 逐个压缩。

代码 Diff、通用文本，也都有对应的处理路径。

HTML 压缩器，实测在 181 页 HTML 抽取基准上，压缩 94.9%，F1 分数 0.919，召回率 98.2%。

LLM 拿到的信息几乎无损，不影响任务执行。

Read Maturation，延迟压缩保护缓存

Headroom 针对大文件读取场景，专门做了延迟压缩的策略 Read Maturation，避免破坏大模型的缓存机制。

如一个 2000 行的源码文件，传统做法是会将全部内容塞进上下文。

这一大块新内容插入到消息历史中间，会把插入点之后的所有已缓存内容挤掉，缓存机制失效。

Read Maturation 的做法是"先暂存，后压缩"。

文件刚被读取时，内容先暂存在一个缓冲区，不立即塞进上下文。

如果文件在接下来几轮里不再被频繁访问（默认静默 5 轮），说明它不是当前焦点，这时才压缩注入。

如果文件被反复引用，说明它是当前任务的焦点，就保持原样。

设计原则是"no cached byte is ever mutated"，已缓存的字节永远不被修改。

该功能默认关闭，为实验性。

原因是它改变了消息时序，某些 agent harness 对消息顺序有假设，可能导致意外行为。

Output Shaper，输出也可减少

因为原作者用的是Claude Code，而且 LLM 的输出也要付费，在 Opus 级模型上，输出 token 是输入的 5 倍。

所以针对输出也作了针对型设置。

很多输出其实是浪费，"Great, let me" 这种前言、或者是重新打印刚展示的代码、又或者在读取文件这种常规步骤上的深度思考。

Headroom 提供了 Output Shaper，两种机制来设置大模型减少输出：Verbosity streering 和 Effort routing。

Verbosity steering，在 system prompt 末尾追加一条简短的"be terse, don't restate context"提示。

Effort routing，当一个 turn 只是模型在工具结果后恢复时，比如文件读取、测试通过，它把模型的 thinking effort 调低。

针对新问题和错误信息，保持全部 effort。

Effort routing 依赖 Anthropic API 特有的 output_config.effort 和 thinking.budget_tokens 字段。

这两个字段是 Claude 独有的，ChatGPT 和 Gemini 不支持，但是 Verbosity steering 仍然有效。

实测效果，A/B 对照实验，留 10% 对话不处理作为对照组。

输出 token 平均省 31.7%，置信区间 27.7% 到 35.7%。

Output Shaper 默认关闭，需要显式开启。

评测效果

前面介绍了实现机制，现在介绍如何评测 Headroom 的评测。

一、压缩性能测试

在 Apple M 系列 CPU 上，对每种内容类型跑 compress 函数，记录原始 tokens、压缩后 tokens、节省比例、延迟。

JSON 数组 100 条，3163 压到 297，省 90.6%，延迟 1 毫秒。

构建日志 200 行，2412 压到 148，省 93.9%，延迟 1 毫秒。

设置 “grep 结果”和 “Python 源码” 0% 压缩。

SmartCrusher 只压 JSON 数组，代码默认透传以保正确性，不硬压。

二、准确性测试

四个标准基准测试。

GSM8K 数学题，100 题，baseline 准确率 0.870，Headroom 后 0.870，delta ±0.000。

TruthfulQA 事实题，100 题，baseline 0.530，Headroom 后 0.560，反而高了 0.030。

SQuAD v2 阅读理解，100 题，准确率 97%，压缩 19%。

BFCL 工具调用，100 题，准确率 97%，压缩 32%。

JSON 压缩的测试：100 条生产日志，第 67 条是关键错误。

任务是从日志里找出错误、错误码、解决方案、影响数量。

Baseline 用 10144 tokens，4 题答对 4 题。

Headroom 压到 1260 tokens，4 题还是答对 4 题。

省 87.6%，准确率不变。

原因是 SmartCrusher 把所有 error 无条件保留了。

三、延迟和收益

12 个场景测试，11 个净收益为正。

以 Claude Sonnet 定价 3 美元每百万 tokens 算。

100 条搜索结果，压缩耗时 189 毫秒，LLM 节省 261 毫秒，净收益正 72 毫秒，每千次请求省 26 美元。

1000 条搜索结果，压缩耗时 2012 毫秒，LLM 节省 2969 毫秒，净收益正 957 毫秒，每千次省 297 美元。

压缩增加延迟成本，但测试结果显示：总时间是赚的。

四、生产测试

来自 250 多个 Headroom proxy 实例，5 万多个会话，时间跨度 2026 年 3 月到 4 月。

代理开销中位数 52 毫秒，P90 309 毫秒，P99 4172 毫秒。

中位数压缩率只有 4.8%，原因是很多请求是短对话，无压缩必要。

重度工具使用场景，比如文件读取、shell 输出，压缩率能到 40% 到 80%。

整个集群累计节省 14 亿 tokens，按 Claude 的收费标准，约合 4000 美元。

从项目形态看，Headroom 是一个依赖库，更合适有自己的代码或应用，把它集成进去。

想作为技能使用也不是不行，比如创建一个 Skill ，调 headroom compress，或者启动 headroom proxy 作为后端服务。

context-mode 是一个技能，核心形态是 Claude Code 的 /plugin 安装，或 MCP Server 接入。

它的设计假设是直接挂载到 AI 编程智能体上，作为智能体能力的一部分。

安装

Headroom 的安装只需一行命令：

pip install headroom-ai

如果要全功能，加 all 标签：

pip install headroom-ai[all]

启动命令：

headroom proxy 端口、后端、区域参数

设置 Claude Code 的 ANTHROPIC_BASE_URL 指向这个本地端口。

附带的 CLI 工具。

headroom audit-reads：告诉你哪些文件被反复读、哪些读完后立刻被压缩掉造成浪费。

headroom learn：挖掘历史会话，推荐适合你的输出 verbosity 级别。

headroom output-savings：统计省了多少 output token。

headroom perf：看整体节省情况。

提醒

当然，项目也不是十全十美。

一、压缩率 60% 到 95% 是最佳场景数字，实测混合场景在 20% 到 50%，生产实测的中位数大约 4.8%。

二、Context Tracker 的主动展开功能可能增加 token 消耗，因为它会主动把压缩内容展开塞回上下文。

如果发现 token 不降反升，可以关掉这个功能。

三、ContentRouter 是管道的性能瓶颈，P99 延迟 4172 毫秒。

大部分场景是亚毫秒到几十毫秒，但极端情况会卡 4 秒。

你会试试在自己项目中使用它吗？

欢迎评论区留言

附录：

Headroom Proxy 模式启动命令示例。

# 终端 1：启动代理
headroom proxy --port 8787 --backend litellm-vertex_ai --region global --code-aware

# 终端 2：让 Claude Code 走代理
export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
export ANTHROPIC_MODEL=claude-sonnet-4-6
claude -p "你的任务"

context-mode 安装命令（Claude Code 用户）。

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Headroom CLI 工具速查。

• • headroom audit-reads：分析 Read 机会和浪费
• • headroom learn --verbosity：推荐输出 verbosity 级别
• • headroom output-savings：统计输出节省
• • headroom perf：查看整体节省情况
• • headroom init codex：初始化 Codex hooks 集成

项目地址：https://github.com/chopratejas/headroom

推荐地址：

吴恩达的开源智能体框架，一个接口接入所有大模型

我去！Codex 官方宣布支持第三方模型｜附接入完整指南

107 分钟的会议录音，免费转文字+自动标注说话人

Loop Engineering 如何使用AI编程智能体：构建可循环系统

Claude Fable 5 系统提示词曝光：Anthropic 为适应最强大模型做了哪些改动？

推理模型新成员：MAI-Thinking-1

比 Superpowers 更贴近AI编程工程实践的51 个 Agent 和 35 个技能

Claude Code 最佳实践：一个开发者的完整修炼手册

装了300个Skill，AI 智能体怎么知道该用哪个？

Mac上双开Codex

MemPrivacy：面向端云智能体的隐私保护个性化记忆管理框架

Anthropic 百万行代码库的官方最佳实践

jcode 深度解析：纯 Rust 打造，它凭什么号称「最强 Coding Agent」？

没人整理过的 DeepSeek 进化史：25篇论文里的技术蜕变