每日一个开源项目（第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 共享压缩后的记忆，自动去重，避免同一信息被重复消耗多次

快速开始

# 安装完整版（含所有扩展）
pip install "headroom-ai[all]"

# 或按需安装扩展：[proxy] [mcp] [ml] [code] [memory] [langchain] 等
pip install "headroom-ai[proxy,mcp]"

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

from headroom import Headroom

hr = Headroom()

# 压缩消息列表，传给 LLM 前调用
compressed = hr.compress(messages)

# 正常调用 LLM
response = client.messages.create(
    model="claude-opus-4-5",
    messages=compressed.messages,
)

# 查看节省了多少 Token
print(f"压缩率: {compressed.compression_ratio:.1%}")
print(f"节省 Token: {compressed.tokens_saved}")

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

# 启动透明代理
headroom proxy --port 8787

# 只需把 base_url 指向代理，其余代码不变

import anthropic

# 只改一行：把 API 请求打到 headroom proxy
client = anthropic.Anthropic(base_url="http://localhost:8787")

# 之后的代码完全不变
response = client.messages.create(...)

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

headroom wrap claude    # 包装 Claude Code
headroom wrap aider     # 包装 Aider
headroom wrap cursor    # 包装 Cursor
headroom 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	简单截断	LLM 摘要	手动过滤
信息保留	✅ 可逆，原文可取回	❌ 永久丢失	⚠️ 可能失真	⚠️ 依赖规则
集成成本	✅ 1行代码 / 0行代码	✅ 简单	❌ 需要额外 LLM 调用	❌ 维护成本高
压缩质量	✅ 结构感知	❌ 无感知	⚠️ 通用摘要	⚠️ 场景局限
成本	✅ 节省 API 费用	✅ 无额外成本	❌ 额外 Token 消耗	✅ 无额外成本

---

项目详细剖析

压缩流水线架构

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 token
def process_payment(
    user_id: int,
    amount: float,
    currency: str = "USD",
    retry_count: int = 3
) -> PaymentResult:
    """处理支付请求，支持重试机制"""
    for attempt in range(retry_count):
        try:
            # 验证用户余额
            balance = get_user_balance(user_id)
            if balance < amount:
                raise InsufficientFunds(...)
            # ... 200 行实现细节 ...
        except NetworkError:
            if attempt == retry_count - 1:
                raise
            time.sleep(2 ** attempt)

# AST 压缩后：约 60 token
def process_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_id

headroom_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 提供了真实的基准测试（非合成数据）：

工作负载	压缩前 Token	压缩后 Token	节省比例
代码搜索（100条结果）	17,765	1,408	92%
SRE 事故调试	65,694	5,118	92%
GitHub Issue 分流	54,174	14,761	73%
代码库探索	78,502	41,254	47%

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

基准测试	压缩率	精度变化
GSM8K（数学推理）	-	delta = ±0.000（完全不变）
SQuAD v2（阅读理解）	19%	保持 97% 精度

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

---

项目地址与资源

官方资源

• 🌟 GitHub : chopratejas/headroom
• 🐛 Issue Tracker : github.com/chopratejas...
• 📦 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 与技能的市场，每一个都在真实的企业级工作流中经过验证，不堆砌概念，只留下真正有效的东西。

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