Headroom：给AI Agent做上下文压缩，省下大半Token

Headroom 是一个上下文压缩层，在工具输出、日志、RAG 分块、文件与对话历史进入大模型前先做结构化瘦身。实测编码 Agent 场景可省 21%–57% 输入 token，重复 JSON 数组与日志行可达 90% 以上，且关键错误行逐字节保留、答案质量不变。提供 Python/TypeScript 库、FastAPI 代理与 MCP server 三种接入方式，Apache 2.0 开源。

适用人群：1. 正在开发或运维 AI Agent 应用的工程师，尤其是多轮工具调用、日志量大的编码类 Agent；2. 使用 Claude Code、Cursor 等支持 MCP 客户端的个人开发者，希望降低调用成本与上下文溢出风险；3. RAG 与 LLM 平台的基础设施/后端工程师，需要在不修改业务代码的前提下做透明优化。

适用场景：1. 编码 Agent 长时间运行：把累积的工具返回、终端日志、文件内容压缩后再送入模型，避免上下文窗口被噪声占满；2. RAG 检索增强链路：对召回的分块与结构化 JSON 结果去冗余，提升单位上下文内的有效信息密度；3. 已上线 LLM 应用的零侵入优化：通过本地代理把请求转发路径改一个 base_url，即可获得 token 节省。

推荐理由：它切中的是 AI Agent 最真实的成本痛点：输入 token。相比粗暴截断或摘要，Headroom 采用结构感知的压缩策略，对 JSON、日志这类高冗余内容收益惊人，同时承诺关键行逐字节保留，避免把真正的错误信息压掉。三种接入形态让它既能做实验也能进生产，对于任何跑长链路 Agent 的团队都值得先花半小时验证一遍。

项目定位与背景

大模型应用的成本大头往往不在输出，而在输入。一个跑了几十轮的编码 Agent，每一轮都要把历史对话、工具返回、日志、检索片段重新塞进上下文，token 像滚雪球一样增长。Headroom 要解决的正是这种上下文通胀：它不改变模型，也不改变 Agent 的业务逻辑，而是在内容抵达 LLM 之前做一层压缩，把冗余结构、重复行、无信息量字段去掉，保留真正承载语义的部分。项目以 Apache 2.0 开源，PyPI 与 npm 双通道发布，Star 数已接近八万，并登上 Trendshift 日榜第一，说明这个痛点足够普世。

核心功能与技术架构

Headroom 提供三种接入形态，覆盖绝大多数工程场景：一是 Python/TypeScript 库，直接在代码里调用压缩能力；二是基于 FastAPI 的本地代理，把 OpenAI、Anthropic 等请求指向代理端口即可透明生效，业务代码零改动；三是 MCP server，可直接挂到 Claude Code、Cursor 等支持 MCP 的客户端上。压缩对象被明确划分为工具输出、日志、RAG 分块、文件内容与对话历史五类，分别采用不同策略。

技术上的关键判断是先分类再压缩。README 给出的实测数据是：四个典型 Agent 场景下输入 token 减少 21%–57%，重复度高的 JSON 数组和日志行可达 90% 以上，而散文类内容收益很小，这恰好说明它是结构感知的，而不是无差别地砍字符。项目还在 HuggingFace 上放出了 kompress-v2-base 模型，用于更精细的语义级压缩。

创新点与亮点

最值得一提的设计是关键信息逐字节保真。首页示意图给出的例子很有说服力：一段 55,957 token 的 Agent 提示被压到 24,340 token，而位于第 67 条的那个 FATAL 日志行原封不动地留了下来。这解决了很多粗暴截断方案的致命伤——日志里真正有用的往往就是那一行错误，压掉了等于白跑。

其次是可调的压缩强度。开发者可以按内容类型设置激进或保守策略，对 JSON 大胆去重、对散文几乎不动，避免一刀切带来的语义漂移。第三是零侵入的代理模式，对于已经上线的 Agent 应用，改一个 base_url 就能拿到收益，迁移成本极低。此外项目还提供了 llms.txt 索引，方便 Agent 自己去读文档，这个细节本身就很有 AI 原生的味道。

与同类项目对比

同赛道常见的两类方案：一类是 LLMLingua 这类基于小模型的 prompt 压缩，效果好但会改写原文、需要额外推理开销，且难以保证关键行不丢；另一类是应用层的粗暴截断或摘要，实现简单但不可控。Headroom 走的是第三条路——结构化、可预期、尽量无损地删除冗余，再配合代理与 MCP 两种部署形态，更贴近工程落地。代价是它对散文类内容帮助有限，会引入一次额外处理延迟，压缩策略也需要按业务调优。

上手指南与快速开始

上手非常轻：Python 侧执行 pip install headroom-ai，前端侧 npm i headroom-ai。最省事的验证方式是启动本地代理，把 SDK 的 base_url 指过去，跑一轮真实 Agent 任务，对比压缩前后的 token 数与回答质量。如果用的是 Claude Code 或 Cursor，直接在 MCP 配置里加上 headroom 的 server 条目即可。建议先在日志与工具输出这类高冗余场景试用，确认关键行未被误删，再逐步扩大到 RAG 与对话历史。

总结与展望

Headroom 把上下文工程从一种玄学调参，变成了可度量、可插拔的基础设施。它不是万灵药——散文压缩收益有限，策略需要调，但它精准地咬住了 Agent 时代最贵的那块成本。随着上下文窗口继续变大而价格未必变便宜，这类压缩层的价值只会更明显。