Headroom 完全指南：面向 LLM 应用的上下文优化层——透明代理、compress() SDK 与两阶段压缩管线

本文基于 Headroom 项目的主文档（wiki/index.md），系统介绍 Headroom 的定位、四种接入方式（零代码代理、Python/TypeScript SDK、编码 Agent 包装、框架集成）、两阶段压缩管线的源码级实现，以及云端后端与安装依赖细节。读完你可以掌握：如何用 headroom proxy 在不改一行代码的前提下为任意 LLM 应用削减 token，如何用 compress() 函数级嵌入自有 Python 客户端，以及 ContentRouter 如何按内容类型路由到不同的压缩器。

1. Headroom 是什么：LLM 应用的上下文优化层

Headroom 将自身定位为 The Context Optimization Layer for LLM Applications（LLM 应用的上下文优化层）：压缩你的 AI Agent 读取的一切内容——工具输出、日志、数据库查询结果、RAG 检索片段、文件读取、API 响应——在它们进入模型之前完成压缩。官方口径是"同样的回答，几分之一的 token"。

从 wiki/index.md 的核心论断看：Agent 的每次工具调用、DB 查询、文件读取、RAG 检索中，70-95% 是样板噪声（boilerplate）。Headroom 在内容到达模型前把这些噪声压缩掉，使 LLM 看到更少的噪声、响应更快、成本更低。

整体数据流如下（继承自原文档）：

Your Agent / App
    │
    │  tool outputs, logs, DB reads, RAG results, file reads, API responses
    ▼
 Headroom  ← proxy, Python library, or framework integration
    │
    ▼
 LLM Provider  (OpenAI, Anthropic, Google, Bedrock, 100+ via LiteLLM)

Headroom 有三种基本工作形态：

1. 透明代理（transparent proxy）：零代码改动，把任意工具的 API 指向本地代理即可；
2. Python 函数（compress()）：在应用代码中显式调用压缩管线；
3. 框架集成：LangChain、Agno、Strands、LiteLLM、MCP 等。

项目当前版本可从 pyproject.toml 确认：包名 headroom-ai，版本 0.37.0，描述为 "The Context Optimization Layer for LLM Applications"，要求 Python ≥ 3.10，Apache-2.0 协议，可免费商用。

2. 快速上手：四种接入方式

2.1 透明代理（零代码改动）

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

然后把任意工具指向代理：

# Point any tool at the proxy
ANTHROPIC_BASE_URL=http://localhost:8787 claude
OPENAI_BASE_URL=http://localhost:8787/v1 your-app

就这样。现有代码不做任何修改即可运行，原文档声称可获得 40-90% 的 token 削减。从 headroom/cli/doctor.py 与 headroom/cli/init.py 的源码可以确认，代理默认端口为 8787，且可用环境变量 HEADROOM_PORT 覆盖。

如果希望代理作为常驻本地运行时（wrap 可复用或自动恢复），参见 持久化安装。

2.2 Python SDK：compress()

from headroom import compress

result = compress(messages, model="claude-sonnet-4-5-20250929")
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    messages=result.messages,
)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

适用于任何 Python LLM 客户端。完整指南见 Python SDK 文档。

源码级补充。 compress() 的真实签名与返回结构定义在 headroom/compress.py：

def compress(
    messages: list[dict[str, Any]],
    model: str = "claude-sonnet-4-5-20250929",
    model_limit: int = 200000,
    optimize: bool = True,
    hooks: Any = None,
    config: CompressConfig | None = None,
    **kwargs: Any,
) -> CompressResult:

关键参数：

• messages：Anthropic 或 OpenAI 格式的消息列表；
• model：模型名，用于 token 计数与上下文窗口判定；
• model_limit：模型上下文窗口（token 数），默认 200000；
• optimize：设为 False 时直通不压缩（用于 A/B 测试）；
• config / **kwargs：CompressConfig 可选项，包括 compress_user_messages、target_ratio、protect_recent、protect_analysis_context、kompress_model、frozen_message_count 等。

返回的 CompressResult（headroom/compress.py）包含 messages（压缩后的消息）、tokens_before、tokens_after、tokens_saved、compression_ratio（0.0 表示无节省，1.0 表示全部移除）与 transforms_applied（实际应用的变换列表）。

从源码结构看，compress() 内部会：先复制 CompressConfig 防止 kwargs 覆盖污染调用方持有的共享配置；再通过 hooks 的 pre_compress / compute_biases 计算压缩偏置；提取用户查询作为相关性上下文（让 SmartCrusher 不仅按统计特征、也按与用户问题的相关性来保留内容）；最后调用管线并带有一个膨胀保护——若压缩后 token 反而变多，直接回退为原始消息并记录告警（headroom/compress.py），与代理侧各 provider handler 的 inflation guard 保持一致。

