headroomlabs-ai/headroom

项目介绍

Headroom 位于 AI 代理与模型服务之间，压缩代理读到的内容——工具输出、日志、RAG 片段、文件和对话历史——再发给模型。它同时提供 Python/TypeScript 库、本地代理、代理包装命令和 MCP Server，既能接入自己拼 prompt 的应用，也能作用于无法改代码的编码代理。

压缩按内容类型分流：SmartCrusher 处理 JSON，CodeCompressor 对多种语言做 AST 级压缩，Kompress-v2-base 处理自然语言。原文通过 CCR 缓存在本地，模型可按需取回，因此压缩可逆；易变内容会被标记，避免破坏服务商的 KV-cache 前缀。

快速使用

在自己的应用里拼 prompt 时，安装库并在调用模型前压缩消息列表：

pip install headroom-ai

from headroom import compress

result = compress(messages, model="gpt-4o")
client.chat.completions.create(model="gpt-4o", messages=result.messages)

对编码代理，安装完整 CLI 后包装对应工具。该命令会启动本地代理并把该工具配置为经其转发，作用范围是当前会话：

uv tool install --python 3.13 "headroom-ai[all]"
headroom wrap claude

两种方式配置完成后，headroom doctor 可确认路由正常，代理运行时 headroom dashboard 显示实时节省量。想得到适用于自己的数字，用 headroom savings 统计实际流量；README 中的基准表是固定种子、离线运行的，复现的是项目方数据而非你的负载。TypeScript SDK、代理与 MCP 用法见快速开始。

使用约束

• 需要 Python 3.11+。CLI 只随 PyPI 包发布；npm 包是 TypeScript 库，不提供 headroom 命令。
• 原生 wheel 覆盖 macOS Apple Silicon 和 Linux。Intel macOS 需改用 Docker 或系统 ONNX Runtime 方案（issue #941）；不支持 AVX2 的 x86 主机回退到非 ONNX 路径。
• [all] 不包含框架适配器，[langchain]、[agno]、[strands] 等需单独安装；依赖 PyTorch 的功能也是单独 extra。
• 节省比例取决于内容：重复 JSON 数组和日志压缩最多，散文和已很紧凑的输出几乎不压缩，短 prompt 可能原样返回。
• 默认开启匿名遥测，上报压缩比例、计数、服务商与模型 ID、操作系统与架构，不发送 prompt、代码或路径；可用 HEADROOM_BEACON=off、HEADROOM_TELEMETRY=off、DO_NOT_TRACK=1 或 HEADROOM_OFFLINE=1 关闭。
• 输出 token 精简默认关闭，且默认给出的是估计值，只有配置 holdout 后才显示实测。
• 使用第三方 OpenAI 兼容服务时需传 --openai-api-url 或设置 OPENAI_TARGET_API_URL，否则请求会发往默认 OpenAI 端点。

HotRepo 点评

该项目在 2026-10-19 的全语言日榜记录到 76,073 stars，当日新增 317；2026-11-13 进入 Python 日榜第 8 名时累计 79,529 stars、6,226 forks。对一个上下文压缩工具来说这是很陡的曲线，相关争议在 Hacker News 上也能看到：有评论者质疑头条基准在真实代理编码场景中不成立，并追问服务商为何不默认提供同类能力（讨论）；另有回复指出 JSON 去空白本身就可能带来可观的 token 节省（回复）。仓库用可复现的证明脚本、准确率评测和可逆缓存回应了部分质疑，但节省比例因负载而异，真正的检验是在自己的流量上跑 headroom savings，而不是只看表格。