AI-Chain
AI 工具指南 Headroom AI 编码 开源

AI 编码工具都在省 token？我找到了一个「无感压缩」开源方案，省了 92%

分享:
AI 编码工具都在省 token？我找到了一个「无感压缩」开源方案，省了 92%

AI 编码工具都在省 token？我找到了一个「无感压缩」开源方案，省了 92%

背景与痛点

我最近用 Claude Code 和 Codex 写专案的时候，越来越感觉到一个问题：token 费用会随着专案规模指数成长。

不是因为我变笨了，而是因为每个工具输出、每次 API 呼叫回传的资料量都在膨胀。一个 grep 指令可能回传上千行结果，一次 git diff 可能带着几十个档案的完整差异，再加上 RAG 检索回来的 chunk、日志档案的原始内容……这些都塞进 context window 里，而 LLM 的输入端要钱。

我算过一笔帐：一个中等规模的 Python 专案，每天用 Claude Code 工作 8 小时，token 用量轻易突破 50 万。以 Claude Sonnet 的输入价格计算，一个月大概要烧掉几百美金。如果用的是 Opus，这个数字会再翻五倍。

更讨厌的是，很多内容其实「 compressible」。JSON 格式的工具输出有重复的栏位名称，AST 结构的程式码有可预测的缩排模式，日志档案有大量标准化的时间戳和等级前缀。人类可以一眼看出这些是浪费，但 LLM 看不到。

所以当我看到 Headroom 这个专案的时候，我的第一反应是：这是不是又一个「吹得很厉害但实际上没有差那么多」的东西？

看完文档和 benchmark 之后，我改变了想法。

Headroom 是什么

Headroom 是一个开源的上下文压缩层（context compression layer），专门针对 AI agent 和 LLM 应用设计。它的核心理念很直接：在资料送达 LLM 之前，把它压缩到最小，但保持资讯不失真。

专案目前 58,746 stars，Apache 2.0 授权，Python 和 TypeScript 双语言支援。由前 Anthropic 工程师建立，2026 年 1 月发布，不到半年就达到五万星，成长速度非常惊人。

Headroom 提供三种使用模式：

1. Library：直接在你的程式码里呼叫 compress()，适合嵌入你自己的应用

1. Proxy：一个本地代理伺服器，零程式码改动就能串接任何 LLM 客户端

1. MCP Server：透过 Model Context Protocol 服务任何支援 MCP 的客户端

它是怎么做的

Headroom 的核心架构有三层：

ContentRouter 是入口。它先判断资料的类型——是 JSON、程式码、日志、还是自然语言文本——然后选择对应的压缩器。

SmartCrusher 负责 JSON 资料。它能识别阵列、巢状物件、混合类型，然后移除重复的栏位名称、压缩键值对。一个包含 100 笔资料库查询结果的 JSON，压缩后可以小到只剩关键栏位和值。

CodeCompressor 处理程式码。它会解析 AST（抽象语法树），然后移除不必要的缩排、合并相似的程式码片段、压缩 import 语句。对 Python、JavaScript/TypeScript、Go、Rust 等语言都有支援。

还有一个 Kompress-v2-base 模型，这是 Headroom 自己训练的压缩模型，专门针对 agent 工作负载的文本优化。它不是简单的 tokenizer 压缩，而是理解语意的「语意压缩」——同样的意思可以用更少的 token 表达。

最后是 CacheAligner。这东西很聪明——它稳定化 prefix 部分，确保provider 的 KV cache 能命中。这意味着不仅压缩后省 token，连 cache 命中带来的速度提升和费用节省也一并拿到了。

整个流程是这样的：

你的 agent → Headroom（本地运行，资料不出机器）→ 压缩后的 prompt → LLM provider

而且压缩是可逆的（CCR — Compressed Context Retrieval）。原始资料会缓存在本地，LLM 如果需要查证某个细节，可以透过 headroom_retrieve 工具找回原始内容。

Benchmark 数据

Headroom 的 benchmark 数据很有意思。他们在真实的 agent 工作负载上测试：

  • 程式码搜寻（100 笔结果）：从 17,765 token 压缩到 1,408 token，节省 92%
  • SRE 事故除错：从 65,694 token 压缩到 5,118 token，节省 92%
  • GitHub issue 分类：从 54,174 token 压缩到 14,761 token，节省 73%
  • 程式码库探索：从 78,502 token 压缩到 41,254 token，节省 47%

准确性方面也很不错：GSM8K 数学测试前后都是 0.870（零落差），TruthfulQA 事实性测试从 0.530 提升到 0.560。SQuAD v2 和 BFCL 在 19-32% 压缩率下保持 97% 的准确率。

这不只是理论数字。一个真实的场景是：10,144 token 的工具输出，压缩后变成 1,260 token，但 LLM 仍然能找到其中标示的 FATAL 错误。

如何开始使用

安装

# 透过 uv 安装（推荐）
uv tool install "headroom-ai[all]"
# 或者透过 pip
pip install "headroom-ai[all]"

需要 Python 3.10 以上。[all] 套件包含所有功能：代理伺服器、MCP 服务、ML 模型、程式码压缩器等。

第一种方式：Proxy（推荐新手）

Proxy 模式是最简单的开始方式。它会启动一个本地代理伺服器，拦截所有发往 LLM provider 的请求，在送达前进行压缩：

