Headroom 是一个面向 AI 代理的中间层。用来压缩工具输出、日志、代码和对话历史，在它们进入大模型之前先把内容压缩到更小的 token 数量。这样可以显著降低模型调用成本，同时不会丢失任何信息——通过可逆压缩机制随时取回原文。

为什么你会遇到痛点？

如果你正在调用往往成为瓶颈：

• 高昂的 token 费用即使是一样功能，输入长度不同也导致成本飙升。
• 调试难度大每一次请求都要走一条复杂链路，难以定位问题所在。
• 部署繁琐Python 与 Rust 混合开发，让本地安装与 CI/CD 环境配置变得繁重。
• 可 性有限想自定义新的压缩逻辑，却发现每改一次都得从头写一套管线。

Headroom 的设计正是为了解决这些痛点，它将所有复杂性隐藏在统一接口后面让你只关注业务逻辑即可。话说回来，

数据流总览

No matter which entry you choose—library,proxy,wrap or MCP— core job remains identical:

1. Around agent and model:
• The agent thinks it's talking directly to model.
• The model receives a compressed payload.
2. Cancellable compression:

   四个入口，一条管线

   用法	接入方式	典型命令 / 代码
   库	直接导入函数 from headroom import compress
   代理	headroom proxy --port
   包裹	headroom wrap claude

   This looks like four distinct paths but under hood y all converge on a single place:

   • The library calls compress。which lazily constructs a singleton TransformPipeline.

3. The proxy starts HeadroomProxy,also creating its own TransformPipeline. Each vendor gets its own pipeline instance.
4. The wrap command simply spins up a local proxy and forwards traffic—no new compression logic is added.
5. MCP installs a tool that internally uses same compression pipeline when invoked by model.
6. Your bug fix only touches one spot and instantly propagates across all four interfaces.

*Tip*: If you’re debugging *** compression isn’t happening as expected,start by inspecting this single pipeline instance.

生命周期契约与 点

The heart of Headroom’s orchestration lies in two files: