摘要

只要你在用 Claude Code、Codex、Cursor 之类的 AI 编程助手,大概率已经感受过"上下文越用越贵"的痛:一次工具调用返回的日志、一份 RAG 检索结果、一段冗长的文件内容,动辄几千甚至上万 token,而模型真正需要的信息可能只是其中的一小段。开源项目 Headroom 就是为了解决这个问题而生——它在工具输出、日志、文件、RAG 片段真正送进 LLM 之前,先对它们做一层本地压缩,在保持回答质量不变的前提下,平均砍掉 60%-95% 的 token 消耗,而且压缩是可逆的,原文随时可以按需取回。

核心优势

Headroom 与市面上常见的"上下文裁剪"工具最大的不同,在于它把压缩这件事做成了一整套系统,而不是一次性的截断技巧:

• 内容感知的压缩策略:内置 ContentRouter 会自动识别内容类型——JSON 交给 SmartCrusher,代码交给基于 AST 的 CodeCompressor,普通文本交给自研的 Kompress-v2-base 模型(已开源在 HuggingFace),而不是用一刀切的摘要或截断。
• 可逆压缩(CCR):压缩后的原文会被本地缓存,LLM 如果发现自己确实需要完整信息,可以主动调用 headroom_retrieve 把原文取回来,不会因为压缩丢失关键上下文。
• 本地优先,数据不出机器:无论是作为 Python/TypeScript 库直接调用,还是起一个本地代理 headroom proxy,所有压缩都在本地完成,不经过第三方服务器。
• 跨 Agent 共享记忆:Claude、Codex、Gemini 等多个 Agent 可以共用同一份上下文记忆,并自动去重,避免每个工具都要重新"认识"一遍项目。
• headroom learn 自动纠错:从失败的历史会话里挖掘教训,自动写入 CLAUDE.local.md / AGENTS.md / GEMINI.md,相当于让 Agent 自己攒经验、自己改毛病。
• 连模型的"输出"也一起省:大多数压缩工具只优化输入,Headroom 还提供 Output Shaper——通过精简系统提示词的"啰嗦度"要求、在模型只是"顺着工具结果继续走"时自动调低推理力度,从写回的这一头也省 token(在 Opus 级别模型上,输出的单价是输入的 5 倍,这部分的收益甚至更可观)。
• CacheAligner 稳定前缀:压缩过程会特意保持提示词前缀稳定,确保 Anthropic / OpenAI 等提供商的 KV Cache 能真正命中,压缩和缓存命中率两不误。

官方给出的真实工作负载测试数据也很直观:代码搜索场景 token 从 17,765 降到 1,408(节省 92%),SRE 故障排查从 65,694 降到 5,118(节省 92%),GitHub issue 分诊节省 73%。同时在 GSM8K、TruthfulQA、SQuAD v2、BFCL 等标准评测集上,准确率几乎没有下降甚至略有提升——这说明压缩没有以牺牲效果为代价。

面向人群

• 每天高频使用 AI 编程 Agent 的开发者:希望在不改代码的前提下,直接省下可观的 token 费用。
• 同时使用多个 Agent(Claude Code、Codex、Cursor 等)的团队或个人:需要跨 Agent 共享上下文记忆,避免重复"教"每个工具项目背景。
• 对可追溯性有要求的场景:压缩后的原文可按需找回,不必担心信息永久丢失,适合对准确性敏感的调试、审计类工作。
• 需要精细控制 LLM 成本的技术负责人:无论是单机使用的开源版,还是需要统一部署、看板、SSO 的团队版,Headroom 都有对应的路径。

不太适合的场景:如果你只用单一模型厂商自带的上下文压缩(比如某家的原生 compaction),且不需要跨 Agent 记忆,或者你的运行环境完全无法启动本地进程(比如某些强隔离沙箱),那么 Headroom 的价值会打折扣。

使用方法

快速上手(60 秒)

Headroom 提供三种接入方式:直接作为库调用、起一个零代码改动的本地代理,或者用 wrap 命令一键包裹现有 Agent。

# 1 — 安装(pip 版本自带 headroom 命令行工具)
pip install "headroom-ai[all]"          # Python,含 CLI
npm install headroom-ai                 # TypeScript SDK(仅库,不含 CLI)

# 2 — 三选一
headroom wrap claude                    # 一键包裹 Claude Code 等编程 Agent
headroom proxy --port 8787              # 起本地代理,零代码改动接入任意语言项目
# 或者在代码里直接调用:
# from headroom import compress

# 3 — 验证效果
headroom doctor        # 健康检查,确认压缩路由是否生效
headroom perf          # 查看性能数据
headroom dashboard     # 实时省钱看板(需要代理正在运行)

需要 Python 3.10+。headroom wrap 目前支持 Claude Code、Codex、Aider、Copilot CLI、OpenClaw、OpenCode、Cline、Continue、Goose、OpenHands、Mistral Vibe 等主流 Agent,想撤销包裹直接用 headroom unwrap <tool>。

在任意 Python 应用里直接调用也很简单:

from headroom import compress

compressed_messages = compress(messages, model="claude-sonnet-5")

TypeScript 项目同理:

import { compress } from 'headroom-ai';

const compressed = await compress(messages, { model });

进阶用法

开启输出端压缩,连模型"写回来"的内容也一起省:

export HEADROOM_OUTPUT_SHAPER=1     # 默认关闭
headroom proxy --port 8787

如果代理是被 headroom wrap 复用而非新启动的,环境变量需要在 wrap 之前设置好——不过新版本已经支持通过本地回环接口 POST /admin/runtime-env 热同步配置,无需重启代理即可生效。

让 Headroom 自动学出你偏好的啰嗦程度,而不是手动调参:

headroom learn --verbosity            # 先看看学到了什么(不生效)
headroom learn --verbosity --apply    # 确认后应用,代理从此按这个尺度回答

衡量输出端到底省了多少:由于无法真正对照"模型本来会写多少",Headroom 默认给出一个带置信区间的估算值;如果想要更精确的实测数据,可以留一部分对话不做压缩作为对照组:

export HEADROOM_OUTPUT_HOLDOUT=0.1
headroom output-savings
# Reduction: 31.7%  (95% CI 27.7% … 35.7%)   [estimated]

接入已有技术栈也很轻量,常见的挂载点包括:

你的技术栈	接入方式
Anthropic / OpenAI SDK	withHeadroom(new Anthropic())
Vercel AI SDK	wrapLanguageModel({ model, middleware: headroomMiddleware() })
LiteLLM	litellm.callbacks = [HeadroomCallback()]
LangChain	HeadroomChatModel(your_llm)
MCP 客户端	headroom mcp install

对于处在企业代理/SSL 检测环境下的用户,项目文档也专门给出了证书信任、Rust 工具链预装等排障方案,细节可以在仓库的 README 中查到。

如果团队规模更大,需要统一部署、集中配置、组织级用量看板和 SSO,Headroom 也提供自托管或全托管的企业方案,核心压缩能力本身则始终保持 Apache 2.0 开源。

项目地址:github.com/headroomlabs-ai/headroom