Headroom：AI 代理的上下文压缩层

一句话简介：Headroom 是一个本地运行的上下文压缩层，在 AI 代理的工具输出、日志、RAG 结果到达 LLM 之前将它们压缩，用更少的 Token 获得同样的答案。

工具概览

核心功能

1. 多类型内容智能压缩

Headroom 的核心价值在于它能压缩所有类型的代理输入内容，而不仅仅是文本。它内置了三种压缩引擎：

• SmartCrusher：专为 JSON 数据设计，可将 JSON 数据压缩 60-95%，特别适合处理 API 响应、配置文件等结构化数据
• CodeCompressor：基于 AST（抽象语法树）的代码压缩，支持 Python、JS/TS、Go、Rust、Java、C/C++ 等语言
• Kompress-v2-base：基于 HuggingFace 上训练的文本压缩模型，针对 AI 代理交互场景优化

例如，一次 100 条结果的工具搜索输出从 17,765 Token 压缩到 1,408 Token（节省 92%），SRE 事件调试从 65,694 Token 压缩到 5,118 Token（节省 92%）。

2. 三种部署模式，灵活适配

Headroom 提供了三种使用方式，从开箱即用到深度集成都能满足：

• 代理模式（Proxy）：运行 headroom proxy --port 8787，零代码改动，任何语言都能用。代理会拦截所有 API 请求并实时压缩
• Agent 包装（Wrap）：一条命令即可包装主流 AI 编程代理：headroom wrap claude，支持 Claude Code、Codex、Grok、Cursor、Aider、Copilot、OpenClaw 等 15+ 工具
• 库模式（Library）：在 Python 或 TypeScript 代码中直接调用 compress(messages)，适合集成到自研应用中

3. 可逆压缩（CCR）

与传统的有损压缩不同，Headroom 采用 CCR（Compressed Context Retrieval）机制。压缩后的原始数据会缓存在本地，当 LLM 需要查看详细信息时，可以通过 headroom_retrieve 工具按需获取原文。这保证了压缩不会丢失关键信息。

4. 输出 Token 优化

大多数压缩工具只优化发送给 LLM 的输入，但 Headroom 还能减少模型返回的输出 Token。对于 Opus 类模型，输出成本是输入的 5 倍，这个优化非常关键。它通过两种方式实现：

• 简洁性引导：在系统提示末尾追加简短指令，让模型保持简洁、不复述上下文
• 努力度路由：对于例行步骤（如读取文件、通过测试），自动降低模型的思考努力度；对新问题和错误保持完整思考

5. 跨代理共享记忆

Headroom 支持跨多个 AI 代理（Claude、Codex、Gemini、Grok 等）的共享上下文记忆，自动去重。你可以在 Claude Code 中搜索到的代码上下文，在下次使用 Codex 时直接复用，无需重复搜索。

适用人群

• 日常使用 AI 编程代理的开发者和工程师：如果你每天使用 Claude Code、Cursor 或 Codex 进行编程工作，Headroom 能显著降低 Token 消耗
• 多代理工作者：同时使用多个 AI 编程工具的用户，共享记忆功能可以避免重复工作
• RAG 应用开发者：压缩 RAG 检索结果可以大幅减少上下文占用，提高检索效率
• 关注成本控制的团队：对于 LLM API 花费较高的团队，Headroom 的压缩效果可以直接转化为成本节约

与同类工具对比

Headroom 的核心差异化在于本地运行 + 全类型压缩 + 可逆设计，这在隐私敏感场景（企业内网、医疗、金融）中尤为重要。

如何使用

快速开始（60 秒）

第一步：安装

# 使用 uv 安装（推荐）
uv tool install --python 3.13 "headroom-ai[all]"

# 或使用 pip
pip install "headroom-ai[all]"

第二步：选择使用模式

# 模式 1：一键部署（本地服务 + 代理配置）
headroom deploy

# 模式 2：包装一个编程代理
headroom wrap claude

# 模式 3：手动代理模式
headroom proxy --port 8787

# 模式 4：在代码中使用库
from headroom import compress
compressed = compress(messages)

第三步：验证与监控

# 健康检查
headroom doctor

# 查看压缩效果
headroom perf

# 实时节省仪表盘（需代理运行中）
headroom dashboard

完整使用示例：包装 Claude Code

# 安装
pip install "headroom-ai[all]"

# 包装 Claude Code（自动启动代理 + 安装 Serena 语义导航）
headroom wrap claude

# 正常使用 Claude Code，所有请求自动通过 Headroom 压缩
# 使用完成后，恢复原状
headroom unwrap claude

在 Python 代码中使用

from headroom import compress

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Help me debug this error..."},
    {"role": "assistant", "content": "Let me look at the logs..."},
    {"role": "user", "content": "<large_tool_output_json>"},
]

compressed_messages = compress(messages)
# 返回压缩后的消息列表，Token 大幅减少

实测数据

Headroom 在真实代理工作负载上的压缩效果：

基准测试显示的准确性保持情况：

总结

Headroom 是一个设计精良的 AI 代理工具，解决了 Agent 场景中一个长期被忽视的问题：上下文爆炸。当 AI 代理调用工具、读取文件、检索知识库时，产生的大量文本会迅速填满 LLM 的上下文窗口，既浪费 Token 又可能稀释关键信息。

Headroom 的优势在于： 1. 本地优先：数据不出本机，隐私安全有保障 2. 全类型压缩：JSON、代码、文本全覆盖，不限于单一格式 3. 可逆设计：原文可检索，不担心信息丢失 4. 开箱即用：一条命令包装主流代理，零代码改动 5. 跨代理记忆：不同代理间共享上下文，效率倍增

推荐指数：★★★★☆（4.5/5）

对于每天使用 AI 编程代理的开发者来说，Headroom 是一个值得安装的工具。它不仅能降低 Token 成本，还能通过压缩后的更精准上下文提升代理的工作质量。唯一的潜在短板是增加了本地运行组件的复杂度，但对于重度用户来说，这点代价完全值得。

想精确计算压缩前后的 Token 差异？用 文本计数器 统计输入输出长度，配合 Headroom 的压缩比数据做成本估算。

相关链接：GitHub 仓库 · 官方文档 · Discord 社区