## 项目概述

Headroom 是一个面向 AI 代理的上下文压缩层，旨在减少发送给大语言模型（LLM）的令牌数量，同时保持答案质量。它支持多种部署模式：作为 Python/TypeScript 库、本地代理服务器、MCP 服务器，以及命令行工具。Headroom 能够压缩工具输出、日志、文件、RAG 分块和对话历史，声称对 JSON 数据可减少 60-95% 的令牌，对编码代理可减少 15-20% 的令牌。项目采用 Apache-2.0 许可证，主要使用 Python 编写，并提供 TypeScript SDK。

## 核心功能

- **多模式部署**：支持库模式（`compress(messages)`）、代理模式（`headroom proxy`）、代理包装（`headroom wrap`）和 MCP 服务器。
- **内容感知压缩**：通过 ContentRouter 检测内容类型，并使用 SmartCrusher（JSON）、CodeCompressor（AST）和 Kompress-v2-base（文本）等压缩器。
- **可逆压缩（CCR）**：原始内容被本地缓存，LLM 可通过 `headroom_retrieve` 按需检索。
- **跨代理记忆**：共享存储，支持 Claude、Codex、Gemini、Grok 等，自动去重。
- **输出令牌减少**：通过代理调整模型输出，减少冗余表述和深度思考。
- **`headroom learn`**：从失败会话中挖掘经验，写入 `CLAUDE.local.md` 等文件。
- **缓存对齐**：检测可能破坏提供商 KV 缓存前缀的易变内容，并发出警告。
- **实时区域压缩**：仅压缩新增字节，保持冻结前缀不变，避免缓存失效。

## 适用与不适用场景

**适用场景：**
- 日常使用 AI 编码代理，希望在不修改代码的情况下节省令牌。
- 跨多个代理工作，需要共享记忆。
- 需要可逆压缩，原始内容可在 TTL 内检索。

**不适用场景：**
- 仅使用单一提供商的原生压缩，且不需要跨代理记忆。
- 在沙盒环境中运行，无法启动本地进程。

## 技术架构与依赖

- **核心组件**：CacheAligner、ContentRouter、CCR、SmartCrusher、CodeCompressor、Kompress-v2-base。
- **语言**：Python 3.10+（核心），TypeScript SDK（`headroom-ai` npm 包）。
- **依赖**：FastAPI（代理）、LiteLLM（定价）、ONNX Runtime（内容检测）、HuggingFace 模型（文本压缩）。
- **可选扩展**：`[proxy]`、`[mcp]`、`[ml]`、`[code]`、`[memory]`、`[vector]`（HNSW）、`[relevance]`、`[image]`、`[agno]`、`[langchain]`、`[evals]`、`[pytorch-mps]`。
- **平台支持**：macOS Apple Silicon、Linux（x86_64/aarch64）、Windows（部分）。

## 安装与快速开始

```bash
# 安装 CLI（推荐使用 uv）
uv tool install --python 3.13 "headroom-ai[all]"

# 或使用 pip
pip install "headroom-ai[all]"

# TypeScript SDK（仅库，无 CLI）
npm install headroom-ai

# 快速开始
headroom deploy                         # 一键本地部署
headroom wrap claude                    # 包装编码代理
headroom proxy --port 8787              # 启动代理
headroom doctor                         # 健康检查
```

## 典型使用方法

**库模式（Python）：**
```python
from headroom import compress
compressed = compress(messages, model="claude-3-5-sonnet")
```

**代理模式：**
```bash
headroom proxy --port 8787
# 配置客户端使用 http://127.0.0.1:8787 作为 API 端点
```

**MCP 服务器：**
```bash
headroom mcp install
# 在 MCP 客户端中配置 headroom 服务器
```

**包装代理：**
```bash
headroom wrap claude
headroom unwrap claude
```

## 配置与部署要点

- **环境变量**：`HEADROOM_OUTPUT_SHAPER=1` 启用输出缩减，`HEADROOM_TLS_STRICT=0` 处理严格 TLS，`HEADROOM_UPDATE_CHECK=off` 禁用更新检查。
- **代理配置**：可通过 `--backend bedrock` 等参数指定后端，支持 AWS Bedrock。
- **MCP 配置**：对于 Codex 等客户端，需使用绝对路径配置 `command`。
- **企业部署**：支持 Docker 镜像（`ghcr.io/chopratejas/headroom:latest`），提供托管服务。
- **平台注意事项**：Intel macOS 需手动安装 ONNX Runtime；x86 主机需 AVX2 支持。