# 启动代理，port 8787
headroom proxy --port 8787
# 设定 LLM 客户端使用代理
# Anthropic Claude SDK
export ANTHROPIC_BASE_URL=http://localhost:8787/v1
# 或者 OpenAI SDK
export OPENAI_BASE_URL=http://localhost:8787/v1

这样你的所有 LLM 请求都会自动经过 Headroom 压缩。不需要改任何程式码。

第二种方式：Agent Wrap（推荐进阶用户）

如果你使用 Claude Code、Codex 或 Cursor 等编码代理，可以用 wrap 命令一键设定：

# 包装 Claude Code
headroom wrap claude
# 包装 Codex
headroom wrap codex
# 包装 Cursor（手动设定部分）
headroom wrap cursor
# 包装 Copilot CLI
headroom wrap copilot --subscription

Wrap 命令会启动本地代理、设定 MCP 服务、配置代理客户端，然后启动编码代理。一次搞定。

第三种方式：Library（推荐整合到自己应用）

如果你有自己的 AI 应用，可以直接汇入压缩函数：

from headroom import compress
# 压缩 messages
compressed_messages = compress(messages, model="claude-sonnet-4-20250514")
# 压缩后送给 LLM
response = anthropic_client.messages.create(
    model="claude-sonnet-4-20250514",
    messages=compressed_messages
)

TypeScript 版本：

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

验证压缩效果

安装完成后，可以用以下命令验证：

# 健康检查
headroom doctor
# 效能测试
headroom perf
# 即时节省仪表板
headroom dashboard

进阶功能：Output Token 减少

Headroom 不只有输入压缩。它还能减少模型输出的 token。这对使用 Opus 等昂贵模型的用户特别重要——输出价格通常是输入的五倍。

启用方法：

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

它会做两件事：

1. 冗余引导：在系统提示词末尾加上「精简回答、不要重复内容」的指示（确保 prompt cache 命中）

1. effort 路由：当一个回合只是模型在工具执行后继续（如读取档案、通过测试），自动降低模型的「思考程度」

支援的框架

Headroom 支援非常广泛的框架：

| 框架 | 支援方式 |

|------|----------|

| Anthropic SDK | 内建 |

| OpenAI SDK | 内建 |

| LangChain | HeadroomChatModel |

| LiteLLM | HeadroomCallback |

| Agno | HeadroomAgnoModel |

| Vercel AI SDK | wrapLanguageModel middleware |

| FastAPI | ASGI 中间件 |

| 任何 MCP 客户端 | headroom mcp install |

| Claude Code / Codex / Cursor / Copilot | headroom wrap |

限制与注意事项

什么时候不适合用 Headroom：

  • 如果你只用单一 provider 的原生压缩功能，且不需要跨代理记忆体共享
  • 如果你在沙箱环境中，本地进程无法运行
  • 对压缩率要求极度严格的工作负载——某些高度结构化的资料可能压缩空间有限

需要注意的技术限制：

  • 压缩是「有损」的：虽然 benchmark 显示准确性几乎不受影响，但在极端情况下，压缩后可能遗漏一些边缘案例的细节
  • CCR 可逆压缩有 TTL 限制：原始资料会缓存一段时间，超时后就无法找回
  • x86 处理器需要 AVX2 指令集才能使用完整的 ONNX 功能（ARM64 / Apple Silicon 无此限制）
  • 企业网路如果用了 SSL 检查（MITM proxy），可能需要额外的 TLS 设定

成本方面：

Headroom 本身是免费开源软体（Apache 2.0）。但使用 Kompress-v2-base 模型需要下载 ONNX Runtime（约几百 MB），以及压缩模型本身。本地运行不需要额外费用，但如果用他们的企业托管服务则有费用。

我的判断

我为什么认为 Headroom 值得关注？

因为它解决了一个真实且日益严重的问题。随着 AI agent 变得越来越强大，它们需要处理的上下文也越来越多。一个 agent 一天可能读取数百个档案、执行数十次 shell 指令、处理无数的 API 回应。这些都是 token 成本。

Headroom 的聪明之处在于，它不是「简单地截断」上下文——那样会丢失重要资讯。它是理解内容结构后进行智慧压缩。JSON 压缩会保留栏位结构但移除重复，程式码压缩会理解语法但移除不必要的空白，文本压缩会保留语意但精简表达。

而且它的可逆设计很重要。压缩后的资料不是「丢掉了」，而是「暂时藏起来了」。LLM 如果需要，随时可以找回原始内容。这是一个非常务实的工程决策。

从生态系的角度看，Headroom 也展现了强大的网路效应。从它的周边项目可以发现：已经有人为它写了 Zed 扩展、Swift 封装、Go 实作、Web 仪表板、甚至日本语版本的规则重实作。这表示它正在成为这个领域的基础设施。

结论

如果你每天都在使用 Claude Code、Codex、Cursor 或其他 AI 编码工具，Headroom 可能是你今年最需要安装的工具之一。

它不需要你改程式码（Proxy 模式），不需要你改工作流程（Agent Wrap 模式），也不需要你理解压缩原理（它自动处理）。你只需要安装、启动、然后继续工作。省下来的就是真金白银。

58,746 颗星不是白来的。

参考资料