一周涨1.4 万星!让你的 AI 编码助手省钱又高效的实用工具,完全本地免费运行

平时用各种 AI 工具写代码、调试问题。说实话，用得越多，账单就越肉疼。工具调用一次返回几千行日志，代码搜索甩出上百个结果，RAG 拉一堆文档……上下文动辄几万 Token，钱包和响应速度都遭不住。

今天介绍这个项目专门解决这个痛点：在内容发给大模型前，先聪明地压缩一下。实际效果能省 60-95% 的 Token，答案质量基本不变。听起来有点玄乎，但我看了真实案例和数据，觉得值得分享给同样在折腾 AI 智能体的朋友们。

项目简介

Headroom 可以压缩 AI 智能体读取的所有内容 —— 工具输出、日志、RAG 块、文件和对话历史 —— 在发送给 LLM 之前完成。答案几乎不变，但 Token 消耗大幅降低。

Headroom 就像一个智能过滤器，根据内容类型自动选择压缩方式：JSON 工具输出保留异常和关键边界，代码保留结构和签名，日志突出错误和失败部分，普通文本去掉冗余。 更厉害的是，它支持可逆压缩（CCR）。压缩后的内容发给模型，如果模型觉得需要更多细节，可以随时调用工具取回原始数据。几乎不丢信息，却大幅减少了输入量。

主要功能

• 库模式 —— Python / TypeScript 中直接调用 compress(messages)
• 代理模式 —— headroom proxy --port 8787，无需修改代码，适用于任何语言
• 智能体包装 —— 一条命令 headroom wrap claude|codex|cursor|aider|copilot
• MCP 服务 —— 提供 headroom_compress、headroom_retrieve、headroom_stats 等工具，供任何 MCP 客户端使用
• 跨智能体内存 —— Claude、Codex、Gemini 等共享存储，自动去重
• headroom learn —— 从失败会话中挖掘经验，自动写入 CLAUDE.md / AGENTS.md 修正
• 可逆压缩 (CCR) —— 原始内容永不删除，LLM 需要时可随时检索

效果怎么样

项目提供了几个真实场景的对比数据：

代码搜索（100 条结果）：从 17,765 Token 降到 1,408 Token，节省 92%； SRE 故障调试：65,694 → 5,118 Token，92% 节省； GitHub Issue 分类：54,174 → 14,761 Token，73% 节省。

在基准测试里，数学题、事实问答等准确率基本持平，甚至在某些 QA 任务上表现还更好。有一个经典例子：10,144 Token 的日志里埋着一个关键 FATAL 错误，压缩后只剩 1,260 Token，模型依然准确找到了它。 这些不是实验室数据，而是实际智能体工作负载下的表现。

工作原理（30 秒了解）

  你的智能体 / 应用    (Claude Code, Cursor, Codex, LangChain, Agno, Strands 等)         │   prompts · 工具输出 · 日志 · RAG 结果 · 文件         ▼    ┌────────────────────────────────────────────────────┐    │  Headroom（完全本地运行 —— 数据永不离开你的设备） │    │  ────────────────────────────────────────────────  │    │  CacheAligner  →  ContentRouter  →  CCR            │    │                    ├─ SmartCrusher   (JSON)        │    │                    ├─ CodeCompressor (AST)         │    │                    └─ Kompress-base  (文本, HF)    │    │                                                    │    │  跨智能体内存  ·  headroom learn  ·  MCP           │    └────────────────────────────────────────────────────┘         │   压缩后的 prompt  +  检索工具         ▼  LLM 提供商  (Anthropic · OpenAI · Bedrock · …)

• ContentRouter —— 自动识别内容类型，选择最佳压缩器
• SmartCrusher / CodeCompressor / Kompress-base —— 针对 JSON、代码 AST 和普通文本的专用压缩
• CacheAligner —— 稳定 prompt 前缀，充分利用 KV 缓存
• CCR —— 可逆压缩，本地存储原始内容，LLM 通过 headroom_retrieve 按需取回

→ 架构文档 · CCR 可逆压缩 · Kompress-base 模型卡

60 秒快速上手

# 1. 安装pip install "headroom-ai[all]"# Pythonnpm install headroom-ai                 # Node / TypeScript# 2. 选择使用方式headroom wrap claude                    # 包装编码智能体headroom proxy --port 8787              # 零代码改动代理模式# 或：from headroom import compress      # 库模式直接集成# 3. 查看节省效果headroom perf

可选 extras：[proxy]、[mcp]、[ml]、[code]、[memory] 等。要求 Python 3.10+。

支持的智能体矩阵

任何 OpenAI 兼容客户端均可通过 headroom proxy 使用。MCP 原生支持：headroom mcp install。

项目地址

https://github.com/chopratejas/headroom