> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/headroomlabs-ai/headroom) · [上游 README](https://github.com/headroomlabs-ai/headroom/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 
  ██╗  ██╗███████╗ █████╗ ██████╗ ██████╗  ██████╗  ██████╗ ███╗   ███╗
  ██║  ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║
  ███████║█████╗  ███████║██║  ██║██████╔╝██║   ██║██║   ██║██╔████╔██║
  ██╔══██║██╔══╝  ██╔══██║██║  ██║██╔══██╗██║   ██║██║   ██║██║╚██╔╝██║
  ██║  ██║███████╗██║  ██║██████╔╝██║  ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║
  ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝     ╚═╝
              The context compression layer for AI agents

JSON 数据 token 减少 60–95%，编程智能体 token 减少 15-20% · library · proxy · MCP · content-aware compressors · local-first · reversible

CI codecov PyPI npm Model: Kompress-v2-base License: Apache 2.0 Docs

Docs · Install · Proof · Agents · Discord · llms.txt

AI agents / LLMs: 请在此阅读 /llms.txt，或获取 实时索引 / 完整文档 blob。

---

chopratejas%2Fheadroom | Trendshift

Headroom 会在数据到达 LLM 之前，压缩 AI 智能体读取的一切内容——工具输出、日志、RAG 分块、文件和对话历史。答案相同，token 仅为原来的一小部分。

Headroom in action
实时：10,144 → 1,260 tokens — 同样发现了 FATAL。

## 功能 - **Library** — 在 Python 或 TypeScript 中使用 `compress(messages)`，可内联嵌入任何应用 - **Proxy** — `headroom proxy --port 8787`，零代码改动，支持任何语言 - **Agent wrap** — 一条命令运行 `headroom wrap claude|codex|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe`；用 `headroom unwrap ` 撤销 - **MCP server** — `headroom_compress`、`headroom_retrieve`、`headroom_stats`，适用于任何 MCP 客户端 - **Cross-agent memory** — 在 Claude、Codex、Gemini 之间共享存储，自动去重 - **`headroom learn`** — 挖掘失败会话，将修正写入 `CLAUDE.local.md`（默认，已 gitignore）或 `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` - **Output token reduction** — 精简模型*写回*的内容（不仅是发送内容）：去除套话/重复代码，并在常规步骤中跳过深度「思考」。参见 [Output token reduction](#output-token-reduction-cut-what-the-model-writes-back)。 - **Reversible (CCR)** — 原文按需缓存，可供检索 ## 工作原理（30 秒） ``` 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、AST 或散文文本 - **CacheAligner** — 稳定前缀，使提供商 KV 缓存真正命中 - **CCR** — 本地存储原文；若需要，LLM 会调用 `headroom_retrieve` → [Architecture](https://headroom-docs.vercel.app/docs/architecture) · [CCR reversible compression](https://headroom-docs.vercel.app/docs/ccr) · [Kompress-v2-base model card](https://huggingface.co/chopratejas/kompress-v2-base) ## 快速开始（60 秒） ```bash # 1 — Install uv tool install "headroom-ai[all]" # Install `headroom` CLI as a global tool in self-contained virtual env pip install "headroom-ai[all]" # Python — ships the `headroom` CLI npm install headroom-ai # TypeScript SDK only — no `headroom` CLI # 2 — Pick your mode (the `headroom` commands below come from the uv or pip install) 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 — Verify setup and see the savings headroom doctor # health check — confirms routing is working headroom perf headroom dashboard # live savings dashboard (proxy must be running) ``` 建议使用 headroom 时，每次启动一个包装后的智能体会话，以确保完成所有必要设置。包装编程智能体时，headroom 会启动本地代理，设置提供 rtk 和 tokensave 等工具的 MCP 服务器，并启动配置为将请求代理到 headroom 的编程智能体会话。 `headroom` CLI **仅**通过 PyPI 包分发。npm 版 `headroom-ai` 是 TypeScript SDK——供导入的库（`import { compress } from 'headroom-ai'`），不是 CLI，因此不提供 `headroom` 命令。 细粒度 extras：`[proxy]`、`[mcp]`、`[ml]`、`[code]`、`[memory]`、`[vector]`（可选 HNSW 后端——需要 C++ 工具链，不包含在 `[all]` 中）、`[relevance]`、`[image]`、`[agno]`、`[langchain]`、`[evals]`、`[pytorch-mps]`（Apple GPU 内存嵌入器卸载——设置 `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`）。需要 **Python 3.10+**。 ### Codex / 全局安装 如果 Codex 或其他 MCP 客户端无法可靠继承 shell 中的 `PATH`，请将 Headroom 安装为持久化的 uv 工具，并让客户端指向绝对二进制路径： ```bash uv tool install "headroom-ai[all]" command -v headroom ``` 然后在 MCP 配置中使用返回的路径： ```toml [mcp_servers.headroom] command = "/absolute/path/from/command-v/headroom" args = ["mcp", "serve"] ``` `command = "headroom"` 仅在客户端以已包含 uv 工具目录的 `PATH` 启动时有效。 ## 验证 **真实智能体工作负载上的节省：** | 工作负载 | 之前 | 之后 | 节省 | |-------------------------------|-------:|-------:|--------:| | 代码搜索（100 条结果） | 17,765 | 1,408 | **92%** | | SRE 事件调试 | 65,694 | 5,118 | **92%** | | GitHub issue 分拣 | 54,174 | 14,761 | **73%** | | 代码库探索 | 78,502 | 41,254 | **47%** | **标准基准测试中保持精度：** | Benchmark | Category | N | Baseline | Headroom | Delta | |------------|----------|----:|---------:|---------:|------------| | GSM8K | 数学 | 100 | 0.870 | 0.870 | **±0.000** | | TruthfulQA | 事实性 | 100 | 0.530 | 0.560 | **+0.030** | | SQuAD v2 | 问答 | 100 | — | **97%** | 19% compression | | BFCL | 工具 | 100 | — | **97%** | 32% compression | 复现：`python -m headroom.evals suite --tier 1` · [完整基准测试与方法学](https://headroom-docs.vercel.app/docs/benchmarks) ## 输出 token 削减（精简模型写回的内容） 上文所述都能缩小你**发送**的 prompt。但你也要为模型**写回**的每个 token 付费——而在 Opus 级模型上，输出成本是输入的 5 倍。其中大量输出是浪费："好的，让我…" 这类开场白、重复打印你刚展示给它的代码，以及在读取文件等常规步骤上的冗长 "思考"。 Headroom 也能从代理侧削减这些输出，无需你改动任何代码： - **冗长度引导（Verbosity steering）** — 在 system prompt 末尾追加一条简短的 "保持简洁，不要复述上下文" 说明（这样你的 prompt 缓存仍能命中）。 - **努力度路由（Effort routing）** — 当某轮对话只是模型在工具结果之后继续（例如文件读取、测试通过），它会降低模型的思考努力度。新问题与错误仍保持全力。 开启方式： ```bash export HEADROOM_OUTPUT_SHAPER=1 # off by default headroom proxy --port 8787 ``` > **已在运行代理？** 这些开关在每次请求时都会*实时*读取，因此若代理是 `headroom wrap` **复用**（而非重新启动），之后 export 的环境变量它看不到——其环境在启动时已被快照。`headroom wrap` 现在会通过 loopback `POST /admin/runtime-env` 将你当前的设置热同步到运行中的代理，因此会**立即**生效，**无需重启**（无冷启动、无请求丢弃、无缓存丢失）。请在你 `wrap` 之前设置它们。在共享代理上，这些覆盖是全局的——以最后一次显式设置为准。 **找到适合你的简洁度。** 人们不会*说*自己想要多简洁——他们会*表现出来*（打断冗长回复，或在读完之前就继续下一步）。`headroom learn --verbosity` 会读取你过往会话并自动选择级别： ```bash headroom learn --verbosity # preview what it found (dry run) headroom learn --verbosity --apply # save it; the proxy uses it from now on ``` **查看你节省了多少输出 token。** 输出节省是*反事实*的——我们永远看不到模型*本来会*写什么——因此 Headroom 报告的是诚实的**估计值及置信区间**，而不是编造数字： ```bash 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 削减](https://headroom-docs.vercel.app/docs/savings) Star History Chart ## Agent 兼容性矩阵 | Agent | `headroom wrap` | Notes | |--------------|:---------------:|----------------------------------| | Claude Code | ✅ | `--memory` · `--code-graph` · `--1m` · `--tool-search` | | Codex | ✅ | shares memory with Claude | | Cursor | Manual setup | starts proxy and prints base URLs for Cursor settings | | Aider | ✅ | starts proxy + launches | | Copilot CLI | ✅ | starts proxy + launches | | OpenClaw | ✅ | installs as ContextEngine plugin | | OpenCode | ✅ | injects config · starts proxy + launches | | Cline | ✅ | starts proxy + injects config | | Continue | ✅ | starts proxy + injects config | | Goose | ✅ | starts proxy + launches | | OpenHands | ✅ | starts proxy + launches | | Mistral Vibe | ✅ | starts proxy + launches | | Cortex Code | Library only | 60–65% savings (library mode; no `wrap`) | 任何 OpenAI 兼容客户端均可通过 `headroom proxy` 使用。MCP 原生：`headroom mcp install`。 使用 `headroom unwrap ` 撤销持久化包装（支持：`claude`、`copilot`、`codex`、`opencode`、`openclaw`）。 ### GitHub Copilot CLI 订阅模式 Headroom 可将 GitHub Copilot CLI 订阅流量路由到本地代理： ```bash headroom copilot-auth login headroom wrap copilot --subscription -- --model gpt-4o ``` 这样 Headroom 就能拦截 OpenAI 兼容的 Copilot CLI 请求，在转发到 GitHub Copilot 托管 API 之前应用相同的代理压缩流水线。该包装器会将 Headroom 可复用的 GitHub OAuth token 兑换为 Copilot 的短期 API token，并在启动时将上游端点打印为 `COPILOT_PROVIDER_API_URL=...`。 `headroom copilot-auth login` 会存储 Headroom 专用的 Copilot OAuth token。这样可以避免依赖通用的 GitHub 或 Copilot CLI token——它们虽可读取 Copilot 账户元数据，但仍可能被 Copilot 的 token 兑换端点拒绝。 对于 GitHub Enterprise Server 或自定义域名的 Copilot 部署，请在启动前设置部署域名： ```bash export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com ``` 对于 `github.com/enterprises/your-enterprise` 这类 GitHub.com Enterprise Cloud URL，请勿设置 enterprise-domain 覆盖。Headroom 会使用 GitHub 的正常 token 兑换端点，以及为已登录账户公布的 Copilot API 端点。 平台支持说明：通过 Copilot CLI Keychain 存储在 macOS 上复用认证已通过冒烟测试。Windows Credential Manager、Linux Secret Service / `secret-tool`，以及 Docker/CI token 注入路径已实现或计划作为认证发现路径，但在被视为完全验证之前仍需要真实操作系统验证。对于 Docker 和 CI，建议显式传入 `GITHUB_COPILOT_TOKEN` 或 `GITHUB_COPILOT_GITHUB_TOKEN`，而不是依赖宿主机钥匙串访问。 ## 何时使用 · 何时跳过 **非常适合，如果你…** - 每天运行 AI 编程 agent，希望在不改代码的情况下节省成本 - 跨多个 agent 工作，并希望共享记忆 - 需要可逆压缩——在配置的 TTL 内可通过 CCR 取回原文 **可以跳过，如果你…** - 只使用单一提供商的原生压缩，且不需要跨 agent 记忆 - 在沙箱环境中工作，本地进程无法运行
集成 — 将 Headroom 接入任意技术栈 | Your setup | Hook in with | |------------------------|------------------------------------------------------------------| | Any Python app | `compress(messages, model=…)` | | Any TypeScript app | `await compress(messages, { model })` | | Anthropic / OpenAI SDK | `withHeadroom(new Anthropic())` · `withHeadroom(new OpenAI())` | | Vercel AI SDK | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` | | LiteLLM | `litellm.callbacks = [HeadroomCallback()]` | | LangChain | `HeadroomChatModel(your_llm)` | | Agno | `HeadroomAgnoModel(your_model)` | | Strands | [Strands 指南](https://headroom-docs.vercel.app/docs/strands) | | ASGI apps | `app.add_middleware(CompressionMiddleware)` | | Multi-agent | `SharedContext().put / .get` | | MCP clients | `headroom mcp install` |
内含功能 - **SmartCrusher** — 通用 JSON：字典数组、嵌套对象、混合类型。 - **CodeCompressor** — 面向 AST（抽象语法树）的压缩，支持 Python、JS/TS、Go、Rust、Java、C/C++、Perl。 - **Kompress-v2-base** — 我们的 HuggingFace 模型，在 agentic traces 上训练。 - **图像压缩** — 通过训练的 ML 路由器实现 40–90% 缩减。 - **CacheAligner** — 稳定前缀，使 Anthropic/OpenAI KV 缓存能够真正命中。 - **Live-zone 压缩** — 仅压缩新增字节（新的工具输出、最新轮次）；冻结前缀保持字节级一致，避免破坏提供商缓存。历史记录永不丢弃。 - **CCR** — 可逆压缩；LLM 按需检索原始内容。 - **跨 Agent 记忆** — 共享存储、Agent 来源追踪、自动去重。 - **SharedContext** — 在多 Agent 工作流之间传递压缩上下文。 - **`headroom learn`** — 基于插件的失败挖掘，适用于 Claude、Codex、Gemini。
流水线内部机制 Headroom 在 `compress()`、SDK 和代理之间暴露统一的稳定请求生命周期： `Setup` → `Pre-Start` → `Post-Start` → `Input Received` → `Input Cached` → `Input Routed` → `Input Compressed` → `Input Remembered` → `Pre-Send` → `Post-Send` → `Response Received` - **Transforms** 负责实际工作：CacheAligner → ContentRouter → SmartCrusher / CodeCompressor / Kompress-base（仅 live-zone；IntelligentContext 和 RollingWindow 已在 PR-B1 中退役）。 - **Pipeline extensions** 通过 `on_pipeline_event(...)` 观察或自定义生命周期阶段。 - **Compression hooks** 与规范生命周期并列，作为额外的扩展接入点。 - **Proxy extensions** 仍是服务器/应用集成的接入点，用于 ASGI 中间件、路由和启动策略。 提供商和工具特定行为位于 `headroom/providers/` 下，核心编排专注于生命周期、序列和策略。 - **CLI/工具切片**：`headroom/providers/claude`、`copilot`、`codex`、`openclaw` - **提供商运行时切片**：`headroom/providers/claude`、`gemini`，以及 `headroom/providers/registry.py` 中的共享后端/运行时调度 - **核心文件保持编排优先**：`wrap.py`、`client.py`、`cli/proxy.py` 和 `proxy/server.py` 将提供商特定的环境塑造、API 目标规范化、后端选择和传输调度委托出去。
## 面向团队的 Headroom Headroom OSS 面向**个人开发者**：在笔记本电脑上运行 `headroom proxy` 或 `headroom wrap`，几分钟内即可开始削减 token —— 免费、本地优先，数据不会离开你的机器。 在**整个工程组织**中运行则是另一回事：需要共享的、始终在线的部署；集中式配置与版本发布；组织范围的节省仪表板；SSO 和访问控制；气隙/VPC 安装；以及关键时刻有人可联系。这正是我们帮助企业解决的问题 —— 自托管加支持，或全托管。 **如果你的团队在 LLM token 上花费真金白银** —— Claude Code、Codex、Cursor 或在 CI 中运行的 Agent —— **并且你希望所有人都能享受这些节省，而不仅仅是一台笔记本电脑：** → 请发送邮件至 **[hello@headroomlabs.ai](mailto:hello@headroomlabs.ai)**，附上你的技术栈和大概的月度 LLM 支出，我们将帮助你在整个组织中推广 Headroom。 本仓库中的一切均为开源（Apache 2.0）。托管服务仅面向希望由我们部署、支持和扩展的团队。 ## 安装 ```bash pip install "headroom-ai[all]" # Python, everything — includes the `headroom` CLI npm install headroom-ai # TypeScript SDK (library only — no `headroom` CLI) docker pull ghcr.io/chopratejas/headroom:latest ``` 细粒度 extras：`[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]`）。 使用 `pipx`？请显式选择受支持的解释器： ```bash pipx install --python python3.13 "headroom-ai[all]" ``` > **若想看到美元节省，请选择 3.13。** 仪表板的 *Proxy $ Saved* 磁贴使用 [LiteLLM](https://github.com/BerriAI/litellm), 为压缩定价，而 LiteLLM 无法在 Python 3.14+ 上安装。在 3.14 上仍可追踪 token 节省，但美元数字会保持 `$0.00`。如果你已在 3.14 上安装，请使用 `pipx reinstall headroom-ai --python python3.13` 切换并重启代理。 → [安装指南](https://headroom-docs.vercel.app/docs/installation) —— Docker 标签、持久化服务、PowerShell、devcontainers。 > **CPU 要求（x86/x86_64）：** 基于 ONNX 的功能 —— Magika 内容检测和嵌入相关性 —— 使用预编译的 ONNX Runtime，需要 **AVX2**。在没有 AVX2 的 x86 主机上（部分 Docker/QEMU 环境和较旧的云 VM），Headroom 会自动回退到非 ONNX 路径（BM25 相关性、启发式检测），而不是崩溃。`arm64`/Apple Silicon 不需要 AVX2。 ### 更新 ```bash 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 checkout、可编辑安装、Docker 镜像和外部管理的系统 Python（PEP 668），它会打印正确的手动步骤，而不是盲目猜测。 代理还会在启动时显示一行「有可用更新」提示。它最多每天检查一次 PyPI，在后台进行，从不阻塞。使用 `HEADROOM_UPDATE_CHECK=off` 可退出（在 `--stateless` 模式和 CI 中也会跳过）。 ### 企业 / SSL 检查环境 如果 `pip install "headroom-ai[all]"` 因 `CERTIFICATE_VERIFY_FAILED`（`unable to get local issuer certificate`）失败，说明你的网络使用了 **SSL 检查** —— 一个呈现公司颁发 CA 的 MITM 代理。构建后端（`maturin`）通过你的 TLS 栈不信任的连接下载 `rustup`。**请先安装 Rust**，这样构建过程就不会再去获取它： ```bash # 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，然后运行 `pip install "headroom-ai[all]"`。在可用的情况下，预构建 wheel 可完全避免 Rust 构建：`pip install --only-binary headroom-ai headroom-ai`。预构建 wheel 已为 Windows（`win_amd64`）、Linux（`x86_64` / `aarch64`）和 macOS（Apple Silicon 和 Intel）发布，因此这些平台的安装永远不需要本地 Rust 工具链 —— 上述先装 Rust 的流程仅适用于没有匹配 wheel 时的平台无关 sdist 回退。 有两个运行时资源通过 TLS 获取；如果被阻止，请通过 `REQUESTS_CA_BUNDLE` / `SSL_CERT_FILE` / `CURL_CA_BUNDLE` 信任你的企业 CA： - **`cdn.pyke.io`** —— Rust 核心的 ONNX Runtime。也可使用 `ORT_STRATEGY=system` 和 `ORT_LIB_LOCATION=/path/to/onnxruntime` 预先提供。 - **`huggingface.co`** —— `kompress-base` 压缩模型。预先下载并使用 `HF_HUB_OFFLINE=1` 运行，或将 `HF_ENDPOINT` 设置为受信任的镜像。 在禁用压缩（纯网关）的情况下运行，两者都不需要。 #### 「CA 证书的 Basic Constraints 未标记为 critical」（Python 3.13+ 严格模式） 这与上述失败**不同**。如果 TLS 失败并显示： ``` [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Basic Constraints of CA cert not marked critical ``` 则说明企业 CA **已被**找到并信任 —— 将其添加到 CA 捆绑包不会有任何改变。Python 3.13 + OpenSSL 3.x 默认启用 `VERIFY_X509_STRICT`，它强制执行 RFC 5280 §4.2.1.9：CA 证书的 `basicConstraints` 必须标记为 *critical*。Zscaler 等检查根证书将 `CA:TRUE` 设置时未带 critical 位，因此证书链被拒绝。 将 **`HEADROOM_TLS_STRICT=0`** 设置为仅清除 Headroom 所管控的每个 TLS 上下文中*仅有的* strict 标志 — 包括代理的 httpx 上游客户端**以及**用于模型下载的 urllib3/`huggingface_hub` 路径。证书链校验、签名、过期与主机名校验均保持开启；这严格窄于禁用验证。 ```bash HEADROOM_TLS_STRICT=0 headroom proxy --port 8787 ``` Rust 核心的 ONNX 下载（`cdn.pyke.io`）使用独立的 TLS 栈（rustls / 操作系统信任库），不受 `HEADROOM_TLS_STRICT` 影响。在 Windows 上，企业根证书必须位于**计算机**证书存储区（浏览器已在此信任该证书）；或使用 `ORT_STRATEGY=system` + `ORT_LIB_LOCATION=/path/to/onnxruntime` 预置 ONNX Runtime，以完全跳过下载。 ## headroom learn

headroom learn 运行演示

`headroom learn` — 挖掘失败会话，将修正写入 `CLAUDE.local.md`（默认，gitignored；团队共享文件请使用 `--target CLAUDE.md`）/ `AGENTS.md` / `GEMINI.md`。 ## Documentation | 从这里开始 | 深入了解 | |-------------------------------------------------------------------------------|------------------------------------------------------------------------------------| | [快速入门](https://headroom-docs.vercel.app/docs/quickstart) | [架构](https://headroom-docs.vercel.app/docs/architecture) | | [代理](https://headroom-docs.vercel.app/docs/proxy) | [压缩原理](https://headroom-docs.vercel.app/docs/how-compression-works) | | [MCP 工具](https://headroom-docs.vercel.app/docs/mcp) | [CCR — 可逆压缩](https://headroom-docs.vercel.app/docs/ccr) | | [记忆](https://headroom-docs.vercel.app/docs/memory) | [缓存优化](https://headroom-docs.vercel.app/docs/cache-optimization) | | [失败学习](https://headroom-docs.vercel.app/docs/failure-learning) | [基准测试](https://headroom-docs.vercel.app/docs/benchmarks) | | [配置](https://headroom-docs.vercel.app/docs/configuration) | [限制](https://headroom-docs.vercel.app/docs/limitations) | | [持久化安装](https://headroom-docs.vercel.app/docs/persistent-installs) (`headroom init` / `headroom install apply`) | [节省分析](https://headroom-docs.vercel.app/docs/savings) (`headroom savings` / `headroom perf` / `headroom doctor`) | ## Compared to Headroom **在本地**运行，覆盖**所有**内容类型，兼容所有主流框架，且**可逆**。 | | 范围 | 部署 | 本地 | 可逆 | |------------------------------------------------------------------------------|------------------------------------------------|------------------------------------|:-----:|:----------:| | **Headroom** | 全部上下文 — 工具、RAG、日志、文件、历史 | 代理 · 库 · 中间件 · MCP | Yes | Yes | | [RTK](https://github.com/rtk-ai/rtk) | CLI 命令输出 | CLI 包装器 | Yes | No | | [lean-ctx](https://github.com/yvgude/lean-ctx) | 工具输出、文件、shell、历史 | 代理 · 库 · 中间件 · MCP · CLI | Yes | Yes | | [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | 发送至其 API 的文本 | 托管 API 调用 | No | No | | OpenAI Compaction | 对话历史 | 提供商原生 | No | No | > **致谢。** Headroom 内置了出色的 [RTK](https://github.com/rtk-ai/rtk) 二进制文件，用于 shell 输出改写 — `git show --short`、作用域 `ls`、摘要化安装器。衷心感谢 RTK 团队；他们的工具是我们技术栈的一等公民，Headroom 会压缩其下游的一切内容。Headroom 也可将 [lean-ctx](https://github.com/yvgude/lean-ctx) 用作选定的 CLI 上下文工具；运行 `headroom wrap ...` 前请设置 `HEADROOM_CONTEXT_TOOL=lean-ctx`。 ## Contributing ```bash git clone https://github.com/chopratejas/headroom.git && cd headroom uv sync --extra dev && uv run pytest ``` 位于 `.devcontainer/` 中的 Devcontainers（默认 + 含 Qdrant 与 Neo4j 的 `memory-stack`）。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## Community - **[Discord](https://discord.gg/yRmaUNpsPJ)** — 提问、反馈、实战经验。 - **[HuggingFace 上的 Kompress-v2-base](https://huggingface.co/chopratejas/kompress-v2-base)** — 我们文本压缩背后的模型。 ## License Apache 2.0 — 参见 [LICENSE](LICENSE)。