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

大家好我是Java1234_小锋老师。先说说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 筛一遍。否是你的 Agent / 应用Claude Code · Cursor · 自研程序原始上下文工具输出 · 日志 · RAG · 文件Headroom本地运行CacheAligner稳定前缀提高缓存命中ContentRouter识别内容类型SmartCrusher处理 JSONCodeCompressor处理代码 ASTKompress-base处理普通文本CCR 缓存原文压缩后的 Prompt 检索工具说明LLM 提供商Anthropic · OpenAI · Bedrock 等模型需要更多细节?直接回答大幅省 Token调用 headroom_retrieve从本地缓存取回原文简单说就是三步识别内容类型——JSON 走 JSON 的压缩器代码走 AST 分析普通文字走专用小模型智能压缩——去掉重复、冗余和低价值信息保留关键内容原文备份——压缩后的内容带着一个「哈希 ID」模型觉得不够用时可以按需取回另外还有一个CacheAligner很多云厂商会对相同前缀做 KV 缓存Headroom 会尽量让每次请求的前缀保持稳定让缓存真正命中进一步省钱。三种用法挑一种就行Headroom 不绑死某一种技术栈常见有三种接入方式1. 代理模式最省事headroom proxy--port8787把你的 AI 客户端指向本地 8787 端口不用改一行业务代码任何语言、任何框架都能用。2. 一行命令包装 Agentheadroom wrap claude# 或 codex / cursor / aider / copilot直接帮你启动代理并拉起对应的编程 AgentClaude Code、Cursor、Codex 等都支持。3. 库/SDK 嵌入Pythonfromheadroomimportcompress compressedcompress(messages,modelclaude-sonnet-4-20250514)TypeScriptimport{compress}fromheadroom-ai;constcompressedawaitcompress(messages,{model:gpt-4o});如果你用 LangChain、Agno、Vercel AI SDK、LiteLLM 等框架也都有对应的集成方式。MCP 客户端可以跑headroom mcp install获得headroom_compress、headroom_retrieve等工具。CCR压缩了还能找回来传统压缩有个两难压狠了怕丢信息压轻了省不了钱。Headroom 的CCRCompress-Cache-Retrieve机制把这个矛盾化解了大模型本地缓存Headroom工具/API大模型本地缓存Headroom工具/APIalt[压缩版够用][需要更多细节]返回大量数据如 1000 条搜索结果SmartCrusher 压缩为 Top 15 条原文按 hash 存入缓存发送压缩版 检索说明直接完成任务调用 headroom_retrieve(hash)按 hash 取回原文约 1ms返回完整数据也就是说压缩是 aggressive 的但数据不是「删掉了」而是「暂存了」。模型觉得 15 条结果够用就省 90% Token觉得不够一个工具调用就能把原文拉回来。真实场景能省多少项目官方在真实 Agent 工作负载上做过测试数据比较有说服力场景压缩前压缩后节省比例代码搜索100 条结果17,7651,40892%SRE 故障排查65,6945,11892%GitHub Issue 分类54,17414,76173%代码库探索78,50241,25447%准确率方面在 GSM8K、TruthfulQA、SQuAD v2 等基准测试上压缩前后得分基本持平有些场景甚至略有提升——去掉噪音后模型反而更聚焦。另外Headroom 还能压缩模型写回来的内容输出 Token。开启HEADROOM_OUTPUT_SHAPER1后可以减少「好的让我来……」这类废话以及重复粘贴已有代码的习惯对 Opus 这类输出单价更高的模型尤其划算。适合谁用不适合谁比较适合每天用 AI 编程 AgentToken 账单看得心疼的人工具输出、RAG 检索结果经常很大的 Agent 应用开发者同时在 Claude、Codex、Cursor 之间切换想要共享上下文的人需要激进压缩、但又不能接受「压完找不回来」的场景可以跳过只用单一云厂商自带的对话压缩且不需要跨 Agent 能力运行环境完全沙箱化不能跑本地进程怎么开始安装Python 3.10pipinstallheadroom-ai[all]或者 Node 环境npminstallheadroom-ai快速体验三步走# 1. 安装见上# 2. 选一种模式headroom wrap claude# 包装编程 Agent# 或headroom proxy--port8787# 纯代理模式# 3. 查看节省效果headroom perf首次运行会下载约 500MB 的压缩模型Kompress-base之后会缓存在本地只下一次。写在最后AI Agent 时代上下文管理正在变成和模型选型一样重要的「基础设施」。Headroom 的思路很直接不是让模型变聪明而是别让模型读垃圾。4 万 Star 说明大家确实被 Token 账单折磨得不轻。如果你也在跑 Agent、搭 RAG、或者天天用 Cursor 写代码不妨花一分钟装个 Headroom 试试——本地跑、开源免费、压缩可逆试错成本很低。项目地址再次附上https://github.com/chopratejas/headroom