2.3 编码 Agent：headroom wrap

headroom wrap claude       # Claude Code
headroom wrap copilot -- --model claude-sonnet-4-20250514
headroom wrap codex        # OpenAI Codex CLI
headroom wrap aider        # Aider
headroom wrap cursor       # Cursor
headroom wrap openclaw     # OpenClaw plugin bootstrap

wrap 会启动代理、把你的工具指向它、并自动压缩一切。从 headroom/cli/wrap.py 源码可见，wrap 是按工具拆分的子命令（claude、copilot、codex 等），均支持 --port（默认 8787）、--memory（启用跨会话持久记忆）、--no-proxy（复用已存在的代理）、--prepare-only 等选项，-- 之后的参数会原样透传给被包装的 CLI。

2.4 TypeScript SDK

import { compress } from 'headroom-ai';

const result = await compress(messages, { model: 'claude-sonnet-4-5-20250929' });
// Use result.messages with any LLM client
console.log(`Saved ${result.tokensSaved} tokens`);

兼容 Vercel AI SDK、OpenAI Node SDK 与 Anthropic TS SDK。完整指南见 TypeScript SDK 文档，源码位于 sdk/typescript/。

2.5 LiteLLM 回调

import litellm
from headroom.integrations.litellm_callback import HeadroomCallback

litellm.callbacks = [HeadroomCallback()]
# All 100+ providers now compressed automatically

通过 LiteLLM 回调机制，把压缩能力扩展到 LiteLLM 支持的全部 100+ 提供商（Together、Groq、Fireworks、Ollama、vLLM 等）。

3. 框架集成

原文档列出六类集成，全部继承如下：

LangChain —— 包装任意 chat model，支持 memory、retrievers、tools、streaming、async：

from headroom.integrations import HeadroomChatModel

llm = HeadroomChatModel(ChatOpenAI(model="gpt-4o"))

指南见 LangChain 集成。

Agno —— 完整的 Agent 框架集成，带可观测性钩子：

from headroom.integrations.agno import HeadroomAgnoModel

model = HeadroomAgnoModel(Claude(id="claude-sonnet-4-20250514"))
agent = Agent(model=model)

指南见 Agno 集成。

Strands —— Strands Agents 的模型包装 + 工具输出 hook provider：

from headroom.integrations.strands import HeadroomStrandsModel

model = HeadroomStrandsModel(wrapped_model=bedrock_model)
agent = Agent(model=model)

指南见 Strands 集成。

MCP 工具 —— 面向 Claude Code、Cursor 或任意 MCP 客户端的三个工具：headroom_compress、headroom_retrieve、headroom_stats：

headroom mcp install && claude

从 headroom/ccr/mcp_server.py 源码可确认三个工具的职责：headroom_compress 按需压缩内容（无需代理），headroom_retrieve 按 hash 取回未压缩的原文，headroom_stats 输出会话级压缩统计（压缩次数、节省量、成本）。指南见 MCP 文档。

TypeScript SDK —— compress()、Vercel AI SDK 中间件、OpenAI 与 Anthropic 客户端包装：

npm install headroom-ai

OpenClaw —— OpenClaw Agent 的 ContextEngine 插件，在 assemble() 中自动压缩上下文：

headroom wrap openclaw

插件源码在 plugins/openclaw/。全部集成模式见 集成指南。

4. 工作原理：两阶段管线

Headroom 对每个请求运行两阶段管线（继承自原文档）：

Your Prompt → CacheAligner → ContentRouter → LLM Provider
                              │── JSON  → SmartCrusher
                              │── Code  → CodeCompressor
                              │── Text  → Kompress
                              └── Logs  → LogCompressor

阶段 1：CacheAligner —— 稳定消息前缀，让提供商的 KV 缓存真正命中。Claude 对缓存前缀提供 90% 的读取折扣，CacheAligner 的作用就是让这种缓存命中实际发生。

阶段 2：ContentRouter —— 自动检测内容类型（JSON、代码、日志、搜索结果、diff、HTML、纯文本），并路由到最优压缩器：

