04 · 上下文压缩

为什么需要上下文压缩

Agent 每次工具调用（读文件、grep、构建日志）都会向上下文窗口追加大量文本。如果不加控制，以下问题会随对话轮次累积：

问题	影响
Token 成本线性增长	多轮对话中，每次请求都携带完整历史；tool 输出 10KB，10 轮后至少增长 100KB
窗口容量挤压	上下文窗口被历史 tool 输出占满，留给新代码、diff、推理的空间减少
模型性能退化	上下文越长，LLM 注意力分散，关键信息被稀释——即「lost in the middle」效应
延迟增加	更大的请求体意味着更长的网络传输与首 token 延迟

上下文压缩的核心思想：在 tool 输出进入对话历史之前，用结构化摘要或关键段替代原始内容，减小 token 体积的同时保留语义信息。

Token 成本速算

模型	输入 $/1M tokens	典型 50KB tool 输出	10 轮累积成本
GPT-4o	~$2.50	~$0.03	~$0.30
Claude 3.5 Sonnet	~$3.00	~$0.04	~$0.40
Claude Opus	~$15.00	~$0.19	~$1.90

以上为估算值。实际成本取决于 tokenizer 分词密度、system prompt 大小及模型定价变化。

压缩率 70–90% 时，上述成本可降为原来的 1/3–1/10。对于高频 Agent 使用场景（日均 50+ 轮对话），差异显著。

本文以 Headroom 为实践载体，记录其 proxy + MCP 双通道接入方式。依据 Headroom 官方文档（Installation → Docker、Proxy Server、MCP Tools）。

Headroom 与 rtk 的分工

两种压缩机制作用于不同层面，可并存：

工具	压缩对象	介入层
Headroom	发送给 LLM 的 messages（对话 + tool 结果）	API / proxy 层（:8787）+ MCP 按需
rtk	Shell 命令的 终端 stdout	命令执行层（preToolUse hook）

rtk 安装

rtk 通过 rtk init 安装到对应的 Agent，支持 Cursor、OpenCode、Claude Code、Windsurf、Cline、Kilo Code、Gemini CLI 等：

# 安装 rtk 本体
brew install rtk

# 安装到 Cursor
rtk init -g --agent cursor --auto-patch

# 安装到 OpenCode
rtk init --agent opencode --auto-patch

# 安装到 Claude Code（默认）
rtk init -g --agent claude

不同 Agent 的安装产物略有差异：Cursor 通过 preToolUse hook 注入 ~/.cursor/hooks.json，OpenCode 和 Claude Code 通过插件生效。

flowchart LR
  Agent[Agent]
  MCP[Headroom MCP]
  Proxy[Headroom Proxy :8787]
  API[OpenAI / Anthropic]

  Agent -->|按需压缩| MCP
  MCP --> Proxy
  Agent -->|API 请求| Proxy
  Proxy -->|压缩后转发| API

安装

Docker 部署

Installation → Docker 提供容器化部署：

docker pull ghcr.io/chopratejas/headroom:latest

docker run -d \
  --name headroom \
  --restart unless-stopped \
  -p 8787:8787 \
  ghcr.io/chopratejas/headroom:latest

需通过 proxy 转发到真实 API 时，注入 provider 密钥：

docker rm -f headroom

docker run -d \
  --name headroom \
  --restart unless-stopped \
  -p 8787:8787 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e OPENAI_API_KEY=sk-... \
  ghcr.io/chopratejas/headroom:latest

验证

curl http://127.0.0.1:8787/health
curl http://127.0.0.1:8787/stats

/health 返回 "status":"healthy" 即 proxy 就绪。

自定义上游验证

非 Docker 部署时，确认 OPENAI_TARGET_API_URL 已正确设置：curl -s http://127.0.0.1:8787/v1/models 应返回上游的模型列表而非 connection_error。

配置 MCP

MCP Tools 暴露三个工具：

工具	功能
headroom_compress	按需压缩大段内容（JSON、日志、搜索结果）
headroom_retrieve	通过 hash 取回原始内容，支持 query 参数定向搜索
headroom_stats	查询当前会话的压缩统计

Cursor

写入 ~/.cursor/mcp.json（全局，所有项目生效）或项目 .cursor/mcp.json（优先于全局，建议 commit 到 git 供团队共享）。Cursor 暂无 MCP 配置的云端同步，换机器需手动复制全局文件。

{
  "mcpServers": {
    "headroom": {
      "command": "docker",
      "args": ["exec", "-i", "headroom", "headroom", "mcp", "serve"]
    }
  }
}

OpenCode

写入 ~/.config/opencode/opencode.json 的 mcp 字段：

{
  "mcp": {
    "headroom": {
      "type": "local",
      "command": ["docker", "exec", "-i", "headroom", "headroom", "mcp", "serve", "--proxy-url", "http://localhost:8787"],
      "enabled": true
    }
  }
}

OpenCode 的 headroom 需要额外指定 --proxy-url http://localhost:8787，使 MCP 压缩与 proxy 共用同一管道。同时在 provider 中将 Anthropic Base URL 指向 proxy：

{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "http://localhost:8787"
      }
    }
  }
}

这样 OpenCode 的 LLM 流量走 proxy 全量自动压缩，MCP 工具提供按需压缩补充。

HTTP 备选

文档亦支持 "type": "http", "url": "http://127.0.0.1:8787/mcp"。若连接异常，优先改用上面的 stdio 方案。

生效与验证

1. 确认 docker ps 中 headroom 为 Up (healthy)
2. 重启 Agent 客户端，在对应设置面板确认 headroom 连接状态
   • Cursor：Settings → Tools & MCP，headroom 显示绿点
   • OpenCode：opencode.json 中 enabled: true，启动后自动加载
3. Agent 对话中应能调用 headroom_compress / headroom_stats

容器内自检：

docker exec headroom headroom mcp status

MCP 与 Proxy 的关系

• Proxy（:8787）：HTTP 层自动压缩所有经 proxy 的 LLM 流量
• MCP 工具：Agent 按需调用压缩 / 取回 / 统计；与 proxy 共用压缩管道，不会对同一内容重复压缩

仅需 MCP、无需全量 proxy 的场景，可 pip install "headroom-ai[mcp]" 后执行 headroom mcp serve。

三种接入路径

Headroom 提供三条互不排斥的路径，按使用场景组合。

路径 A：MCP 按需压缩

Agent 在对话中按需调用 MCP 工具——适合「tool 输出过大，先压缩再推理」的场景：

场景	工具	用法
grep / 测试输出过长	headroom_compress	传入 content，获得 compressed + hash
压缩后需查阅原文	headroom_retrieve	传入 hash；可选 query 在原文中定向检索
查看会话压缩统计	headroom_stats	返回 tokens_saved、savings_percent、最近事件

压缩结果示例（MCP 文档）：

{
  "compressed": "[key matches with context...]",
  "hash": "a1b2c3d4e5f6...",
  "original_tokens": 12000,
  "compressed_tokens": 3200,
  "savings_percent": 73.3,
  "transforms": ["router:search:0.27"]
}

原文在本地 store 保留约 1 小时；proxy store 约 5 分钟。过期后 headroom_retrieve 返回 not found，需从源重新获取。

在 Agent 对话中可直接说：「用 headroom 压缩这段输出再分析」。

路径 B：Proxy 全量自动压缩

将 LLM 客户端的 API 地址指向 http://127.0.0.1:8787，每次请求的 messages 在转发前自动压缩。详见 Quickstart → proxy mode 与 Proxy → Agent wrapping。

# Claude Code
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

# OpenAI 兼容
OPENAI_BASE_URL=http://127.0.0.1:8787/v1 your-app

本地安装（非 Docker）

uv tool install "headroom-ai[proxy,mcp,code]"

本地安装适合需要自定义上游代理的场景（如 omniroute、one-api 等）：

# 指定上游（默认转发到官方 API）
OPENAI_TARGET_API_URL=http://localhost:20128/v1 headroom proxy --port 8787

上行中 proxy 监听 :8787，所有请求经压缩后转发到 http://localhost:20128/v1。OPENAI_TARGET_API_URL 指向自定义 OpenAI 兼容 API 时，无需再设置 OPENAI_API_KEY。

flowchart LR
  Agent[Agent]
  Proxy[Headroom Proxy :8787]
  Upstream[自定义上游 :20128]

  Agent -->|API 请求| Proxy
  Proxy -->|压缩后转发| Upstream

认证方式

官方 API 需配置对应密钥（proxy 转发时携带）：

OpenCode

OpenCode 直接在配置文件中设置 provider Base URL，无需命令行变量。

Anthropic 官方 API：

{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "http://localhost:8787"
      }
    }
  }
}

OpenAI 兼容自定义上游（如 omniroute）：

代理请求经 headroom 压缩后转发到自定义上游（需 proxy 启动时设 OPENAI_TARGET_API_URL）：

{
  "provider": {
    "omniroute": {
      "api": "openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:8787/v1"
      }
    }
  }
}

写入 ~/.config/opencode/opencode.json。配合 MCP 中的 --proxy-url flag，MCP 与 proxy 共用同一压缩管道。

Cursor 桌面版：headroom wrap cursor

Proxy 文档 支持 headroom wrap cursor。该命令会打印 Cursor 需填写的 Base URL（不会自动写入 Cursor Settings），并按当前工作目录名生成按项目归因的 /p/<目录名>/ 前缀。

直接在 Cursor 填入以下格式的 URL（将 <目录名> 替换为项目根目录文件夹名）：

模型类型	Override Base URL	API Key
OpenAI 兼容	http://127.0.0.1:8787/p/<目录名>/v1	你的 OpenAI Key
Anthropic（proxy 侧）	http://127.0.0.1:8787/p/<目录名>	你的 Anthropic Key

Cursor 能力边界

• Cursor 仅有 Override OpenAI Base URL 入口；headroom wrap cursor 打印的 Anthropic Base URL 供 proxy 路由参考，Claude BYOK 当前无独立 Anthropic Override，不保证走 proxy
• Agent / Composer / Tab 补全不一定全部走 BYOK proxy；Cursor 订阅内置模型走自家后端。不确定时，以 /stats 的 api_requests 为依据，与 路径 A（MCP） 并用

验证 proxy 是否收到 Cursor 流量：curl -s http://127.0.0.1:8787/stats 中 summary.api_requests 应在对话后 > 0。

获取 wrap 打印的完整说明（在项目根目录执行）：

# 已装 headroom CLI
headroom wrap cursor

# 或临时容器（挂载当前目录，保留目录名用于 /p/<目录名>/ 归因）
docker run --rm --entrypoint headroom \
  -v "$(pwd):$(pwd)" -w "$(pwd)" \
  ghcr.io/chopratejas/headroom:latest wrap cursor

执行后将打印类似以下内容：OpenAI 用 http://127.0.0.1:8787/p/<项目名>/v1，Anthropic 用 http://127.0.0.1:8787/p/<项目名>，<项目名> 为当前目录名。同时向 .cursorrules 注入 rtk 终端过滤说明。

路径 C：纯压缩（不调 LLM）

Proxy → POST /v1/compress 仅运行压缩管道，适合脚本集成或功能验证：

curl -X POST http://127.0.0.1:8787/v1/compress \
  -H 'Content-Type: application/json' \
  -d '{
    "messages": [{"role": "user", "content": "很长的内容..."}],
    "model": "gpt-4o"
  }'

响应含 tokens_before、tokens_after、tokens_saved、compression_ratio、transforms_applied。设置请求头 x-headroom-bypass: true 可跳过压缩做对照实验。

推荐组合

组件	作用
headroom 容器 :8787	proxy 常驻，提供 /stats、MCP 后端、路径 B/C
MCP 配置（Cursor / OpenCode）	Agent 按需 compress / retrieve / stats
Provider Base URL 指向 proxy	全量自动压缩（OpenCode 配置文件 / Cursor Override OpenAI Base URL / CLI 环境变量）

Proxy 压缩 HTTP 流量，MCP 压缩 Agent 主动提交的大块内容；二者数据面独立，不会双重压缩。

验证压缩效果

1. 实时统计：GET /stats

curl http://127.0.0.1:8787/stats | python3 -m json.tool

关键字段：

路径	含义
summary.api_requests	经 proxy 转发的 API 请求数（路径 B）
summary.compression.requests_compressed	触发压缩的请求数
summary.compression.total_tokens_removed	累计节省 token
summary.compression.avg_compression_pct	平均压缩比例
summary.cost.total_saved_usd	估算节省费用（美元）
summary.mcp.compressions	MCP headroom_compress 调用次数
summary.mcp.tokens_removed	MCP 路径节省 token
agent_usage.totals.tokens_saved	按 agent 聚合的节省量

全为 0 表示尚无流量经过 proxy 或 MCP——容器 healthy 仅说明服务就绪，不代表已产生压缩。

2. 健康摘要：GET /health

curl http://127.0.0.1:8787/health

除 status: healthy 外，stats 块通常含 total_requests、tokens_saved、savings_percent 的简要汇总。

3. 历史趋势：GET /stats-history

curl http://127.0.0.1:8787/stats-history
curl "http://127.0.0.1:8787/stats-history?format=csv&series=weekly"

按小时 / 日 / 周 / 月 rollup，数据持久化在容器内 ~/.headroom/proxy_savings.json（可通过 volume 挂载持久化）。若镜像启用 dashboard，浏览器访问 http://127.0.0.1:8787/dashboard 查看图表。

4. Prometheus 指标：GET /metrics

curl http://127.0.0.1:8787/metrics

示例指标：headroom_tokens_saved_total、headroom_requests_total、headroom_compression_ratio_bucket。适合接入 Grafana 等监控系统。

5. Agent 内：headroom_stats MCP

在 Agent 对话中调用 headroom_stats，或在 MCP 管理面板确认 headroom 已连接后直接询问。返回 compressions、tokens_saved、recent_events（最近 10 条压缩/取回记录）。

6. 容器日志

docker logs -f headroom

启动时打印路由表（/v1/messages、/v1/chat/completions、/mcp 等）。请求经 proxy 时若日志级别为 INFO 可见处理记录；排错可添加环境变量 HEADROOM_LOG_LEVEL=DEBUG 重建容器。

自检清单

# 容器与 proxy 是否就绪
docker ps --filter name=headroom
curl -s http://127.0.0.1:8787/health

# MCP 是否在线（Cursor 侧）
docker exec headroom headroom mcp status

# 路径 C 手动压测
curl -s -X POST http://127.0.0.1:8787/v1/compress \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"assistant","content":"重复日志..."}],"model":"gpt-4o"}'

# 查看累计统计
curl -s http://127.0.0.1:8787/stats

/v1/compress 响应中 tokens_saved > 0 即压缩生效。Cursor MCP 使用后 summary.mcp.compressions 递增；Cursor Override proxy 生效后 summary.api_requests 递增。

接入其它客户端

Claude Code、Codex、Aider 等 CLI 见 Proxy → Agent wrapping：

headroom wrap claude    # 或 codex / aider
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude
OPENAI_BASE_URL=http://127.0.0.1:8787/v1 your-app

自定义上游（非官方 API）时，确保 proxy 启动时设置了 OPENAI_TARGET_API_URL，否则默认转发到 api.openai.com。

Cursor 桌面版见上文 路径 B → headroom wrap cursor。

日常运维

docker ps --filter name=headroom
docker logs -f headroom
docker restart headroom
curl http://127.0.0.1:8787/stats
curl http://127.0.0.1:8787/stats-history

若 docker 报 daemon 未连接，需先启动 Docker。

常驻部署

Headroom proxy 通过 Docker Compose 管理（restart: unless-stopped），与 OmniRoute 同文件部署。详见 Headroom 使用。

压缩效果参考

内容类型	典型节省
JSON 数组	70–90%
构建/测试日志	80–95%
搜索结果	60–80%
源代码	40–70%

详见 How Compression Works。

卸载

docker rm -f headroom
docker rmi ghcr.io/chopratejas/headroom:latest   # 可选：删除镜像

从 ~/.cursor/mcp.json 移除 headroom 条目并重启 Cursor。

延伸阅读

Headroom Proxy ServerAgent wrapping、/v1/compress、/stats 与 headroom wrap cursor

Headroom MCP Toolscompress / retrieve / stats 与 Streamable HTTP

Headroom QuickstartSDK compress() 与 proxy 零改代码两种模式

上一篇：上下文注入：Rules、Skills 与 PluginsAgent 外部知识注入：分层架构、加载顺序与 Token 预算