# https://github.com/chopratejas/headroom 项目说明书
生成时间：2026-05-30 18:14:18 UTC
## 目录
- [Headroom 概述](#overview)
- [安装指南](#installation)
- [快速开始](#quickstart)
- [代理服务器](#proxy-server)
- [CCR 可逆压缩](#ccr)
- [压缩算法](#compression)
- [MCP 服务器集成](#mcp-integration)
- [CLI 代理包装器](#cli-wrappers)
- [代理间内存系统](#memory-system)
- [配置参考](#configuration)
## Headroom 概述
### 相关页面
相关主题：[安装指南](#installation), [压缩算法](#compression)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/chopratejas/headroom/blob/main/README.md)
- [headroom/cli/wrap.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
- [headroom/cli/learn.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/learn.py)
- [crates/headroom-py/src/lib.rs](https://github.com/chopratejas/headroom/blob/main/crates/headroom-py/src/lib.rs)
- [headroom/cli/proxy.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
- [headroom/cli/init.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/init.py)
- [sdk/typescript/README.md](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/README.md)
- [sdk/typescript/examples/shared-context-multi-agent.ts](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/examples/shared-context-multi-agent.ts)
# Headroom 概述
Headroom 是一个专为 AI 编程助手设计的**上下文压缩系统**，通过多层级压缩技术显著减少发送给 LLM 的 token 数量，从而节省高达 90% 的使用成本。该项目支持多种主流 AI 编程工具（包括 Claude Code、Codex、Cursor、Aider、Copilot CLI 等），并提供跨代理共享记忆、压缩缓存检索（CCR）等高级功能。资料来源：[README.md]()
## 核心功能特性
Headroom 的压缩能力建立在多个协同工作的核心组件之上：
| 功能组件 | 功能描述 |
|---------|---------|
| **ML Router** | 基于训练模型的智能路由，实现高达 90% 的压缩率 |
| **CacheAligner** | 稳定化前缀，使 Anthropic/OpenAI KV 缓存能够命中 |
| **IntelligentContext** | 基于评分的上下文适配，根据重要性分配资源 |
| **CCR** | 可逆压缩系统，LLM 可按需检索原始内容 |
| **Cross-agent Memory** | 跨代理共享存储，支持代理溯源和自动去重 |
| **SharedContext** | 压缩上下文在多代理工作流中高效传递 |
资料来源：[README.md]()
## 架构设计
### 整体架构图
```mermaid
graph TB
subgraph 用户层["用户层"]
CLI[CLI 工具]
SDK_Py[Python SDK]
SDK_TS[TypeScript SDK]
end
subgraph 核心层["核心压缩层"]
Proxy[Headroom Proxy]
Compress[compress 函数]
Transforms[Transforms 变换]
end
subgraph Transforms["Transforms 组件"]
CA[CacheAligner]
CR[ContentRouter]
SC[SmartCrusher]
CC[CodeCompressor]
KB[Kompress-base]
IC[IntelligentContext]
RW[RollingWindow]
end
subgraph 存储层["存储与检索"]
Memory[Cross-agent Memory]
CCR[CCR 缓存]
DB[(向量数据库)]
end
CLI --> Proxy
SDK_Py --> Compress
SDK_TS --> Compress
Proxy --> Transforms
Compress --> Transforms
Transforms --> Memory
Transforms --> CCR
Memory --> DB
CCR --> DB
```
### 请求生命周期
Headroom 在 `compress()`、SDK 和 Proxy 中暴露统一稳定的请求生命周期：
```mermaid
graph LR
S[Setup] --> PS[Pre-Start] --> PstS[Post-Start] --> IR[Input Received]
IR --> ICa[Input Cached] --> IRo[Input Routed] --> ICo[Input Compressed]
ICo --> IRe[Input Remembered] --> PSe[Pre-Send] --> PSt[Post-Send] --> RR[Response Received]
```
**生命周期阶段说明：**
| 阶段 | 说明 |
|-----|------|
| Setup | 初始化配置和依赖 |
| Pre-Start / Post-Start | 启动钩子，执行预热操作 |
| Input Received | 接收原始消息 |
| Input Cached | 缓存原始输入 |
| Input Routed | 智能路由决策 |
| Input Compressed | 应用压缩变换 |
| Input Remembered | 记忆系统交互 |
| Pre-Send / Post-Send | 发送前后的钩子 |
| Response Received | 接收并处理响应 |
资料来源：[README.md]()
## 安装与快速开始
### 安装方式
```bash
# 基础安装
pip install headroom-ai
# 包含代码感知压缩（需要 tree-sitter）
pip install headroom-ai[code]
# 开发安装
pip install -e ".[dev]"
```
### CLI 基础用法
```bash
# 启动代理包装器（自动配置代理和上下文工具）
headroom wrap cline
headroom wrap goose
headroom wrap claude
# 启动独立代理
headroom wrap claude -- session
# 启动本地代理
headroom proxy
# 学习模式
headroom learn
headroom learn --apply
```
资料来源：[headroom/cli/wrap.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
## 代理包装器（Wrap）
`headroom wrap` 命令提供一键式集成，自动配置代理环境、注入上下文工具指导，并启动 Headroom 代理。
### 支持的代理
| 代理 | CLI 上下文工具 | MCP 支持 | 包装模式 |
|-----|--------------|---------|---------|
| Claude | `--rtk` · `--memory` · `--code-graph` | ✓ | 模式 A（启动子进程）|
| Codex | 共享记忆 | ✓ | 模式 A |
| Cursor | 打印配置（粘贴一次）| ✗ | 配置指导 |
| Aider | ✓ | ✓ | 启动代理 + 启动代理 |
| Copilot CLI | ✓ | ✓ | 启动代理 + 启动代理 |
| OpenClaw | ✓ | 安装为 ContextEngine 插件 | 插件模式 |
| Cline | ✓ | ✓ | 模式 B（代理观察）|
| Goose | ✓ | ✓ | 模式 B |
资料来源：[headroom/cli/wrap.py:1-200]()
### Wrap 命令行选项
| 选项 | 说明 | 默认值 |
|-----|------|-------|
| `--port` | 代理监听端口 | 8080 |
| `--rtk` | 设置 RTK 上下文工具 | 启用 |
| `--no-rtk` | 跳过 CLI 上下文工具设置 | - |
| `--memory` | 启用跨代理记忆 | 禁用 |
| `--no-memory` | 禁用记忆功能 | - |
| `--code-graph` | 启用代码图分析 | 禁用 |
| `--prepare-only` | 仅准备配置，不启动代理 | - |
| `--verbose` | 详细输出 | - |
### 内存注入机制
Wrap 命令会自动向代理配置文件注入内存使用指导：
```python
def _inject_memory_agents_md(file_path: Path) -> bool:
"""注入内存使用指导到 AGENTS.md（幂等操作）"""
memory_block = """## Memory
Use the `headroom_memory` MCP server for persistent cross-session knowledge.
**Before** answering questions about prior decisions, conventions, project context,
architecture, user preferences — call `memory_search` first.
**After** making durable decisions, discovering conventions — call `memory_save`."""
```
资料来源：[headroom/cli/wrap.py:1-100]()
## Python SDK
### 基础压缩调用
```python
from headroom import compress
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "..."},
]
result = compress(messages, model="claude-sonnet-4-20250514")
print(f"压缩后: {result.compressed_tokens} tokens")
print(f"节省: {result.savings_percent:.0f}%")
```
### SmartCrusher 配置
SmartCrusher 是核心压缩变换之一，可通过 `SmartCrusherConfig` 精细控制：
```python
from headroom._core import SmartCrusherConfig
config = SmartCrusherConfig(
enabled=True,
min_items_to_analyze=5,
min_tokens_to_crush=100,
max_items_after_crush=10,
relevance_threshold=0.25,
)
```
| 配置字段 | 类型 | 说明 |
|---------|-----|------|
| enabled | bool | 是否启用 SmartCrusher |
| min_items_to_analyze | int | 最少分析项目数 |
| min_tokens_to_crush | int | 最少压缩 token 数 |
| max_items_after_crush | int | 压缩后最大项目数 |
| relevance_threshold | float | 关联性阈值（0.0-1.0）|
资料来源：[crates/headroom-py/src/lib.rs]()
### 压缩钩子（Hooks）
```python
from headroom import CompressContext, CompressEvent
class MyHooks:
def pre_compress(self, ctx: CompressContext) -> dict:
return {"priority": 1.0}
def post_compress(self, event: CompressEvent):
print(f"节省 {event.tokens_saved} tokens")
```
## TypeScript SDK
### 安装
```bash
npm install headroom-ai
```
### OpenAI 与 Anthropic 适配器
```typescript
import { withHeadroom } from "headroom-ai/vercel-ai";
import { withHeadroomOpenAI, withHeadroomAnthropic } from "headroom-ai";
import OpenAI from "openai";
import Anthropic from "@anthropic-ai/sdk";
// OpenAI 压缩
const openai = withHeadroomOpenAI(new OpenAI());
const response = await openai.chat.completions.create({
model: "gpt-4o",
messages,
});
// Anthropic 压缩
const anthropic = withHeadroomAnthropic(new Anthropic());
const message = await anthropic.messages.create({
model: "claude-sonnet-4-20250514",
messages,
});
```
### SharedContext（多代理）
```typescript
import { SharedContext } from "headroom-ai";
const ctx = new SharedContext({
model: "gpt-4o",
ttl: 3600,
maxEntries: 100
});
// Agent A 存储（自动压缩）
const entry = await ctx.put("research", bigAgentOutput);
console.log(`节省: ${entry.savingsPercent.toFixed(0)}%`);
// Agent B 读取（~80% 更小）
const summary = ctx.get("research");
// Agent B 按需获取完整内容
const full = ctx.get("research", { full: true });
```
### 错误处理
```typescript
import {
HeadroomError,
HeadroomAuthError,
HeadroomCompressError,
ConfigurationError,
} from "headroom-ai";
try {
await client.compress(messages);
} catch (err) {
if (err instanceof HeadroomAuthError) {
console.error("认证失败 — 检查 HEADROOM_API_KEY");
} else if (err instanceof HeadroomCompressError) {
console.error(`压缩错误 ${err.statusCode}: ${err.errorType}`);
}
}
```
资料来源：[sdk/typescript/README.md]()
## 代理服务（Proxy）
`headroom proxy` 启动一个本地 HTTP 代理，拦截并压缩所有 AI API 调用。
### 代理选项
| 选项 | 环境变量 | 说明 |
|-----|---------|------|
| `--port` | HEADROOM_PORT | 代理监听端口 |
| `--budget` | HEADROOM_BUDGET | 每日预算限制（USD）|
| `--code-aware/--no-code-aware` | HEADROOM_CODE_AWARE_ENABLED | 启用 AST 代码压缩 |
| `--exclude-tools` | HEADROOM_EXCLUDE_TOOLS | 排除的工具列表 |
| `--log-file` | - | JSONL 日志文件路径 |
| `--log-messages` | - | 启用完整消息日志 |
| `--codex-wire-debug` | - | Codex 调试快照 |
### 代理配置示例
```bash
# 基础代理
headroom proxy --port 8080
# 带预算限制
headroom proxy --budget 10.00
# 启用代码感知压缩
HEADROOM_CODE_AWARE_ENABLED=1 headroom proxy
# 排除特定工具
headroom proxy --exclude-tools "read_file,write_file"
```
资料来源：[headroom/cli/proxy.py]()
### 请求结果处理
代理引入了 `RequestOutcome` 机制，用于统一处理不同场景下的请求结果：
```mermaid
graph TD
Req[请求] --> Route{路由决策}
Route -->|缓存命中| CacheHit[缓存响应]
Route -->|缓存未命中| Compress[压缩处理]
Compress --> Transforms{Transforms 应用}
Transforms -->|CCR 可逆| CCR[压缩缓存检索]
Transforms -->|智能路由| IC[IntelligentContext]
Transforms -->|其他| Std[标准压缩]
CCR --> Retriever[检索器]
```
## 学习模式（Learn）
`headroom learn` 通过 LLM 分析对话历史，挖掘工具调用失败模式，生成预防性上下文。
### 架构
```mermaid
graph LR
Sessions[会话历史] --> Analyzer[SessionAnalyzer]
Analyzer --> Plugin{插件系统}
Plugin -->|Claude| ClaudePlugin[Claude Learn]
Plugin -->|Codex| CodexPlugin[Codex Learn]
Plugin -->|Gemini| GeminiPlugin[Gemini Learn]
Plugin -->|External| ExtPlugin[外部插件]
Analyzer --> Recommendations[上下文建议]
```
### 用法示例
```bash
# 自动检测代理和模型
headroom learn
# 分析并应用建议
headroom learn --apply
# 指定模型分析
headroom learn --model gpt-4o
# 分析所有项目
headroom learn --all
headroom learn --agent codex --all
# 并行工作线程数
headroom learn --workers 4
```
资料来源：[headroom/cli/learn.py]()
## MCP 集成
Headroom 支持 MCP（Model Context Protocol）服务器，可通过 `headroom mcp install` 安装。
### MCP 服务
| 服务 | 功能 |
|-----|------|
| `headroom_memory` | 跨会话持久化记忆 |
| `memory_search` | 搜索记忆内容 |
| `memory_save` | 保存重要信息 |
| `memory_list` | 列出记忆条目 |
### 安装 MCP 服务器
```bash
# 安装 headroom MCP 服务器
headroom mcp install
# Codex 等代理需要注册
from headroom.mcp_registry import CodexRegistrar
_setup_headroom_mcp(CodexRegistrar(), port=8080, force=True)
```
> **注意：** 当前版本中 `headroom proxy` **不提供** HTTP MCP 端点（`/mcp` 返回 404）。如需 MCP 支持，请使用 stdio 模式连接。资料来源：[Issue #460](https://github.com/chopratejas/headroom/issues/460)
## 配置管理
### 初始化配置
`headroom init` 命令创建或更新项目级配置文件：
```python
# 配置结构
{
"model": "claude-sonnet-4-20250514",
"provider": "anthropic",
"hooks": {
"pre_compress": {...},
"post_compress": {...}
}
}
```
### Codex 配置管理
```python
def _strip_codex_init_block(content: str) -> str:
"""从 Codex config.toml 中移除所有 Headroom 管理的块"""
# 移除任何提供者标记 → 结束标记范围
while _CODEX_PROVIDER_MARKER_START in content:
...
```
资料来源：[headroom/cli/init.py]()
## 已知问题与限制
### CCR 在多代理线程中的消息归属问题
**问题描述：** `_append_context_to_latest_non_frozen_user_turn()` 将主动扩展块注入到最新用户消息内容中。在多代理设置中，该消息可能包含结构化 XML 归属标记（``），注入的块会导致消息归属损坏。
**状态：** 社区已报告（[Issue #503](https://github.com/chopratejas/headroom/issues/503)），等待修复。
### MCP HTTP 端点不可用
**问题描述：** 文档暗示 `headroom proxy` 可用作 `/mcp` 端点，但当前安装的包返回 404。stdio MCP 服务器正常工作。
**状态：** 社区已报告（[Issue #460](https://github.com/chopratejas/headroom/issues/460)），需要文档澄清。
### 记忆系统按项目隔离
**修复版本：** v0.21.34
之前的版本中，记忆会在不同项目间泄漏。v0.21.34 引入按项目存储隔离，确保项目间记忆不会交叉污染。
### LiteLLM 安全问题
**问题描述：** `litellm` PyPI 包在 v1.82.8 版本存在供应链攻击风险，包含恶意 `.pth` 文件。
**建议：** 评估是否需要继续使用 LiteLLM 集成，评估替代方案。资料来源：[Issue #56](https://github.com/chopratejas/headroom/issues/56)
## 社区资源
| 资源 | 链接 |
|-----|------|
| 实时排行榜 | [headroomlabs.ai/dashboard](https://headroomlabs.ai/dashboard) — 累计节省 60B+ tokens |
| Discord 社区 | [discord.gg/yRmaUNpsPJ](https://discord.gg/yRmaUNpsPJ) |
| Kompress-base 模型 | [HuggingFace](https://huggingface.co/chopratejas/kompress-base) |
| 最新版本 | [Release v0.22.2](https://github.com/chopratejas/headroom/releases/tag/v0.22.2) |
## 贡献指南
```bash
# 克隆并设置开发环境
git clone https://github.com/chopratejas/headroom.git && cd headroom
pip install -e ".[dev]" && pytest
# 开发容器
# .devcontainer/ 包含默认配置和 memory-stack 配置（Qdrant & Neo4j）
```
## 相关链接
- [代理集成指南](Integration)
- [压缩变换详解](Transforms)
- [记忆系统文档](Memory)
- [CCR 机制说明](CCR)
- [SDK 参考文档](SDK-Reference)
---
## 安装指南
### 相关页面
相关主题：[Headroom 概述](#overview)
相关源码文件
以下源码文件用于生成本页说明：
- [pyproject.toml](https://github.com/chopratejas/headroom/blob/main/pyproject.toml)
- [Dockerfile](https://github.com/chopratejas/headroom/blob/main/Dockerfile)
- [docs/content/docs/installation.mdx](https://github.com/chopratejas/headroom/blob/main/docs/content/docs/installation.mdx)
- [README.md](https://github.com/chopratejas/headroom/blob/main/README.md)
- [headroom/cli/wrap.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
- [headroom/cli/proxy.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
- [CONTRIBUTING.md](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md)
- [sdk/typescript/README.md](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/README.md)
# 安装指南
本文档详细介绍 Headroom 的各种安装方式，包括 Python 包安装、TypeScript SDK 安装、Docker 部署、CLI 工具配置以及 MCP 服务器设置。Headroom 是一个上下文压缩平台，通过智能压缩技术帮助 AI 编码助手（如 Claude Code、Codex、Cursor 等）减少 token 消耗，节省高达 90% 的上下文成本。
## 系统要求
### Python 环境
Headroom 支持 Python 3.10 及以上版本。核心包 `headroom-ai` 包含 Python SDK 和 CLI 工具，Rust 扩展提供高性能压缩实现。
```bash
# 检查 Python 版本
python --version
# Python 3.10+
```
### 可选依赖
| 依赖项 | 用途 | 安装选项 |
|--------|------|----------|
| Rust 工具链 | 编译高性能 Rust 扩展 | `pip install headroom-ai[rust]` |
| tree-sitter | AST 代码感知压缩 | `pip install headroom-ai[code]` |
| qdrant-client | 向量数据库（记忆系统） | `pip install headroom-ai[memory]` |
| anthropic | Claude API 调用 | 默认安装 |
| openai | OpenAI API 调用 | 默认安装 |
### Node.js 环境（TypeScript SDK）
使用 TypeScript SDK 时需要 Node.js 18+ 和包管理器（npm、yarn 或 pnpm）。
## pip 安装（推荐方式）
### 基础安装
```bash
pip install headroom-ai
```
### 完整安装（包含所有可选依赖）
```bash
pip install "headroom-ai[all]"
```
完整安装包含：
- `[rust]` — Rust 加速扩展（性能提升约 3-5 倍）
- `[code]` — tree-sitter 代码感知压缩
- `[memory]` — Qdrant 向量数据库支持
- `[dev]` — 开发依赖和测试工具
### 分阶段安装
```bash
# 仅核心功能
pip install headroom-ai
# 启用 Rust 加速
pip install headroom-ai[rust]
# 启用代码感知压缩
pip install headroom-ai[code]
# 启用记忆系统
pip install headroom-ai[memory]
```
资料来源：[pyproject.toml:1-50](https://github.com/chopratejas/headroom/blob/main/pyproject.toml)
## TypeScript / JavaScript SDK 安装
### 使用 npm
```bash
npm install headroom-ai
```
### 使用 yarn
```bash
yarn add headroom-ai
```
### 使用 pnpm
```bash
pnpm add headroom-ai
```
### SDK 模块导入
```typescript
import { compress } from "headroom-ai";
import { withHeadroom, withHeadroomOpenAI, withHeadroomAnthropic } from "headroom-ai";
import { headroomMiddleware } from "headroom-ai/vercel-ai";
```
资料来源：[sdk/typescript/README.md:1-30](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/README.md)
## Docker 安装
### 下载预构建镜像
Headroom 提供官方 Docker 镜像，适用于不想配置本地 Python 环境的用户：
```bash
docker pull ghcr.io/chopratejas/headroom:latest
```
### 运行容器
```bash
# 基本用法
docker run -p 8080:8080 \
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
-e OPENAI_API_KEY=$OPENAI_API_KEY \
ghcr.io/chopratejas/headroom:latest
# 挂载本地配置
docker run -p 8080:8080 \
-v ~/.headroom:/root/.headroom \
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
ghcr.io/chopratejas/headroom:latest proxy
```
### 构建自定义镜像
```dockerfile
FROM ghcr.io/chopratejas/headroom:latest
# 添加自定义配置
COPY ./headroom.yaml /root/.headroom/config.yaml
# 启动命令
CMD ["proxy", "--port", "8080"]
```
资料来源：[Dockerfile:1-30](https://github.com/chopratejas/headroom/blob/main/Dockerfile)
## CLI 工具配置
### 验证安装
安装完成后，`headroom` CLI 命令应可用：
```bash
headroom --version
```
### 代理服务器启动
启动 Headroom 代理作为本地 API 代理：
```bash
# 启动默认代理（端口 8080）
headroom proxy
# 指定端口
headroom proxy --port 8080
# 启用记忆系统
headroom proxy --memory
# 启用流量学习
headroom proxy --learn
# 组合多个选项
headroom proxy --memory --learn --port 8080
```
### 代理配置参数
| 参数 | 环境变量 | 默认值 | 说明 |
|------|----------|--------|------|
| `--port` | `HEADROOM_PORT` | 8080 | 代理监听端口 |
| `--memory` | `HEADROOM_MEMORY_ENABLED` | false | 启用记忆系统 |
| `--learn` | `HEADROOM_LEARN_ENABLED` | false | 启用流量学习 |
| `--backend` | `HEADROOM_BACKEND` | anthropic | 后端提供商 |
| `--budget` | `HEADROOM_BUDGET` | 无 | 每日预算限制（美元） |
| `--exclude-tools` | `HEADROOM_EXCLUDE_TOOLS` | 无 | 排除的工具列表 |
| `--memory-storage` | `HEADROOM_MEMORY_STORAGE` | user | 记忆存储模式 |
资料来源：[headroom/cli/proxy.py:1-100](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
### CLI 包装器命令
Headroom 提供 `wrap` 子命令，为各种 AI 编码代理自动配置压缩功能：
| 代理 | 命令 | 附加选项 |
|------|------|----------|
| Claude Code | `headroom wrap claude` | `--memory`, `--code-graph` |
| Codex | `headroom wrap codex` | `--memory`, `--code-graph` |
| Cursor | `headroom wrap cursor` | 无（打印配置） |
| Aider | `headroom wrap aider` | `--memory`, `--code-graph` |
| Copilot CLI | `headroom wrap copilot` | `--memory`, `--code-graph` |
| Goose | `headroom wrap goose` | `--memory`, `--code-graph` |
| OpenCode | `headroom wrap opencode` | `--memory`, `--code-graph` |
```bash
# Claude Code 包装
headroom wrap claude
# Codex 包装
headroom wrap codex
# 带记忆系统的包装
headroom wrap claude --memory
# 跳过 MCP 工具
headroom wrap codex --no-mcp
# 跳过 CLI 上下文工具
headroom wrap codex --no-context-tool
```
资料来源：[headroom/cli/wrap.py:1-80](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
## MCP 服务器安装
### MCP 服务器安装命令
```bash
# 安装 Claude Code MCP 服务器
headroom mcp install
# 指定代理端口
headroom mcp install --port 8080
```
### MCP 工具列表
| 工具名称 | 功能 | 说明 |
|----------|------|------|
| `memory_search` | 搜索记忆 | 跨会话检索知识 |
| `memory_save` | 保存记忆 | 持久化重要信息 |
| `memory_list` | 列出记忆 | 查看已存储条目 |
| `headroom_retrieve` | CCR 检索 | 恢复压缩内容 |
| `headroom_stats` | 统计信息 | 查看压缩统计 |
### MCP 配置注意事项
> **已知问题**：部分用户报告 `headroom proxy` 的 `/mcp` HTTP 端点返回 404 错误。如遇此问题，请使用 stdio 模式连接 MCP 服务器，而非 HTTP 模式。
>
> 详见：[Issue #460](https://github.com/chopratejas/headroom/issues/460)
```json
{
"mcpServers": {
"headroom": {
"command": "headroom",
"args": ["mcp", "run"],
"env": {
"HEADROOM_PORT": "8080"
}
}
}
}
```
## 开发环境安装
### 从源码克隆
```bash
git clone https://github.com/chopratejas/headroom.git
cd headroom
```
### 使用虚拟环境
```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/macOS
# 或
.\venv\Scripts\activate # Windows
# 安装开发依赖
pip install -e ".[dev]"
```
### 安装 Rust 扩展（开发）
```bash
# 确保已安装 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 编译 Rust 扩展
cd crates/headroom-py
maturin develop
```
### 运行测试
```bash
# 运行所有测试
pytest
# 运行特定模块测试
pytest tests/test_compress.py
# 带覆盖率
pytest --cov=headroom
```
### Devcontainer 支持
Headroom 提供预配置的 Devcontainer，包含两种配置：
- **默认配置**：基础开发环境
- **memory-stack 配置**：包含 Qdrant 和 Neo4j 的记忆系统开发环境
```bash
# 在 VS Code 中打开
code --remote container .
# 或使用命令
devcontainer open --workspace-folder .
```
资料来源：[CONTRIBUTING.md:1-50](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md)
## 环境变量配置
### API 密钥配置
```bash
# Anthropic（Claude）
export ANTHROPIC_API_KEY="sk-ant-..."
# OpenAI
export OPENAI_API_KEY="sk-..."
# Google Gemini
export GOOGLE_API_KEY="..."
```
### 代理配置
| 环境变量 | 说明 | 默认值 |
|----------|------|--------|
| `HEADROOM_PORT` | 代理监听端口 | 8080 |
| `HEADROOM_BACKEND` | 默认后端提供商 | anthropic |
| `HEADROOM_PROXY_URL` | 上游代理 URL | 无 |
| `HEADROOM_MEMORY_ENABLED` | 启用记忆系统 | false |
| `HEADROOM_LEARN_ENABLED` | 启用流量学习 | false |
| `HEADROOM_EXCLUDE_TOOLS` | 排除的工具列表 | 无 |
| `HEADROOM_BUDGET` | 每日预算（美元） | 无 |
| `HEADROOM_CODE_AWARE_ENABLED` | 启用代码感知压缩 | false |
| `HEADROOM_AGENT_TYPE` | 代理类型标识 | unknown |
### CLI 上下文工具选择
```bash
# 使用 RTK（默认）
export HEADROOM_CONTEXT_TOOL=rtk
# 使用 lean-ctx
export HEADROOM_CONTEXT_TOOL=lean-ctx
```
## 安装验证
### 验证 Python 安装
```python
from headroom import compress
messages = [
{"role": "user", "content": "Hello"}
]
result = compress(messages, model="claude-sonnet-4-20250514")
print(result)
```
### 验证 CLI
```bash
headroom --version
headroom proxy --help
headroom wrap --help
```
### 验证 TypeScript SDK
```typescript
import { compress } from "headroom-ai";
const result = await compress([
{ role: "user", content: "Hello" }
], { model: "gpt-4o" });
console.log(result);
```
## 常见安装问题
### Rust 扩展编译失败
如果 `maturin` 编译失败，检查 Rust 工具链版本：
```bash
rustup update
rustc --version # 需要 1.70+
```
### MCP 服务器连接问题
如遇 MCP 连接问题（参见 [Issue #460](https://github.com/chopratejas/headroom/issues/460)）：
1. 确认使用正确的连接方式（stdio 优先）
2. 检查端口配置一致性
3. 查看日志输出排查问题
### LiteLLM 安全警告
> **安全注意**：2025 年期间，PyPI 上的 `litellm` 包曾遭遇供应链攻击（v1.82.8 版本）。Headroom 默认不依赖 `litellm`，如需使用请确保从可信来源安装并锁定版本。
>
> 详见：[Issue #56](https://github.com/chopratejas/headroom/issues/56)
### 权限问题
```bash
# macOS/Linux：解决 pip 安装权限
pip install --user headroom-ai
# 或使用虚拟环境
python -m venv headroom-env
source headroom-env/bin/activate
pip install headroom-ai
```
## 卸载
### pip 卸载
```bash
pip uninstall headroom-ai
```
### 清理配置
```bash
# 删除配置目录
rm -rf ~/.headroom
# 删除代理日志
rm -rf ~/.headroom/logs
# 清理 MCP 配置（手动编辑相关配置文件）
```
## 另请参阅
- [快速开始指南](./Getting-Started) — 使用 Headroom 的基础教程
- [代理集成](./Agent-Integrations) — 各 AI 编码代理的配置详情
- [记忆系统](./Memory-System) — 跨会话记忆功能说明
- [API 参考](./API-Reference) — Python/TypeScript SDK 完整 API
- [配置参考](./Configuration) — 高级配置选项
---
## 快速开始
### 相关页面
相关主题：[Headroom 概述](#overview), [CLI 代理包装器](#cli-wrappers), [代理服务器](#proxy-server)
相关源码文件
以下源码文件用于生成本页说明：
- [headroom/cli/main.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/main.py)
- [headroom/cli/wrap.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
- [headroom/cli/proxy.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
- [headroom/cli/learn.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/learn.py)
- [headroom/cli/init.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/init.py)
- [sdk/typescript/README.md](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/README.md)
- [README.md](https://github.com/chopratejas/headroom/blob/main/README.md)
# 快速开始
Headroom 是一个 AI 上下文压缩平台，旨在减少向大型语言模型发送的 token 数量，从而节省成本并提高响应速度。通过智能压缩技术，Headroom 能够在保持语义完整性的前提下，将上下文体积缩减高达 90%。
## 安装
### 基础安装
```bash
pip install headroom-ai
```
### 完整安装（含代码感知压缩）
```bash
pip install "headroom-ai[code]"
```
代码感知压缩依赖 `tree-sitter`，需要额外的系统依赖。启用方式：
```bash
export HEADROOM_CODE_AWARE_ENABLED=1
```
或者使用命令行标志：
```bash
headroom proxy --code-aware
```
资料来源：[headroom/cli/proxy.py:1-50]()
### 验证安装
```bash
headroom --version
```
## 核心使用模式
Headroom 提供三种主要使用模式，适用于不同的使用场景：
| 模式 | 命令 | 适用场景 | 特点 |
|------|------|----------|------|
| **Proxy 模式** | `headroom proxy` | 任何 OpenAI/Anthropic 兼容客户端 | 透明代理，自动压缩 |
| **CLI Wrap 模式** | `headroom wrap ` | 支持的 AI 编码助手 | 自动配置，一键启动 |
| **SDK 模式** | `compress()` 函数 | Python/TypeScript 应用 | 程序化集成 |
资料来源：[headroom/cli/main.py:1-100]()
## Proxy 模式
Proxy 模式将 Headroom 作为本地 HTTP 代理服务器运行，拦截并压缩所有发往 AI 提供商的请求。
### 启动代理
```bash
headroom proxy
```
默认情况下，代理在 `http://127.0.0.1:8080` 监听。
### 配置代理端口
```bash
headroom proxy --port 9999
```
### 关键配置选项
| 选项 | 环境变量 | 说明 | 默认值 |
|------|----------|------|--------|
| `--port` | `HEADROOM_PROXY_PORT` | 代理监听端口 | `8080` |
| `--budget` | `HEADROOM_BUDGET` | 每日预算限制（USD） | 无限制 |
| `--code-aware` | `HEADROOM_CODE_AWARE_ENABLED` | 启用 AST 代码压缩 | 禁用 |
| `--exclude-tools` | `HEADROOM_EXCLUDE_TOOLS` | 排除压缩的工具列表 | 无 |
| `--log-file` | - | JSONL 日志文件路径 | 无 |
| `--log-messages` | - | 启用完整消息日志 | 禁用 |
资料来源：[headroom/cli/proxy.py:50-150]()
### 代理工作流程
```mermaid
graph TD
A[AI 客户端] --> B[Headroom Proxy]
B --> C{缓存命中?}
C -->|是| D[返回缓存结果]
C -->|否| E[压缩请求]
E --> F[转发至上游 API]
F --> G[压缩响应]
G --> H[存储缓存]
H --> I[返回压缩结果]
D --> A
I --> A
```
### 配置客户端使用代理
配置环境变量：
```bash
export OPENAI_API_BASE=http://127.0.0.1:8080/v1
export ANTHROPIC_API_BASE=http://127.0.0.1:8080
```
## CLI Wrap 模式
CLI Wrap 模式是 Headroom 最便捷的使用方式，专为支持的 AI 编码助手设计。
### 支持的助手
| 助手 | 支持状态 | 集成方式 |
|------|----------|----------|
| Goose | 完整支持 | 自动启动代理 + 上下文工具 |
| Claude Code | 完整支持 | 共享内存，自动配置 |
| Codex | 完整支持 | MCP 检索工具配置 |
| Cursor | 基础支持 | 输出配置信息 |
| Aider | 完整支持 | 启动代理并启动 |
| Cline | 完整支持 | `.clinerules` 文件注入 |
| Copilot CLI | 完整支持 | 启动代理并启动 |
| OpenClaw | 完整支持 | ContextEngine 插件 |
资料来源：[headroom/cli/wrap.py:1-100]()
### 基本用法
以 Claude Code 为例：
```bash
headroom wrap claude -- session
```
这会自动：
1. 启动 Headroom 代理
2. 设置 CLI 上下文工具（RTK 或 lean-ctx）
3. 启动 Claude Code 会话
### 跳过特定组件
```bash
# 仅启动代理，不设置上下文工具
headroom wrap claude --no-context-tool
# 仅设置，不启动代理
headroom wrap claude --prepare-only
# 跳过 MCP 工具
headroom wrap claude --no-mcp
```
### Wrap 流程详解
```mermaid
graph TD
A[headroom wrap <agent>] --> B[检测代理状态]
B --> C{代理运行中?}
C -->|否| D[启动 Headroom 代理]
C -->|是| E[复用现有代理]
D --> F[设置 CLI 上下文工具]
E --> F
F --> G{RTK 或 lean-ctx?}
G -->|RTK| H[下载并安装 RTK 二进制]
G -->|lean-ctx| I[设置 lean-ctx 路径]
H --> J[注入指令到标记文件]
I --> J
J --> K[配置 MCP 服务器]
K --> L[启动目标 AI 助手]
J --> L
```
## SDK 集成模式
对于程序化使用场景，Headroom 提供 Python 和 TypeScript SDK。
### Python SDK
#### 安装
```bash
pip install headroom-ai
```
#### 基本压缩示例
```python
from headroom import compress
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Analyze this data..."},
]
result = compress(messages, model="gpt-4o")
print(f"压缩前: {result.tokens_before} tokens")
print(f"压缩后: {result.tokens_after} tokens")
print(f"节省: {result.tokens_saved} tokens ({result.savings_percent:.1f}%)")
```
#### 集成 OpenAI SDK
```python
from headroom import with_headroom
from openai import OpenAI
client = with_headroom(OpenAI())
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}]
)
```
资料来源：[sdk/typescript/README.md:1-100]()
### TypeScript SDK
#### 安装
```bash
npm install headroom-ai
```
#### 基本压缩示例
```typescript
import { compress } from "headroom-ai";
const messages = [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Analyze this data..." },
];
const result = await compress(messages, { model: "gpt-4o" });
console.log(`压缩前: ${result.tokensBefore} tokens`);
console.log(`节省: ${result.tokensSaved} tokens`);
```
#### 集成 Vercel AI SDK
```typescript
import { withHeadroom } from "headroom-ai/vercel-ai";
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";
const model = withHeadroom(openai("gpt-4o"));
const result = await generateText({ model, prompt: "Hello!" });
```
资料来源：[sdk/typescript/examples/basic-compress.ts:1-50]()
## 内存功能
Headroom 提供跨会话持久化内存功能，支持代理在多个会话间共享上下文。
### 启用内存
```bash
headroom proxy --memory
```
或使用 wrap 命令：
```bash
headroom wrap claude --memory
```
### MCP 服务器
内存功能通过 MCP（Model Context Protocol）暴露工具：
| 工具 | 功能 |
|------|------|
| `memory_search` | 搜索相关记忆 |
| `memory_save` | 保存新的记忆 |
| `memory_list` | 列出所有记忆 |
| `memory_delete` | 删除指定记忆 |
### MCP 安装
```bash
headroom mcp install
```
这会将 Headroom MCP 服务器注册为本地工具，供支持 MCP 的编辑器使用。
> **注意**：当前 `headroom proxy` 不提供 HTTP MCP 端点（如 `/mcp`），仅支持 stdio 模式的 MCP 服务器。如果需要通过 HTTP 访问 MCP，请使用独立的 MCP 服务器配置。 资料来源：[issues/460](https://github.com/chopratejas/headroom/issues/460)
## 学习功能
Headroom 可以从过去的会话中学习，分析工具调用失败模式并生成预防性上下文。
### 基本用法
```bash
headroom learn --apply
```
### 指定代理和模型
```bash
headroom learn --agent claude --model claude-sonnet-4o
```
### 分析所有项目
```bash
headroom learn --all --apply
```
学习功能支持多种代理：
- Claude Code
- Codex
- Gemini CLI
- 外部插件（可通过 pip 安装）
资料来源：[headroom/cli/learn.py:1-80]()
## 压缩钩子（Hooks）
通过钩子系统可以在压缩过程中注入自定义逻辑。
### Python 钩子示例
```python
from headroom import compress, CompressHook
class MyHook(CompressHook):
def pre_compress(self, messages, ctx):
# 在压缩前修改消息
return messages
def post_compress(self, event):
print(f"节省了 {event.tokens_saved} tokens")
result = compress(messages, model="gpt-4o", hooks=MyHook())
```
### TypeScript 钩子示例
```typescript
import { compress, CompressContext, CompressEvent } from "headroom-ai";
class MyHooks {
postCompress(event: CompressEvent) {
console.log(`节省了 ${event.tokensSaved} tokens`);
}
}
const result = await compress(messages, { model: "gpt-4o", hooks: new MyHooks() });
```
资料来源：[sdk/typescript/examples/hooks-custom-compression.ts:1-60]()
## 常见工作流
### 工作流一：独立代理开发
```mermaid
graph LR
A[启动代理] --> B[启动 Claude Code]
B --> C[编写代码]
C --> D[压缩上下文]
D --> E[节省 token]
E --> C
```
### 工作流二：团队共享上下文
```mermaid
graph TD
A[Agent A 完成任务] --> B[保存关键决策到内存]
B --> C[Agent B 开始工作]
C --> D[搜索相关记忆]
D --> E[恢复上下文]
E --> F[继续开发]
```
### 工作流三：多代理协作
```mermaid
graph TD
A[研究 Agent] -->|共享上下文| B[开发 Agent]
B -->|共享上下文| C[测试 Agent]
A -->|内存共享| C
B -->|内存共享| A
```
## 故障排除
### 代理无法启动
检查端口是否被占用：
```bash
lsof -i :8080
```
使用其他端口：
```bash
headroom proxy --port 9999
```
### 压缩未生效
1. 确认代理正在运行
2. 检查环境变量配置是否正确
3. 验证 API 密钥设置
### MCP 工具不可用
确认使用正确的 MCP 配置方式，stdio 模式需要通过 MCP 客户端配置，不支持 HTTP 端点直接访问。 资料来源：[issues/460](https://github.com/chopratejas/headroom/issues/460)
### Token 计数不准确
如果使用自定义 provider，确保模型名称与实际使用的一致：
```python
result = compress(messages, model="your-model-name")
```
## 环境变量参考
| 变量 | 说明 | 示例 |
|------|------|------|
| `HEADROOM_PROXY_PORT` | 代理端口 | `8080` |
| `HEADROOM_BUDGET` | 每日预算（USD） | `10.0` |
| `HEADROOM_CODE_AWARE_ENABLED` | 启用代码感知压缩 | `1` |
| `HEADROOM_EXCLUDE_TOOLS` | 排除的工具列表 | `["read_file","bash"]` |
| `HEADROOM_CONTEXT_TOOL` | 选择上下文工具 | `lean-ctx` 或 `rtk` |
| `OPENAI_API_BASE` | OpenAI API 地址 | `http://127.0.0.1:8080/v1` |
| `ANTHROPIC_API_BASE` | Anthropic API 地址 | `http://127.0.0.1:8080` |
资料来源：[headroom/cli/proxy.py:30-100]()
## 参见
- [代理参考](proxy.md) - Headroom 代理详细配置
- [Wrap 命令](wrap.md) - CLI Wrap 完整文档
- [内存系统](memory.md) - 跨会话记忆管理
- [SDK 文档](sdk.md) - Python/TypeScript SDK 详细指南
- [压缩策略](compression.md) - 压缩配置与调优
---
## 代理服务器
### 相关页面
相关主题：[快速开始](#quickstart), [CCR 可逆压缩](#ccr), [配置参考](#configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [headroom/cli/proxy.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
- [headroom/cli/wrap.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
- [headroom/cli/init.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/init.py)
- [headroom/mcp_registry/__init__.py](https://github.com/chopratejas/headroom/blob/main/headroom/mcp_registry/__init__.py)
- [README.md](https://github.com/chopratejas/headroom/blob/main/README.md)
- [plugins/openclaw/README.md](https://github.com/chopratejas/headroom/blob/main/plugins/openclaw/README.md)
# 代理服务器
Headroom 代理服务器（`headroom proxy`）是项目的核心组件之一，作为本地 HTTP 代理运行在 AI 提供商和编码代理之间。它拦截所有发往 AI 提供商的请求，应用上下文压缩策略，然后将压缩后的请求转发给上游提供商。
## 核心定位
代理服务器的主要职责包括：
- **请求拦截与转发**：捕获来自 Claude、Codex、Copilot 等编码代理的 API 请求
- **上下文压缩**：通过多级转换管道压缩对话历史，减少 token 消耗
- **记忆管理**：支持跨会话的持久化记忆存储与检索
- **CCR 缓存**：实现可逆压缩，LLM 可按需检索原始内容
- **流量统计**：记录压缩前后的 token 数量，计算节省比例
资料来源：[README.md:1-30](https://github.com/chopratejas/headroom/blob/main/README.md)
## 架构概览
```mermaid
graph TD
A[编码代理
Claude/Codex/Copilot] --> B[Headroom 代理服务器]
B --> C{请求类型判断}
C -->|聊天补全| D[OpenAI 处理器]
C -->|Anthropic API| E[Anthropic 处理器]
C -->|MCP 工具调用| F[MCP 路由器]
D --> G[压缩管道]
E --> G
G --> H[CacheAligner]
G --> I[ContentRouter]
G --> J[SmartCrusher]
G --> K[CodeCompressor]
G --> L[IntelligentContext]
H --> M[上游 API]
I --> M
J --> M
K --> M
L --> M
M --> N[响应处理]
N --> O[编码代理]
B --> P[(记忆存储
Qdrant/Neo4j)]
```
代理服务器采用模块化设计，核心压缩逻辑通过 `headroom.transforms` 模块提供，支持通过插件机制扩展。
## 启动方式
### 基本启动
```bash
# 启动默认配置
headroom proxy
# 指定端口
headroom proxy --port 8080
# 启用记忆功能
headroom proxy --memory
```
### 初始化后启动
使用 `headroom init` 命令安装持久化集成后，可直接启动：
```bash
# 为支持的代理安装集成并启动
headroom init
# 指定后端提供商
headroom init --backend anthropic --port 8080
```
资料来源：[headroom/cli/init.py:1-60](https://github.com/chopratejas/headroom/blob/main/headroom/cli/init.py)
## CLI 配置选项
### 基础选项
| 选项 | 默认值 | 说明 |
|------|--------|------|
| `--port` | `8787` | 代理监听端口 |
| `--backend` | `anthropic` | 后端提供商（anthropic/openai/any-llm） |
| `--anyllm-provider` | `None` | any-llm 后端的提供商类型 |
| `--region` | `None` | Bedrock/Vertex 风格云区域的区域标识 |
| `--memory` | `False` | 在代理运行时启用持久化记忆 |
| `--verbose` | `False` | 输出调试级别诊断信息 |
资料来源：[headroom/cli/proxy.py:1-50](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
### 预算与限流
| 选项 | 环境变量 | 说明 |
|------|----------|------|
| `--budget` | `HEADROOM_BUDGET` | 每日预算上限（美元），超限后返回 402 |
| `--rate-limit` | `HEADROOM_RATE_LIMIT` | 每分钟最大请求数 |
| `--max-concurrent` | `HEADROOM_MAX_CONCURRENT` | 最大并发请求数 |
```bash
# 设置每日 5 美元预算限制
headroom proxy --budget 5.0
# 或通过环境变量
export HEADROOM_BUDGET=5.0
headroom proxy
```
### Anthropic 专用选项
| 选项 | 环境变量 | 默认值 | 说明 |
|------|----------|--------|------|
| `--anthropic-pre-upstream-concurrency` | `HEADROOM_ANTHROPIC_PRE_UPSTREAM_CONCURRENCY` | `max(2, min(8, CPU数))` | 预上游信号量限制，防止请求风暴 |
| `--anthropic-pre-upstream-acquire-timeout-seconds` | `HEADROOM_ANTHROPIC_PRE_UPSTREAM_ACQUIRE_TIMEOUT_SECONDS` | `15.0` | 信号量等待超时，超时返回 503+Retry-After |
| `--anthropic-pre-upstream-memory-context-timeout-seconds` | `HEADROOM_ANTHROPIC_PRE_UPSTREAM_MEMORY_CONTEXT_TIMEOUT_SECONDS` | `2.0` | 记忆上下文查找超时（fail-open） |
```bash
# 调整 Anthropic 并发控制参数
headroom proxy \
--anthropic-pre-upstream-concurrency 4 \
--anthropic-pre-upstream-acquire-timeout-seconds 20
```
资料来源：[headroom/cli/proxy.py:100-180](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
### 代码感知压缩
| 选项 | 环境变量 | 说明 |
|------|----------|------|
| `--code-aware` / `--no-code-aware` | `HEADROOM_CODE_AWARE_ENABLED` | 启用/禁用基于 AST 的代码压缩（需要 `pip install headroom-ai[code]`） |
```bash
# 启用 AST 代码压缩
headroom proxy --code-aware
export HEADROOM_CODE_AWARE_ENABLED=1
```
### 日志与调试
| 选项 | 说明 |
|------|------|
| `--log-file` | JSONL 日志文件路径 |
| `--log-messages` | 启用完整消息日志（记录请求/响应内容） |
| `--codex-wire-debug` | 启用 Codex 流量快照和匹配的 proxy.log 帧追踪 |
| `--codex-wire-debug-dir` | Codex 流量快照目录（默认：`~/.headroom/logs/codex_wire`） |
### 工具排除
| 选项 | 环境变量 | 说明 |
|------|----------|------|
| `--exclude-tools` | `HEADROOM_EXCLUDE_TOOLS` | 排除指定工具不做压缩（逗号分隔） |
```bash
# 排除特定工具
headroom proxy --exclude-tools read_file,bash
export HEADROOM_EXCLUDE_TOOLS="read_file,bash,grep"
```
资料来源：[headroom/cli/proxy.py:200-280](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
## 请求生命周期
代理服务器暴露统一的请求生命周期，贯穿 `compress()`、SDK 和代理：
```mermaid
stateDiagram-v2
[*] --> Setup: 初始化
Setup --> PreStart: 配置加载
PreStart --> PostStart: 管道就绪
PostStart --> InputReceived: 收到请求
InputReceived --> InputCached: KV缓存对齐
InputCached --> InputRouted: 内容路由
InputRouted --> InputCompressed: 执行压缩
InputCompressed --> InputRemembered: 记忆检索
InputRemembered --> PreSend: 预发送检查
PreSend --> PostSend: 实际发送
PostSend --> ResponseReceived: 收到响应
ResponseReceived --> [*]: 流程结束
```
### 转换组件
转换组件负责实际压缩工作：
| 组件 | 功能 |
|------|------|
| `CacheAligner` | 稳定前缀，使 Anthropic/OpenAI KV 缓存真正命中 |
| `ContentRouter` | 基于内容的智能路由 |
| `SmartCrusher` | 重要性评分驱动的上下文削减 |
| `CodeCompressor` | 代码专用压缩 |
| `Kompress-base` | 基于 ML 模型的文本压缩 |
| `IntelligentContext` | 基于评分的重要性上下文适配 |
资料来源：[README.md:1-30](https://github.com/chopratejas/headroom/blob/main/README.md)
## MCP 集成
### MCP 服务器注册
代理服务器支持 MCP（Model Context Protocol）工具调用路由：
```mermaid
graph LR
A[代理服务器] --> B[/mcp 端点]
B --> C{请求类型}
C -->|retrieve| D[CCR 检索]
C -->|memory_search| E[记忆搜索]
C -->|memory_save| F[记忆存储]
```
### 已知限制
> **注意**：当前版本的 `headroom proxy` 在 `/mcp` 端点返回 404，与 stdio MCP 服务器行为不一致。详情参见 [issue #460](https://github.com/chopratejas/headroom/issues/460)。
对于需要 MCP 功能的场景，建议使用 stdio 模式：
```bash
# 通过 MCP stdio 模式使用
headroom mcp install
```
资料来源：[headroom/cli/wrap.py:100-150](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
## 与编码代理集成
### 支持的代理
| 代理 | CLI包装 | MCP支持 | 集成方式 |
|------|---------|---------|----------|
| Claude | `--wrap claude` | `--memory` | 直接包装 |
| Codex | `--wrap codex` | ✓ | 启动代理+代理 |
| Cursor | `--wrap cursor` | ✗ | 输出配置信息 |
| Aider | `--wrap aider` | ✗ | 启动代理+代理 |
| Copilot CLI | `--wrap copilot` | ✗ | 启动代理+代理 |
| OpenClaw | `--wrap openclaw` | ✓ | ContextEngine 插件 |
### Codex 包装示例
```bash
# 包装 Codex，所有流量经过代理
headroom wrap codex --port 8787
# 跳过 MCP 检索工具设置
headroom wrap codex --no-mcp
# 跳过 RTK 上下文工具
headroom wrap codex --no-rtk
```
资料来源：[headroom/cli/wrap.py:200-300](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
### OpenClaw 插件配置
```typescript
// plugins/openclaw/src/convert.ts
{
proxyUrl: "http://127.0.0.1:8787", // 自动检测本地代理
autoStart: true, // 自动启动本地代理
routeCodexViaProxy: true, // 重写 Codex 提供商使用代理
startupTimeoutMs: 20000 // 等待代理就绪的超时
}
```
资料来源：[plugins/openclaw/README.md:1-50](https://github.com/chopratejas/headroom/blob/main/plugins/openclaw/README.md)
## 多代理记忆共享
代理服务器支持跨代理的持久化记忆存储：
```mermaid
graph TD
A[Agent A] -->|memory_save| B[(记忆存储)]
B --> C[Agent B]
B --> D[Agent C]
C -->|memory_search| B
D -->|memory_search| B
```
### 记忆存储后端
- **Qdrant**：向量相似度搜索
- **Neo4j**：图关系存储
### 相关问题
> **已知问题**：在多代理设置中，CCR 主动扩展块会注入到最新的用户消息内容中。在多代理场景下，该消息可能包含结构化的 XML 属性标记（``），注入的块会导致消息归属损坏。详情参见 [issue #503](https://github.com/chopratejas/headroom/issues/503)。
资料来源：[headroom/cli/wrap.py:50-80](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
## 统计与监控
### 运行时统计
代理服务器提供实时统计数据：
```json
{
"requests_total": 1250,
"tokens_before": 456789,
"tokens_after": 124567,
"tokens_saved": 332222,
"savings_percent": 72.7,
"cache_hits": 89,
"memory_queries": 234
}
```
### 长期统计
当前版本的统计信息在会话结束或代理重启后会丢失。如需长期追踪，建议使用：
- **Live Leaderboard**：https://headroomlabs.ai/dashboard
- **Discord 社区**：https://discord.gg/yRmaUNpsPJ
资料来源：[README.md:1-30](https://github.com/chopratejas/headroom/blob/main/README.md)
## 常见问题与故障排除
### 代理启动失败
```bash
# 端口被占用
Error: [Errno 98] Address already in use
headroom proxy --port 8788 # 更换端口
# API 密钥未设置
headroom proxy --verbose # 查看详细错误
export ANTHROPIC_API_KEY=sk-ant-...
```
### CCR 检索失败
```bash
# 检查 CCR 缓存状态
headroom proxy --log-messages
# 确保 MCP 服务器正确注册
headroom mcp install
```
### 预算耗尽
```bash
# 查看当前预算使用
curl http://localhost:8787/stats
# 调整预算限制
headroom proxy --budget 10.0
```
### 代理未生效
1. 确认编码代理的 API 端点指向代理地址
2. 检查环境变量 `HTTP_PROXY` / `HTTPS_PROXY`
3. 使用 `--verbose` 检查日志输出
## 环境变量参考
| 变量名 | 说明 |
|--------|------|
| `HEADROOM_BUDGET` | 每日预算限制（美元） |
| `HEADROOM_CODE_AWARE_ENABLED` | 启用代码感知压缩 |
| `HEADROOM_EXCLUDE_TOOLS` | 排除的工具列表（逗号分隔） |
| `HEADROOM_ANTHROPIC_PRE_UPSTREAM_CONCURRENCY` | Anthropic 预上游并发数 |
| `HEADROOM_LOG_FILE` | 日志文件路径 |
| `HEADROOM_CONTEXT_TOOL` | CLI 上下文工具（rtk/lean-ctx） |
## 相关命令
| 命令 | 说明 |
|------|------|
| `headroom proxy` | 启动代理服务器 |
| `headroom wrap ` | 包装编码代理并启动代理 |
| `headroom init` | 安装持久化集成 |
| `headroom mcp` | MCP 相关操作 |
| `headroom learn` | 从失败中学习生成建议 |
| `headroom compress` | 直接压缩消息列表 |
## 参见
- [上下文压缩](../context-compression/README.md) — 压缩管道详细文档
- [CCR 机制](../ccr/README.md) — 可逆压缩与检索机制
- [记忆系统](../memory/README.md) — 跨会话持久化记忆
- [CLI 参考](../cli-reference/README.md) — 命令行工具完整参考
- [SDK 集成](../sdk/README.md) — Python/TypeScript SDK 使用指南
---
## CCR 可逆压缩
### 相关页面
相关主题：[压缩算法](#compression), [代理服务器](#proxy-server)
相关源码文件
以下源码文件用于生成本页说明：
- [headroom/ccr/context_tracker.py](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/context_tracker.py)
- [headroom/ccr/response_handler.py](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/response_handler.py)
- [headroom/ccr/tool_injection.py](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/tool_injection.py)
- [crates/headroom-core/src/ccr/mod.rs](https://github.com/chopratejas/headroom/blob/main/crates/headroom-core/src/ccr/mod.rs)
- [crates/headroom-core/src/ccr/backends/in_memory.rs](https://github.com/chopratejas/headroom/blob/main/crates/headroom-core/src/ccr/backends/in_memory.rs)
- [crates/headroom-core/src/ccr/backends/redis.rs](https://github.com/chopratejas/headroom/blob/main/crates/headroom-core/src/ccr/backends/redis.rs)
- [crates/headroom-core/src/ccr/backends/sqlite.rs](https://github.com/chopratejas/headroom/blob/main/crates/headroom-core/src/ccr/backends/sqlite.rs)
- [crates/headroom-py/src/lib.rs](https://github.com/chopratejas/headroom/blob/main/crates/headroom-py/src/lib.rs)
- [sdk/typescript/examples/hooks-custom-compression.ts](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/examples/hooks-custom-compression.ts)
# CCR 可逆压缩
## 概述
CCR（Compress-Cache-Retrieve，可逆压缩）是 Headroom 中的核心特性之一，它实现了**可逆的上下文压缩**机制。与传统的有损压缩不同，CCR 在压缩内容时保留原始数据，生成唯一的哈希标识符（CCR Hash），使得 LLM 在需要时能够通过工具调用检索完整的原始内容。
资料来源：[README.md:1-20]()
### 核心价值
- **无损压缩**：压缩后的内容可以完全还原，保证信息完整性
- **按需检索**：LLM 根据任务需求主动请求原始内容
- **高压缩率**：通常可实现 70-90% 的 token 节省，同时保留检索能力
- **跨会话持久化**：通过配置后端存储，CCR 缓存可跨会话保留
```mermaid
graph LR
A[原始消息] --> B[CCR 压缩]
B --> C[压缩内容 + Hash]
C --> D[发送给 LLM]
D --> E{LLM 需要原始内容?}
E -->|是| F[调用 retrieve 工具]
F --> G[通过 Hash 还原]
G --> H[返回原始内容]
E -->|否| I[继续处理]
```
## 架构设计
### 组件结构
CCR 系统由以下核心组件构成：
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| ContextTracker | `headroom/ccr/context_tracker.py` | 追踪压缩上下文和哈希映射 |
| ResponseHandler | `headroom/ccr/response_handler.py` | 处理 LLM 响应中的检索请求 |
| ToolInjection | `headroom/ccr/tool_injection.py` | 向 LLM 注入检索工具定义 |
| CCR Core (Rust) | `crates/headroom-core/src/ccr/mod.rs` | 核心压缩/还原逻辑 |
| 存储后端 | `crates/headroom-core/src/ccr/backends/*.rs` | 多种存储实现 |
资料来源：[crates/headroom-core/src/ccr/mod.rs:1-50]()
### 存储后端
CCR 支持多种存储后端实现，以适应不同的部署场景：
| 后端 | 文件 | 适用场景 | 持久化 |
|------|------|----------|--------|
| InMemory | `in_memory.rs` | 开发/测试 | 否 |
| Redis | `redis.rs` | 生产环境/分布式 | 是 |
| SQLite | `sqlite.rs` | 单机/轻量级部署 | 是 |
资料来源：[crates/headroom-core/src/ccr/backends/in_memory.rs:1-30]()
```mermaid
classDiagram
class CcrBackend {
<>
+store(hash, original, ttl) StoreResult
+retrieve(hash) Original
+delete(hash) bool
+stats() BackendStats
}
class InMemoryBackend {
-store: HashMap
+store() StoreResult
+retrieve() Original
}
class RedisBackend {
-client: Redis
+store() StoreResult
+retrieve() Original
}
class SqliteBackend {
-conn: Connection
+store() StoreResult
+retrieve() Original
}
CcrBackend <|-- InMemoryBackend
CcrBackend <|-- RedisBackend
CcrBackend <|-- SqliteBackend
```
## 工作原理
### 压缩阶段
1. **内容保护**：系统首先识别并保护特殊标签内容（如 HTML 标签、代码块标记等），避免在压缩过程中被修改
```rust
// 保护标签的核心逻辑
fn protect_tags(text: &str, compress_tagged_content: bool) -> (String, Vec<(String, String)>) {
// 返回: (清理后的文本, 受保护块的占位符列表)
}
```
资料来源：[crates/headroom-py/src/lib.rs:80-95]()
2. **生成哈希**：对原始内容生成唯一哈希标识符
3. **存储映射**：将 `哈希 → 原始内容` 的映射存入选定的后端
4. **替换内容**：将原始内容替换为压缩摘要和哈希标记
### 检索阶段
当 LLM 需要原始内容时：
1. LLM 调用 `headroom_retrieve` 工具，传入哈希值
2. 系统根据哈希从后端查询原始内容
3. 原始内容被注入到响应中供 LLM 使用
```mermaid
sequenceDiagram
participant LLM as LLM 模型
participant Proxy as Headroom Proxy
participant Store as CCR Store
participant App as 应用后端
LLM->>Proxy: 需要原始内容
调用 headroom_retrieve(hash)
Proxy->>Store: 根据 hash 查询
Store->>Store: 查找原始内容
alt 内容存在
Store-->>Proxy: 返回原始内容
Proxy-->>LLM: 注入原始内容
else 内容不存在
Store-->>Proxy: Hash not found
Proxy-->>LLM: 返回错误信息
end
```
## 配置与使用
### Python SDK
```python
from headroom import compress
result = compress(messages, model="claude-sonnet-4-20250514")
# 查看压缩结果中的 CCR 哈希
print(f"压缩前: {result.tokens_before} tokens")
print(f"压缩后: {result.tokens_after} tokens")
print(f"可检索的 CCR 哈希: {result.ccr_hashes}")
```
### TypeScript SDK
```typescript
import { compress } from "headroom-ai";
// 压缩消息
const result = await compress(messages, { model: 'gpt-4o' });
console.log(`压缩前: ${result.tokensBefore} tokens`);
console.log(`压缩后: ${result.tokensAfter} tokens`);
console.log(`可检索的 CCR 哈希: ${result.ccrHashes.join(', ')}`);
```
资料来源：[sdk/typescript/examples/hooks-custom-compression.ts:50-65]()
### 钩子回调
通过自定义钩子监听压缩结果：
```typescript
class CcrTrackingHooks implements CompressionHooks {
postCompress(event: CompressEvent) {
console.log(`[hook] Post-compress: ${event.tokensBefore} → ${event.tokensAfter}`);
console.log(`[hook] CCR hashes (retrievable): ${event.ccrHashes.join(', ')}`);
}
}
const result = await compress(messages, {
model: 'gpt-4o',
hooks: new CcrTrackingHooks()
});
```
资料来源：[sdk/typescript/examples/hooks-custom-compression.ts:1-80]()
## 工具注入
### MCP 服务器集成
Headroom 通过 MCP（Model Context Protocol）向 LLM 暴露检索工具：
```python
# headroom/ccr/tool_injection.py 负责工具定义注入
def inject_retrieve_tool_schema() -> dict:
"""生成 headroom_retrieve 工具的 schema 定义"""
```
资料来源：[headroom/ccr/tool_injection.py:1-40]()
### Codex 集成
Codex 通过 `~/.codex/config.toml` 注册 Headroom MCP 服务器，实现检索功能：
```python
# 在 wrap codex 命令中自动配置
if not no_mcp:
from headroom.mcp_registry import CodexRegistrar
_setup_headroom_mcp(CodexRegistrar(), port, verbose=verbose, force=True)
```
资料来源：[headroom/cli/wrap.py:150-180]()
### 响应处理器
```python
# headroom/ccr/response_handler.py
def handle_retrieve_request(request: dict) -> dict:
"""处理 LLM 的检索请求，返回原始内容"""
hash_value = request.get("hash")
original = context_tracker.retrieve(hash_value)
return {"original": original}
```
资料来源：[headroom/ccr/response_handler.py:1-50]()
## 多智能体场景
在多智能体协作场景中，CCR 面临特殊的挑战：
```mermaid
graph TD
A[Agent A 压缩消息] -->|包含 peer_turn 标记| B[生成 CCR 哈希]
B --> C[Agent B 接收压缩内容]
C -->|需要原始| D[调用 retrieve]
D -->|多智能体属性| E[CCR 存储]
E --> F[返回原始内容]
```
### 已知问题
**BUG #503**：CCR 主动展开块在多智能体线程中会破坏消息归属。
在多智能体设置中，`_append_context_to_latest_non_frozen_user_turn()` 函数将主动展开块注入到最新用户消息内容中。当该消息包含结构化的 XML 属性标记（如 ``）时，注入的展开块会导致归属信息被破坏。
**症状表现**：
- 多智能体场景下消息归属不正确
- Agent 身份信息丢失
- 协作上下文混淆
**影响版本**：当前活跃开发版本
资料来源：[BUG #503](https://github.com/chopratejas/headroom/issues/503)
### 缓解措施
1. 在多智能体场景中谨慎使用主动展开功能
2. 监控消息归属的正确性
3. 关注后续版本修复
## API 参考
### Python API
#### `headroom.ccr.ContextTracker`
```python
class ContextTracker:
def store(self, content: str, ttl: int | None = None) -> str:
"""存储内容并返回哈希值"""
def retrieve(self, hash: str) -> str | None:
"""根据哈希检索原始内容"""
def delete(self, hash: str) -> bool:
"""删除指定哈希的内容"""
```
资料来源：[headroom/ccr/context_tracker.py:1-60]()
### Rust API
#### `CcrStore` trait
```rust
pub trait CcrStore: Send + Sync {
fn store(&self, original: &str, ttl_seconds: Option) -> CcrResult;
fn retrieve(&self, hash: &str) -> Option;
fn delete(&self, hash: &str) -> bool;
fn stats(&self) -> StoreStats;
}
```
资料来源：[crates/headroom-core/src/ccr/mod.rs:60-100]()
### 配置选项
| 选项 | 环境变量 | 类型 | 默认值 | 说明 |
|------|----------|------|--------|------|
| 启用 CCR | `HEADROOM_CCR_ENABLED` | bool | true | 是否启用可逆压缩 |
| 存储后端 | `HEADROOM_CCR_BACKEND` | str | memory | 存储后端类型 |
| TTL | `HEADROOM_CCR_TTL` | int | 3600 | 默认过期时间（秒） |
| Redis URL | `HEADROOM_CCR_REDIS_URL` | str | - | Redis 连接地址 |
## 性能考量
### 存储后端选择
| 场景 | 推荐后端 | 理由 |
|------|----------|------|
| 开发/测试 | InMemory | 无需额外依赖，响应最快 |
| 单实例生产 | SQLite | 持久化，开销低 |
| 分布式/高可用 | Redis | 支持集群，高并发 |
### TTL 设置建议
- **短期任务**（< 1小时）：TTL 设置为任务预估时间的 2 倍
- **跨会话任务**：使用 Redis 后端，设置较长的 TTL（24-72 小时）
- **持久化需求**：禁用 TTL 或使用持久化后端
## 故障排查
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 检索返回 None | 哈希已过期或不存在 | 检查 TTL 设置 |
| 哈希不一致 | 多实例存储未同步 | 使用 Redis 后端 |
| 存储失败 | 后端连接错误 | 检查后端服务状态 |
### 日志检查
启用详细日志查看 CCR 操作：
```bash
headroom proxy --log-messages
```
## 参见
- [压缩管道](./compression-pipeline.md) - 了解 CCR 在整体压缩流程中的位置
- [SmartCrusher](./smart-crusher.md) - 智能内容分析组件
- [MCP 服务器](./mcp-server.md) - MCP 工具集成
- [多智能体内存](./multi-agent-memory.md) - 跨 Agent 共享上下文
---
## 压缩算法
### 相关页面
相关主题：[Headroom 概述](#overview), [CCR 可逆压缩](#ccr)
相关源码文件
以下源码文件用于生成本页说明：
- [headroom/transforms/smart_crusher.py](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/smart_crusher.py)
- [headroom/transforms/code_compressor.py](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/code_compressor.py)
- [headroom/transforms/content_router.py](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py)
- [crates/headroom-core/src/transforms/smart_crusher/mod.rs](https://github.com/chopratejas/headroom/blob/main/crates/headroom-core/src/transforms/smart_crusher/mod.rs)
- [crates/headroom-core/src/transforms/mod.rs](https://github.com/chopratejas/headroom/blob/main/crates/headroom-core/src/transforms/mod.rs)
- [crates/headroom-py/src/lib.rs](https://github.com/chopratejas/headroom/blob/main/crates/headroom-py/src/lib.rs)
- [headroom/cli/proxy.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
# 压缩算法
Headroom 的核心价值在于通过多层压缩算法减少发送给大语言模型的上下文 tokens 数量，从而显著降低 API 调用成本。Headroom 采用了多种互补的压缩策略，构成了一个灵活可配置的压缩管道。
## 压缩管道概述
Headroom 的压缩管道采用模块化设计，多个压缩转换器（Transforms）按顺序执行，每个转换器负责处理特定类型的内容。压缩管道遵循统一的请求生命周期：
```
Setup → Pre-Start → Post-Start → Input Received → Input Cached → Input Routed → Input Compressed → Input Remembered → Pre-Send → Post-Send → Response Received
```
资料来源：[README.md](https://github.com/chopratejas/headroom/blob/main/README.md)
### 核心压缩转换器
| 转换器名称 | 功能描述 | 适用场景 |
|-----------|---------|---------|
| SmartCrusher | 基于机器学习的智能内容压缩 | 通用文本、对话历史 |
| CodeCompressor | 针对代码内容的 AST 感知压缩 | 代码片段、diff、文件内容 |
| ContentRouter | 内容路由与压缩策略分发 | 决定内容走哪条压缩路径 |
| CacheAligner | 稳定前缀以优化 KV 缓存命中 | Anthropic/OpenAI 流式响应 |
| IntelligentContext | 基于重要性评分的上下文拟合 | 需要保留关键信息的场景 |
| RollingWindow | 滑动窗口上下文管理 | 对话历史修剪 |
资料来源：[headroom/transforms/content_router.py](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py)
```mermaid
graph TD
A[Input Messages] --> B[ContentRouter]
B --> C{内容类型判断}
C -->|代码内容| D[CodeCompressor]
C -->|对话内容| E[SmartCrusher]
C -->|混合内容| F[多策略并行]
D --> G[CacheAligner]
E --> G
F --> G
G --> H[IntelligentContext]
H --> I[Output Compressed]
style A fill:#e1f5fe
style I fill:#c8e6c9
```
## SmartCrusher 智能压缩
SmartCrusher 是 Headroom 的核心压缩组件，使用 ML 路由实现高达 90% 的压缩率。它通过分析内容的相关性和重要性来决定保留或丢弃哪些部分。
### 配置参数
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| enabled | bool | true | 是否启用智能压缩 |
| min_items_to_analyze | int | 3 | 最小分析项目数 |
| min_tokens_to_crush | int | 500 | 最小 tokens 阈值 |
| max_items_after_crush | int | 10 | 压缩后最大项目数 |
| relevance_threshold | float | 0.3 | 相关性阈值 |
资料来源：[crates/headroom-py/src/lib.rs:120-135](https://github.com/chopratejas/headroom/blob/main/crates/headroom-py/src/lib.rs)
### 压缩结果结构
```python
class CrushResult:
compressed: str # 压缩后的内容
original: str # 原始内容
was_modified: bool # 是否被修改
strategy: str # 使用的压缩策略
```
资料来源：[crates/headroom-py/src/lib.rs:155-170](https://github.com/chopratejas/headroom/blob/main/crates/headroom-py/src/lib.rs)
### 工作流程
```mermaid
sequenceDiagram
participant Input as 输入内容
participant Analyze as 相关性分析
participant Score as 重要性评分
participant Select as 策略选择
participant Output as 压缩输出
Input->>Analyze: 文本分块
Analyze->>Score: 计算相关性分数
Score->>Select: 根据阈值筛选
Select->>Output: 应用压缩策略
```
## CodeCompressor 代码压缩
CodeCompressor 是专门针对代码内容优化的压缩器，支持基于 AST（抽象语法树）的分析。它可以理解代码结构，对代码进行语义级别的压缩。
### 功能特性
- **AST 感知分析**：理解代码语法结构
- **智能注释处理**：区分重要注释与冗余注释
- **死代码识别**：识别并移除未使用的代码片段
- **依赖关系保留**：确保压缩后的代码依赖关系完整
资料来源：[headroom/transforms/code_compressor.py](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/code_compressor.py)
### 启用方式
代码感知压缩需要安装可选依赖：
```bash
pip install headroom-ai[code]
```
通过命令行启用：
```bash
headroom proxy --code-aware
# 或使用环境变量
HEADROOM_CODE_AWARE_ENABLED=1 headroom proxy
```
资料来源：[headroom/cli/proxy.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
## CCR 可逆压缩机制
CCR（Compress-Cache-Retrieve）是 Headroom 的一种可逆压缩机制。压缩后的内容保留原始内容的哈希值，LLM 可以在需要时检索完整原始内容。
### 工作原理
```mermaid
graph LR
A[原始内容] -->|压缩| B[压缩内容 + 哈希]
B -->|存储| C[CCR缓存]
B -->|发送| D[LLM上下文]
D -->|请求| E[检索原始内容]
E -->|命中| F[返回原始内容]
```
### CCR 标记保护
在压缩过程中，CCR 使用特殊的标记机制保护重要内容不被破坏：
```rust
#[pyfunction]
fn protect_tags(text: &str, compress_tagged_content: bool) -> (String, Vec<(String, String)>);
```
- `protect_tags`：保护特殊标签，将内容块替换为占位符
- `restore_tags`：将占位符还原为原始内容块
资料来源：[crates/headroom-py/src/lib.rs:180-195](https://github.com/chopratejas/headroom/blob/main/crates/headroom-py/src/lib.rs)
### 多代理线程中的 CCR 问题
> **注意**：在多代理场景中使用 CCR 时，存在已知问题。当 `_append_context_to_latest_non_frozen_user_turn()` 注入主动扩展块时，可能与消息中的 XML 属性标记（如 ``）产生冲突。
资料来源：[BUG #503](https://github.com/chopratejas/headroom/issues/503)
## ContentRouter 内容路由
ContentRouter 负责分析输入内容并将其路由到最合适的压缩策略。它是压缩管道的入口点，决定后续处理流程。
### 路由决策因素
| 因素 | 说明 |
|-----|------|
| 内容类型 | 纯文本、代码、JSON、结构化数据 |
| 内容长度 | 短内容 vs 长内容 |
| 上下文相关性 | 与当前任务的关联程度 |
| 历史模式 | 之前的压缩效果反馈 |
资料来源：[headroom/transforms/content_router.py](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py)
### 压缩策略配置
ContentRouter 支持按模式配置不同的压缩策略：
```python
class CompressionPolicy:
# 轻量模式 - 保留更多内容
light: CompressionTuning
# 平衡模式 - 平衡压缩率与信息保留
balanced: CompressionTuning
# 激进模式 - 最大压缩
aggressive: CompressionTuning
```
资料来源：[headroom/cli/proxy.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
## 管道扩展机制
Headroom 提供多种扩展点允许开发者自定义压缩行为：
### 管道事件钩子
```python
def on_pipeline_event(event: PipelineEvent):
"""观察或自定义管道生命周期阶段"""
pass
```
### 压缩钩子
压缩钩子位于管道生命周期旁边，提供额外的扩展接口：
```python
def on_compress(compression_event: CompressionEvent):
"""在压缩前后执行自定义逻辑"""
pass
```
资料来源：[README.md](https://github.com/chopratejas/headroom/blob/main/README.md)
### 代理扩展
代理扩展是服务器与应用集成的接口，用于 ASGI 中间件、路由和启动策略：
```python
# Proxy extensions for ASGI middleware
class ProxyExtension:
def on_startup(self):
"""代理启动时的初始化逻辑"""
pass
def on_shutdown(self):
"""代理关闭时的清理逻辑"""
pass
```
## Rust 核心实现
Headroom 的核心压缩逻辑使用 Rust 编写以保证性能。Rust 模块位于 `crates/headroom-core/src/transforms/` 目录下。
### Python FFI 接口
```rust
#[pymodule]
fn _core(py: Python<'_>, m: &PyModule) -> PyResult<()> {
m.add_function(wrap_pyfunction!(protect_tags, m)?, "protect_tags")?;
m.add_function(wrap_pyfunction!(restore_tags, m)?, "restore_tags")?;
m.add_function(wrap_pyfunction!(is_html_tag, m)?, "is_html_tag")?;
m.add_function(wrap_pyfunction!(known_html_tag_names, m)?, "known_html_tag_names")?;
Ok(())
}
```
资料来源：[crates/headroom-py/src/lib.rs:210-220](https://github.com/chopratejas/headroom/blob/main/crates/headroom-py/src/lib.rs)
### HTML 标签识别
Rust 核心提供高性能的 HTML5 标签识别功能：
```rust
fn is_html_tag(name: &str) -> bool {
rust_is_known_html_tag(name)
}
fn known_html_tag_names() -> Vec<&'static str> {
rust_known_html_tag_names().to_vec()
}
```
这些函数确保压缩过程保留有效的 HTML 标签结构。
## 配置与调优
### 命令行配置
```bash
# 启用代码感知压缩
headroom proxy --code-aware
# 设置每日预算限制
headroom proxy --budget 10.0
# 或使用环境变量
HEADROOM_BUDGET=10.0 headroom proxy
# 排除特定工具
headroom proxy --exclude-tools tool1,tool2
HEADROOM_EXCLUDE_TOOLS=tool1,tool2 headroom proxy
```
资料来源：[headroom/cli/proxy.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
### 压缩策略调优字段
| 字段 | 说明 | 示例值 |
|-----|------|-------|
| compression_ratio | 目标压缩比例 | 0.5 |
| preserve_importance | 重要性保留级别 | high/medium/low |
| cache_alignment | 是否启用缓存对齐 | true/false |
| ccr_enabled | 是否启用 CCR | true/false |
## 性能优化
### 缓存对齐（CacheAligner）
CacheAligner 通过稳定前缀使 Anthropic/OpenAI 的 KV 缓存能够有效命中，减少重复计算：
```mermaid
graph LR
A[请求1前缀] -->|首次| B[计算并缓存]
C[请求2前缀] -->|相同| D[缓存命中]
E[请求3前缀] -->|不同| F[部分缓存]
```
### Rust 扩展优化
Headroom 使用 Rust 编写核心压缩逻辑，wheel 构建时进行了以下优化：
- `strip`：移除调试符号
- `thin-LTO`：轻量链接时优化
- `single codegen unit`：单一代码生成单元
资料来源：[Release v0.21.37](https://github.com/chopratejas/headroom/releases/tag/v0.21.37)
## 常见问题
### 压缩后内容丢失
如果发现压缩后重要内容丢失：
1. 检查 `relevance_threshold` 设置是否过低
2. 使用 CCR 机制确保原始内容可检索
3. 通过压缩钩子观察压缩过程
### 多代理场景下的 CCR 问题
在多代理线程中使用 CCR 时，主动扩展块可能与 XML 属性标记冲突。已知问题 [#503](https://github.com/chopratejas/headroom/issues/503) 正在修复中。
### 代码压缩不生效
确保已安装 `[code]` 扩展：
```bash
pip install headroom-ai[code]
```
并确认 `HEADROOM_CODE_AWARE_ENABLED=1` 或使用 `--code-aware` 标志。
## 相关页面
- [管道架构](pipeline-architecture) - 完整的处理管道说明
- [CLI 使用指南](cli-usage) - 命令行工具详细用法
- [代理配置](proxy-configuration) - 代理服务器配置参考
- [SDK 集成](sdk-integration) - Python/TypeScript SDK 使用
## 参见
- [GitHub 仓库](https://github.com/chopratejas/headroom)
- [Kompress-base 模型](https://huggingface.co/chopratejas/kompress-base) - 文本压缩背后的 ML 模型
- [RTK 工具](https://github.com/rtk-ai/rtk) - Shell 输出重写工具
---
## MCP 服务器集成
### 相关页面
相关主题：[代理服务器](#proxy-server), [CLI 代理包装器](#cli-wrappers)
相关源码文件
以下源码文件用于生成本页说明：
- [headroom/mcp_registry/__init__.py](https://github.com/chopratejas/headroom/blob/main/headroom/mcp_registry/__init__.py)
- [headroom/mcp_registry/claude.py](https://github.com/chopratejas/headroom/blob/main/headroom/mcp_registry/claude.py)
- [headroom/mcp_registry/install.py](https://github.com/chopratejas/headroom/blob/main/headroom/mcp_registry/install.py)
- [headroom/integrations/mcp/server.py](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/mcp/server.py)
- [headroom/ccr/mcp_server.py](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/mcp_server.py)
- [headroom/cli/wrap.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
# MCP 服务器集成
## 概述
Headroom 通过 Model Context Protocol (MCP) 实现与多种 AI 编码代理的深度集成。MCP 服务器集成允许 Headroom 在代理运行时提供上下文压缩、内存管理和 CCR（压缩-缓存-检索）功能。集成采用 stdio 传输协议，代理通过本地子进程启动 Headroom MCP 服务器进行通信。
资料来源：[headroom/integrations/mcp/server.py:1-50]()
## 架构设计
### MCP 组件架构
```mermaid
graph TD
subgraph "AI Agent"
A[Claude Code / Codex / OpenCode]
end
subgraph "Headroom MCP Client"
B[MCP SDK Client]
end
subgraph "Headroom MCP Server"
C[Memory Tools]
D[CCR Retrieve Tool]
E[Stats Tool]
end
subgraph "Headroom Core"
F[Memory Store]
G[CCR Hash Store]
H[Compression Engine]
end
B -->|stdio| C
B -->|stdio| D
B -->|stdio| E
C --> F
D --> G
G --> H
```
### MCP 注册器体系
Headroom 为不同的代理提供专门的 MCP 注册器实现：
| 注册器 | 文件路径 | 支持的代理 |
|--------|----------|------------|
| `ClaudeRegistrar` | `headroom/mcp_registry/claude.py` | Claude Code |
| `CodexRegistrar` | `headroom/mcp_registry/__init__.py` | Codex |
| `OpenCodeRegistrar` | `headroom/mcp_registry/__init__.py` | OpenCode |
资料来源：[headroom/mcp_registry/__init__.py:1-30]()
## MCP 工具集
### 内存工具 (Memory Tools)
Headroom MCP 服务器提供跨会话持久化知识管理工具：
| 工具名称 | 功能描述 | 参数 |
|----------|----------|------|
| `memory_search` | 搜索记忆存储 | `query`: 搜索关键词 |
| `memory_save` | 保存新记忆 | `content`: 记忆内容, `tags`: 标签列表 |
| `memory_list` | 列出记忆条目 | 无 |
| `memory_delete` | 删除记忆 | `memory_id`: 记忆标识符 |
```python
# MCP 工具调用示例
{
"tool": "memory_search",
"parameters": {
"query": "项目架构决策"
}
}
```
资料来源：[headroom/cli/wrap.py:180-210]()
### CCR 检索工具
CCR（压缩-缓存-检索）功能允许 LLM 在需要时恢复原始压缩内容：
| 工具名称 | 功能描述 | 参数 |
|----------|----------|------|
| `headroom_retrieve` | 根据哈希恢复原始内容 | `hash`: CCR 哈希标识符 |
```python
# CCR 检索示例
{
"tool": "headroom_retrieve",
"parameters": {
"hash": "sha256_abc123..."
}
}
```
资料来源：[headroom/ccr/mcp_server.py:1-60]()
## 安装与配置
### 标准安装流程
使用 `headroom mcp install` 命令将 Headroom MCP 服务器注册到本地 MCP 配置：
```bash
# 安装 Headroom MCP 服务器
headroom mcp install
# 验证安装
headroom mcp list
```
### Claude Code 集成
Claude Code 通过 `ClaudeRegistrar` 自动配置 MCP 服务器。`wrap` 命令会：
1. 在 `~/.claude/settings.json` 中注册 MCP 服务器
2. 配置 `headroom_memory` 服务器端点
3. 注入内存使用指南到项目 `AGENTS.md`
```bash
# Claude Code 自动启动时已包含 MCP 配置
headroom wrap claude --project /path/to/project
```
资料来源：[headroom/mcp_registry/claude.py:1-50]()
### Codex 集成
Codex 通过配置文件 `~/.codex/config.toml` 管理 MCP 服务器：
```toml
# Codex MCP 配置示例
[mcp_servers.headroom]
command = "headroom"
args = ["mcp", "run", "--port", "8765"]
```
Codex 启动时会从配置读取 MCP 服务器定义，启动长期运行的本地子进程。
```python
# Codex 注册器实现
def _setup_headroom_mcp(
registrar: "CodexRegistrar",
port: int,
verbose: bool = False,
force: bool = False,
) -> None:
"""配置 Headroom MCP 服务器到 Codex 配置"""
# 注入 MCP 配置到 ~/.codex/config.toml
```
资料来源：[headroom/mcp_registry/install.py:1-80]()
## 代理包装流程
### `headroom wrap` 命令
`headroom wrap` 命令是配置 MCP 集成的核心入口：
```bash
headroom wrap [options]
```
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `agent` | 目标代理名称 | 必需 |
| `--port` | MCP 服务器端口 | `8765` |
| `--memory` | 启用内存功能 | `False` |
| `--code-graph` | 启用代码图谱 | `False` |
| `--no-mcp` | 跳过 MCP 配置 | `False` |
```bash
# 完整示例：启动 Claude Code 并启用内存
headroom wrap claude --port 8765 --memory --code-graph
# 启动 Codex 并启用 MCP
headroom wrap codex --port 8765
```
资料来源：[headroom/cli/wrap.py:50-150]()
### MCP 服务器注册流程
```mermaid
sequenceDiagram
participant User
participant CLI as headroom wrap
participant Registrar as MCP Registrar
participant Config as Agent Config
participant MCP as Headroom MCP Server
User->>CLI: headroom wrap
CLI->>Registrar: create_registrar(agent)
Registrar->>Config: read_config()
Config-->>Registrar: existing_config
Registrar->>Registrar: merge_headroom_config()
Registrar->>Config: write_config()
User->>MCP: start_agent
MCP->>Registrar: connect()
Registrar-->>MCP: registered_tools
```
## 已知限制与故障排除
### 常见问题
#### 问题 1：代理 MCP 端点不可用
**症状**：代理报告 MCP 服务器连接失败，`/mcp` 端点返回 404。
**原因**：Headroom 代理使用 stdio 协议而非 HTTP 协议，无法通过 HTTP 端点访问。
**解决方案**：
```bash
# 使用 stdio 模式（默认）
headroom mcp install
# 验证 MCP 服务器可用
headroom mcp list
```
> ⚠️ **注意**：不要尝试通过 `curl http://localhost:8765/mcp` 访问 MCP 服务器，该协议基于 stdio 而非 HTTP。
资料来源：[Issue #460](https://github.com/chopratejas/headroom/issues/460)
#### 问题 2：Codex 端口冲突
**症状**：Codex 无法检索压缩内容，检索指向错误的代理实例。
**原因**：多个 `headroom wrap` 会话使用不同端口，Codex 从配置文件读取的端口可能指向旧实例。
**解决方案**：
```bash
# 强制重新注册到统一端口
headroom wrap codex --port 8765 --force
```
```python
# 注册器强制覆盖实现
def _setup_headroom_mcp(
registrar: "CodexRegistrar",
port: int,
verbose: bool = False,
force: bool = True, # 强制覆盖
) -> None:
```
资料来源：[headroom/cli/wrap.py:220-250]()
#### 问题 3：多代理场景下消息归属损坏
**症状**：CCR 主动扩展块注入到错误的消息中，导致多代理线程中消息归属混乱。
**原因**：`_append_context_to_latest_non_frozen_user_turn()` 将扩展块注入最新用户消息，但在多代理设置中该消息可能包含结构化 XML 归属标记（``）。
**影响**：注入的块会破坏 XML 结构，导致消息解析错误。
> 此问题已在 [Issue #503](https://github.com/chopratejas/headroom/issues/503) 中报告。
## MCP 服务器实现
### 服务端架构
```mermaid
graph LR
subgraph "Server Entry"
E[MCP Server Entry]
end
subgraph "Tool Handlers"
TH1[memory_search handler]
TH2[memory_save handler]
TH3[memory_list handler]
TH4[headroom_retrieve handler]
end
subgraph "Storage Layer"
S1[Memory Store]
S2[CCR Hash Store]
end
E --> TH1
E --> TH2
E --> TH3
E --> TH4
TH1 --> S1
TH2 --> S1
TH3 --> S1
TH4 --> S2
```
### MCP 服务器启动
```python
# headroom/integrations/mcp/server.py
def run_mcp_server(
port: int = 8765,
memory_enabled: bool = True,
ccr_enabled: bool = True,
) -> None:
"""启动 Headroom MCP 服务器
Args:
port: 服务端口（stdio 模式下未使用）
memory_enabled: 启用内存工具
ccr_enabled: 启用 CCR 检索工具
"""
# 初始化 MCP 服务器
# 注册工具处理器
# 进入事件循环
```
### 工具注册表
```python
# 工具定义结构
TOOL_DEFINITIONS = [
{
"name": "memory_search",
"description": "Search memory store for relevant entries",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"}
},
"required": ["query"]
}
},
{
"name": "memory_save",
"description": "Save a new memory entry",
"input_schema": {
"type": "object",
"properties": {
"content": {"type": "string"},
"tags": {"type": "array", "items": {"type": "string"}}
},
"required": ["content"]
}
}
]
```
资料来源：[headroom/integrations/mcp/server.py:100-180]()
## 内存功能详解
### 内存存储策略
Headroom 内存采用按项目隔离的存储策略，确保项目间记忆不会交叉污染：
```python
# 内存存储路径结构
~/.headroom/
└── memory/
└── {project_id}/
├── memories.jsonl
└── embeddings/
```
### 自动记忆摘要
内存工具支持自动摘要功能，当记忆超过阈值时触发摘要处理：
```python
# 摘要触发条件
SUMMARY_THRESHOLD_TOKENS = 2000
SUMMARY_AGENT_MODEL = "claude-sonnet-4-20250514"
```
### 记忆搜索与排序
记忆搜索使用相关性排序，返回最相关的条目：
| 排序字段 | 说明 |
|----------|------|
| `relevance_score` | 与查询的相关性得分 |
| `last_accessed` | 最后访问时间 |
| `created_at` | 创建时间 |
| `access_count` | 访问次数 |
资料来源：[headroom/mcp_registry/__init__.py:50-120]()
## 最佳实践
### MCP 配置检查清单
- [ ] 确认目标代理支持 MCP 协议
- [ ] 使用 `headroom mcp install` 正确安装
- [ ] 验证 `headroom mcp list` 显示所有工具
- [ ] 检查代理配置文件中的端口设置
- [ ] 多代理场景下使用统一端口避免冲突
### 内存使用指南
**查询前搜索**：在询问关于历史决策、约定、项目上下文等问题前，先调用 `memory_search`。
**保存决策后**：在做出持久决策、发现约定或学习重要事实后，调用 `memory_save` 以便后续会话使用。
```python
# 推荐的工作流
1. memory_search({"query": "项目的认证方案"})
2. # 基于搜索结果回答问题
3. memory_save({
"content": "项目使用 OAuth 2.0 + JWT",
"tags": ["认证", "安全", "架构"]
})
```
资料来源：[headroom/cli/wrap.py:185-210]()
## 相关页面
- [代理包装指南](wrap-guide) - 了解如何使用 `headroom wrap` 集成各代理
- [内存系统](memory-system) - 深入了解跨会话记忆管理
- [CCR 压缩缓存检索](ccr-compression) - CCR 机制的工作原理
- [代理集成概览](agent-integrations) - 所有支持的代理及配置方法
## 外部资源
- [Model Context Protocol 官方文档](https://modelcontextprotocol.io/)
- [Headroom 官网](https://headroomlabs.ai)
- [Discord 社区](https://discord.gg/yRmaUNpsPJ)
---
## CLI 代理包装器
### 相关页面
相关主题：[快速开始](#quickstart), [MCP 服务器集成](#mcp-integration), [代理间内存系统](#memory-system)
相关源码文件
以下源码文件用于生成本页说明：
- [headroom/cli/wrap.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
- [headroom/cli/init.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/init.py)
- [headroom/providers/claude/__init__.py](https://github.com/chopratejas/headroom/blob/main/headroom/providers/claude/__init__.py)
- [headroom/providers/codex/__init__.py](https://github.com/chopratejas/headroom/blob/main/headroom/providers/codex/__init__.py)
- [headroom/providers/cursor/__init__.py](https://github.com/chopratejas/headroom/blob/main/headroom/providers/cursor/__init__.py)
- [headroom/providers/aider/__init__.py](https://github.com/chopratejas/headroom/blob/main/headroom/providers/aider/__init__.py)
# CLI 代理包装器
## 概述
CLI 代理包装器（`headroom wrap`）是 Headroom 的核心命令行接口，用于自动将 AI 编码代理与 Headroom 代理服务集成。通过包装启动流程，该命令能够自动完成代理配置、上下文工具设置、MCP 服务器注册等多项任务，使用户无需手动修改配置即可享受上下文压缩带来的 token 节省。
资料来源：[headroom/cli/wrap.py:1-100]()
## 核心功能
| 功能 | 说明 |
|------|------|
| 自动代理启动 | 启动指定代理并配置其流量通过 Headroom 代理 |
| 上下文工具集成 | 自动安装并配置 RTK 或 lean-ctx 作为上下文工具 |
| MCP 服务器注册 | 为支持 MCP 的代理注册 headroom MCP 服务器 |
| 内存上下文注入 | 可选地将记忆搜索结果注入到代理上下文中 |
| CCR 检索支持 | 启用可逆压缩，允许代理按需检索原始内容 |
资料来源：[headroom/cli/wrap.py:150-200]()
## 支持的代理
Headroom CLI 包装器支持多种主流 AI 编码代理，每个代理都有专门的集成逻辑：
```mermaid
graph TD
A[headroom wrap] --> B[claude]
A --> C[codex]
A --> D[cursor]
A --> E[aider]
A --> F[copilot]
A --> G[openclaw]
B --> B1[Claude Code 集成]
C --> C1[Codex 配置注入]
D --> D1[Cursor 配置输出]
E --> E1[Aider 代理启动]
F --> F1[Copilot CLI 配置]
G --> G1[OpenClaw 插件]
```
### 代理支持矩阵
| 代理 | 包装支持 | 集成方式 |
|------|---------|----------|
| Claude Code | ✅ | 启动子进程 + MCP 注册 |
| Codex | ✅ | config.toml 配置注入 |
| Cursor | ✅ | 打印配置（一次性粘贴） |
| Aider | ✅ | 启动代理 + 代理进程管理 |
| Copilot CLI | ✅ | 启动代理 + 代理进程管理 |
| OpenClaw | ✅ | ContextEngine 插件安装 |
资料来源：[headroom/providers/claude/__init__.py:1-50]()
## 使用方法
### 基本用法
```bash
# 包装 Claude Code
headroom wrap claude
# 包装 Codex
headroom wrap codex
# 包装 Aider
headroom wrap aider
# 包装 Copilot CLI
headroom wrap copilot
```
### 常用选项
| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--port` | 代理服务监听端口 | 8787 |
| `--no-rtk` | 跳过 RTK/lean-ctx 上下文工具安装 | False |
| `--no-mcp` | 跳过 MCP 服务器注册 | False |
| `--no-memory` | 禁用记忆上下文注入 | False |
| `--memory` | 启用跨会话记忆功能 | False |
| `--learn` | 启用失败模式学习功能 | False |
| `--code-graph` | 启用代码图分析 | False |
| `--verbose` | 输出详细调试信息 | False |
资料来源：[headroom/cli/wrap.py:200-280]()
### 高级用法
```bash
# 指定自定义端口
headroom wrap claude --port 9999
# 禁用所有上下文工具
headroom wrap codex --no-rtk --no-mcp
# 启用记忆和代码图
headroom wrap aider --memory --code-graph
# 完整诊断输出
headroom wrap claude --verbose
```
## 内部工作原理
### 包装流程
```mermaid
sequenceDiagram
participant User
participant CLI as headroom wrap
participant Proxy as Headroom Proxy
participant Agent as AI Agent
participant MCP as MCP Server
participant RTK as RTK/lean-ctx
User->>CLI: headroom wrap
CLI->>CLI: 解析参数并验证环境
CLI->>RTK: 安装/验证上下文工具
CLI->>Proxy: 启动代理服务
CLI->>MCP: 注册 MCP 服务器
CLI->>Agent: 启动代理进程
Agent->>Proxy: API 请求
Proxy->>Agent: 压缩后的响应
Note over Agent: 代理使用压缩上下文
可通过 MCP 检索原始内容
```
### 代理特定配置逻辑
#### Claude Code
Claude Code 集成会启动一个子进程，并通过环境变量配置 API 路由：
```python
# 关键配置步骤
1. 设置 ANTHROPIC_BASE_URL 指向本地代理
2. 注册 headroom MCP 服务器
3. 配置 RTK 作为 git 输出重写工具
```
资料来源：[headroom/providers/claude/__init__.py:50-120]()
#### Codex
Codex 集成通过修改 `~/.codex/config.toml` 和项目 `AGENTS.md` 实现配置注入：
```mermaid
graph LR
A[config.toml] --> B[provider 配置]
A --> C[MCP 服务器地址]
B --> D[API 路由重写]
C --> E[headroom_retrieve 工具]
F[AGENTS.md] --> G[RTK 使用说明]
F --> H[代理记忆指南]
```
资料来源：[headroom/cli/init.py:100-180]()
#### Cursor
Cursor 集成采用"一次性配置"模式，输出必要的配置代码供用户手动粘贴：
```python
# 配置输出内容
CURSOR_MODEL_OVERRIDE_JSON = {
"apiKey": "headroom",
"baseURL": "http://localhost:8787/v1"
}
```
资料来源：[headroom/providers/cursor/__init__.py:30-80]()
## 上下文工具集成
### RTK 配置
RTK（Run Tool Kit）是 Headroom 默认的 git 输出重写工具。包装过程会自动：
1. 检测 RTK 二进制文件是否已安装
2. 如未安装，提示用户安装或使用 `--no-rtk` 跳过
3. 在 AGENTS.md 中注入 RTK 使用说明
4. 配置代理使用 RTK 进行命令输出优化
```bash
# RTK 安装检查逻辑
_rtk_path = _ensure_rtk_binary(verbose=verbose)
if _rtk_path:
_inject_rtk_instructions(agents_md, verbose=verbose)
```
资料来源：[headroom/cli/wrap.py:300-380]()
### lean-ctx 替代方案
通过设置 `HEADROOM_CONTEXT_TOOL=lean-ctx` 环境变量，可以使用 lean-ctx 替代 RTK：
```bash
export HEADROOM_CONTEXT_TOOL=lean-ctx
headroom wrap claude
```
lean-ctx 安装逻辑会覆盖 RTK 的默认行为：
```python
if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:
_setup_lean_ctx_agent(agent, verbose=verbose)
else:
_setup_rtk_agent(agent, verbose=verbose)
```
资料来源：[headroom/cli/wrap.py:380-420]()
## MCP 服务器集成
### 注册机制
MCP 服务器注册允许代理调用 `headroom_retrieve` 工具检索被压缩的原始内容：
```mermaid
graph TD
A[压缩请求] --> B[Proxy]
B --> C[CCR 存储]
C --> D[返回压缩内容 + 哈希]
D --> E[LLM 处理]
E --> F[headroom_retrieve 调用]
F --> G[MCP 服务器]
G --> H[检索原始内容]
```
### 各代理的 MCP 配置
| 代理 | MCP 配置方式 | 配置文件 |
|------|-------------|----------|
| Claude Code | 环境变量 | 进程环境 |
| Codex | config.toml | `~/.codex/config.toml` |
| Aider | 命令行参数 | 启动参数 |
| Copilot CLI | 环境变量 | 进程环境 |
资料来源：[headroom/cli/wrap.py:420-500]()
### 已知问题
> ⚠️ **问题 #503**：CCR 主动扩展块在多代理线程中会破坏消息归属。
>
> `_append_context_to_latest_non_frozen_user_turn()` 函数会将主动扩展块注入到最新用户消息内容中。在多代理设置中，该消息可能包含结构化的 XML 归属标记（``），注入的块最终会导致归属损坏。
资料来源：[GitHub Issue #503](https://github.com/chopratejas/headroom/issues/503)
> ⚠️ **问题 #460**：MCP 设置文档需要澄清代理 `/mcp` 不可用的情况。
>
> 当前 MCP 文档暗示 `headroom proxy` 可以用作 `/mcp` 端点的 HTTP MCP 端点，但使用当前安装的包时此端点返回 404，而 stdio MCP 服务器正常工作。
资料来源：[GitHub Issue #460](https://github.com/chopratejas/headroom/issues/460)
## 记忆功能
启用 `--memory` 选项后，包装器会：
1. 启动带有记忆后端的代理服务
2. 自动注入 `memory_search` 工具到代理的可用工具列表
3. 在系统消息中添加记忆使用指南
4. 将相关记忆内容注入到代理上下文
```bash
# 启用记忆功能
headroom wrap claude --memory
# 启用记忆并指定项目根目录
headroom wrap aider --memory --memory-project-root /path/to/project
```
### 记忆配置选项
| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--memory-qdrant-url` | Qdrant 完整 URL | localhost |
| `--memory-qdrant-host` | Qdrant 主机 | localhost |
| `--memory-qdrant-port` | Qdrant 端口 | 6333 |
| `--memory-top-k` | 注入的记忆数量 | 10 |
| `--no-memory-tools` | 禁用自动记忆工具注入 | False |
| `--no-memory-context` | 禁用自动记忆上下文注入 | False |
资料来源：[headroom/cli/proxy.py:150-220]()
## 诊断与调试
### 详细输出模式
使用 `--verbose` 标志获取详细的诊断信息：
```bash
headroom wrap claude --verbose
```
verbose 模式会输出：
- 参数解析详情
- 文件路径操作记录
- 子进程调用及退出码
- RTK/lean-ctx 安装状态
### 日志记录
代理服务支持 JSONL 日志输出：
```bash
headroom wrap claude --log-file ~/.headroom/logs/session.jsonl
```
启用消息日志记录：
```bash
headroom wrap claude --log-messages
```
## See Also
- [代理服务](../proxy/代理服务.md) - Headroom HTTP 代理的完整配置参考
- [MCP 服务器](../mcp/MCP服务器.md) - MCP 协议集成详解
- [压缩管道](../core/压缩管道.md) - 上下文压缩的技术细节
- [记忆系统](../memory/记忆系统.md) - 跨会话记忆功能
- [CLI 参考](../cli/CLI参考.md) - 完整命令行接口文档
---
## 代理间内存系统
### 相关页面
相关主题：[CLI 代理包装器](#cli-wrappers), [CCR 可逆压缩](#ccr), [配置参考](#configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [headroom/memory/__init__.py](https://github.com/chopratejas/headroom/blob/main/headroom/memory/__init__.py)
- [headroom/memory/bridge.py](https://github.com/chopratejas/headroom/blob/main/headroom/memory/bridge.py)
- [headroom/memory/core.py](https://github.com/chopratejas/headroom/blob/main/headroom/memory/core.py)
- [headroom/memory/adapters/sqlite.py](https://github.com/chopratejas/headroom/blob/main/headroom/memory/adapters/sqlite.py)
- [headroom/memory/backends/local.py](https://github.com/chopratejas/headroom/blob/main/headroom/memory/backends/local.py)
- [headroom/shared_context.py](https://github.com/chopratejas/headroom/blob/main/headroom/shared_context.py)
- [headroom/cli/wrap.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
# 代理间内存系统
## 概述
代理间内存系统（Inter-Agent Memory System）是 Headroom 提供的一项核心功能，旨在解决多智能体（multi-agent）工作流中的上下文共享与持久化问题。在复杂的多代理协作场景中，每个代理都会产生大量的上下文信息，这些信息需要在不同代理之间高效传递，同时还需要支持跨会话的持久化存储。资料来源：[headroom/shared_context.py:1-30]()
代理间内存系统的核心特性包括：
- **跨代理共享存储**：支持多个代理访问和写入统一的内存存储，实现上下文信息的无缝传递
- **代理溯源**：记录每条记忆的来源代理，便于追踪和审计
- **自动去重**：智能识别并合并重复的记忆内容，避免存储冗余
- **按项目隔离**：确保不同项目的记忆不会相互污染，防止信息泄漏
- **压缩传输**：所有共享的上下文内容都会经过自动压缩处理，节省带宽和存储成本
## 架构设计
### 整体架构图
```mermaid
graph TB
subgraph "代理层 (Agent Layer)"
A1[Claude Code]
A2[Codex]
A3[Gemini CLI]
A4[OpenCode]
end
subgraph "MCP 服务层 (MCP Service Layer)"
MC[headroom_memory MCP Server]
end
subgraph "核心内存层 (Core Memory Layer)"
SC[SharedContext 共享上下文]
MB[Memory Bridge 内存桥接]
MR[MemoryRanker 记忆排序]
end
subgraph "存储层 (Storage Layer)"
SQL[SQLite 适配器]
LOC[Local 后端]
QDR[Qdrant 向量存储]
N4J[Neo4j 图数据库]
end
subgraph "压缩层 (Compression Layer)"
CC[CCR 可逆压缩]
IC[IntelligentContext 智能上下文]
end
A1 & A2 & A3 & A4 --> MC
MC --> MB
MB --> SC
MB --> MR
SC --> CC
SC --> IC
MR --> SQL
SC --> SQL
SQL --> LOC
SQL --> QDR
SQL --> N4J
style MC fill:#e1f5fe
style SC fill:#fff3e0
style CC fill:#f3e5f5
```
### 核心组件职责
| 组件名称 | 文件位置 | 主要职责 |
|---------|---------|---------|
| SharedContext | `headroom/shared_context.py` | 管理跨代理的上下文压缩存储，提供 put/get/stats 接口 |
| Memory Bridge | `headroom/memory/bridge.py` | 协调 MCP 服务与后端存储之间的数据传输 |
| MemoryRanker | `headroom/memory/core.py` | 对记忆内容进行相关性排序，优化检索质量 |
| SQLite Adapter | `headroom/memory/adapters/sqlite.py` | 提供结构化数据存储，支持关系查询 |
| Local Backend | `headroom/memory/backends/local.py` | 实现本地文件系统的持久化存储 |
## 核心数据结构
### 记忆条目结构
```python
class MemoryEntry:
id: str # 唯一标识符 (UUID)
content: str # 记忆内容 (已压缩)
agent: str # 来源代理标识
project: str # 所属项目路径
tags: list[str] # 标签分类
created_at: float # 创建时间戳
accessed_at: float # 最后访问时间
version: int # 版本号 (分支感知)
ccr_hash: str # CCR 压缩哈希 (用于还原)
```
### 记忆存储配置
| 配置项 | 默认值 | 说明 | 环境变量 |
|-------|-------|------|---------|
| 存储后端 | SQLite | 本地关系型存储 | `HEADROOM_MEMORY_BACKEND` |
| 存储路径 | `~/.headroom/memory/` | 数据库文件目录 | `HEADROOM_MEMORY_PATH` |
| 向量维度 | 1536 | 嵌入向量长度 | `HEADROOM_EMBEDDING_DIM` |
| 最大条目数 | 10000 | 单项目记忆上限 | `HEADROOM_MAX_ENTRIES` |
| TTL (秒) | 86400 | 记忆过期时间 | `HEADROOM_MEMORY_TTL` |
资料来源：[headroom/memory/core.py:50-120]()
## 工作流程
### 记忆保存流程
```mermaid
sequenceDiagram
participant Agent as 代理 (Claude/Codex)
participant MCP as headroom_memory MCP Server
participant Bridge as Memory Bridge
participant Store as SharedContext
participant Compress as CCR 压缩引擎
Agent->>MCP: memory_save(content, metadata)
MCP->>Bridge: 转发保存请求
Bridge->>Compress: 压缩记忆内容
Compress-->>Bridge: 返回压缩结果 + CCR哈希
Bridge->>Store: 存储压缩内容 + 元数据
Store-->>Bridge: 返回存储确认 + 记忆ID
Bridge-->>MCP: 返回记忆ID
MCP-->>Agent: 确认保存成功
```
### 记忆检索流程
```mermaid
sequenceDiagram
participant Agent as 代理
participant MCP as headroom_memory MCP Server
participant Ranker as MemoryRanker
participant Store as SharedContext
participant DB as SQLite
Agent->>MCP: memory_search(query, filters)
MCP->>Ranker: 请求相关性排序
Ranker->>DB: 查询相关记忆
DB-->>Ranker: 返回候选记忆列表
Ranker-->>Store: 排序后的记忆ID列表
Store->>Store: 应用访问时间衰减
Store-->>MCP: 返回排序后的记忆
MCP-->>Agent: 返回检索结果
```
## 使用方法
### 通过 CLI 启用内存功能
在启动代理时使用 `--memory` 标志启用内存系统：
```bash
# 启用 Claude Code 并开启内存功能
headroom wrap claude --memory
# 启用 Codex 并开启内存功能
headroom wrap codex --memory
# 同时启用代码图谱分析
headroom wrap claude --memory --code-graph
```
资料来源：[headroom/cli/wrap.py:150-180]()
### 通过 MCP 服务直接调用
代理可以通过 `headroom_memory` MCP 服务器访问记忆功能：
```typescript
// 保存记忆
await mcpServer.callTool("memory_save", {
content: "项目使用 Monorepo 架构",
agent: "researcher",
tags: ["architecture", "monorepo"]
});
// 检索相关记忆
const results = await mcpServer.callTool("memory_search", {
query: "项目的代码架构是什么？",
limit: 5
});
// 列出当前项目的所有记忆
const memories = await mcpServer.callTool("memory_list", {
project: "/path/to/project"
});
// 获取记忆详情（包含 CCR 哈希用于还原）
const detail = await mcpServer.callTool("memory_get", {
id: "memory-uuid-here"
});
```
### 通过 SharedContext API 编程使用
```python
from headroom import SharedContext
# 初始化共享上下文
ctx = SharedContext(
model="gpt-4o",
ttl=3600, # 1小时过期
max_entries=100 # 最多100条
)
# 代理 A 存储数据（自动压缩）
entry = ctx.put("research", big_agent_output, agent="researcher")
print(f"压缩率: {entry.savings_percent:.0%}")
# 代理 B 读取压缩后的数据
compressed = ctx.get("research")
# 代理 B 需要原始数据时获取完整版本
full = ctx.get("research", full=True)
# 查看统计信息
stats = ctx.stats()
print(f"条目数: {stats.entries}")
print(f"节省Token: {stats.total_tokens_saved}")
```
资料来源：[headroom/shared_context.py:80-150]()
## 配置选项
### 环境变量配置
| 环境变量 | 类型 | 默认值 | 说明 |
|---------|------|-------|------|
| `HEADROOM_MEMORY_ENABLED` | bool | false | 启用/禁用内存系统 |
| `HEADROOM_MEMORY_BACKEND` | string | sqlite | 存储后端类型 |
| `HEADROOM_MEMORY_PATH` | string | ~/.headroom/memory/ | 存储路径 |
| `HEADROOM_MEMORY_TTL` | int | 86400 | 默认过期时间（秒） |
| `HEADROOM_MEMORY_MAX_ENTRIES` | int | 10000 | 单项目最大条目数 |
| `HEADROOM_EMBEDDING_MODEL` | string | auto | 嵌入模型选择 |
| `HEADROOM_AUTO_TAIL` | bool | true | 自动清理过期记忆 |
### 代理 AGENTS.md 内存引导
当使用 `headroom wrap` 启动代理时，系统会自动向项目的 `AGENTS.md` 文件注入内存使用指南：
```markdown
## Memory
Use the `headroom_memory` MCP server for persistent cross-session knowledge.
**Before** answering questions about prior decisions, conventions, project context,
architecture, user preferences, org info, codenames, debugging history, or anything
from past sessions — call `memory_search` first.
**After** making durable decisions, discovering conventions, or learning important
facts — call `memory_save` to persist them for future sessions.
Memory is your first source of truth for anything not visible in the current conversation.
```
资料来源：[headroom/cli/wrap.py:200-230]()
## 存储后端
### SQLite 适配器
SQLite 是默认的存储后端，提供可靠的关系型数据存储：
```python
# 内部实现概要
class SQLiteAdapter:
def __init__(self, db_path: Path):
self.conn = sqlite3.connect(db_path)
self._init_schema()
def _init_schema(self):
"""初始化记忆表结构"""
self.conn.execute("""
CREATE TABLE IF NOT EXISTS memories (
id TEXT PRIMARY KEY,
content TEXT NOT NULL, -- 压缩后的内容
ccr_hash TEXT NOT NULL, -- CCR 哈希用于还原
agent TEXT NOT NULL,
project TEXT NOT NULL,
tags TEXT, -- JSON 数组
created_at REAL NOT NULL,
accessed_at REAL NOT NULL,
version INTEGER DEFAULT 1,
UNIQUE(project, ccr_hash) -- 自动去重
)
""")
# 创建索引以加速查询
self.conn.execute("CREATE INDEX IF NOT EXISTS idx_project ON memories(project)")
self.conn.execute("CREATE INDEX IF NOT EXISTS idx_agent ON memories(agent)")
```
### Local 后端
Local 后端将记忆存储为文件系统中的 JSON 文件：
```python
class LocalBackend:
"""基于文件系统的记忆存储"""
def __init__(self, base_path: Path):
self.base_path = base_path
self.base_path.mkdir(parents=True, exist_ok=True)
def _get_project_dir(self, project: str) -> Path:
"""按项目隔离存储"""
safe_project = project.replace("/", "_").replace(".", "_")
return self.base_path / safe_project
def put(self, entry: MemoryEntry) -> str:
"""保存记忆到文件"""
project_dir = self._get_project_dir(entry.project)
file_path = project_dir / f"{entry.id}.json"
file_path.write_text(json.dumps(asdict(entry)))
return entry.id
def get(self, memory_id: str, project: str) -> MemoryEntry | None:
"""从文件读取记忆"""
project_dir = self._get_project_dir(project)
file_path = project_dir / f"{memory_id}.json"
if file_path.exists():
return MemoryEntry(**json.loads(file_path.read_text()))
return None
```
资料来源：[headroom/memory/adapters/sqlite.py:40-100]()
## 已知问题与限制
### Issue #503: CCR 主动扩展块污染多代理线程消息归属
在多代理设置中，当 `_append_context_to_latest_non_frozen_user_turn()` 函数向最新的用户消息内容注入主动扩展块时，如果该消息包含结构化的 XML 属性标记（``），注入的块可能会破坏消息的归属信息。
**影响范围**：多代理协作场景中，消息来源可能被错误标记
**影响版本**：v0.22.2 及之前版本
**状态**：社区已报告，等待修复
### Issue #462: 按项目隔离存储
v0.21.34 版本修复了项目间记忆泄漏问题。之前的版本中，不同项目的记忆可能相互污染，导致代理获取到不相关的上下文。
**修复内容**：
- 引入 `HEADROOM_MEMORY_PATH` 环境变量支持
- 所有记忆操作现在严格按项目路径隔离
- 跨项目记忆访问需要显式授权
### 性能注意事项
| 场景 | 建议 | 原因 |
|-----|------|------|
| 大规模记忆检索 | 使用 `memory_search` 而非 `memory_list` | 避免全表扫描 |
| 频繁写入 | 批量操作优于单条写入 | 减少 I/O 次数 |
| 长对话场景 | 启用 `HEADROOM_AUTO_TAIL` | 自动清理过期记忆 |
| 多代理并发 | 确保使用相同项目路径 | 避免存储路径冲突 |
## 与其他系统的集成
### MCP 服务集成
`headroom_memory` MCP 服务器提供标准化的记忆操作接口：
```bash
# 启动 MCP 服务器
headroom mcp start --memory
# 或者通过代理启动
headroom proxy --enable-memory
```
### OpenClaw 插件集成
OpenClaw 插件可以通过配置使用 Headroom 的记忆系统：
```typescript
// plugins/openclaw/src/convert.ts
const config = {
memoryEnabled: true,
memoryProject: process.cwd(),
proxyUrl: "http://127.0.0.1:8787"
};
```
### LangChain 集成
在 LangChain 代理中使用 Headroom 记忆：
```python
from langchain.agents import AgentExecutor, initialize_agent
from headroom.memory import MemoryBridge
# 创建记忆桥接
memory = MemoryBridge(backend="sqlite")
# 初始化代理时注入记忆能力
agent = initialize_agent(
tools,
llm,
agent="conversational-react-description",
memory=memory.as_langchain_memory()
)
```
## 最佳实践
### 记忆组织策略
1. **按主题标签分类**：使用一致的标签体系便于检索
2. **包含代理来源**：每条记忆应记录创建代理
3. **保持原子性**：每条记忆应包含一个独立的知识点
4. **定期清理**：使用 `memory_tail` 删除过时记忆
### 压缩效率优化
```python
# 高效保存模式
ctx.put(
key="research-findings",
value=agent_output,
agent="researcher",
tags=["research", "Q3-2024"],
ttl=7 * 24 * 3600 # 7天过期
)
# 批量检索优化
results = ctx.batch_get(
keys=["key1", "key2", "key3"],
full=False # 仅获取压缩版本
)
```
## 参见
- [上下文压缩系统](./上下文压缩系统.md) - 了解 CCR 可逆压缩技术
- [请求生命周期](./请求生命周期.md) - 内存系统在整体请求流程中的位置
- [MCP 服务集成](./MCP服务集成.md) - 深入了解 MCP 协议支持
- [多代理协作](./多代理协作.md) - 跨代理工作流配置指南
- [配置参考](./配置参考.md) - 完整的环境变量与配置项说明
---
## 配置参考
### 相关页面
相关主题：[代理服务器](#proxy-server)
相关源码文件
以下源码文件用于生成本页说明：
- [headroom/cli/proxy.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
- [headroom/models/config.py](https://github.com/chopratejas/headroom/blob/main/headroom/models/config.py)
- [headroom/cli/wrap.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
- [headroom/cli/learn.py](https://github.com/chopratejas/headroom/blob/main/headroom/cli/learn.py)
- [.env.act.example](https://github.com/chopratejas/headroom/blob/main/.env.act.example)
- [headroom/compression/detector.py](https://github.com/chopratejas/headroom/blob/main/headroom/compression/detector.py)
# 配置参考
本文档提供 Headroom 完整配置选项的详细参考，包括命令行参数、环境变量、API 参数以及各组件的配置方式。
## 概述
Headroom 提供多层配置体系，涵盖代理服务（Proxy）、CLI 封装（Wrap）、学习模块（Learn）以及压缩引擎的核心参数。配置通过命令行标志、环境变量和配置文件三种方式生效，其中环境变量通常以 `HEADROOM_` 前缀开头。
资料来源：[.env.act.example](https://github.com/chopratejas/headroom/blob/main/.env.act.example)
## 代理服务配置（Proxy）
代理服务是 Headroom 的核心组件，作为中间层拦截并压缩 AI 模型的请求/响应。启动代理使用 `headroom proxy` 命令。
### 基础参数
| 参数 | 环境变量 | 类型 | 默认值 | 说明 |
|------|----------|------|--------|------|
| `--port` | `HEADROOM_PORT` | int | 8080 | 代理监听端口 |
| `--host` | `HEADROOM_HOST` | string | 127.0.0.1 | 代理绑定地址 |
| `--budget` | `HEADROOM_BUDGET` | float | None | 每日预算限额（美元） |
资料来源：[headroom/cli/proxy.py:45-65](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
### 日志配置
| 参数 | 环境变量 | 类型 | 说明 |
|------|----------|------|------|
| `--log-file` | - | string | JSONL 日志文件路径 |
| `--log-messages` | - | flag | 启用完整消息日志（包含请求/响应内容） |
| `--codex-wire-debug` | - | flag | 启用 Codex wire 快照和代理日志帧追踪 |
| `--codex-wire-debug-dir` | - | string | Codex wire 快照目录（默认 `~/.headroom/logs/codex_wire`） |
资料来源：[headroom/cli/proxy.py:70-95](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
### 压缩策略配置
```mermaid
graph LR
A[输入请求] --> B[CompressionPolicy]
B --> C[F1: 基础模式]
B --> D[F2: 平衡模式]
B --> E[F3: 激进模式]
C --> F[SmartCrusher]
D --> G[ContentRouter]
E --> H[IntelligentContext]
F --> I[CacheAligner]
G --> I
H --> I
I --> J[输出压缩]
```
#### 代码感知压缩
| 参数 | 环境变量 | 类型 | 说明 |
|------|----------|------|------|
| `--code-aware/--no-code-aware` | `HEADROOM_CODE_AWARE_ENABLED` | bool | 启用 AST 树感知压缩（需安装 `headroom-ai[code]`） |
资料来源：[headroom/cli/proxy.py:100-120](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
### 工具过滤配置
| 参数 | 环境变量 | 类型 | 说明 |
|------|----------|------|------|
| `--exclude-tools` | `HEADROOM_EXCLUDE_TOOLS` | string | 排除的工具列表，逗号分隔 |
> **注意**：v0.22.0 引入了 `--exclude-tools` 标志，允许用户指定不经过压缩管道的工具调用。
资料来源：[headroom/cli/proxy.py:1-150](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py)
## CLI 封装配置（Wrap）
`headroom wrap` 命令用于启动 AI 编码助手并自动配置代理环境。不同代理有不同的配置选项。
### 通用参数
| 参数 | 说明 |
|------|------|
| `--port` | 指定代理端口（默认 8080） |
| `--verbose` | 输出详细安装过程信息 |
| `--prepare-only` | 仅准备环境，不启动子进程 |
| `--no-context-tool` | 跳过 CLI 上下文工具（rtk/lean-ctx）设置 |
| `--no-mcp` | 跳过 MCP 服务器注册 |
资料来源：[headroom/cli/wrap.py:1-200](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
### 代理特定参数
#### Claude Code
```bash
headroom wrap claude --session "my-session" --no-rtk
```
| 参数 | 说明 |
|------|------|
| `--session` | 指定 Claude 会话名称 |
| `--no-rtk` | 跳过 rtk/lean-ctx 设置 |
#### Goose
```bash
headroom wrap goose --port 9090
```
Goose 支持通过环境变量路由到代理：
```bash
export OPENAI_BASE_URL=http://127.0.0.1:9090/v1
export ANTHROPIC_BASE_URL=http://127.0.0.1:9090
```
#### Cline
```bash
headroom wrap cline --port 9999
```
Cline 配置说明：
```
Settings > Cline > API Provider
Anthropic Base URL: http://127.0.0.1:9999
OpenAI Compatible Base URL: http://127.0.0.1:9999/v1
```
资料来源：[headroom/cli/wrap.py:200-400](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
### Codex 特定参数
```bash
headroom wrap codex --port 8080 --no-context-tool
```
| 参数 | 说明 |
|------|------|
| `--port` | 指定代理端口 |
| `--no-context-tool` | 跳过 rtk 上下文工具 |
| `--no-mcp` | 跳过 MCP 服务器注册 |
Codex 会通过 `~/.codex/config.toml` 配置文件自动启动 Headroom MCP 服务器。
资料来源：[headroom/cli/wrap.py:400-600](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)
## 学习模块配置（Learn）
`headroom learn` 命令分析历史对话以发现工具调用失败模式并生成预防性上下文。
### 参数
| 参数 | 短写 | 类型 | 默认值 | 说明 |
|------|------|------|--------|------|
| `--project` | - | Path | 当前目录 | 要分析的项目路径 |
| `--all` | - | flag | False | 分析所有已知项目 |
| `--apply` | - | flag | False | 直接应用分析建议 |
| `--agent` | - | string | auto | 指定代理类型（claude/codex/gemini） |
| `--model` | - | string | auto | 用于分析的 LLM 模型 |
| `--workers` | `-j` | int | auto | 并行工作线程数（默认 min(CPU数, 8)） |
资料来源：[headroom/cli/learn.py:1-80](https://github.com/chopratejas/headroom/blob/main/headroom/cli/learn.py)
### 示例
```bash
# 自动检测代理和模型
headroom learn
# 使用指定模型分析
headroom learn --model gpt-4o --apply
# 分析所有项目
headroom learn --all
# 指定代理类型
headroom learn --agent codex --all
```
## 环境变量参考
### 代理相关
| 变量 | 类型 | 说明 |
|------|------|------|
| `HEADROOM_PORT` | int | 代理监听端口 |
| `HEADROOM_HOST` | string | 代理绑定地址 |
| `HEADROOM_BUDGET` | float | 每日预算限额（美元） |
| `HEADROOM_EXCLUDE_TOOLS` | string | 排除的工具列表 |
| `HEADROOM_CODE_AWARE_ENABLED` | bool | 启用代码感知压缩 |
| `HEADROOM_CONTEXT_TOOL` | string | 选择上下文工具（rtk/lean-ctx） |
### 内存模块
| 变量 | 类型 | 说明 |
|------|------|------|
| `HEADROOM_MEMORY_ENABLED` | bool | 启用跨会话内存 |
| `HEADROOM_MEMORY_TTL` | int | 内存条目 TTL（秒） |
### MCP 服务器
| 变量 | 类型 | 说明 |
|------|------|------|
| `HEADROOM_MCP_TRANSPORT` | string | MCP 传输类型（stdio/http） |
> **注意**：Issue #460 报告了 `/mcp` HTTP 端点在某些安装版本中返回 404。当前版本中，MCP 服务器主要通过 stdio 协议工作。
资料来源：[.env.act.example](https://github.com/chopratejas/headroom/blob/main/.env.act.example)
## 压缩策略配置模型
```mermaid
graph TD
A[CompressionPolicy] --> B[mode: F1 | F2 | F3]
A --> C[max_tokens: int]
A --> D[preserve_system: bool]
A --> E[preserve_last_user: bool]
B --> F[F1: 基础 - SmartCrusher]
B --> G[F2: 平衡 - ContentRouter]
B --> H[F3: 激进 - IntelligentContext]
```
### 策略字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| `mode` | string | 压缩模式：F1（基础）、F2（平衡）、F3（激进） |
| `max_tokens` | int | 压缩后最大 token 数 |
| `preserve_system` | bool | 是否保留系统消息 |
| `preserve_last_user` | bool | 是否保留最后一条用户消息 |
资料来源：[headroom/models/config.py](https://github.com/chopratejas/headroom/blob/main/headroom/models/config.py)
## 压缩检测配置
```python
# 启用压缩的条件配置
CompressionDetectorConfig(
min_tokens_to_compress=500, # 最小压缩阈值
min_messages=3, # 最小消息数
exclude_providers=[], # 排除的提供商
exclude_models=[], # 排除的模型
)
```
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `min_tokens_to_compress` | int | 500 | 触发压缩的最小 token 数 |
| `min_messages` | int | 3 | 触发压缩的最小消息数 |
| `exclude_providers` | list | [] | 跳过压缩的提供商列表 |
| `exclude_models` | list | [] | 跳过压缩的模型列表 |
资料来源：[headroom/compression/detector.py](https://github.com/chopratejas/headroom/blob/main/headroom/compression/detector.py)
## 配置优先级
```mermaid
graph LR
A[环境变量] --> B[命令行参数]
B --> C[配置文件]
C --> D[默认值]
style A fill:#ff6b6b
style B fill:#feca57
style C fill:#48dbfb
style D fill:#1dd1a1
```
配置优先级（高到低）：
1. **命令行参数** - 最高优先级
2. **环境变量** - 次优先级
3. **配置文件** - 较低优先级
4. **默认值** - 最低优先级
## 常见配置场景
### 场景 1：轻量级开发（节省资源）
```bash
headroom proxy --port 8080 \
--mode F1 \
--log-file /tmp/headroom.log
```
### 场景 2：生产环境（高精度压缩）
```bash
headroom proxy --port 8080 \
--mode F3 \
--code-aware \
--budget 10.0 \
--log-messages
```
### 场景 3：多代理协作
```bash
# 启动代理，启用内存模块
headroom proxy --port 8080 \
--memory \
--exclude-tools "memory_search,memory_save"
# 封装多个代理
headroom wrap claude --port 8080 &
headroom wrap codex --port 8080 &
```
### 场景 4：调试 Codex 集成
```bash
headroom proxy --port 8080 \
--codex-wire-debug \
--codex-wire-debug-dir ./debug_logs \
--log-messages
```
## 配置验证
启动代理后，可通过以下方式验证配置：
```bash
# 检查代理状态
curl http://127.0.0.1:8080/health
# 查看可用模型
curl http://127.0.0.1:8080/v1/models
```
## 故障排除
### 问题：代理端口冲突
```
Error: Address already in use
```
**解决方案**：
```bash
# 查看占用端口的进程
lsof -i :8080
# 使用其他端口
headroom proxy --port 9090
```
### 问题：MCP 端点返回 404
Issue #460 报告了 `/mcp` HTTP 端点在某些版本中不可用。
**解决方案**：
- 使用 stdio 传输的 MCP 服务器（默认）
- 或通过 `HEADROOM_MCP_TRANSPORT=http` 显式配置
### 问题：预算限制提前触发
**解决方案**：
```bash
# 检查当日使用量
headroom stats
# 提高预算限额
headroom proxy --budget 50.0
```
## 相关文档
- [代理服务](proxy.md) - 完整的代理使用指南
- [CLI 命令参考](cli-commands.md) - 所有 CLI 命令详解
- [压缩策略](compression-strategies.md) - 各压缩模式的算法细节
- [内存模块](memory-module.md) - 跨会话内存配置
## 更新日志
| 版本 | 更新内容 |
|------|----------|
| v0.22.0 | 新增 `--exclude-tools` 标志和 `HEADROOM_EXCLUDE_TOOLS` 环境变量 |
| v0.21.32 | 新增 per-mode CompressionPolicy tuning fields |
| v0.21.0 | 引入 F1/F2/F3 压缩模式体系 |
---
---
## Doramagic 踩坑日志
项目：chopratejas/headroom
摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：docs: clarify MCP setup when proxy /mcp is unavailable。
## 1. 安装坑 · 来源证据：docs: clarify MCP setup when proxy /mcp is unavailable
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：docs: clarify MCP setup when proxy /mcp is unavailable
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_109db57bc201482abc7bf318a0ee4792 | https://github.com/chopratejas/headroom/issues/460 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。
## 2. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1129940957 | https://github.com/chopratejas/headroom | host_targets=mcp_host, claude, claude_code, cursor
## 3. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1129940957 | https://github.com/chopratejas/headroom | README/documentation is current enough for a first validation pass.
## 4. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1129940957 | https://github.com/chopratejas/headroom | last_activity_observed missing
## 5. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1129940957 | https://github.com/chopratejas/headroom | no_demo; severity=medium
## 6. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1129940957 | https://github.com/chopratejas/headroom | no_demo; severity=medium
## 7. 安全/权限坑 · 来源证据：[BUG] CCR proactive expansion blocks corrupt message attribution in multi-agent threads
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] CCR proactive expansion blocks corrupt message attribution in multi-agent threads
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5ab74a3c022a4924998aaa72cc334c04 | https://github.com/chopratejas/headroom/issues/503 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 8. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1129940957 | https://github.com/chopratejas/headroom | issue_or_pr_quality=unknown
## 9. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1129940957 | https://github.com/chopratejas/headroom | release_recency=unknown