Headroom：给你的 AI 助手砍掉一半 Token，关键日志一行不丢

项目简介：Headroom 是给 AI Agent 用的"上下文压缩层"——工具输出、日志、文件、RAG 片段和对话历史，在送进大模型之前先在你自己的机器上压一遍：答案不变，Token 大幅减少。项目 2026 年 1 月创建，目前 Star 超过 7.6 万，PyPI 与 npm 双端发布，Apache-2.0 许可，最近一次代码推送在 10 月 17 日。

核心亮点：

• 三类内容三把刀：SmartCrusher 处理 JSON（按字段方差统计保留异常值、越界值和首尾边界），CodeCompressor 按 AST 压缩 Python/JS/TS/Go/Rust/Java/C 等八种语言源码，Kompress-v2-base 用自研 HuggingFace 模型处理自然语言；
• 可逆压缩（CCR）：原文缓存在本地，模型需要细节时调用 headroom_retrieve 工具取回全文——压缩不等于丢弃；
• 不打断 KV 缓存：CacheAligner 只标记会击穿 provider 缓存的易变内容、从不重写 prompt；live-zone 只压新增字节，冻结前缀保持逐字节一致， Anthropic/OpenAI 的缓存命中率不受影响；
• 四种接入方式：Python/TS 库内联调用、零改代码的本地代理、一条命令包裹 Claude/Codex/Cursor/Copilot 等十余种编码 Agent、以及带三个工具的 MCP Server；
• 顺手管输出和记忆：不仅压"发出去的"，还削减模型回写的 token；跨 Agent 共享记忆并自动去重；headroom learn 挖掘失败会话，把纠正写进 CLAUDE.md/AGENTS.md。

为什么值得关注：第一，效果可验证。官方用四个真实 MCP 输出格式做基准：代码搜索 17,199→13,597 tokens（省 21%）、SRE 事故排查 55,957→24,340（省 57%）、代码库探索 58,801→33,895（省 42%）、GitHub issue 分诊 46,067→32,429（省 30%）。压缩重复的 JSON 数组和日志行收益最大；10K token 的 JSON 结果压一次 p50 只要 0.21 毫秒，100K 也才 1.4 毫秒，基本不影响 Agent 延迟。

第二，隐私与工程做得干净。压缩全程在本机完成，不把 prompt 或文件内容发往任何地方；原文留在本地缓存可随时回取。对天天在终端里跑 Agent、日志动辄几万 token 的开发者，这是"不改工作流"的省钱方式——订阅制按量计费的时代，上下文成本是每个团队都在偷偷心疼的账。

第三，边界说得诚实。文档明确写了收益随内容重复度变化：散文和已经很紧凑的输出压不动多少；评估要用自己的流量跑 headroom savings，而不是看别人的数字。一个把局限写在明面上的项目，比声称万能的项目更值得信任。

快速上手：需要 Python 3.10+（推荐用 uv 安装 CLI）：

# 1. 安装（CLI 在 PyPI 包里；TypeScript 项目只需 SDK：npm install headroom-ai）
uv tool install --python 3.13 "headroom-ai[all]"

# 2. 选择接入方式
headroom doctor              # 自检，确认路由生效
headroom wrap claude         # 包一层 Claude Code（支持 codex/cursor/copilot 等）
headroom proxy --port 8787   # 零改代码的本地代理，任何语言可用

# 3. 看省了多少
headroom dashboard

也可以在代码里内联使用：

from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "分析这些结果"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
resp = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"省下 {result.tokens_saved} tokens（{result.compression_ratio:.0%}）")

注意 npm 的 headroom-ai 只是 TypeScript SDK，不带命令行；CLI 只随 PyPI 包发布。

适用人群：长期使用 Claude Code、Cursor、Codex 的开发者；日志与 RAG 类 Agent 的工程团队；按 token 计费、想先做成本优化的技术负责人；以及想系统研究"上下文工程"这套方法论的工程师。

免责声明：本文项目信息来自 GitHub 公开仓库，数据为发文时点状态，可能随版本迭代变化。内容仅供技术交流参考，不构成任何使用承诺，请以项目官方文档为准。

引用链接