内容类型	压缩器	工作原理
JSON 数组	SmartCrusher	统计分析：保留错误、异常、边界。无硬编码规则。
源代码	CodeCompressor	AST 感知（tree-sitter）。保留函数签名，折叠函数体。
纯文本	Kompress	ModernBERT token 分类。移除冗余 token 同时保留语义。
构建/测试日志	LogCompressor	保留失败、错误、警告。丢弃通过的噪声。
搜索结果	SearchCompressor	按与用户查询的相关性排序，保留最相关的匹配。
Git diff	DiffCompressor	保留变更块（hunks），丢弃未变更上下文。
HTML	HTMLExtractor	剥离标记，提取可读内容。

这些压缩器在源码中一一对应到 headroom/transforms/ 目录下的独立模块：smart_crusher.py、code_compressor.py、kompress_compressor.py、log_compressor.py、search_compressor.py、diff_compressor.py、html_extractor.py；路由与缓存稳定逻辑分别在 content_router.py（compress(CompressInput) -> CompressOutput）与 cache_aligner.py。

上下文管理：管线内部自动处理，采用 live-zone-only（仅活跃区）压缩策略——只压缩最新的内容块（最近一条用户消息与工具结果），从不丢弃历史消息。系统提示词、工具定义与较早的对话轮次属于提供商缓存的"热区"，保持原样不动，从而让 prompt caching 持续生效。

内容不会丢失：被压缩的内容进入 CCR 存储（Compress-Cache-Retrieve，源码见 headroom/ccr/）。LLM 会获得一个 headroom_retrieve 工具，需要更多细节时可以取回完整原文。架构细节见 架构文档，CCR 原理见 CCR 文档。

5. 结果与基准数据

原文档给出的标志性示例：100 条生产日志，1 条关键错误埋在位置 67。

指标	基线	Headroom
输入 token	10,144	1,260
正确回答数	4/4	4/4

token 减少 87.6%，答案不变。 FATAL 错误被自动保留——不是靠关键词匹配，而是靠对字段方差（field variance）的统计分析。

真实负载

场景	压缩前	压缩后	节省
代码搜索（100 条结果）	17,765	1,408	92%
SRE 事故调试	65,694	5,118	92%
代码库探索	78,502	41,254	47%
GitHub issue 分诊	54,174	14,761	73%

准确性基准

基准	类别	样本数	准确率	压缩率
GSM8K	数学	100	0.870	0.000 delta
TruthfulQA	事实	100	0.560	+0.030 delta
SQuAD v2	QA	100	97%	19% 削减
BFCL	工具/函数	100	97%	32% 削减
CCR Needle	无损	50	100%	77% 削减

完整基准方法见 基准文档，已知限制见 限制文档。仓库内还有配套的基准脚本可供复现与深入分析，例如 benchmarks/compression_benchmark.py、benchmarks/agent_cost_benchmark.py 与 benchmarks/ccr_regression_benchmark.py。

6. 核心特性一览

原文档列出八项关键特性，全部继承：

• 无损压缩（CCR）：激进压缩、存储原文、给 LLM 一个取回全部细节的工具，什么都不丢弃。见 CCR 文档。
• 智能内容检测：自动识别 JSON、代码、日志、文本、diff、HTML，路由到最优压缩器，零配置。见 压缩文档。
• 缓存优化：稳定前缀使提供商 KV 缓存命中，跟踪冻结消息以保住 90% 读取折扣。
• 图片压缩：经训练的 ML 路由器按图选择 resize/质量权衡，实现 40-90% 的图片 token 削减。见 图片压缩文档。
• 持久记忆：分层记忆（user/session/agent/turn），SQLite + HNSW 后端，跨对话存活。见 记忆文档。从 pyproject.toml 的 memory extra 可确认：默认使用纯 Python 的 sqlite-vec 后端（无需 C++ 工具链），可选 vector extra 启用 HNSW。
• 失败学习：读取历史会话、找出失败的工具调用、与成功调用做关联、把学习结果写入 CLAUDE.md。见 Learn 文档。
• 多 Agent 上下文：压缩 Agent 之间流转的内容，任意框架可用：

ctx = SharedContext()
ctx.put("research", big_output)
summary = ctx.get("research")  # ~80% smaller

见 共享上下文文档。

• 指标与可观测性：Prometheus 端点、逐请求日志、成本跟踪、预算限制、管线耗时分解。见 指标文档。

7. 云端提供商与代理后端

开箱即用支持任意 LLM 提供商（继承自原文档）：

headroom proxy                                          # Direct Anthropic/OpenAI
headroom proxy --backend bedrock --region us-east-1     # AWS Bedrock
headroom proxy --backend vertex_ai --region us-central1 # Google Vertex AI
headroom proxy --backend azure                          # Azure OpenAI
headroom proxy --backend openrouter                     # OpenRouter (400+ models)

