headroom：LLM 上下文压缩利器

它是什么

Headroom 是一个面向 AI Agent 与 LLM 应用的「上下文压缩层」。它位于你的 Agent 与模型 API 之间，把即将送进模型的上下文——工具调用返回、运行日志、RAG 检索块、文件内容、对话历史——先压缩一遍，再交给模型。官方定位可以概括成三句话：压缩工具输出、日志、文件和 RAG 分块；编码类 Agent 少用约 20% token，JSON 类内容少用 60%–95% token，而答案保持一致；提供 Library、Proxy、MCP Server 三种形态。

背景在于，Agent 的上下文正在被大量低信息密度的内容填满：一次 shell 命令输出上千行日志、一次 API 调用返回一大坨嵌套 JSON、一次向量检索塞进十几个 chunk，而模型真正需要的往往只有其中几行。上下文越长，调用成本越高、首字延迟越大，注意力也会被稀释（常说的 "lost in the middle"）。Headroom 的思路不是换模型、也不是简单砍掉召回条数，而是在「写进 prompt 之前」做一轮有选择的压缩，把冗余丢掉、把关键信息留下。

项目以 Apache-2.0 协议开源，同时通过 PyPI 与 npm 分发，配套官方文档站、Discord 社区以及 llms.txt 索引。

核心功能 / 内容清单

多类型输入压缩：工具输出、日志、文件内容、RAG chunk、对话历史都在覆盖范围内。不同类型的冗余结构并不一样，结构规整的 JSON 与日志可压缩空间最大，这也是官方给出高压缩比的来源。
保留关键行的压缩策略：README 用一张示意图说明取舍——一个 55,957 token 的 agent prompt 被压到 24,340 token 实际发给模型，而第 67 项中的 FATAL 日志行逐字节保留。这说明设计目标是「压掉冗余而非压掉信息」，但从机制上讲它仍是压缩而非无损重放。
三种接入形态：既可作为库直接嵌入代码（PyPI/npm 上的 headroom-ai），也可作为代理挡在应用与模型 API 之间（业务代码几乎零改造），还可作为 MCP Server 供支持 MCP 的客户端调用。三种形态对应从「最省事」到「最可控」的取舍。
配套压缩模型：项目在 Hugging Face 上提供 kompress-v2-base 模型作为压缩能力的一部分，这意味着压缩不只是一堆正则与截断规则，而是有模型参与判断。
面向 AI 助手的文档索引：提供 llms.txt 与完整文档 blob，方便让 AI 编程助手直接读取项目用法，减少手动翻文档的成本。

典型使用场景

场景一：编码 Agent 的命令与日志输出。 当 Agent 执行测试、构建、部署命令时，stdout 常是几百上千行，真正有价值的是几行报错和栈顶信息。做法是在工具调用返回之后、把结果回填进 context 之前过一遍 Headroom，让原始输出留在本地文件或磁盘上，只把压缩结果和关键行交给模型。官方所说的「编码 Agent 省约 20% token」针对的正是这类负载——比例不算夸张，但请求量大时节省是持续的。

场景二：大量 JSON 的工具 / MCP 返回值。 查询数据库、调用 SaaS API、读取结构化配置时，返回体里字段名、嵌套层级和重复键值占了大部分体积，模型真正关心的可能只是其中几个字段。这类内容冗余度高、结构可预测，因此压缩比能达到 60%–95%。这一场景最适合用 Proxy 形态接入：把模型的 base_url 指向 Headroom 代理，业务代码不动，所有请求统一经过压缩。

场景三：RAG 与长会话。 检索回来的多个 chunk 之间常有重复段落、页眉页脚和样板文本，多轮会话历史也会不断累积。把压缩层放在检索之后、拼接 prompt 之前，可以在不减少召回条数的前提下压低最终 prompt 长度，等于用压缩换召回预算。

适合谁用

做 AI Agent 或编程助手产品的团队：上下文成本与延迟是直接的产品指标，而压缩层是一个相对独立、可插拔的优化环节。
重度依赖工具调用（function calling / MCP）的开发者：工具返回值通常是最不可控、最脏、也最长的上下文来源。
RAG 应用开发者：可以把压缩当作检索之后的第二道过滤，用来提升单次请求的有效信息密度。
对合规与自托管敏感的场景：Apache-2.0 且可本地部署，代理层跑在自己的网络内，不必把日志和业务数据交给第三方服务。
收益有限的场景：上下文本来就很短的应用，压缩带来的绝对节省不明显；对逐字节正确性有强制要求、不能接受任何有损处理的流水线，也需要谨慎评估。

快速上手

三条路径，按改造程度从低到高排列：

1. Proxy（改动最小）：按官方说明启动 Headroom 代理服务，把应用的模型 base_url 指向它，其余代码保持不变。

2. Library（控制最细）：Python 侧通过 pip 安装 headroom-ai，Node 侧通过 npm 安装 headroom-ai，在工具结果、检索结果进入 prompt 之前调用压缩接口，可逐处决定压什么、不压什么。

3. MCP Server（面向支持 MCP 的客户端）：在 MCP 客户端配置中注册 Headroom，让客户端侧的上下文在送往模型前经过压缩。

README 同时提供了 llms.txt 与完整文档索引，可以让 AI 编程助手直接读取，减少查文档的往返。具体的安装命令、参数、环境变量与模型配置，以官方 README 与官方文档站为准。

注意事项

压缩是有损的：README 强调「关键行字节级保留」，但这不等于信息无损。上线前应针对自己的真实负载做 A/B 对比，尤其是错误信息、堆栈、订单号、价格、时间戳这类一个字符都不能错的字段，建议用白名单或结构化规则单独保护。
压缩比差异极大：20% 与 60%–95% 这两个数字差距悬殊，说明收益高度依赖内容类型。JSON、日志等高冗余文本收益最大，自然语言散文和代码收益有限，不要用统一预期做成本与容量规划。
代理模式的工程要求：代理处在应用与模型服务之间，需要处理好 API Key 转发、超时与重试、并发吞吐，以及失败降级路径——压缩层不可用时应当能直连模型，而不是让整条链路一起挂掉。
隐私与数据边界：日志和工具输出常含敏感信息。自托管能降低外流风险，但仍需确认压缩模型与运行环境是否完全在本地、是否会向外上报数据。
依赖与资源：使用自带压缩模型时需要额外的模型下载与推理资源（CPU/GPU 视配置而定）；若走远程模型，则要额外考虑网络延迟与稳定性，否则节省的 token 成本可能被延迟抵消。
协议：Apache-2.0，允许商用、修改与再分发，需保留版权与许可声明，具体条款以仓库 LICENSE 文件为准。