你每天在给 LLM 喂垃圾
打开你的 Claude Code 会话，看一下 token 用量——是不是经常一上午就烧掉几十万 token？其中大头不是你的 prompt，而是 Agent 调工具返回的结果：一次 grep 搜出来 100 条结果占 17,000 token，一次 git log 占 3,000 token，一次 cat 一个大文件直接吃掉 8,000 token。
这些输出里，Agent 真正需要的信息可能只有 10-20%。剩下的都是格式、重复行、无关内容。你在为垃圾付钱。
Headroom 就是插在这中间的一层——Agent 照常调工具，Headroom 在工具输出到达 LLM 之前把它压缩一遍，然后把原始数据存起来，万一 LLM 需要细节，可以通过一个 retrieve 工具拿回来。
它到底是什么
一句话：一个本地运行的上下文压缩层，压缩 Agent 读到的所有东西——工具输出、日志、RAG 结果、文件、对话历史——在不丢失答案质量的前提下砍掉 20-92% 的 token。
Headroom 不是又一个 Coding Agent。它是一个中间件，坐在你的 Agent 和 LLM API 之间，做三件事：
- 检测内容类型——JSON、代码、日志、纯文本，每种用不同的压缩策略
- 压缩——JSON 砍到 60-95%，代码 AST 感知压缩，文本用自研的 Kompress-v2 模型
- 缓存对齐——稳定 prompt 前缀，让 Anthropic/OpenAI 的 KV Cache 命中率拉满
四种接入方式
这是 Headroom 最聪明的设计——它知道自己不可能只服务一种用户，所以给了四种接入方式：
| 方式 | 适合谁 | 改动量 | 命令 |
|---|---|---|---|
| Agent Wrap | 用 Claude Code / Codex / Cursor 等终端 Agent 的人 | 零代码 | headroom wrap claude |
| Proxy | 任何语言、任何框架 | 改个 base URL | headroom proxy --port 8787 |
| Library | Python / TypeScript 开发者 | 一行 import | compress(messages) |
| MCP Server | 支持 MCP 的 Agent | 加个配置 | headroom mcp install |
最推荐的是 headroom wrap——一条命令搞定一切：启动本地代理、配置 Agent 环境变量、注入 MCP 工具、启动 Agent 会话。结束时 headroom unwrap claude 一键还原。
压缩引擎拆解
Headroom 不是简单的"截断"或"摘要"。它有三个专门的压缩器，根据内容类型自动路由：
🗜️ SmartCrusher — JSON 杀手
Agent 调 API、查数据库、跑 CI，返回的大量是 JSON。SmartCrusher 专门处理嵌套 JSON：数组去重、键名缩写、空值删除、类型保持。实测 JSON 压缩率 60-95%，而且压缩后的数据是结构化的，LLM 能直接理解，不会变成乱码。
🔧 CodeCompressor — AST 感知代码压缩
支持 Python、JS/TS、Go、Rust、Java、C/C++、Perl。不是简单删注释，而是解析 AST 后保留函数签名、类型标注、控制流，砍掉函数体内的实现细节。对 cat 大文件特别有效——代码压缩率 40-60%，LLM 还是能看懂代码结构。
🧠 Kompress-v2-base — 通用文本压缩
Headroom 自研的 HuggingFace 模型，专门在 Agent trace 数据上训练过。处理日志、错误信息、文档等非结构化文本。文本压缩率 15-30%，benchmark 上 GSM8K 精度 ±0，TruthfulQA 还涨了 0.03。
🔄 CCR — 可逆压缩
这是最实用的设计。压缩后的数据如果 LLM 觉得信息不够，它可以通过 headroom_retrieve 工具把原始数据要回来。这意味着压缩是无损的——信息没丢，只是不主动塞给 LLM 了。
真实数据
| 场景 | 压缩前 | 压缩后 | 省 |
|---|---|---|---|
| 代码搜索（100 条结果） | 17,765 | 1,408 | 92% |
| SRE 事故排查 | 65,694 | 5,118 | 92% |
| GitHub Issue 分拣 | 54,174 | 14,761 | 73% |
| 代码库探索 | 78,502 | 41,254 | 47% |
代码搜索和 SRE 排查场景压缩 92%，因为这些场景返回大量重复格式的 JSON 和日志。代码库探索只有 47%，因为代码本身就信息密度高，能压的空间有限。
输出端也能省
Headroom 不只压缩你发给 LLM 的 token，还能砍 LLM 写回来的 token。两个机制：
- Verbosity Steering——在 system prompt 末尾加一句「简洁回答，不要重复上下文」，利用 prompt cache 不影响命中
- Effort Routing——当 Agent 只是在读文件、跑测试这种例行操作时，自动降低模型的 thinking effort；遇到新问题和错误时恢复全力
输出 token 在 Opus 级模型上价格是输入的 5 倍，这块省下来的钱比压缩输入还多。
export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787
# 输出端压缩默认关闭，需要手动开启怎么接入
最快上手：60 秒
# 安装（选一个）
pip install "headroom-ai[all]" # Python
uv tool install "headroom-ai[all]" # uv（推荐，隔离环境）
# 一行命令接入 Claude Code
headroom wrap claude
# 或者接入 Codex
headroom wrap codex
# 或者接入 OpenCode
headroom wrap opencode
# 看看省了多少
headroom perfProxy 模式（零代码改动）
# 启动本地代理
headroom proxy --port 8787
# 然后把你的 Agent 的 API base URL 改成 http://localhost:8787
# Claude Code: ANTHROPIC_BASE_URL=http://localhost:8787
# OpenAI 兼容: OPENAI_BASE_URL=http://localhost:8787MCP 模式
# 安装为 MCP Server
headroom mcp install
# Agent 会多出三个工具：
# headroom_compress - 手动压缩文本
# headroom_retrieve - 获取压缩前的原始数据
# headroom_stats - 查看压缩统计Python Library
from headroom import compress
# 直接压缩 messages
compressed = compress(messages, model="claude-sonnet-4-20250514")
# 或者包装 SDK
from headroom import withHeadroom
from anthropic import Anthropic
client = withHeadroom(Anthropic())
# 之后所有 API 调用自动压缩跨 Agent 记忆
Headroom 还有一个被低估的功能：跨 Agent 共享记忆。你在 Claude Code 里搜索过的信息、分析过的代码结构，Codex 和 Gemini 也能访问。不用重复搜索，不用重复分析。
加上 headroom learn 能从失败的会话中提取教训写入 CLAUDE.local.md，等于给 Agent 加了一个"从错误中学习"的能力。
跟其他方案比
| 维度 | Headroom | RTK | OpenAI Compaction | lean-ctx |
|---|---|---|---|---|
| 压缩范围 | 所有内容——工具、RAG、日志、文件、历史 | CLI 命令输出 | 对话历史 | 工具输出、文件、shell |
| 部署方式 | 代理 / 库 / MCP / wrap | CLI 包装 | Provider 内置 | 代理 / 库 / MCP / CLI |
| 本地运行 | ✅ | ✅ | ❌ | ✅ |
| 可逆压缩 | ✅ CCR | ❌ | ❌ | ✅ |
| 跨 Agent 记忆 | ✅ | ❌ | ❌ | ❌ |
| 输出端压缩 | ✅ | ❌ | ❌ | ❌ |
| Agent 兼容 | 16+ 个 Agent | CLI 通用 | 仅 OpenAI | 通用 |
一句话：RTK 是"把 CLI 输出写短"，OpenAI Compaction 是"压缩对话历史"，Headroom 是"压缩 Agent 读到的一切"。不是一个量级的东西。
踩坑实录
坑 1：Python 版本。推荐用 Python 3.13。3.14 装不上 LiteLLM，dashboard 的美元节省显示永远是 $0.00。3.10-3.13 都能用，但 3.13 是甜点。
坑 2：ONNX 要求 AVX2。Headroom 的内容检测用了 ONNX Runtime，需要 x86 的 AVX2 指令集。Apple Silicon 没问题，但一些老的 Docker/QEMU 环境会回退到非 ONNX 路径（BM25 + 启发式检测），精度略降但不会崩。
坑 3：wrap 环境变量快照。headroom wrap 启动时会快照当前环境变量。如果你先 wrap 再 export 新的 HEADROOM_OUTPUT_SHAPER=1，代理看不到。要在 wrap 之前 export，或者用 headroom unwrap 再 wrap 一次。
坑 4：企业 SSL 检查。公司网络用了 Zscaler 之类的 SSL 检查代理，pip install 会报证书错误。设置 HEADROOM_TLS_STRICT=0 只关严格模式，不影响链验证和签名检查。
坑 5：代理缓存命中。Headroom 的 CacheAligner 会稳定 prompt 前缀来提高 KV Cache 命中率。但如果你在 wrap 之前已经跑了一段对话，前缀已经"脏了"，CacheAligner 的效果会打折扣。建议在会话开始时就 wrap。
适合谁
- 每天用 Coding Agent 的人——token 费是实打实的开销，省 20% 意味着每月省几十到几百刀
- 同时用多个 Agent 的人——跨 Agent 记忆是杀手级功能，Claude Code 分析过的代码 Codex 不用再搜一遍
- 跑 Agent CI/CD 的团队——SRE 排查场景压缩 92%，CI 日志分析省大量 token
- 上下文经常爆的人——压缩后同样的上下文窗口能塞更多信息
不适合：只用一个 Agent 做简单任务的人，Provider 自带的 compaction 够用了。
总结
Headroom 做的事情本质上是：在 Agent 和 LLM 之间加一个智能过滤器，让 LLM 只看到它需要的信息，而不是所有信息。
61K Star 不是白来的——它解决了 Coding Agent 最实际的问题：token 费太高、上下文窗口太小、工具输出太啰嗦。而且接入成本几乎为零，一条命令搞定。
如果你每天用 Claude Code 或 Codex 写代码，headroom wrap claude 应该是你今天就该跑的一条命令。
# 现在就装
pip install "headroom-ai[all]"
headroom wrap claude
# 然后正常写代码，看看 headroom perf 省了多少