Headroom – AI智能体的上下文压缩层

Headroom 是一个开源的上下文压缩层，专为 AI 智能体设计。它能在智能体读取工具输出、日志、RAG 块、文件和对话历史之前进行压缩，显著减少发送给大语言模型的 token 数量，同时保持答案的准确性和完整性。根据实际测试，压缩率可达 60-95%，例如在代码搜索场景中，token 从 17,765 降至 1,408（节省 92%）；在 SRE 事故调试中，从 65,694 降至 5,118（节省 92%）。

Headroom 提供多种使用模式，以适应不同的开发环境：

• 库模式：在 Python 或 TypeScript 应用中直接调用 compress(messages) 函数。
• 代理模式：通过 headroom proxy --port 8787 启动一个 HTTP 代理，无需修改代码即可集成。
• 智能体封装：支持 headroom wrap claude|codex|cursor|aider|copilot 等命令，一键包装常用 AI 智能体。
• MCP 服务器：提供 headroom_compress、headroom_retrieve、headroom_stats 工具，供任何 MCP 客户端使用。

Headroom 的核心机制包括内容路由器（ContentRouter），它能自动检测内容类型并选择最佳压缩器（如 SmartCrusher 处理 JSON、CodeCompressor 进行 AST 感知压缩、Kompress-base 处理文本）。缓存对齐器（CacheAligner）稳定前缀以利用供应商的 KV 缓存，可逆压缩（CCR）将原始数据本地存储，LLM 可在需要时通过 headroom_retrieve 检索。

此外，Headroom 还支持输出 token 缩减（Output Token Reduction），通过向系统提示添加简洁指令和降低例行步骤的思考深度，减少模型生成的冗余内容。该功能默认关闭，可通过环境变量 HEADROOM_OUTPUT_SHAPER=1 启用。Headroom 还能智能学习用户的偏好，通过 headroom learn --verbosity 自动设定合适的简洁程度。

Headroom 与多种主流框架和工具集成，包括 Anthropic SDK、OpenAI SDK、Vercel AI SDK、LiteLLM、LangChain、Agno 等。对于 GitHub Copilot CLI 订阅用户，Headroom 提供了专门的认证和路由支持。

项目已在 GitHub 开源，拥有超过 45,000 个星标和 3,200 个分叉。安装简单，支持 pip 和 npm，需要 Python 3.10+ 或 Node.js 环境。