GitHub 狂揽 4万+ Star！这个项目直接让你省下60–95%的Token 。。。

大家好，我是锋哥。

今天分享一个非常火爆的开源项目 - headroom

先说说：Token 到底烧在哪了？

如果你经常用 Claude Code、Cursor、Codex 这类 AI 编程助手，大概都有过这种体验：

搜一下代码，返回 100 条结果，一下子就是好几万 Token
读日志、查 Issue、跑工具，每一轮对话都在往上下文里堆东西
模型不仅要「读」你发过去的内容，还要「写」回复——两边都算钱

问题往往不在你的问题本身，而在工具输出、日志、RAG 检索结果、历史对话这些「背景噪音」。它们占了大头，但真正有用的可能只有一小部分。

Headroom 就是专门解决这个问题的。它在你的应用和 LLM 之间加了一层「压缩滤镜」：把要发给模型的内容先瘦身，模型该答对的还是答对，Token 却能少掉 60%～95%。

Headroom 是什么？

Headroom 是一个开源的 AI Agent 上下文压缩层，由 Tejas Chopra 发起，目前在 GitHub 上已有 4 万+ Star。

它压缩的对象包括：

工具调用返回的结果（比如代码搜索、文件读取）
日志和报错信息
RAG 检索到的文档片段
文件内容和对话历史

几个关键特点：

特点	说明
本地运行	数据留在你的机器上，不经过第三方 API
可逆压缩	原文会缓存在本地，模型需要时可以再取回
多种接入方式	库、代理、MCP 服务器，怎么方便怎么来
跨 Agent 记忆	Claude、Codex、Cursor 等可以共享压缩后的上下文

它怎么工作的？

可以把 Headroom 想象成一条「预处理流水线」：你的 Agent 本来要直接把一大坨内容扔给模型，现在先经过 Headroom 筛一遍。

简单说就是三步：

识别内容类型——JSON 走 JSON 的压缩器，代码走 AST 分析，普通文字走专用小模型
智能压缩——去掉重复、冗余和低价值信息，保留关键内容
原文备份——压缩后的内容带着一个「哈希 ID」，模型觉得不够用时可以按需取回

另外还有一个 CacheAligner：很多云厂商会对相同前缀做 KV 缓存，Headroom 会尽量让每次请求的前缀保持稳定，让缓存真正命中，进一步省钱。

三种用法，挑一种就行

Headroom 不绑死某一种技术栈，常见有三种接入方式：

1. 代理模式（最省事）

headroom proxy --port 8787

把你的 AI 客户端指向本地 8787 端口，不用改一行业务代码，任何语言、任何框架都能用。

2. 一行命令包装 Agent

headroom wrap claude    # 或 codex / cursor / aider / copilot

直接帮你启动代理并拉起对应的编程 Agent，Claude Code、Cursor、Codex 等都支持。

3. 库/SDK 嵌入

Python：

from headroom import compress
compressed = compress(messages, model="claude-sonnet-4-20250514")

TypeScript：

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

如果你用 LangChain、Agno、Vercel AI SDK、LiteLLM 等框架，也都有对应的集成方式。MCP 客户端可以跑 headroom mcp install，获得 headroom_compress、headroom_retrieve 等工具。

CCR：压缩了还能找回来

传统压缩有个两难：压狠了怕丢信息，压轻了省不了钱。

Headroom 的 CCR（Compress-Cache-Retrieve） 机制把这个矛盾化解了：

也就是说：压缩是 aggressive 的，但数据不是「删掉了」，而是「暂存了」。模型觉得 15 条结果够用就省 90% Token；觉得不够，一个工具调用就能把原文拉回来。

真实场景能省多少？

项目官方在真实 Agent 工作负载上做过测试，数据比较有说服力：

场景	压缩前	压缩后	节省比例
代码搜索（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、TruthfulQA、SQuAD v2 等基准测试上，压缩前后得分基本持平，有些场景甚至略有提升——去掉噪音后，模型反而更聚焦。

另外，Headroom 还能压缩模型写回来的内容（输出 Token）。开启 HEADROOM_OUTPUT_SHAPER=1 后，可以减少「好的，让我来……」这类废话，以及重复粘贴已有代码的习惯，对 Opus 这类输出单价更高的模型尤其划算。

怎么使用？

安装（Python 3.10+）：

pip install "headroom-ai[all]"

或者 Node 环境：

npm install headroom-ai

快速体验三步走：

# 1. 安装（见上）


    


# 2. 选一种模式
headroom wrap claude          # 包装编程 Agent
# 或
headroom proxy --port8787    # 纯代理模式

# 3. 查看节省效果
headroom perf

首次运行会下载约 500MB 的压缩模型（Kompress-base），之后会缓存在本地，只下一次。

项目地址再次附上：https://github.com/chopratejas/headroom

2026年，锋哥又开始收Python+AI大模型学员了！目前活动，送AI编程+Java编程 VIP

最近锋哥录制了一些AI编程视频教程

高清视频+源码+领取。

扫描下方公众号【小锋学AI 】回复：888，

可获取下载链接

👇👇👇

👆长按上方二维码 2 秒

回复「888」即可获取