每日一个开源项目（第122篇）：headroom - 给 AI Agent 装上上下文压缩层，Token 最高省 95%

引言

“Token 不够用，不一定是上下文窗口太小——更可能是里面塞了太多垃圾。”

这是"每日一个开源项目"系列的第122篇文章。今天的主角是headroom——一个专为 AI Agent 设计的上下文压缩层。

随着 Agent 越来越复杂，它们的上下文越填越满：工具返回的 JSON 动辄几千行、RAG 检索出的文档大量冗余、搜索结果包含无关内容、日志里充斥着无意义的噪声。最终结果是：Agent 的 Token 消耗飙升，成本失控，有时甚至超出窗口限制。

headroom 的答案是：在内容进入 LLM 之前先压缩它。不是截断，不是摘要（会丢失信息），而是保留关键信息、去掉冗余——还支持按需取回原文。

你将学到什么

• Agent 上下文为什么会"膨胀"，以及膨胀的代价
• headroom 的四种集成模式：Library / Proxy / Agent Wrap / MCP Server
• SmartCrusher、CodeCompressor、Kompress-base 三种压缩引擎的工作原理
• CCR（可逆压缩检索）：压缩后仍然能取回原文
• 真实基准测试数据：不同工作负载下的压缩率与精度保持情况

前置知识

• 基础 Python 使用经验
• 了解 LLM API 的基本用法（Token 计费概念）
• 使用过至少一种 AI Agent 框架（可选）

项目背景

项目简介

headroom 自称"AI Agent 的上下文压缩层"，定位在用户输入与 LLM 之间。它的核心逻辑是：工具输出、日志、代码片段、RAG 检索结果往往包含大量对当前问题无关的内容，把这些冗余去掉，LLM 反而能看得更清楚、答得更准——同时节省大量 Token。

与简单的截断或摘要不同，headroom 的压缩是可逆的：原始内容本地保留，LLM 可以通过headroom_retrieve工具按需取回，不会因为压缩而丢失任何信息。

作者/团队介绍

• 作者: Tejas Chopra（chopratejas）
• 语言组成: Python 76.9% + Rust 18.3% + TypeScript 2.7%
• License: Apache 2.0

项目数据

• ⭐ GitHub Stars:12,800+
• 🍴 Forks: 823
• 📦 版本: v0.23.0（最新）
• 📄 License: Apache 2.0
• 🌐 支持: Python 3.10+，Node.js，Docker

主要功能

核心作用

headroom 在 Agent 的工具输出到达 LLM 之前拦截并压缩内容，降低噪声、节省 Token、避免上下文窗口超限。整体定位是一个透明的压缩中间件——不改变 Agent 的逻辑，只改变内容的密度。

使用场景

1. 代码搜索与分析

   • 搜索 100 个文件返回 17,765 个 token，压缩后仅 1,408 个（节省 92%），Agent 只看到与问题相关的代码片段

2. SRE 事故调试

   • 系统日志、堆栈跟踪、指标数据混合输入，65,694 token 压缩至 5,118（节省 92%），关键异常信息反而更突出

3. GitHub Issue 分流

   • 批量处理 Issue，54,174 token 压缩至 14,761（节省 73%），分类准确率不降

4. RAG 检索增强生成

   • 检索出的文档块去冗余后，LLM 不再被不相关内容干扰，回答精度反而提升

5. 多 Agent 协作

   • 跨 Agent 共享压缩后的记忆，自动去重，避免同一信息被重复消耗多次

快速开始

# 安装完整版（含所有扩展）pipinstall"headroom-ai[all]"# 或按需安装扩展：[proxy] [mcp] [ml] [code] [memory] [langchain] 等pipinstall"headroom-ai[proxy,mcp]"

方式一：Library 模式（代码内嵌）

fromheadroomimportHeadroom hr=Headroom()# 压缩消息列表，传给 LLM 前调用compressed=hr.compress(messages)# 正常调用 LLMresponse=client.messages.create(model="claude-opus-4-5",messages=compressed.messages,)# 查看节省了多少 Tokenprint(f"压缩率:{compressed.compression_ratio:.1%}")print(f"节省 Token:{compressed.tokens_saved}")

