1. Headroom 是什么

Headroom 是一款面向 AI Agent 的上下文压缩层。它在 LLM 收到请求之前，对工具输出、日志、RAG 片段、文件内容和对话历史做内容感知压缩，把 token 用量压到原来的 5%～40%，同时尽量保持回答质量不变。

简单说，它解决的是另一头的问题：CodeGraph 帮 agent 更快找到该读什么；Headroom 帮 agent 更省地读已经找到的内容。

项目已发布到 PyPI 和 npm：headroom-ai。支持 Claude Code、Cursor、Codex、Copilot CLI、OpenCode、Cline、Continue 等主流 AI 编程工具。

• 项目仓库：https://github.com/chopratejas/headroom
• 官方文档：https://headroom-docs.vercel.app/docs

2. 为什么需要它

AI 编程助手在干活时，真正烧 token 的往往不是你的提问，而是工具返回——一次 grep 几百行、一次 API 调用几千行 JSON、一次 metrics 查询 60 个重复数据点。这些内容大部分对当前任务来说是冗余的，但 agent 必须把它们整段塞进上下文。

Headroom 的思路是：在请求发往 LLM 之前，按内容类型选压缩器，把冗余剥掉；若压缩过头，agent 还能通过 CCR（Compress-Cache-Retrieve）按需取回原文。

没有 Headroom，agent 为重复数据付全款；有了 Headroom，agent 先读摘要，需要细节再检索。

3. 有/无 Headroom 对比

3.1 同一个场景，两条路径

假设 agent 正在排查一次 SRE 故障，连续调用了 metrics、logs、deployments 等 5 个工具。

不使用 Headroom：

工具返回 22,048 tokens → 全部进入上下文
     → 多轮对话继续累积 → 上下文窗口迅速填满
     → 成本随会话长度线性增长

使用 Headroom：

工具返回 22,048 tokens → SmartCrusher 分析统计特征
     → 保留异常点、错误项、首尾样本 → 压缩至 2,190 tokens（约 90%）
     → 原文缓存，agent 需要时可 headroom_retrieve
     → 模型仍能定位 CPU 尖峰和关键错误

3.2 基准测试

真实 agent 工作负载（官方 README）：

准确性保留（标准 benchmark）：

生产遥测（250+ 代理实例，opt-in）： 累计节省约 14 亿 token；压缩管道中位数开销约 17ms，相对 LLM 推理（通常 2～10 秒）可忽略。

规律很明显：工具输出越重、JSON 越多、会话越长，Headroom 收益越大；短对话、纯代码阅读场景收益有限。

3.3 什么时候不用也行

4. 工作原理

Headroom 在 LLM 请求链路上插入一层压缩管道，经历以下阶段：

Agent 请求 → CacheAligner → ContentRouter → 压缩器 → CCR 缓存
                ↓                ↓              ↓
           稳定前缀缓存      检测内容类型    SmartCrusher / CodeCompressor / Kompress
                ↓
           压缩后 prompt + retrieve 工具 → LLM Provider

4.1 ContentRouter：按类型选压缩器

ContentRouter 检测消息块的内容类型，路由到对应压缩器：

压缩在确定性规则下完成，不额外调用 LLM，因此可预测、无幻觉风险，管道中位数约 17ms。

4.2 SmartCrusher：统计而非截断

SmartCrusher 是处理 JSON 工具输出的主力。它不会简单砍掉数组尾部，而是先做字段分析：

• 常量字段：如 60 条记录里 host 全是 prod-1，提取到 __headroom_constants
• 时序变点：CPU 在第 45 个点从 45% 跳到 92%，保留尖峰区间
• 日志聚类：相似 error message 合并，每簇保留 1～2 条
• 安全项：含 error / exception / failed 的条目永远保留

示例：100 条生产日志、关键错误在第 67 条——压缩后 10,144 → 1,260 tokens，4/4 问答仍正确。

4.3 CCR：可逆压缩

CCR（Compress-Cache-Retrieve）是 Headroom 的核心设计：

1. Compress：SmartCrusher 把 1000 条压到 20 条
2. Cache：原文存入本地 LRU 缓存，生成 hash
3. Retrieve：LLM 调用 headroom_retrieve(hash=...) 取回全文

Proxy 的 Response Handler 会自动处理 retrieve 工具调用，客户端无感知。Context Tracker 还会在多轮对话中追踪已压缩内容，当新提问与旧压缩数据相关时主动展开。

这意味着可以激进压缩而零信息丢失风险——最坏情况是 agent 把原文要回来。

4.4 Live Zone 策略

Headroom 不会丢弃历史消息，只压缩最新内容块（live zone）：

• 不碰：系统 prompt、工具定义、较早的对话轮次（保持 provider prefix cache 稳定）
• 可压：最新的 user 消息、最新的 tool result

这样既省 token，又不破坏 Anthropic / OpenAI 的 KV cache 命中。

