Headroom：面向 AI 智能体的上下文压缩层

工具概述

Headroom 是一个面向 AI 智能体（AI agent）的上下文压缩中间层，由独立开发者在 Hacker News 发布。它通过在 prompt、工具输出、日志、RAG 结果、文件与会话历史进入大模型之前对其进行压缩，帮助使用 Claude、GPT、Gemini、Grok 等模型的代理在不损失回答质量的前提下显著降低 Token 消耗。项目以 Python 包 headroom-ai 发布，同时提供 TypeScript SDK，并自带 CLI 与本地代理。

核心能力

Headroom 提供四种接入方式，覆盖不同工程场景：

库（Library）：在 Python 或 TypeScript 中直接调用 compress(messages)，嵌入任意应用；
代理（Proxy）：通过 headroom proxy --port 8787 启动本地代理，零代码改动接入任意语言的客户端；
智能体封装（Agent wrap）：一条命令即可为 Claude Code、Codex、Grok、Copilot、Cursor、Aider、Cline、Goose 等十余款主流编码代理启用压缩；
MCP 服务器：提供 headroom_compress、headroom_retrieve、headroom_stats 三个工具，供任意 MCP 客户端调用。

此外，它还提供跨代理共享记忆（自动去重）以及 headroom learn 模块，能够从失败会话中挖掘修正建议，写入 CLAUDE.local.md 等本地文件。

压缩原理

Headroom 的处理流水线由四个组件构成，全部在本地运行，数据不外传：

ContentRouter：识别内容类型，分发到合适的压缩器；
SmartCrusher：针对 JSON 数据的结构化压缩；
CodeCompressor：基于 AST 的代码压缩；
Kompress-v2-base：通用文本压缩模型，已发布在 Hugging Face。

CacheAligner 用于稳定 prompt 前缀，提升上游 KV 缓存命中率；CCR（Compress-Cache-Retrieve）机制则将原文缓存在本地，当模型需要细节时再通过 headroom_retrieve 取回，实现「可逆压缩」。

实测效果

官方在真实代理工作负载上公布的压缩效果：

代码搜索（100 条结果）：17,765 → 1,408 Token，节省 92%；
SRE 故障排查：65,694 → 5,118 Token，节省 92%；
GitHub Issue 分流：54,174 → 14,761 Token，节省 73%；
代码库探索：78,502 → 41,254 Token，节省 47%。

在 GSM8K、TruthfulQA、SQuAD v2、BFCL 等标准基准上，启用 Headroom 后准确率与基线基本持平，例如 GSM8K 均为 0.870，TruthfulQA 由 0.530 略升至 0.560。

输出侧压缩

除压缩输入外，Headroom 还对模型输出做瘦身：在 Opus 等输出费用约为输入 5 倍的模型上，自动剔除「Great, let me…」式开场白、重复代码以及对常规步骤的冗长思考过程，从而进一步降低单次调用总成本。该项目以 MIT 类开源协议发布，要求 Python 3.10 及以上环境。