方式二：Proxy 模式（零代码改动）

# 启动透明代理headroom proxy--port8787# 只需把 base_url 指向代理，其余代码不变

importanthropic# 只改一行：把 API 请求打到 headroom proxyclient=anthropic.Anthropic(base_url="http://localhost:8787")# 之后的代码完全不变response=client.messages.create(...)

方式三：Agent Wrap（一行命令包装现有 Agent）

headroom wrap claude# 包装 Claude Codeheadroom wrap aider# 包装 Aiderheadroom wrap cursor# 包装 Cursorheadroom wrap codex# 包装 Codex CLI

查看压缩统计

headroom perf# 输出: 今日节省 Token: 48,392 | 累计节省: $12.40

核心特性

1. 四种集成模式

   • Library / Proxy / Agent Wrap / MCP Server，按需选择，无需改造已有架构

2. CCR 可逆压缩（Compressed Context Retrieval）

   • 压缩后原文本地存储，LLM 可通过headroom_retrieve工具按需取回，压缩不等于丢弃

3. 跨 Agent 共享记忆

   • 多个 Agent 访问同一记忆存储，自动去重，避免重复消耗相同信息

4. headroom learn自动学习

   • 分析失败的 Agent 会话，自动将经验写入 CLAUDE.md / AGENTS.md，让下次运行更聪明

5. 全内容类型覆盖

   • JSON（SmartCrusher）、代码（AST 级别 CodeCompressor）、纯文本（Kompress-base）、图像均支持

6. 本地优先，隐私安全

   • 所有压缩计算本地完成，数据不离开本机

项目优势对比

项目详细剖析

压缩流水线架构

headroom 的内部处理流程分为三个阶段：

用户输入 / 工具输出 ↓ CacheAligner ← 对齐缓存，避免重复处理相同内容 ↓ ContentRouter ← 识别内容类型，路由到对应引擎 ├── SmartCrusher (JSON / 结构化数据) ├── CodeCompressor (代码，AST 级别) └── Kompress-base (纯文本，HuggingFace 模型) ↓ 压缩后内容 → LLM ↓ 原文本地存储（CCR 索引）← 支持按需检索

CacheAligner：识别已经处理过的内容，跳过重复压缩，降低计算开销。

ContentRouter：分析消息内容类型（JSON 结构、代码语法、纯文本），路由到最适合的压缩引擎。不同类型的内容用不同策略压缩，效果远好于通用方案。

三种压缩引擎

① SmartCrusher（JSON / 结构化数据）

工具调用的返回值通常是 JSON，包含大量与当前问题无关的字段。SmartCrusher 分析 LLM 的上一条查询，提取相关字段，丢弃无关结构：

# 原始工具返回：1200 token{"results":[{"id":"abc123","title":"...","content":"...",# 与查询相关"metadata":{# 无关字段"created_at":"...","updated_at":"...","author_id":42,"tags":["...","..."],"internal_score":0.87,# ... 20+ 更多无关字段}}# × 99 更多结果]}# 压缩后：约 80 token（节省 93%）# 只保留 title + content，剔除所有 metadata

② CodeCompressor（代码，AST 级别）

代码的压缩不能靠截断——截断会破坏语法，LLM 看到残缺的代码反而更困惑。CodeCompressor 解析 AST（抽象语法树），保留函数签名、类定义、关键注释，压缩掉函数体实现细节：

# 原始代码片段：800 tokendefprocess_payment(user_id:int,amount:float,currency:str="USD",retry_count:int=3)->PaymentResult:"""处理支付请求，支持重试机制"""forattemptinrange(retry_count):try:# 验证用户余额balance=get_user_balance(user_id)ifbalance<amount:raiseInsufficientFunds(...)# ... 200 行实现细节 ...exceptNetworkError:ifattempt==retry_count-1:raisetime.sleep(2**attempt)# AST 压缩后：约 60 tokendefprocess_payment(user_id:int,amount:float,currency:str="USD",retry_count:int=3)->PaymentResult:"""处理支付请求，支持重试机制"""...# [实现已压缩，可通过 headroom_retrieve 取回]