4.5 输出 token 优化（可选）

输入压缩之外，Headroom 还能减少模型写回的 token（Opus 类模型输出单价是输入的 5 倍）：

• Verbosity steering：在 system prompt 末尾追加简洁指令，不破坏 prompt cache
• Effort routing：工具结果后的常规续写降低 thinking effort，新问题和错误保持全力

1
2

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

headroom learn --verbosity 还可从历史会话学习你的简洁偏好。

5. 快速上手

5.1 安装

1
2
3
4
5

# Python（含 headroom CLI）
pip install "headroom-ai[all]"

# TypeScript SDK（库模式，无 CLI）
npm install headroom-ai

需要 Python 3.10+。[all] 覆盖核心栈；框架适配器（LangChain、Agno 等）需单独安装 extras。

5.2 三种接入方式

方式 A：Wrap Agent（最省事）

1
2
3
4

headroom wrap claude          # Claude Code
headroom wrap codex           # Codex CLI
headroom wrap copilot         # Copilot CLI
headroom wrap opencode        # OpenCode

一条命令启动 proxy 并改写 agent 配置。撤销：headroom unwrap claude。

方式 B：Proxy（零代码改动）

1
2
3
4
5

headroom proxy --port 8787

# 另开终端，把 base URL 指向 proxy
ANTHROPIC_BASE_URL=http://localhost:8787 claude
# 或 OPENAI_BASE_URL=http://localhost:8787/v1

任何 OpenAI 兼容客户端都能用。Cursor 需手动在设置里改 API Base URL。

方式 C：SDK 内联

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

TypeScript：import { compress } from 'headroom-ai'。

5.3 验证与查看收益

1
2
3
4

headroom doctor              # 健康检查，确认路由正常
headroom perf                # 查看压缩统计
headroom dashboard           # 实时 savings 面板（需 proxy 运行中）
curl http://localhost:8787/stats

5.4 MCP 接入

1

headroom mcp install

暴露三个 MCP 工具，供任意 MCP 客户端使用。

6. MCP 工具说明

典型流程：工具输出被压缩后，响应里会带 __headroom_hash；agent 需要更多细节时调用 headroom_retrieve。

7. 使用建议

1. 工具输出重的场景优先开：JSON API 响应、metrics、build log、多工具 agent 会话收益最大
2. 代码场景默认透传是合理的：不要强行压函数体，agent 读代码本来就需要完整逻辑
3. 信任 CCR：压缩后若 agent 答不完整，它会自动 retrieve；不必为了保险关闭压缩
4. 长会话用 proxy / wrap：累积效应比单次对话明显得多
5. 跨 agent 协作开 memory：Claude 和 Codex 可共享 SharedContext，避免重复上下文
6. headroom learn 挖失败会话：自动把踩坑经验写入 CLAUDE.local.md / AGENTS.md

几个设计原则值得了解：

• 本地优先：压缩、缓存、retrieve 全在本地，默认不上传 prompt 内容
• 确定性优于 LLM 摘要：不用 LLM 做压缩，避免幻觉和额外 API 成本
• 可逆优于截断：CCR 让激进压缩没有信息丢失风险
• Cache 友好：Live zone + CacheAligner 设计，不破坏 provider KV cache

8. CLI 常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

headroom wrap <agent>       # 包装 agent（claude/codex/copilot/...）
headroom unwrap <agent>     # 撤销包装
headroom proxy --port 8787  # 启动 proxy
headroom doctor             # 健康检查
headroom perf               # 压缩性能报告
headroom dashboard          # 实时面板
headroom learn              # 挖掘失败会话，写入 correction
headroom learn --verbosity  # 学习简洁偏好
headroom output-savings     # 输出 token 节省估算
headroom update             # 检查并升级
headroom mcp install        # 安装 MCP 配置

9. 与 CodeGraph 的关系

Headroom 和 CodeGraph 解决 agent 上下文问题的不同侧面，可以叠加使用：

一个负责「导航」，一个负责「减负」——在同一条 agent 流水线上互补。

10. 小结

Headroom 把 AI 编程助手从「为冗余工具输出付全款」，变成「先读压缩摘要，需要时再取原文」。

• 对比：无 Headroom 时 tool output 原样进上下文（SRE 场景 6 万+ tokens）；有 Headroom 时通常 60%～92% 压缩，准确性 benchmark 基本持平
• 原理：ContentRouter 按类型路由 → SmartCrusher / CodeCompressor / Kompress 确定性压缩 → CCR 缓存原文可 retrieve
• 使用：安装 headroom-ai → headroom wrap claude 或 headroom proxy → headroom doctor 验证

如果你已经在用 Cursor 或 Claude Code 写代码，且 agent 会话里 tool output 经常占大头，花一分钟跑一遍 wrap 流程，通常就能在长会话里看到明显的 token 节省。