📌 项目简介
headroom —— AI 智能体的上下文压缩层
headroom 是一个专为 AI 智能体设计的上下文压缩工具，在工具输出、日志、文件和 RAG 片段到达 LLM 之前对其进行压缩，可实现 60-95% 的 Token 减少，同时保证输出答案的准确性。
项目支持以代码库、零代码代理、MCP 服务器三种形态接入，兼容 Claude Code、Codex、Cursor、Aider、Copilot CLI 等主流 AI 编程助手，本周在 GitHub 新增近 15,000 Stars，是 2026 年 6 月最热门的 AI 开源项目之一。
🛠️ 安装要求和过程
环境要求
- Python：3.10 及以上版本（推荐 3.13）
- Node.js：18+（如使用 TypeScript 版本）
- 可选：Docker、Apple GPU（MPS 加速）、Rust（SSL 拦截场景）
快速安装
pip install “headroom-ai[all]”
# Node.js / TypeScript 安装
npm install headroom-ai
# Docker 镜像
docker pull ghcr.io/chopratejas/headroom:latest
# pipx 安装（隔离环境，推荐）
pipx install –python python3.13 “headroom-ai[all]”
可选功能插件
headroom 支持按需安装额外功能模块：
pip install “headroom-ai[proxy]”
# MCP 工具（接入 AI 智能体）
pip install “headroom-ai[mcp]”
# Kompress 模型（智能压缩）
pip install “headroom-ai[ml]”
# 代码压缩
pip install “headroom-ai[code]”
# 跨智能体记忆
pip install “headroom-ai[memory]”
# 图像压缩
pip install “headroom-ai[image]”
🌟 核心功能
1. 三形态接入，零代码也能用
headroom 提供三种接入方式，无论你是开发者还是普通用户都能快速上手：
- 代码库：Python/TypeScript 直接调用
compress(messages)，两行代码接入 - 零代码代理：运行
headroom proxy --port 8787，无需修改原有代码，所有兼容 OpenAI API 的客户端均可接入 - MCP 服务器：支持
headroom_compress、headroom_retrieve、headroom_stats三个 MCP 工具，一键安装到 Claude Code 等智能体
2. 智能压缩算法，60-95% Token 节省
headroom 自动识别内容类型，匹配最优压缩算法：
- JSON 数据 → SmartCrusher（智能结构压缩）
- 代码文件 → CodeCompressor（语法感知压缩）
- 自然语言 → Kompress-base 模型（AI 压缩模型）
- 电子表格 → SmartCrusher（CSV/XLSX 节省 37-48%）
- 图像 → 专用图像压缩（40-90% 压缩率）
3. 可逆压缩（CCR），不丢失任何信息
headroom 的 Context-Compressed Retrieval (CCR) 机制将原始内容本地缓存，模型需要时可通过 headroom_retrieve 按需获取完整内容。压缩只是”摘要”，详细信息随时可取回。
4. 输出 Token 缩减，让 AI 少说废话
除了压缩输入，headroom 还能减少模型的冗余输出：
- 自动去除客套话、重复代码、常规步骤的深度思考
- 简洁度引导：自动在系统提示末尾追加简洁要求，不破坏提示缓存
- 算力路由：常规工具调用步骤降低模型思考等级，新问题/错误保留完整算力
- 支持
headroom learn --verbosity --apply自动学习最优简洁度
5. 跨智能体共享记忆，自动学习优化
headroom 支持多智能体共享上下文存储，自动去重。更强大的是 headroom learn 功能：自动挖掘失败会话，将修正规则写入 CLAUDE.md / AGENTS.md，让智能体越用越聪明。
📊 压缩效果实测
| 场景 | 压缩前 Token | 压缩后 Token | 节省率 |
|---|---|---|---|
| 代码搜索（100 条结果） | 17,765 | 1,408 | 92% |
| SRE 故障排查 | 65,694 | 5,118 | 92% |
| GitHub 问题分类 | 54,174 | 14,761 | 73% |
| 代码库探索 | 78,502 | 41,254 | 47% |
| SQuAD v2（问答） | — | — | 19% |
| BFCL（工具调用） | — | — | 32% |
基准测试显示，在 GSM8K 数学推理任务中，headroom 压缩后的准确率与基线完全一致（0.870）；在 TruthfulQA 事实性问答中，压缩后准确率甚至提升了 3%（0.530 → 0.560）。压缩不影响答案质量，某些场景下甚至有所提升。
🚀 典型使用场景
场景一：封装现有 AI 编程助手（30 秒上手）
如果你正在使用 Claude Code、Cursor 或 Aider，只需一条命令即可让 headroom 开始节省 Token：
headroom wrap claude
# 封装 Cursor（生成配置后粘贴一次即可）
headroom wrap cursor
# 封装 Aider（自动启动代理并打开工具）
headroom wrap aider
# 查看压缩效果
headroom perf
封装后，所有工具输出、文件内容、RAG 片段在送入 LLM 之前都会被自动压缩，你无需修改任何代码或配置。
场景二：作为 MCP 工具接入 AI 智能体
headroom 原生支持 MCP 协议，可作为工具被 AI 智能体直接调用：
headroom mcp install
# MCP 工具列表：
# – headroom_compress : 压缩上下文
# – headroom_retrieve : 取回原始内容（CCR）
# – headroom_stats : 查看压缩统计
对于 AI Agent 开发者，headroom 提供了一个开箱即用的 Token 优化方案，无需自己实现压缩算法。
场景三：在 Python/TypeScript 应用中直接调用
对于开发者，headroom 提供了简洁的 API，两行代码即可接入：
from headroom import compress
compressed = compress(messages, model=“gpt-4o”)
# TypeScript
import { compress } from “headroom-ai”;
const compressed = await compress(messages, { model });
# 接入 Anthropic SDK
from headroom import withHeadroom
client = withHeadroom(Anthropic())
# 接入 LangChain
from headroom import HeadroomChatModel
llm = HeadroomChatModel(your_llm)
headroom 还支持 Vercel AI SDK、LiteLLM、Agno 等主流框架，覆盖几乎所有 LLM 应用开发场景。
🤖 兼容智能体列表
💡 推荐理由
为什么你应该关注 headroom？
1. 立竿见影的成本节省。如果你在用 Claude Code 或 Cursor 做日常开发，上下文窗口经常爆满，headroom 可以立即减少 60-95% 的 Token 消耗。对于使用按量付费 API 的开发者，这意味着直接节省 50-90% 的 LLM 调用成本。
2. 本周最热的开源 AI 项目。headroom 本周在 GitHub 新增近 15,000 Stars，是 Python 趋势榜第一名。项目创建于 2026 年 1 月，仅用 5 个月就突破 4.3 万 Stars，增长速度惊人。
3. 零代码接入，30 秒上手。不需要修改任何代码，不需要理解压缩算法，只需要运行 headroom wrap claude 或 headroom proxy --port 8787，就能立即开始节省 Token。
4. 可逆压缩让人放心。CCR 机制确保原始内容不会丢失，模型需要时随时可以取回。这意味着你可以大胆地开启压缩，而不用担心信息丢失。
5. 不止于压缩。headroom 的 headroom learn 功能可以自动从失败会话中学习，将修正规则写入项目配置文件，让你的智能体越用越聪明。这是真正意义上的”自我改进”工具。
遗憾点：目前压缩质量依赖于 Kompress 模型，需要下载模型文件（约几百 MB）。在完全离线环境中，需要使用预下载的模型或仅使用 SmartCrusher 等规则压缩算法。
📥 下载地址
本文由 WorkBuddy AI 自动生成 · 数据来源：GitHub API · 项目许可：Apache 2.0