③ Kompress-base（纯文本）

对于文档、日志等纯文本，headroom 使用 HuggingFace 上的Kompress-base模型做语义压缩，保留与当前查询最相关的句子，过滤冗余。

CCR：可逆压缩的关键

普通截断是单向的——一旦截掉，信息永久丢失。headroom 的 CCR（Compressed Context Retrieval）机制让压缩变得可逆：

原文 ──────────── 压缩 ──────────→ LLM │ │ └── 存入本地 CCR 索引 │ (按 trace_id 索引) │ │ 需要更多细节时 ↓ headroom_retrieve("trace_id", "函数实现") │ ↓ 从本地索引取回原文片段

在 MCP Server 模式下，LLM 可以主动调用headroom_retrieve工具：

# LLM 决定需要查看完整实现时，自动调用：headroom_retrieve(trace_id="abc123",query="process_payment 的重试逻辑实现")# → 返回原始代码的对应片段

MCP Server 模式

MCP 模式暴露三个工具给 LLM：

# Claude Code / Cursor / 任何支持 MCP 的客户端可以直接调用headroom_compress(content,content_type="auto")# → 压缩内容，返回压缩后文本 + trace_idheadroom_retrieve(trace_id,query)# → 按需取回原文片段headroom_stats()# → 返回当前会话的压缩统计信息

配置示例（claude_desktop_config.json）：

{"mcpServers":{"headroom":{"command":"headroom","args":["mcp"]}}}

headroom learn：从失败中自动学习

这是 headroom 最独特的功能之一。当 Agent 会话失败（任务未完成、LLM 多次重试、上下文超限），headroom learn会分析失败原因，自动将学到的规律写入CLAUDE.md或AGENTS.md：

headroom learn --session-log ./logs/session_2026-06-05.jsonl# 输出示例：# 发现 3 个重复模式：# 1. 在搜索 GitHub API 时总是携带过多 metadata 字段 → 已添加过滤规则到 CLAUDE.md# 2. 处理大型 JSON 响应时上下文超限 3 次 → 已添加 SmartCrusher 提示到 AGENTS.md# 3. 代码分析任务中 CodeCompressor 提升了 40% 成功率 → 已记录配置

实测压缩率与精度数据

headroom 提供了真实的基准测试（非合成数据）：

精度保持（核心问题：压缩会不会让 LLM 答错？）：

关键结论：对于 Agent 工作负载，去掉冗余内容不会降低答案质量，有时反而更好——LLM 不再被不相关内容干扰。

项目地址与资源

官方资源

• 🌟GitHub: chopratejas/headroom
• 🐛Issue Tracker: github.com/chopratejas/headroom/issues
• 📦PyPI:pip install headroom-ai

相关资源

• LangChain 集成文档
• MCP 协议规范
• Kompress-base 模型（HuggingFace）

总结

headroom 解决的是一个被长期低估的问题：上下文里的噪声。我们花了大量时间优化 prompt 措辞，却很少关注工具输出带来的冗余。一次代码搜索返回 17,765 个 token，其中 16,357 个是噪声——而这在复杂 Agent 任务中每分钟都在发生。

四种集成模式（Library / Proxy / Wrap / MCP）让 headroom 几乎可以无侵入地接入任何现有 Agent 架构。CCR 可逆压缩确保压缩不是截断，headroom learn让 Agent 从失败中自动积累经验。

如果你的 Agent 正在面临成本失控或上下文超限的问题，headroom 值得作为第一个尝试的方案。

欢迎了解 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都在真实的企业级工作流中经过验证，不堆砌概念，只留下真正有效的东西。

欢迎来我的个人主页找到更多有用的知识和有趣的产品