或经 LiteLLM 覆盖 100+ 提供商。

源码级参数说明。 headroom/cli/proxy.py 中 --backend 选项的定义给出了完整取值集合与默认值：

• --backend：默认 anthropic（直连），可选 bedrock（AWS）、openrouter、anyllm（any-llm）或 litellm-<provider>（如 litellm-vertex）；对应环境变量 HEADROOM_BACKEND；
• --region：Bedrock/Vertex 等的云区域，默认 us-west-2，环境变量 HEADROOM_REGION；--bedrock-region 已标记为 deprecated，应改用 --region；
• --bedrock-profile：Bedrock 使用的 AWS profile（默认走默认凭据链）；
• --bedrock-api-url：自定义 Bedrock InvokeModel 上游，注意注释中明确要求指向重签名网关（LiteLLM、LocalStack）而非裸 AWS——改写请求体会破坏 SigV4 签名；
• 各 provider 还可分别用 --anthropic-api-url、--openai-api-url、--gemini-api-url、--vertex-api-url 覆盖目标上游，分别对应环境变量 ANTHROPIC_TARGET_API_URL、OPENAI_TARGET_API_URL、GEMINI_TARGET_API_URL、VERTEX_TARGET_API_URL；
• --telemetry / --no-telemetry：匿名用量遥测默认关闭；
• --stateless：禁用一切文件系统写入，纯内存运行。

相关文档：代理文档、Vertex 文档、Docker 安装。

8. 安装与依赖矩阵

uv tool install --python 3.13 "headroom-ai[all]"  # CLI on macOS Apple Silicon/Linux
pip install headroom-ai                # Core library (Python)
pip install "headroom-ai[all]"         # Everything (recommended)
npm install headroom-ai                # TypeScript / Node.js
pip install "headroom-ai[proxy]"       # Proxy server + MCP tools
pip install "headroom-ai[ml]"          # ML compression (Kompress, requires torch)
pip install "headroom-ai[langchain]"   # LangChain integration
pip install "headroom-ai[agno]"        # Agno integration
pip install "headroom-ai[evals]"       # Evaluation framework

要求 Python 3.10+。原文档特别提醒：在 macOS 上，如果你的默认 python3 比当前 wheel 集合更新，CLI 安装路径（uv/pipx）请使用 Python 3.13。

pyproject.toml 中的 extra 全貌（比原文档更完整的依赖边界）：

Extra	内容	备注
proxy	fastapi、uvicorn、httpx[http2]、openai、mcp（<2.0）、magika、zstandard、websockets、onnxruntime、transformers、watchdog、sqlite-vec	代理服务器 + MCP 工具；mcp 固定在 1.x 是因为服务端仍用 v1 Server 装饰器 API
proxy-prod	headroom-ai[proxy] + gunicorn	仅 Unix，生产部署用
code	tree-sitter-language-pack（<1.0）、tree-sitter	CodeCompressor 的 AST 依赖；<1.0 固定是为了保持 node-walk 逻辑兼容
ml	torch（Intel Mac 除外）、transformers、huggingface-hub（>=1.5.0,<2.0）	Kompress 的 ModernBERT 压缩；huggingface-hub 下限固定防止 Kompress 静默降级为不可用
memory	sqlite-vec、sentence-transformers（Intel Mac 除外）	默认纯 Python sqlite-vec 后端，无 C++ 工具链要求
vector	hnswlib	可选 HNSW 后端，需 C++ 工具链编译，故不并入 memory/all
memory-stack	mem0ai、qdrant-client、neo4j	Qdrant + Neo4j 记忆后端辅助

核心依赖（无 extra 即安装）保持轻量：tiktoken（token 计数）、pydantic、litellm（仅模型注册表/定价，惰性导入且带 ImportError 保护）、click、rich、ast-grep-cli、pyyaml。值得注意的是 pyproject.toml 中对 ast-grep-cli 显式排除 0.44.1——该 PyPI 版本被确认为遭供应链投毒的构建（附带窃密可执行文件），这是依赖排除注释中少有的安全事件实录。

9. 下一步阅读

• 快速上手 —— 5 分钟跑起来
• 集成指南 —— 把 Headroom 加入你技术栈的每一种方式
• 架构 —— 管线底层如何工作
• 基准 —— 准确率与延迟数据
• 限制 —— 压缩何时有效、何时无效
• 文件系统契约 —— 规范化的配置/工作区环境变量与路径

Headroom 采用 Apache 2.0 协议，可免费商用；项目主页、PyPI 与 Discord 入口在 wiki/index.md 页脚列出。