🧭 核心功能与工作原理

Headroom 通过智能压缩工具输出、日志、代码和对话历史，来降低 LLM 调用成本并提高响应速度。它运行在本地，数据不会外传。

核心工作流程：

  1. 拦截内容：在 AI 代理的提示词（prompt）到达 LLM 之前，Headroom 通过代理、库或 MCP 服务器拦截它。
  2. 智能路由与压缩：
    • ContentRouter 检测内容类型（JSON、代码、文本）。
    • SmartCrusher 深度压缩 JSON 数据。
    • CodeCompressor 基于抽象语法树（AST）压缩代码。
    • Kompress-v2-base（专用模型）压缩自然语言文本。
  3. 可逆缓存（CCR）：原始内容被本地缓存。如果 LLM 需要完整信息，可以通过 headroom_retrieve 工具按需获取。
  4. 发送给 LLM：压缩后的提示词被发送给 LLM 提供商（如 Anthropic、OpenAI），节省大量 token。

主要部署模式：

  • 库（Library）：直接在 Python 或 TypeScript 代码中调用 compress() 函数。
  • 代理（Proxy）：运行一个本地代理，所有流量经过它，无需修改代码。
  • MCP 服务器：为任何 MCP 客户端提供压缩工具。
  • Agent 包装（Wrap）：一键包装主流 AI 编码代理（headroom wrap claude）。

📦 安装

1. 环境要求

  • Python 版本：需要 Python 3.10 或更高版本。推荐使用 Python 3.13 以获得最佳兼容性（特别是 LiteLLM 计费功能）。
  • 包管理器：推荐使用 uv（快速 Python 包管理器），也可使用 pip 或 pipx。

2. 安装 Headroom

使用 uv（推荐，能获得完整的 CLI 功能）：

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

使用 pip：

1
pip install "headroom-ai[all]"

使用 npm（仅 TypeScript SDK，不包含 CLI 命令）：

1
npm install headroom-ai

🚀 快速开始（60秒）

安装完成后，可以通过以下方式立即使用。

方式一：包装你的 AI 编码代理（最简单）

这是最推荐的方式，尤其适合 Claude Code、Codex、Cursor 等工具。

1
2
3
4
5
6
7
8
9
10
11
# 包装 Claude Code（会自动启动代理并配置）
headroom wrap claude

# 包装 Codex
headroom wrap codex

# 包装 Cursor（会打印代理地址，需在 Cursor 设置中手动配置）
headroom wrap cursor

# 查看所有支持的代理
headroom wrap --help

包装后，代理的所有请求都会经过 Headroom 压缩。撤销包装使用 headroom unwrap <tool>。

方式二：运行独立代理（适合任何客户端）

如果你使用的是自定义脚本或不支持 wrap 的工具，可以单独启动代理。

1
headroom proxy --port 8787

然后，将你的 LLM 请求的 base_url 指向 http://localhost:8787。

方式三：在 Python 代码中作为库使用

1
2
3
4
from headroom import compress

# 压缩消息列表
compressed_messages = compress(messages, model="your-model-name")

⚙️ 核心功能与配置

1. 输出 Token 缩减

除了压缩输入，Headroom 还能减少模型输出的 token 量（如去掉客套话、重复代码）。通过环境变量启用（可实时生效）：

1
2
export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

2. 监控与统计

  • 仪表盘：headroom dashboard（需要代理正在运行）。
  • 健康检查：headroom doctor。
  • 性能测试：headroom perf。
  • 查看节省量：headroom savings。

3. 跨代理共享记忆

Headroom 为 Claude、Codex、Gemini 等代理提供共享的、自动去重的记忆存储。这是通过 headroom wrap 自动启用的。

4. 从失败中学习

headroom learn 命令能分析过去失败的会话，并将修正建议写入本地的 CLAUDE.local.md 文件（可被 Claude Code 等工具读取）。

1
2
headroom learn              # 预览发现的问题
headroom learn --apply      # 应用修正

❓ 常见问题与注意事项

  • 数据隐私：Headroom 完全在本地运行，你的数据（提示词、文件）不会发送给 Headroom 的服务器。原始内容缓存在本地，可通过配置的 TTL 控制保留时间。
  • 兼容性：支持所有主要 AI 提供商（Anthropic、OpenAI、Google、Bedrock 等）和框架（LangChain、Vercel AI SDK、LiteLLM）。
  • CPU 要求：在 x86/x86_64 机器上，需要 CPU 支持 AVX2 指令集以运行 ONNX 加速功能。如果不支持，会自动降级。
  • 网络环境：在企业网络（SSL 检查）下安装或运行时，可能遇到证书问题。需要设置环境变量信任企业 CA 证书，或预下载依赖的模型文件（kompress-base）和 ONNX Runtime。
  • 更新：使用 headroom update 命令可自动检测安装方式并升级到最新版本。

总结

Headroom 是一个为 AI 代理时代设计的实用工具，其核心价值在于通过本地、智能的压缩技术，显著降低 LLM 使用成本并提升效率。对于日常使用 AI 编码代理的开发者，强烈推荐从 headroom wrap <your-agent> 开始，这是最快看到效果的方式。其代理模式和 MCP 服务器为更复杂的集成提供了灵活性。项目处于活跃开发状态，拥有详细的文档和活跃的社区支持。