最近，我在用 Claude Code 分析一个后端项目，代码库不算大，几万行的规模。但是用了几天之后，我突然发现一个问题，就是每次让 Claude 分析代码库，它都要读很久，而且返回的速度越来越慢。

我当时还以为是我的网络出问题了。

后来一查才知道，是"context window"的问题。AI 编程助手在处理你的代码时，会通过工具调用读取代码、执行命令、获取输出，这些结果都会塞进对话上下文。文件越多、对话越长，消耗的 token 就越多。当 token 数量逼近模型的上限，AI 的"记忆力"就开始下降，表现出来就是越来越慢、越来越"健忘"。

估计你也遇到过，就是 AI 助手用着用着就开始"犯傻"，明明是一个很简单的需求，它就是理解不了。

不是它变笨了，而是它的"脑子"被塞满了。

今天介绍的工具，就是来解决这个问题的。

headroom，AI 编程助手的"上下文压缩层"。

打个比方，就像你在看一本超厚的书，里面有大量的重复内容、无关紧要的细节。这时候如果有个人帮你把书"精简"一下，把废话删掉、保留核心信息，但又不丢失任何重要细节，你读书的效率是不是会大幅提升？

headroom 干的就是这个活儿。

它会拦截 AI 编程助手发送给 LLM 的所有内容——工具输出、日志、RAG chunks、搜索结果、文件内容、对话历史——在这些东西到达 LLM 之前，先用各种算法压缩一遍。压缩完之后，LLM 收到的还是同样的信息，只是量少了很多。

少多少呢？

官方的数据是这样的：

• 代码搜索 100 个结果：从 17,765 tokens 压缩到 1,408 tokens，省了 92%
• SRE 事故调试：从 65,694 tokens 压缩到 5,118 tokens，省了 92%
• GitHub issue 分类：从 54,174 tokens 压缩到 14,761 tokens，省了 73%
• 代码库探索：从 78,502 tokens 压缩到 41,254 tokens，省了 47%这几个数字我看到的时候，真的就是一声叹息。92% 是什么概念，就是你原来花 100 块钱的 token，现在只需要花 8 块钱。

你可能会问，压缩这么多，信息不会丢失吗？

这个问题问得好。

headroom 里面有一个核心模块叫 SmartCrusher，它是专门用于压缩 JSON 格式数据的工具，比如工具输出的 JSON 数组。它不是简单地删减内容，而是用统计学的方法来分析数据结构。

SmartCrusher 会这么做：

首先，它会分析每个字段的统计特性——哪些字段所有文件都一样的、哪些字段变化很大的、哪些是异常值。然后它会用一种叫 Kneedle 的算法来选取"最有代表性"的那部分数据。

直接说人话就是，就是它会保留开头 30% 的数据（让你知道返回的东西是什么结构），保留结尾 15% 的数据（因为最新产生的数据往往在数组末尾），中间的部分按照"重要性分数"来筛选。如果你代码库里有什么异常的错误信息，不管压缩得多狠，它都会给你留着。

这是一种"智能有损压缩"。听起来有点矛盾，但效果就是——AI 压缩完还是能回答你的问题，因为它保留的恰恰是最重要的那部分。

那万一 AI 需要完整数据怎么办？

headroom 还有一个叫 CCR 的机制，全称是 Compress-Cache-Retrieve，中文我自己翻译成"压缩-缓存-找回"。

工作流程是这样的：

当你让 AI 搜索 1000 个文件的时候，headroom 先把这 1000 个文件的原始内容存到本地，然后给 AI 发送压缩后的 20 个文件。如果 AI 发现这 20 个文件不够，它会调用 headroom 内置的 headroom_retrieve 工具来请求完整数据，这时候 headroom 会把原始的 1000 个文件调出来给 AI 看。

整个过程对用户是透明的，你感觉不到任何东西在后台发生。

你可以理解为，headroom 给 AI 配了一个"移动硬盘"。AI 看到的都是"精简版"，但完整的"原始数据"从来没被删掉，只是存在了另一个地方，AI 随用随取。

这就很安心了对吧。

怎么用它？

headroom 支持几种不同的使用方式，我一个个说。

第一种：零代码改动——Proxy 模式

如果你不想改任何代码，只需要一行命令：

headroom proxy --port 8787

然后把你原本请求 AI 的地址改成 localhost:8787，headroom 会自动拦截所有请求、压缩、转发。你的代码完全不用动，但 token 消耗就下来了。

第二种：直接包装你的 AI 编程助手

headroom 支持直接包装 Claude Code、Codex、Cursor、Aider、Copilot CLI、OpenClaw 等主流编程助手：

headroom wrap claude

这条命令跑完之后，你的 Claude Code 就自动带上了压缩功能，不需要任何额外配置。

第三种：Python 库

如果你是开发者，想在自己代码里用，直接 import：

from headroom import compressresult = compress(messages, model="gpt-4o")print(f"省了 {result.tokens_saved} tokens")

第四种：TypeScript / Node

import { compress } from 'headroom-ai';const result = await compress(messages, { model: 'gpt-4o' });console.log(`Saved ${result.tokensSaved} tokens`);

安装也很简单：

pip install "headroom-ai[all]"  # Pythonnpm install headroom-ai          # Node / TypeScript

还有一个很有意思的功能叫做 headroom learn。

headroom learn 会分析你使用 AI 编程助手过程中"失败"的会话——就是 AI 理解错了、做错了、需要你纠正的那些对话。然后它会自动生成一些"经验教训"，写成 CLAUDE.md 或者 AGENTS.md 这样的文档，放在你的项目里。

下次 AI 再遇到类似的问题，它就能从这些文档里学到你这个项目特有的规则。

有点像是给 AI 配了一个"纠错本"，让它自己学会少犯同样的错误。

说实话，我用 headroom 之前，对"上下文压缩"这个概念没什么感觉。

我觉得 AI 模型的 context window 越来越大，一个比一个大，还能不够用？

但实际用下来发现，context window 这玩意儿，跟硬盘一样，永远不够用。你给它多大，它就能塞多满。每次 AI 变慢、变笨，不是因为模型本身不行，是因为你往它脑子里塞的东西太多了。

headroom 做的事情，本质上是在教你和 AI 协作的时候，怎么做一个"会做减法"的程序员。

你不需要学会压缩算法，不需要懂什么 Kneedle 算法、BM25 搜索，headroom 全都帮你做了。你只需要装上它，然后继续像平常一样写代码。

不知不觉，你的 AI 助手就变快了，变便宜了，变聪明了。

这种感觉太爽了。

感兴趣的兄弟可以直接去 GitHub 搜 headroom，文档写得很详细，安装也就几分钟的事。