## 限制、风险与许可证

- **许可证**：Apache-2.0。
- **限制**：需要本地进程运行；某些功能（如 ONNX 检测）依赖特定硬件；输出节省为估计值。
- **风险**：压缩可能丢失细节，但 CCR 提供可逆性；代理可能引入延迟；企业环境需注意 SSL 检查。
- **安全**：本地优先，数据不离开机器；但代理会处理敏感数据，需确保环境安全。

## 官方链接

- GitHub 仓库：https://github.com/headroomlabs-ai/headroom
- 文档：https://headroom-docs.vercel.app/docs
- PyPI：https://pypi.org/project/headroom-ai/
- npm：https://www.npmjs.com/package/headroom-ai
- HuggingFace 模型：https://huggingface.co/chopratejas/kompress-v2-base
- Discord：https://discord.gg/yRmaUNpsPJ

安装和使用 Headroom 主要有三种方式，你可以根据自己的技术栈和使用习惯来选择。对于大多数用户，最推荐的方式是通过 **uv** 或 **pip** 进行安装，然后以**代理（Proxy）模式**快速开始。

### 安装指南

Headroom 支持多种安装方式，核心要求是 **Python 3.10+**。

#### 方式一：使用 uv 工具安装（推荐）
如果你在 macOS (Apple Silicon) 或 Linux 上，并希望拥有一个全局的 `headroom` 命令，这是最干净的方式。它会将 Headroom 安装在一个独立的环境中。
```bash
# 安装包含所有功能的完整版本，并指定使用 Python 3.13
uv tool install --python 3.13 "headroom-ai[all]"

# 验证安装
headroom --version
```
如果安装后系统找不到 `headroom` 命令，可以运行 `uv tool update-shell` 来更新 PATH。

#### 方式二：在 Python 项目中使用 pip
如果你更习惯在 Python 的虚拟环境中管理包，可以使用 `pip` 进行安装。

*   **仅核心包**（基础压缩功能）：
    ```bash
    pip install headroom-ai
    ```

*   **安装特定功能**（例如代理服务器、代码压缩等）：
    ```bash
    pip install "headroom-ai[proxy]"  # 代理模式必须
    pip install "headroom-ai[code]"   # 启用AST感知的代码压缩
    pip install "headroom-ai[all]"    # 安装所有功能
    ```

#### 方式三：其他安装方式
*   **Node.js/TypeScript 项目**：`npm install headroom-ai`
*   **Docker 原生模式**：
    *   Linux/macOS: `curl -fsSL https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.sh | bash`
    *   Windows PowerShell: `irm https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.ps1 | iex`

### 快速开始：代理模式

安装完成后，最快速的体验方式就是启动一个本地代理服务器，然后将你的 AI 客户端指向它。

1.  **启动 Headroom 代理**：
    在终端中执行以下命令，Headroom 会在 `8787` 端口启动一个本地代理。
    ```bash
    headroom proxy --port 8787
    ```

2.  **配置你的 AI 工具**：
    将你的 AI 编码工具（如 Claude Code、Cursor 等）的 API 请求地址指向这个本地代理。

    *   **对于 Claude Code**：
        ```bash
        ANTHROPIC_BASE_URL=http://localhost:8787 claude
        ```
    *   **对于任何 OpenAI 兼容客户端**：
        ```bash
        OPENAI_BASE_URL=http://localhost:8787/v1 your-app
        ```
    如果使用 Claude Code 且觉得手动设置麻烦，也可以直接运行 `headroom wrap claude`，它会自动完成配置。

完成这两步后，所有经过代理的 API 请求和工具输出都会被 Headroom 自动压缩优化。

### 💡 补充信息：全局工具 HeadroomSwitch

如果你在 Windows 系统上使用多个 AI Agent，并希望更直观地管理 Headroom 的开关，可以关注社区开发的图形化工具 **HeadroomSwitch**。

它并非官方工具，但可以帮你一键开启/关闭对 Claude Code、Cursor 等 17 种 Agent 的压缩代理，并实时统计节省的 Token 数量。你可以在其 GitHub 仓库找到更多信息。