Headroom：AI令牌优化与上下文压缩工具

概述

Headroom 是面向 AI Agent 的上下文压缩层。它在本地对工具输出、日志、RAG 片段、文件与会话历史进行压缩后再发送给 LLM,从而减少输入与输出两端的 token 消耗。所有压缩过程在用户机器上完成,原始数据不会上传到外部服务。

使用形态

• SDK 库:在 Python 或 TypeScript 中调用 compress(messages),直接在应用内联使用。
• 本地代理:headroom proxy --port 8787,无需修改代码,任意语言客户端均可接入。
• Agent 封装:一条命令即可包裹 Claude、Codex、Grok、Copilot、Cursor、Aider、OpenCode 等主流编码 Agent;headroom unwrap <tool> 可恢复原状。
• MCP 服务器:暴露 headroom_compress、headroom_retrieve、headroom_stats 给任意 MCP 客户端。
• 跨 Agent 记忆:Claude、Codex、Gemini、Grok 共享同一存储,并自动去重。
• headroom learn:从失败会话中挖掘经验,写入 CLAUDE.local.md 等规则文件。
• CCR 可逆压缩:原始内容在本地缓存,模型可通过检索工具按需取回。

技术架构

压缩流水线由 CacheAligner → ContentRouter → CCR 串联组成:

• ContentRouter 检测内容类型并分派压缩器。
• SmartCrusher 处理 JSON 数组与嵌套对象,基于字段方差统计保留关键项。
• CodeCompressor 对 Python、JS/TS、Go、Rust、Java 等语言的源码进行 AST 感知压缩。
• Kompress-v2-base 是发布在 HuggingFace 上的专用文本压缩模型。
• CacheAligner 标记可能破坏 provider KV 缓存前缀的易变内容,不会改写 prompt。
• CCR 本地存储原文件,供 headroom_retrieve 反向调用。
• 仅对 live-zone(新工具输出、最新一轮)做压缩,冻结前缀保持字节一致,保证 provider 缓存命中率。

快速上手

# 1. 安装
uv tool install --python 3.13 "headroom-ai[all]"   # CLI + 全功能
pip install "headroom-ai[all]"                     # Python,含 CLI
npm install headroom-ai                            # 仅 TypeScript SDK

# 2. 选择模式
headroom deploy          # 本地一键部署 + Agent 配置
headroom wrap claude     # 包裹编码 Agent
headroom proxy --port 8787  # 透明代理,零代码改造

# 3. 验证与观测
headroom doctor          # 健康检查
headroom perf
headroom dashboard       # 实时节省面板

Python 内联调用:

from headroom import compress
from openai import OpenAI

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

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

输出 Token 压缩

除输入压缩外,Headroom 还在代理层对模型输出做精简,降低 Opus 等高价模型的回写成本:

• Verbosity Steering:在系统提示末尾追加简短指令,使 prompt 缓存仍命中。
• Effort Routing:仅在机械轮次(读文件、跑测试)下调推理强度,新问题与异常保留满额思考。

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

headroom learn --verbosity 会从历史会话中推断用户的简洁偏好。headroom output-savings 给出带置信区间的估算;设置 HEADROOM_OUTPUT_HOLDOUT=0.1 后转为对照实测值。

压缩效果

四类真实 MCP 输出场景的基准数据:

场景	压缩前	压缩后	节省
代码搜索(100 条结果)	17,199	13,597	21%
SRE 故障排查	55,957	24,340	57%
代码库探索	58,801	33,895	42%
GitHub Issue 分诊	46,067	32,429	30%

压缩耗时极低:10K token JSON 的 p50 约 0.21 ms,100K token 约 1.4 ms,对 Agent 延迟影响可忽略。准确率方面,GSM8K、TruthfulQA、SQuAD v2、BFCL 评测显示压缩前后无显著差异。

Agent 兼容性

headroom wrap 已覆盖 Claude Code、Codex、Grok CLI、Aider、Copilot CLI、VS Code Copilot、OpenCode、Cline、Continue、Goose、OpenHands、Mistral Vibe、Kimi CLI、ZCode 等;Cursor 与 Cortex Code 需手动配置。任意 OpenAI 兼容客户端只需将 base URL 指向本地代理即可。

卸载时执行 headroom unwrap <tool> 即可恢复。GitHub Copilot 与 VS Code Claude Code 插件支持订阅模式与 1M 上下文透传。

集成方式

技术栈	接入方式
Python / TypeScript	compress(messages, model=…)
Anthropic / OpenAI SDK	withHeadroom(new Anthropic())
Vercel AI SDK	wrapLanguageModel({ model, middleware: headroomMiddleware() })
LiteLLM	litellm.callbacks = [HeadroomCallback()]
LangChain / Agno	HeadroomChatModel(your_llm) / HeadroomAgnoModel(your_model)
ASGI 应用	app.add_middleware(CompressionMiddleware)
多 Agent	SharedContext().put / .get
MCP 客户端	headroom mcp install

安装与更新

uv tool install --python 3.13 "headroom-ai[all]"
pip install "headroom-ai[all]"
npm install headroom-ai
docker pull ghcr.io/headroomlabs-ai/headroom:latest

细粒度可选 extras: [proxy]、[mcp]、[ml]、[code]、[memory]、[vector](需 C++ 工具链,不在 [all] 中)、[relevance]、[image]、[agno]、[langchain]、[evals]、[pytorch-mps]。需要 Python 3.10+。

headroom update          # 自动识别 pip / pipx / uv tool 并原地升级
headroom update --check  # 仅查询最新版本

适用与局限

适合场景:每日高频使用编码 Agent、需要跨 Agent 共享记忆、希望压缩可逆(CCR)的用户。短对话、散文、已极度精简的负载收益有限,低于 min_input_words 阈值的输入会原样返回。若仅使用单一 provider 的原生压缩、且不需要跨 Agent 记忆,或运行环境禁止本地进程,可考虑跳过。

遥测

默认开启匿名信标,上报压缩比例、计数器、provider 与模型 ID、操作系统与架构等信息,用于改进压缩策略。