8.0
热点
AI SCORE
开源项目2026-10-20 15:33
Headroom 在本地压缩智能体上下文
GitHub Trending#上下文压缩#Agent#成本优化
Editor brief · 编辑速览
Headroom 在内容进入模型前压缩工具输出、日志、文件及检索片段，提供库、代理和 MCP 等接入方式。项目宣称编程智能体可减少约 20% token，JSON 可减少 60%—95%，效果仍需按任务验证。
快速入门 · 团队版 Headroom · 安装 · 验证结果 · 智能体 · 文档 · Discord · llms.txt
AI 智能体 / LLM：请阅读此处的 /llms.txt，或获取在线索引 · 完整文档文本。
Headroom 会在内容到达 LLM 之前，压缩 AI 智能体读取的一切——工具输出、日志、RAG 分块、文件和对话历史。用少得多的 token，得到同样的答案。压缩在你的机器上运行；任何提示词或文件内容都不会被发送到其他地方进行压缩。
库——在 Python 或 TypeScript 中使用 compress(messages)，可直接嵌入任何应用。
代理——headroom proxy --port 8787，无需修改代码，适用于任何语言。
智能体封装——一条命令即可通过 headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode 封装智能体；使用 headroom unwrap <tool> 撤销。
MCP 服务器——为任何 MCP 客户端提供 headroom_compress、headroom_retrieve、headroom_stats。
跨智能体记忆——Claude、Codex、Gemini 和 Grok 共用一个存储，并自动去重。
headroom learn——分析失败的会话，并将纠正建议写入 CLAUDE.local.md（默认，已被 git 忽略）、CLAUDE.md、AGENTS.md、GEMINI.md 或 GROK.md。
减少输出 token——不仅压缩你发送的内容，也精简模型返回的内容。详见下文。
可逆压缩（CCR）——原始内容缓存在本地，按需检索。
Your agent / app
(Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)
│ prompts · tool outputs · logs · RAG results · files
▼
┌────────────────────────────────────────────────────┐
│ Headroom (runs locally — your data stays here) │
│ ──────────────────────────────────────────────── │
│ CacheAligner → ContentRouter → CCR │
│ ├─ SmartCrusher (JSON) │
│ ├─ CodeCompressor (AST) │
│ └─ Kompress-v2-base (text, HF) │
│ │
│ Cross-agent memory · headroom learn · MCP │
└────────────────────────────────────────────────────┘
│ compressed prompt + retrieval tool
▼
LLM provider (Anthropic · OpenAI · Bedrock · …)
ContentRouter 检测内容类型，并选择对应的压缩器。
SmartCrusher / CodeCompressor / Kompress-v2-base 分别处理 JSON、源代码和自然语言文本。
CacheAligner 会标记可能导致提供商 KV 缓存前缀失效的易变内容。它绝不会改写提示词。
CCR 将原始内容保存在本地，以便模型在需要完整文本时调用 headroom_retrieve。
→ 架构 · CCR · Kompress-v2-base 模型卡
快速上手（60 秒）
# 1 — Install
uv tool install --python 3.13 "headroom-ai[all]" # CLI in a self-contained env
pip install "headroom-ai[all]" # Python — ships the `headroom` CLI
npm install headroom-ai # TypeScript SDK only — no CLI
# 2 — Pick a mode
headroom deploy # turnkey local deployment + agent config
headroom wrap claude # wrap a coding agent
headroom proxy --port 8787 # drop-in proxy, zero code changes
# or: from headroom import compress # inline library
# 3 — Check it and watch the savings
headroom doctor # health check — confirms routing works
headroom perf
headroom dashboard # live savings (proxy must be running)
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%})")
每次都应通过封装命令启动智能体会话，以确保执行配置流程。headroom wrap 会启动本地代理，安装用于语义代码导航的 Serena，并启动已配置为通过 Headroom 路由请求的智能体。对于 Claude Code，Serena 只会注册到当前封装的项目中（作为本地作用域的 MCP 服务器，记录在 ~/.claude.json 中）。使用 --code-memory-scope user 可让所有项目都能使用它，使用 --code-memory none 则可跳过安装。headroom unwrap 可以移除这两种作用域的注册。
headroom CLI 仅随 PyPI 包提供。npm 上的 headroom-ai 包是 TypeScript SDK——它是一个供你导入的库（import { compress } from 'headroom-ai'），不提供 headroom 命令。
我们根据真实 MCP 服务器的输出格式构建了四个场景，使用提供商的 tokenizer 和包内自带的 compress() 进行测量。测试固定随机种子并离线运行，因此你能得到与我们相同的数据：
uv run python benchmarks/index_proof_table.py --seed 20260902
节省幅度取决于载荷的重复程度。在 benchmarks/bench_latency.py 中，重复的 JSON 数组和日志行可实现超过 90% 的压缩率；自然语言文本和信息已经很密集的输出则几乎无法压缩。对你自己的流量运行 headroom savings，即可获得适用于你的实际数据。
压缩耗时极低：对于包含 10K token 的 JSON 搜索结果，p50 耗时为 0.21 ms；对于 100K token，则为 1.4 ms，因此不会给智能体带来可感知的延迟。
准确率。运行 python -m headroom.evals suite --tier 1：
在 N=100 时，±0.03 的差值落在置信区间内，因此 TruthfulQA 的结果表明没有可检测到的差异，而非有所提升。测试方法 →
减少输出 token
上面介绍的功能都在缩减你发送的提示词。模型返回的每个 token 同样需要付费，而在 Opus 级别的模型上，输出成本是输入的 5 倍。大量输出只是些客套和冗余内容：以“好的，让我……”开头的铺垫、原封不动返回给你的代码，以及在读取文件等常规步骤上耗费的深度推理。
Headroom 在代理层精简这些内容，无需修改你的代码：
简洁度引导会在系统提示词末尾附加一条简短指令，要求“简洁作答，不要复述上下文”，因此仍然能命中提示词缓存。
推理力度路由会在当前轮只是模型接着工具结果继续执行时，降低思考力度，例如读取文件之后或测试通过之后。遇到新问题和错误时，则保留完整的推理力度。
这两项功能同时适用于 Anthropic 的 /v1/messages，以及 OpenAI 兼容的 /v1/chat/completions 和 /v1/responses。推理力度路由在 OpenAI 上使用 reasoning_effort，在 Anthropic 上使用 thinking.budget_tokens / output_config.effort；两条路径都遵循相同的只降不升约束，并使用相同的 output_shaper:* 标签。
export HEADROOM_OUTPUT_SHAPER=1 # off by default
headroom proxy --port 8787
已经有代理在运行？这些开关会在每次请求时实时读取，但如果 headroom wrap 复用了已有代理，而不是启动新代理，代理就无法看到你之后通过 export 设置的值——它的环境变量在启动时就已固定。headroom wrap 会通过回环地址上的 POST /admin/runtime-env，将你当前的设置热同步到运行中的代理，使设置生效，无需重启，也不会丢失请求。在共享代理上，这些覆盖设置会全局生效；最后一次显式设置的值优先。
无需配置，就能获得简洁的回答。人们很少明确说出自己希望回答有多简短，而是通过行为来表达：打断冗长的回复，或者还没来得及读完就转向下一个话题。headroom learn --verbosity 会读取历史会话，并选择合适的简洁程度：
headroom learn --verbosity # dry run — preview what it found
headroom learn --verbosity --apply # save it and apply it to the running proxy
处于 cache 模式（默认模式）的代理不会重新读取学习到的级别，因为在对话中途改变级别会使提示词缓存失效。在这种模式下，--apply 会通过 HEADROOM_VERBOSITY_LEVEL 固定该级别；若要在重启后继续保留，请自行设置这个变量。
如何衡量。输出节省量属于反事实估算——我们永远看不到模型原本会写出什么——因此，Headroom 会报告带有置信区间的估计值，并明确标注：
headroom output-savings
# Reduction: 31.7% (95% CI 27.7% … 35.7%) [estimated]
如果希望得到实测值，可以留出 10% 的对话作为不施加输出约束的对照组：export HEADROOM_OUTPUT_HOLDOUT=0.1。此时，仪表盘中的 Output Tokens Saved 卡片会显示 measured（实测），而非 estimated（估算），并附上区间。
→ 减少输出 token
任何兼容 OpenAI 的客户端都可以通过 headroom proxy 使用。原生支持 MCP 的客户端：headroom mcp install。使用 headroom unwrap <tool> 撤销持久化包装配置（claude、copilot、codex、grok、kimi、omp、opencode、openclaw、zcode）。注册表作者应使用规范的 server.json，而不是根据文字说明重新构造 headroom mcp serve 的接口约定。
对于 Anthropic /v1/messages，--mode cache 会跳过自动 --memory 上下文注入，以保持提供商侧的前缀稳定。OpenAI chat/responses 和 Gemini 会将记忆追加到活跃区的尾部。如果需要在 Anthropic 路径上自动注入记忆上下文，请使用 --mode token。
Headroom 可以将 Copilot CLI 的订阅流量路由到本地代理：
headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-4o
包装器会用 Headroom 可重复使用的 GitHub OAuth token 换取 Copilot 的短期 API token，并在启动时以 COPILOT_PROVIDER_API_URL=... 的形式输出上游端点。headroom copilot-auth login 会存储 Headroom 专用的 Copilot OAuth token，而不是依赖通用的 GitHub 或 Copilot CLI token；后两者虽然可以读取账户元数据，但仍会被 Copilot 的 token 交换端点拒绝。
对于 GitHub Enterprise Server 或使用自定义域名部署的 Copilot，请在启动前设置以下变量之一。如果两个变量都设置了，则以 URL 为准：
export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com
export GITHUB_COPILOT_ENTERPRISE_URL=https://ghe.example.com
对于 github.com/enterprises/your-enterprise 这类 GitHub.com Enterprise Cloud URL，两个变量都不要设置——Headroom 会使用 GitHub 的常规 token 交换端点，以及为当前登录账户返回的 Copilot API 端点。
平台支持。通过 Copilot CLI 的 Keychain 存储复用 macOS 身份验证，以及 Windows 设备身份验证，均已通过实际测试。Copilot CLI 1.0.81 不会通过 Headroom 所读取的旧版 Credential Manager 数据结构暴露其 Windows 登录信息，因此请在 Windows 上运行 headroom copilot-auth login。Linux Secret Service / secret-tool 复用已实现，但尚未在真实桌面环境中验证。在 Docker 和 CI 中，请显式传入 GITHUB_COPILOT_TOKEN 或 GITHUB_COPILOT_GITHUB_TOKEN，不要依赖对宿主机钥匙串的访问。
Headroom 会覆盖 Copilot 的 API 代理端点，因此模型选择仍以 VS Code 的模型选择器为准。GPT-5.5、GPT-5.6 Luna/Sol/Terra、Claude Sonnet/Opus 及其他 Copilot 模型在流量经过本地压缩代理时，都会保留原始模型 ID。Headroom 不会修改 VS Code，也不会更改 Codex 设置。
headroom copilot-auth login
headroom wrap vscode
保持命令运行，照常使用 Copilot 即可。上游 Copilot 的短期 token 只保存在代理进程中。完整指南 →
官方 Claude Code 扩展内嵌了 Claude Code，并读取与 CLI 相同的用户设置。安装 proxy 可选依赖，然后在准备通过 VS Code 打开的项目目录中运行包装器：
pip install "headroom-ai[proxy]"
headroom wrap vscode-claude
# Optional: persist Claude Code's client-owned 1M model selector
headroom wrap vscode-claude --1m
首次运行时，请重新加载 VS Code 窗口。使用 Claude Code 面板期间，保持包装器所在的终端运行；仪表盘或启动时输出的代理日志会显示请求和节省量。你的 Anthropic 身份验证和所选模型都会保留。按 Ctrl+C 可停止代理；headroom unwrap vscode-claude 会恢复设置前的配置。
使用 --1m 时，Headroom 会将解析后的 [1m] 模型选择值写入 Claude Code 的顶层用户设置，并在执行 headroom unwrap vscode-claude，或再次运行配置且未带 --1m 时，准确恢复之前的模型。使用 headroom wrap vscode-claude --no-configure --1m 可以只输出该设置，而不写入文件。
1M 模型支持和账户资格由 Claude Code 和 Anthropic 决定。本地测试验证的是设置持久化和恢复功能，并不代表已验证具备相应权限的真实 VS Code 会话，也不代表已验证最终的上下文窗口。完整指南 →
何时使用 · 何时跳过
如果你每天使用编程智能体，希望在不修改代码的情况下节省用量；或者同时使用多个智能体，希望它们共享一份记忆；又或者需要可逆的压缩——原始内容在配置的 TTL 内仍可通过 CCR 检索——那么它很适合你。
如果你只使用某一家提供商的原生压缩功能，而且不需要跨智能体记忆，或者你的工作环境是无法运行本地进程的沙箱，就可以跳过它。
Headroom 在工具输出量较大的长时间智能体会话中效果明显。对于简短对话、普通文本和本身已经高度精简的载荷，压缩幅度很小，甚至没有；低于 min_input_words 的内容块会逐字节原样返回。完整列表见局限性说明。
SmartCrusher——通用 JSON 压缩：支持字典数组、嵌套对象和混合类型。它会保留错误条目、超出正常统计范围的值，以及首尾边界项；筛选依据是字段方差统计，而不是关键词列表。
CodeCompressor——支持 Python、JS/TS、Go、Rust、Java、C/C++、C#、PHP 的 AST 感知压缩。
Kompress-v2-base——我们的 HuggingFace 模型，使用智能体运行轨迹训练。
图像压缩——通过训练过的机器学习路由器，实现 40–90% 的压缩。
CacheAligner——标记会导致提供商 KV 缓存前缀失效的易变内容；绝不重写提示词。
活跃区压缩——只压缩新增字节（新产生的工具输出、最新一轮对话）。冻结的前缀保持逐字节一致，因此提供商缓存得以保留，历史记录也不会被丢弃。
CCR——可逆压缩；模型可按需检索原始内容。
跨智能体记忆——共享存储，带有智能体来源信息，并自动去重。
SharedContext——在多智能体工作流之间传递压缩后的上下文。
headroom learn——基于插件，为 Claude、Codex 和 Gemini 挖掘失败案例。
compress()、各 SDK 和代理共用同一套请求生命周期：
设置 → 启动前 → 启动后 → 接收输入 → 缓存输入 → 路由输入 → 压缩输入 → 记忆输入 → 发送前 → 发送后 → 接收响应
具体工作由转换器完成：CacheAligner → ContentRouter → SmartCrusher / CodeCompressor / Kompress-base，仅作用于活跃区。IntelligentContext 和 RollingWindow 已在 PR-B1 中退役。
流水线扩展通过 on_pipeline_event(...) 观察或自定义生命周期阶段。
压缩钩子与生命周期并行存在，提供额外的扩展接口。
代理扩展是 ASGI 中间件、路由和启动策略的集成接口。
提供商和工具特有的行为位于 headroom/providers/ 下，使核心编排能够专注于生命周期、执行顺序和策略：
CLI/工具模块——headroom/providers/claude、copilot、codex、grok、openclaw
提供商运行时模块——headroom/providers/claude、gemini，共享后端分发逻辑位于 headroom/providers/registry.py
wrap.py、client.py、cli/proxy.py 和 proxy/server.py 将环境变量配置、API 目标规范化、后端选择和传输分发委托给相应模块处理
uv tool install --python 3.13 "headroom-ai[all]" # CLI, isolated app env
pip install "headroom-ai[all]" # Python, everything — includes the CLI
npm install headroom-ai # TypeScript SDK (library only)
docker pull ghcr.io/headroomlabs-ai/headroom:latest
细分可选依赖：[proxy]、[mcp]、[ml]（Kompress-v2-base）、[code]、[memory]、[vector]（可选 HNSW 后端——需要 C++ 工具链，不包含在 [all] 中）、[relevance]、[image]、[agno]、[langchain]、[evals]、[pytorch-mps]（将记忆嵌入模型的计算卸载到 Apple GPU——设置 HEADROOM_EMBEDDER_RUNTIME=pytorch_mps）。需要 Python 3.10+。
[all] 涵盖核心技术栈，但不包含框架适配器。请单独安装这些适配器：pip install "headroom-ai[langchain]"，[agno]、[strands]、[anyllm]、[bedrock] 也采用相同方式。
→ 安装指南——Docker 标签、持久运行的服务、PowerShell、devcontainers。
CLI 建议使用 uv tool install 安装，让命令运行在隔离的应用环境中。在 macOS 上，如果默认的 python3 版本高于当前 wheel 包支持的版本，请传入 --python 3.13：
brew install python@3.13 # if 3.13 is not already available
uv tool install --python 3.13 "headroom-ai[all]"
uv tool update-shell # if ~/.local/bin is not on PATH
headroom --version
Codex 和其他 MCP 客户端通常无法继承交互式 shell 的 PATH。请使用 command -v headroom 返回的绝对路径进行配置：
[mcp_servers.headroom]
command = "/Users/you/.local/bin/headroom"
args = ["mcp", "serve"]
只有当客户端启动时的 PATH 已包含 uv 工具目录，command = "headroom" 才能正常工作。
使用 pipx 时，请明确指定解释器：
pipx install --python python3.13 "headroom-ai[all]"
原生 wheel 包目前覆盖 macOS Apple Silicon 和 Linux。在 Intel macOS 上，请先使用 Docker 原生安装方式，直到提供原生 wheel 支持。
CPU 要求（x86/x86_64）。基于 ONNX 的功能——Magika 内容检测和嵌入相关性计算——使用预编译的 ONNX Runtime，需要 AVX2。在不支持 AVX2 的 x86 主机上（例如某些 Docker/QEMU 环境、较旧的云虚拟机），Headroom 会回退到不依赖 ONNX 的处理方式——BM25 相关性计算、启发式检测——而不会崩溃。arm64 和 Apple Silicon 不需要 AVX2。
headroom update # detects pip / pipx / uv tool and upgrades in place
headroom update --check # report the latest release without upgrading
headroom update --pre # include pre-releases
headroom update 会识别 Headroom 的安装方式（pip/venv、pip --user、pipx、uv tool），并在 macOS、Linux 和 Windows 上执行相应的升级操作。对于 git 检出的源码、可编辑安装、Docker 镜像，以及由外部管理的系统 Python（PEP 668），它会打印正确的手动操作步骤，而不是自行猜测。
代理也会在启动时打印一行“有可用更新”的提示。它每天最多在后台检查一次 PyPI，绝不会阻塞运行。设置 HEADROOM_UPDATE_CHECK=off 可关闭检查；在 --stateless 模式和 CI 环境中也会跳过检查。
如果 pip install "headroom-ai[all]" 因 CERTIFICATE_VERIFY_FAILED (unable to get local issuer certificate) 而失败，说明你的网络启用了 SSL 检查——一个使用公司 CA 证书的中间人代理。构建后端（maturin）会通过 TLS 栈不信任的连接下载 rustup。先安装 Rust，就能避免构建时再下载它：
# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable
# Windows
winget install Rustlang.Rustup && rustup default stable
重启 shell，然后再安装。使用预编译 wheel 包可以完全避免 Rust 构建：pip install --only-binary headroom-ai headroom-ai。Windows（win_amd64）、Linux（x86_64 / aarch64）和 macOS（Apple Silicon 和 Intel）均提供 wheel 包，因此这些平台无需本地 Rust 工具链——上述先安装 Rust 的步骤，仅适用于没有匹配 wheel 包、需要回退到 sdist 源码分发包的情况。
运行时，Headroom 会结合操作系统证书存储和 certifi 的公共根证书来验证上游 TLS。IT 部门通常会将 Zscaler / Netskope / Palo Alto 根证书安装到操作系统证书存储中，因此受管理的计算机通常无需额外配置。headroom doctor --network 会显示每个上游证书的签发者、Headroom 是否信任该证书，以及是否遭到网关拦截页面阻挡。如果根证书不在操作系统证书存储中，请将其导出为 PEM，并设置 HEADROOM_CA_BUNDLE=/path/to/root.pem（NODE_EXTRA_CA_CERTS 也有效）。完整指南及供 IT 部门参考的域名列表：企业网络。
仍有两个下载主机可能需要额外处理：
cdn.pyke.io —— Rust 核心使用的 ONNX Runtime，仅使用 Mozilla 根证书下载。可通过 ORT_STRATEGY=system 和 ORT_LIB_LOCATION=/path/to/onnxruntime 预先提供运行时。
huggingface.co —— kompress-base 模型（Python，使用操作系统证书存储）和 Rust 核心的嵌入模型（仅使用 Mozilla 根证书）。如果该域名被屏蔽，请预先下载模型并设置 HF_HUB_OFFLINE=1 运行，或者将 HF_ENDPOINT 指向可信镜像。
禁用压缩运行时（纯网关模式），这两类资源都不需要。
Intel macOS：没有预编译的 ONNX Runtime（#941）。ort-sys 未提供 x86_64-apple-darwin 的预编译二进制文件，因此即使不经过企业代理，源码构建默认也会失败。请将其指向系统运行时：
brew install onnxruntime
ORT_STRATEGY=system \
ORT_LIB_LOCATION="$(brew --prefix onnxruntime)/lib" \
ORT_PREFER_DYNAMIC_LINK=1 \
pip install "headroom-ai[all]"
# ORT is dlopen'd at runtime too:
export ORT_DYLIB_PATH="$(brew --prefix onnxruntime)/lib/libonnxruntime.dylib"
ORT_LIB_LOCATION 必须指向 lib/，而不是安装前缀目录本身，同时必须设置 ORT_PREFER_DYNAMIC_LINK=1——否则，即便设置了 ORT_STRATEGY=system，仍会尝试静态链接，而 Homebrew 安装的包不提供所需的静态库。
“Basic Constraints of CA cert not marked critical”仅在 HEADROOM_CERT_STORE=bundled 时出现（操作系统证书存储可以正常验证这些根证书）。如果 TLS 因以下错误而失败：
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
Basic Constraints of CA cert not marked critical
则说明已经找到并信任企业 CA，将其添加到 CA 证书包不会产生任何改变。搭配 OpenSSL 3.x 的 Python 3.13 默认启用 VERIFY_X509_STRICT，强制执行 RFC 5280 §4.2.1.9：CA 证书的 basicConstraints 必须标记为 critical。Zscaler 等流量检查服务的根证书设置了 CA:TRUE，却未设置 critical 标志，因此证书链会被拒绝。
HEADROOM_TLS_STRICT=0 只会清除 Headroom 所控制的每个 TLS 上下文中的严格验证标志，涵盖代理的 httpx 上游客户端，以及用于模型下载的 urllib3/huggingface_hub 路径。证书链验证、签名、有效期和主机名检查仍全部启用。
HEADROOM_TLS_STRICT=0 headroom proxy --port 8787
Rust 核心的下载使用 rustls 和 Mozilla 根证书，不受 HEADROOM_TLS_STRICT 及 CA 相关变量影响；请按上文所述，通过 ORT_STRATEGY=system 预先提供 ONNX Runtime，并通过 HF_ENDPOINT 提供模型。
headroom learn 会挖掘失败会话，并将纠正内容写入 CLAUDE.local.md（默认文件，已被 git 忽略；使用 --target CLAUDE.md 可写入团队共享文件）、AGENTS.md 或 GEMINI.md。→ 从失败中学习
默认启用匿名遥测。它会报告压缩的表现：压缩比、计数器、提供商和模型 ID、操作系统及架构。它绝不会发送提示词、生成结果、代码或文件路径。它的存在是为了让我们能够