cat review.md
headroom
一个把 AI Agent 的上下文「瘦身」到只剩骨头的工具。不是删信息，是把信息压缩成 LLM 能懂的最小表示——然后在你需要的时候原样还给你。今天 +1,265 Star，总 6,406 Star，152 个 release，这迭代速度属实有点疯。
// 目录
// 概览
// 为什么我需要这东西
说个真实场景。我每天早上跑 GitHub AI 日报，Claude Code 要翻十几个 repo、读 README、对比版本号、读 Issue 讨论——每次跑完，token 账单能吃掉半杯咖啡钱。最离谱的一次，光工具输出就灌了 78,000 token 进上下文，里面 80% 的内容跟我的问题没有任何关系。
这不是 Claude Code 的问题。所有 AI Agent 都有这个毛病——你让它搜东西，它把搜索结果原封不动丢进上下文；你让它读日志，它把几十兆的 server log 全塞进去；你让它查一个函数定义，它把整个文件读给你看。
LLM 是按 token 计费的。这些冗余信息不是在帮你——是在帮 OpenAI 和 Anthropic 赚你的钱。
headroom 干的事很朴素：在信息到达 LLM 之前，把水分挤掉。不是删除，是压缩。你需要的时候它能解压回来。
// 它是怎么做到的
headroom 的核心思路是 Content-Aware Compression——不是统一算法一刀切，而是先判断内容类型，再用最适合的方式压缩。
整个处理管道分这几步：
CacheAligner：先把输入里的稳定前缀提取出来，让 LLM 提供商的 KV Cache 能命中。这一步不压缩，是「帮 LLM 省钱」——同一个 system prompt 你传一万次，CacheAligner 确保它只算一次。
ContentRouter：检测输入是什么类型——命令行输出？JSON？代码？日志？通用文本？然后路由到对应的压缩器。
三种压缩器各有分工：
SmartCrusher：处理 JSON 和结构化数据。不是粗暴 truncate，是提取关键字段、去重、合并相似条目。比如你搜了 100 个 GitHub Issue，它能把 100 个相同结构的 JSON 压成一份摘要。
CodeCompressor：用 tree-sitter 做 AST 感知的代码压缩。函数体里的实现细节可以压掉，但函数签名、类型定义、import 关系这些 LLM 需要的结构信息保留。你让它读一个 2000 行的文件，它只传 300 行的骨架。
Kompress-base：他们自己训的一个 HuggingFace 模型，处理通用自然语言文本。名字有点搞笑，但效果不是开玩笑的——通用文本场景能压 60-80%。
CCR（Content-Conscious Reversibility）：压缩之后原始内容存在本地 SQLite 里。LLM 需要时可以通过 headroom_retrieve 工具拿回完整版本。不是单向操作——压缩是可逆的。
// 上手
Python 3.10+ 就行。一条命令：
也支持模块化安装——如果你只想要 MCP Server 功能，装 headroom-ai[mcp] 就行，不用拉全量依赖。
// 五种使用姿势
headroom 不强制你改代码。五种模式，从「什么都不改」到「深度集成」都有：
| 模式 | 怎么用 | 适合谁 | 零代码改动？ |
|---|---|---|---|
| Agent Wrap | headroom wrap claude |
用 Claude Code / Codex / Cursor 的开发者 | 是 |
| Proxy 模式 | headroom proxy --port 8787 |
任何语言的项目，本地起一个代理 | 是 |
| Library | from headroom import compress |
Python/TypeScript 项目深度集成 | 否 |
| MCP Server | headroom mcp install |
任何 MCP 客户端（Claude Desktop / Codex 等） | 是 |
| Cross-Agent Memory | SharedContext().put / .get |
多 Agent 协作，共享压缩上下文 | 部分 |
Agent Wrap 是我最常用的方式。一条命令包装 Claude Code，不改任何配置，token 用量直接砍半。Proxy 模式更通用——你把 Claude Code 的 API endpoint 指到 localhost:8787，headroom 在中间透明压缩。
还有个 headroom learn 命令很有意思。它会分析你之前失败的 Agent 会话，找出哪些上下文是多余的，然后把优化建议写进你的 CLAUDE.md。不是黑盒——你打开文件能看到它改了什么。
// 架构：四步流水线
帮 KV Cache 命中
路由到对应压缩器
JSON · 代码 · 文本
可逆检索
// 性能数据
下面这组数据来自 headroom 自己的 benchmark——他们在四种真实 Agent 工作负载上测的：
| 工作负载 | 压缩前 (tokens) | 压缩后 (tokens) | 节省率 |
|---|---|---|---|
| Code Search (100 results) | 17,765 | 1,408 | 92% |
| SRE Incident Debugging | 65,694 | 5,118 | 92% |
| GitHub Issue Triage | 54,174 | 14,761 | 73% |
| Codebase Exploration | 78,502 | 41,254 | 47% |
token 压缩率可视化
Code Search 和 SRE Debugging 两个场景直接砍掉 92% 的 token——这个数字看着夸张，但想想确实合理。100 条搜索结果，大部分是重复结构的 JSON，SmartCrusher 一压就没了。
Codebase Exploration 只有 47%——因为代码本身信息密度高，能压的空间小。这个也在预期之内。
但压缩率高不代表答案质量下降。他们在标准 benchmark 上做了准确度对比：
| Benchmark | 类型 | 样本量 | 基线分 | Headroom分 | 变化 |
|---|---|---|---|---|---|
| GSM8K | 数学推理 | 100 | 0.870 | 0.870 | ±0.000 |
| TruthfulQA | 事实性 | 100 | 0.530 | 0.560 | +0.030 |
| SQuAD v2 | 问答理解 | 100 | 97% 准确率 · 19% 压缩 | 无损 | |
| BFCL | 工具使用 | 100 | 97% 准确率 · 32% 压缩 | 无损 | |
GSM8K 数学推理零损失，TruthfulQA 事实性反而涨了 0.03——压缩掉噪音之后 LLM 的注意力更集中在关键信息上。这个结果不是意外，很多压缩研究都观察到类似现象。
不过我得说一句：这些都是 N=100 的小样本测试，不是大规模独立审计。真要说「压缩不损质量」，还需要更多第三方验证。
// 跟同类工具比
上下文压缩这个赛道其实不缺玩家，但 headroom 的定位很特别：
| 项目 | 覆盖范围 | 部署方式 | 本地运行 | 可逆压缩 | 跨 Agent |
|---|---|---|---|---|---|
| headroom | 全部上下文 | Proxy · Lib · MCP · Wrap | 是 | 是 | 是 |
| RTK | CLI 输出 | CLI Wrapper | 是 | 否 | 否 |
| lean-ctx | CLI + MCP 工具 | CLI Wrapper · MCP | 是 | 否 | 否 |
| Compresr / Token Co. | API 传入文本 | 托管 API | 否 | 部分 | 否 |
| OpenAI Compaction | 对话历史 | 提供商原生 | 否 | 否 | 否 |
headroom 跟这些工具不是简单的谁好谁坏，是定位不同：
RTK 和 lean-ctx 只管 CLI 输出压缩，headroom 覆盖了全部上下文类型（工具输出、日志、文件、对话历史、RAG 结果）。RTK 的 shell 重写能力 headroom 直接集成了。lean-ctx 的 MCP 工具压缩 headroom 也有，但 lean-ctx 更专注 CLI 场景。
Compresr 和 Token Co. 是托管 API——你的数据要过他们的服务器。国内开发者可能不太在意这个，但很多企业合规场景数据不能出本机，headroom 是你本地跑的。
OpenAI 的 Compaction 是个「对话历史压缩」——它只压聊天记录，不压工具输出。而且不开源，你没法审计它到底怎么压的。
headroom 的差异化在于「可逆」——压缩之后存本地，Agent 需要的时候能拿回原始数据。其他工具都是单向的，压了就没了。
// 我的判断
+ 五种模式覆盖从零代码到深度集成的所有场景
+ 可逆压缩（CCR）——不是单向的，Agent 需要时能找回原始数据
+ Python + Rust 混合架构——Python 好上手，Rust 保证性能
+ 跨 Agent 共享记忆，Claude 和 Codex 之间可以传上下文
+ 152 个 release 的高频迭代，Apache 2.0 商用友好
+ 集成生态广——Anthropic SDK / OpenAI SDK / Vercel AI SDK / LiteLLM / LangChain / Agno 全支持
+ headroom learn 能从失败会话里学习并写到 CLAUDE.md
- 75 Open Issues + 54 Open PRs 积压明显
- Benchmark 样本量小（N=100），缺第三方独立审计
- Codebase Exploration 只压了 47%，对纯代码场景提升有限
- 文档还在快速演进中，部分 API 没有覆盖
- Python 3.10+ 门槛不高但 Node.js 版的文档没有 Python 版详细
说几句实话。
这个项目让我想起早期的 LangChain——一个工具解决一个具体问题，模式灵活，生态扩张快。区别是 LangChain 后来变成了「什么都要管」的框架，headroom 目前还很克制——它就做一件事，压缩上下文。
tokan 成本是我每天在盯的数字。如果你跟我一样每天跑 AI Agent，一个月光工具输出的 token 可能就烧掉几百块。headroom 理论上能把这笔钱砍掉一半以上。
但我不建议你现在就把所有 Agent 都套上 headroom。理由很简单：单人维护的项目风险从来不在于技术，在于人。chopratejas 如果明天不更新了，这 75 个 Issue 谁来修？54 个 PR 谁来看？
我的建议：先在非关键工作流上试用。比如日常的代码搜索、Issue 查看——这些场景压缩率高、答案质量有 benchmark 数据撑腰。生产环境的关键决策流程先缓一缓。
还有一个细节值得关注：headroom 集成了 RTK 的 shell 输出重写和 lean-ctx 的 CLI 上下文压缩。这不是从头造轮子，是站在别人肩膀上。脑子清醒的开发者。
总评：8.5 分。上下文压缩赛道目前最完整的一站式方案，但 Bus Factor = 1 的风险不能忽视。值得关注，值得试用，值得在生产环境的小范围验证。