夜雨聆风最近做 AI Agent、RAG、MCP 的同学，应该都有一个共同感受：模型不是不聪明，是上下文太贵、太乱、太容易爆。
你让 Agent 跑一次工具，返回一大坨日志；你把检索结果塞进 prompt，里面夹着重复段落、无关字段、格式噪声；你调试半天，发现真正有用的信息只有几行，但 token 已经烧掉一大片。
今天这个 GitHub 热门项目 Headroom，就是冲着这个问题来的。
Headroom 的定位很直接：AI Agent 的上下文压缩层。
它可以在工具输出、日志、文件内容、RAG chunks 进入 LLM 之前，先做一层压缩，把 token 数降下来。官方描述里提到，通常可以减少 60% 到 95% token，但尽量保持回答质量不变。
它不是单纯的 gzip，也不是把文本粗暴截断，而是面向 LLM 场景做的上下文压缩工具。你可以把它当成一个“进入模型前的清理工”：把冗余、重复、低价值内容压缩掉，留下模型真正需要理解的信息。
Headroom 支持多种使用方式：
• Python Library • Proxy • MCP Server • 本地优先 • 可逆压缩 • 多种压缩算法
这几个关键词放在一起，基本就说明它不是玩具项目，而是想直接接进 Agent 工程链路里。
它解决什么痛点
现在很多 AI 应用的成本，不只是模型调用本身，而是上下文管理。
比如你做一个代码 Agent，它可能会读取文件、跑测试、查日志、调用搜索工具。每一步工具输出都可能非常长。最后塞给 LLM 的时候，prompt 里一半都是重复路径、堆栈噪声、格式化字符、无关日志。
再比如 RAG 场景，很多人以为“召回越多越好”。结果召回了 10 段文档，每段都有标题、导航、页脚、重复介绍，真正有价值的内容被埋在里面。模型看得累，回答也容易跑偏。
Headroom 想解决的就是这些问题：
• token 成本高 • 上下文窗口被浪费 • Agent 工具输出太啰嗦 • RAG chunk 信息密度低 • 日志、文件、命令输出难以直接喂给模型 • 多 Agent / MCP 工作流里上下文越来越臃肿
说白了，它帮你在“把内容交给模型之前”，先做一次智能瘦身。
核心功能
Headroom 目前最吸引人的点，主要有这几个。
第一，压缩工具输出。比如 shell 命令、测试日志、构建日志、报错堆栈，都可以在送入 LLM 之前压缩。
第二，压缩 RAG chunks。如果你在做知识库问答，可以把检索出来的文本先通过 Headroom 处理，再放进 prompt，减少无关信息。
第三，支持多种接入方式。你可以在 Python 代码里直接调用，也可以通过代理层接入，还可以作为 MCP Server 给支持 MCP 的 Agent 使用。
第四，本地优先。这点对国内开发者很重要。很多公司内部日志、代码、文档不能随便上传第三方服务，本地处理会安心很多。
第五，可逆压缩。这意味着它不只是简单摘要，而是尽量保留可恢复、可追踪的上下文结构，适合工程场景。
安装使用步骤
Headroom 的 Python 包名是 headroom-ai。如果你想先快速试一下，可以直接用 pip 安装。
pip install headroom-ai如果你习惯用 uv，也可以这样：
uv pip install headroom-ai安装完成后，可以先在 Python 里做一个最小示例。下面这个例子模拟一段很啰嗦的工具输出，然后交给 Headroom 压缩。
from headroom import Headroomcompressor = Headroom()text = """Running tests...test_user_login passedtest_user_logout passedtest_payment_create failedTraceback (most recent call last): File "tests/test_payment.py", line 42, in test_payment_create assert response.status_code == 200AssertionError: expected 200 but got 500Server logs:INFO request startedINFO loading user profileINFO loading user profileINFO loading user profileERROR payment gateway timeoutERROR payment gateway timeoutERROR payment gateway timeout"""result = compressor.compress(text)print(result)在 Agent 场景里，它更适合放在“工具调用之后，模型读取之前”的位置。
比如你自己写了一个工具函数，用来执行命令：
import subprocessfrom headroom import Headroomcompressor = Headroom()def run_command_for_agent(command: str) -> str: completed = subprocess.run( command, shell=True, capture_output=True, text=True ) raw_output = completed.stdout + "\n" + completed.stderr compressed_output = compressor.compress(raw_output) return compressed_output这样 Agent 拿到的就不是原始输出，而是压缩后的高密度上下文。
如果你在做 RAG，也可以把它放在召回之后：
from headroom import Headroomcompressor = Headroom()def build_context(chunks: list[str]) -> str: compressed_chunks = [] for chunk in chunks: compressed = compressor.compress(chunk) compressed_chunks.append(compressed) return "\n\n".join(compressed_chunks)然后再把 build_context() 的结果塞进 prompt：
prompt = f"""请基于下面资料回答用户问题。资料：{context}问题：{question}"""这个思路很朴素，但很实用：先压缩，再喂模型。
如果你的项目里已经有 MCP 工作流，可以继续关注它的 MCP Server 接入方式。这样就不需要在每个 Agent 里重复写压缩逻辑，而是把 Headroom 作为统一的上下文处理层。
一个实际使用建议
刚开始别急着全量接入，建议先挑 3 类内容测试：
• CI 日志 • 测试失败输出 • RAG 检索片段
这三类内容通常最容易出现 token 浪费，也最容易看到压缩效果。
你可以先记录压缩前后的 token 数、模型回答质量、是否遗漏关键信息。如果压缩后回答仍然稳定，再逐步接入更多工具输出。
比如可以简单打印长度做个粗略观察：
raw = open("error.log", "r", encoding="utf-8").read()compressed = compressor.compress(raw)print("before:", len(raw))print("after:", len(compressed))print(compressed)当然，生产环境里最好用真实 tokenizer 统计 token，而不是只看字符数。
适合谁用
Headroom 特别适合下面几类开发者：
第一类是做 AI Agent 的。只要你的 Agent 会调用工具、读文件、跑命令，就很容易遇到上下文膨胀问题。
第二类是做 RAG 知识库 的。尤其是企业文档、技术文档、客服知识库，原始文本里经常有大量重复和模板内容。
第三类是做 MCP 工具链 的。如果你已经在用 Claude Desktop、Cursor、各种支持 MCP 的 Agent，把 Headroom 放进链路里会很自然。
第四类是对 LLM 成本敏感 的团队。尤其是高频调用、长上下文、多轮 Agent，这种地方省下来的 token 很快就不是小钱。
第五类是做内部 AI 平台的同学。Headroom 这种“基础设施层”的工具，适合包装成统一服务，让不同业务线都能复用。
小结
Headroom 这个项目抓住了一个很真实的问题：AI 应用越复杂，上下文越容易变成垃圾场。
以前我们更多关注模型、向量库、Agent 框架，但真正落地之后会发现，上下文工程本身就是一门功夫。哪些内容该保留，哪些内容该压缩，哪些内容该在进入模型前处理好，都会直接影响成本和效果。
如果你正在做 Agent、RAG 或 MCP 工具链，Headroom 值得拉下来试试。它不一定立刻替代你现有的上下文策略，但很适合作为一个“模型前置压缩层”，帮你的系统少烧 token，多留信息密度。
项目地址：https://github.com/chopratejas/headroom
你现在的 AI 应用里，最浪费 token 的地方是哪一块？是日志、RAG 文档，还是工具输出？欢迎留言聊聊。
