每个 AI 编码代理都面临同样的问题：Token 成本。每个工具调用的输出、每个文件的读取、每段日志都会被塞进上下文窗口并按 Token 计费。对于在大型代码库上运行 Claude Code、Cursor 或 Codex 的团队来说，这些成本会累积成真金白银——以及上下文窗口的头痛问题。
Headroom 是一个开源的、本地优先的 Token 压缩层，位于您的 AI 代理和 LLM 提供商之间，在数据到达 API 之前压缩 AI 代理读取的所有内容——工具输出、日志、RAG 块、文件和对话历史。
Headroom 是什么？#
Headroom 是一个上下文优化引擎，可实现对 JSON 数据 60-95% 的 Token 节省 和 编码代理 15-20% 的 Token 节省，同时保持相同的答案和行为准确性。它是完全可逆的——原始数据缓存在本地，当 LLM 需要完整数据时可以随时检索。
它支持四种模式：
- 代理模式 — 零代码更改的即插即用代理 (
headroom proxy --port 8787) - Agent 包装 — 一条命令包装 Claude Code、Codex CLI、Cursor 等 18+ 代理
- Python/TypeScript 库 — 在代码中内联调用
compress() - MCP 服务器 — 向任何 MCP 兼容的代理提供压缩工具
该项目基于 Python 核心 + Rust 扩展（通过 PyO3）构建，在 AST 解析和压缩方面兼具灵活性和原生性能。
为什么 Headroom 很重要#
Token 节省是真实的#
| 数据类型 | 压缩率 | 方法 |
|---|---|---|
| JSON 工具输出 | 60–95% | SmartCrusher — 通用 JSON 压缩器 |
| 代码文件 | AST 感知 | CodeCompressor（Python, JS/TS, Go, Rust, Java, C/C++, Perl） |
| 散文/文本 | v2 转换器 | Kompress-v2-base（在代理轨迹上训练） |
| 图像 | 40–90% | ML 路由器 + OCR（RapidOCR/SigLIP） |
| 编码代理会话 | 15–20% | 所有压缩器的组合 |
提供商 KV 缓存安全#
Headroom 的实时区域压缩仅压缩新传入的字节（新工具输出、最新轮次），同时保持冻结前缀字节一致。这一点至关重要，因为提供商的 KV 缓存（如 Anthropic 提示缓存）基于字节精确匹配的前缀进行缓存。如果更改前缀，就会破坏缓存。Headroom 从不这样做。
可逆压缩#
当 LLM 需要被裁剪的数据时，Headroom 的 CCR（缓存上下文检索） 系统将原始数据本地存储在 SQLite 或 Redis 中，并注入轻量级检索标签 (<<ccr:HASH>>)。代理可以调用 headroom_retrieve 按需获取原始负载。
输出 Token 缩减#
Headroom 不仅压缩您发送的内容——它还通过以下方式缩减模型写回的内容：
- 详细度控制 — 在提示中添加简洁指令
- 努力路由 — 在读取文件等常规步骤上降低推理预算
支持的集成#
18+ AI 编码代理（通过 headroom wrap）：
Claude Code、Codex CLI、Cursor、Aider、GitHub Copilot CLI、OpenCode、Cline、Continue、OpenClaw、Goose、OpenHands、Mistral Vibe、Oh My Pi、ZCode。
SDK 和框架： Anthropic SDK、OpenAI SDK、Vercel AI SDK、LiteLLM、LangChain、Agno、Strands Agents SDK、FastAPI/ASGI 中间件
安装#
# Python（推荐使用 uv）
uv tool install --python 3.13 "headroom-ai[all]"
# 或通过 pip
pip install "headroom-ai[all]"
# TypeScript SDK
npm install headroom-ai快速开始#
代理模式（零代码更改）#
headroom proxy --port 8787
# 将 LLM 客户端指向 http://localhost:8787Agent 包装模式#
headroom wrap claude
# Claude Code 现在自动发送压缩后的输入
headroom unwrap claude # 撤消内联库使用#
from headroom import compress
compressed = compress(large_json_payload)工作原理#
Agent / App → Headroom Proxy / Library → LLM Provider- 接收输入 — 拦截传入的提示消息或工具负载流
- CacheAligner — 检查并警告可能破坏提供商 KV 缓存前缀的易变内容
- ContentRouter — 检测内容类型（Magika/启发式分析）并选择最佳压缩器
- CCR — 在本地存储原始详细字符串，注入检索标签
- 转发优化后的负载 到 LLM
headroom learn 功能#
Headroom 在本地挖掘过去失败的会话，并自动将修正写入代理内存配置文件（CLAUDE.local.md、AGENTS.md）。这使得代理能够随着时间的推移从自己的错误中学习。
跨代理内存#
一个共享的、去重后的上下文存储，可在同一台机器上的多个 AI 编码代理之间工作。Claude Code、Cursor 和 Codex 可以共享通用内存，而不会重复上下文。
比较#
| 功能 | Headroom | 原生提供商压缩 | 提示缓存代理 |
|---|---|---|---|
| 压缩率 | 60–95%（JSON）, 15–20%（代码） | 可变（丢失上下文） | 无（仅缓存） |
| 可逆 | ✅ CCR 检索 | ❌ 丢失上下文 | ❌ |
| KV 缓存安全 | ✅ CacheAligner | ✅ 同一提供商 | ✅ 同一提供商 |
| 输出缩减 | ✅ 详细度控制 | ❌ | ❌ |
| 跨代理内存 | ✅ 共享上下文存储 | ❌ | ❌ |
| 自我学习 | ✅ headroom learn | ❌ | ❌ |
| 代理集成 | 18+ | 各有不同 | 各有不同 |
| 代码更改 | 零（代理/包装） | 无 | 无 |
总结#
Headroom 解决了 AI 辅助开发中的一个根本性低效问题：向 LLM API 发送冗长、未压缩的数据。凭借 JSON 60-95% 的压缩率、可逆检索、KV 缓存安全的压缩以及零代码更改集成，它是任何大规模使用 AI 编码代理团队最实用的成本节省工具之一。
Apache 2.0 许可、本地优先、可通过 Python + Rust 扩展——Headroom 是任何 AI 代理工作流的即插即用升级。