星标数：79556★ Fork数：6226 《headroom：压缩上下文再送入 LLM 的工具》

Headroom（在 PyPI 和 npm 上为 headroom-ai）会在 AI 代理读取的一切内容到达大模型之前进行压缩，包括工具输出、日志、RAG 分块、文件和对话历史。答案保持不变，输入 token 更少。经实测：在四个代理场景中输入 token 减少 21–57%，对重复的 JSON 数组和日志行可减少 90% 以上，对普通散文效果较小。压缩完全在本机运行，提示词和文件内容不会被发送到任何地方进行压缩。

如果你的应用直接调用 LLM（Python、LangChain、LiteLLM、Agno、Strands），只需 pip install headroom-ai，再调用 compress(messages, model="gpt-4o") 即可，无需 API key、无需下载模型、进程内运行；设置 HEADROOM_OFFLINE=1 可实现完全离线运行。工具消息和助手消息会被压缩，用户消息默认保持原样，除非显式传入 compress_user_messages=True。

如果你运行的是编码代理（Claude Code、Codex、Cursor、Copilot、OpenCode、Aider 等），一条命令即可完成包裹，无需改动任何代码：

主要特点

• 库模式：Python 或 TypeScript 中调用 compress(messages)，内联到任意应用。
• 代理模式（Proxy）：headroom proxy --port 8787，零代码改动，支持任意语言。
• Agent Wrap：一条命令包裹编码代理，headroom unwrap <tool> 可撤销。
• MCP 服务器：提供 headroom_compress、headroom_retrieve、headroom_stats，供任意 MCP 客户端使用。
• 跨代理记忆：在 Claude、Codex、Gemini 和 Grok 之间共享一个记忆存储，自动去重。
• 可逆压缩（CCR）：原始内容缓存在本地，按需取回。

快速开始（60 秒）

# 1 — 安装
uv tool install --python 3.13 "headroom-ai[all]"  # CLI，独立环境
pip install "headroom-ai[all]"                    # Python — 自带 headroom CLI
npm install headroom-ai                           # TypeScript SDK — 无 CLI

# 2 — 选择模式
headroom deploy                         # 一键本地部署 + 代理配置
headroom wrap claude                    # 包裹编码代理
headroom proxy --port 8787              # 即插即用代理，零代码改动
# 或：from headroom import compress     # 内联库

# 3 — 检查并查看节省效果
headroom doctor                         # 健康检查 — 确认路由正常
headroom perf
headroom dashboard                      # 实时代理节省（需代理运行中）

在自己的应用中减少输入 token

from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

📊 本项目 GitHub 星标数：79556。最后更新：2026-11-13，发布：2026-11-10。项目地址：https://github.com/headroomlabs-ai/headroom