【10分钟AI系列】10 分钟省下 80% Token：AI 编程代理的 Token 压缩实战指南-京东云开发者社区

> **Headroom — 让你的 Claude Code / Codex / JoyCode 每月省下数千美元 Token 费用**
>
> 社区实测数据：41.8 亿 Token 已被压缩，$176,600 费用已节省，889 个活跃实例运行中。

<span style="color: #ab4642">如果使用公司的dongcc作为代理，需要先指向headroom，再由headroom转发到dongcc</span>。dongcc配置修复脚本：[git@coding.jd.com:zhangxueli31/headroom-proxy.git](git@coding.jd.com:zhangxueli31/headroom-proxy.git)

## 一句话说清楚

**Headroom 在你的 AI 编程代理（Claude Code / Codex / JoyCode）和大模型之间加一层"压缩层"，自动压缩工具输出、日志、RAG 结果、代码文件等内容，Token 消耗降低 60-95%，回答质量不变。**

## 为什么你该关心

| 痛点 | Headroom 的解法 |
|------|----------------|
| Claude Code 每月 Token 费用上千美元 | 代理输出压缩 80%+，费用直降 |
| 大量搜索结果 / 日志 / 代码上下文浪费 Token | 智能路由：JSON 走 SmartCrusher，代码走 AST 压缩，文本走 Kompress 模型 |
| 多个 Agent 各自为战，上下文不共享 | 跨 Agent 记忆共享 + 自动去重 |
| 压缩后找不到原始内容？ | CCR 可逆压缩：原文件始终保留，LLM 按需检索 |
| 试过其他方案，配置复杂？ | 一行命令搞定：`headroom wrap claude` |

## 真实基准测试数据

| 工作场景 | 压缩前 Token | 压缩后 Token | 节省比例 |
|---------|-------------|-------------|---------|
| 代码搜索（100 条结果） | 17,765 | 1,408 | **92%** |
| SRE 故障排查 | 65,694 | 5,118 | **92%** |
| GitHub Issue 分类 | 54,174 | 14,761 | **73%** |
| 代码仓库探索 | 78,502 | 41,254 | **47%** |

**准确率不变**：GSM8K 数学 0.870→0.870、TruthfulQA 0.530→0.560（反而提升）、SQuAD v2 97% 保留。

## 60 秒快速安装

```bash
# 方式一：pip 安装（推荐，Python 3.10+）
pip install "headroom-ai[all]"

# 方式二：npm 安装（TypeScript 项目）
npm install headroom-ai

# 方式三：Docker
docker pull ghcr.io/chopratejas/headroom:latest
```

**验证安装：**

```bash
headroom --version
headroom perf          # 运行内置性能测试
```

---

## 实战一：Claude Code + Headroom（一行命令）

这是最推荐的方式。`headroom wrap` 会自动：

- 启动本地代理服务器（端口 8787）
- 设置 `ANTHROPIC_BASE_URL` 指向代理
- 启动 Claude Code，所有请求自动经过压缩

### 步骤

```bash
# 1. 安装（如果还没装）
pip install "headroom-ai[all]"

# 2. 一行命令启动
headroom wrap claude

# 3. 正常使用 Claude Code，Token 已自动压缩！
#    你可以像平时一样写代码、搜索、调试
```

### 进阶选项

```bash
# 启用跨 Agent 记忆 + 代码图谱
headroom wrap claude --memory --code-graph

# 指定端口
headroom wrap claude --port 8787

# 查看实时压缩统计
curl http://localhost:8787/stats
```

### 验证压缩生效

```bash
# 在另一个终端查看统计
curl http://localhost:8787/stats | python3 -m json.tool

# 应该看到类似输出：
# {
#   "total_requests": 15,
#   "tokens_saved": 45000,
#   "savings_percent": 72.3
# }
```

### 工作原理

```
Claude Code  ──请求──►  Headroom 代理（localhost:8787）
                            │
                            ├─ SmartCrusher：压缩 JSON 输出
                            ├─ CodeCompressor：AST 压缩代码
                            ├─ Kompress-base：压缩文本/日志
                            ├─ CacheAligner：稳定 KV 缓存前缀
                            └─ CCR：保留原文，按需检索
                            │
                            ▼
                       Anthropic API
```

---

## 实战二：OpenAI Codex + Headroom

Codex 使用 OpenAI API，Headroom 同样一行命令搞定。

### 步骤

```bash
# 1. 安装（如果还没装）
pip install "headroom-ai[all]"

# 2. 一行命令启动
headroom wrap codex

# 3. 正常使用 Codex，Token 已自动压缩！
```

### 进阶选项

```bash
# 启用跨 Agent 记忆（与 Claude Code 共享记忆）
headroom wrap codex --memory

# 手动指定方式（不使用 wrap）
OPENAI_BASE_URL=http://localhost:8787/v1 codex
```

### 跨 Agent 记忆共享

Claude Code 和 Codex 可以共享上下文记忆，避免重复探索：

```bash
# Claude Code 探索完代码库后
headroom wrap claude --memory

# Codex 接手时，自动获取 Claude 的上下文
headroom wrap codex --memory
```

---

## 实战三：京东JoyCode + Headroom（Proxy 模式）

JoyCode 是京东推出的智能编码 IDE（基于 VS Code 架构），目前 Headroom 官方尚未提供 `headroom wrap joycode` 命令，但通过 **Proxy 模式** 可以无缝对接。

### 原理

JoyCode 通过 API 调用大模型，我们可以将 API 地址指向 Headroom 代理：

```
JoyCode  ──API 请求──►  Headroom 代理（localhost:8787）
                              │
                              ├─ 自动压缩上下文
                              │
                              ▼
                         大模型 API
```

### 步骤一：启动 Headroom 代理

```bash
# 安装（如果还没装）
pip install "headroom-ai[all]"

# 启动代理服务器
headroom proxy --port 8787
```

### 步骤二：配置 JoyCode

在 JoyCode 中修改 AI 模型的 API 地址：

- **打开 JoyCode 设置**：`Cmd+,`（Mac）或 `Ctrl+,`（Windows/Linux）
- **搜索**：`API`、`endpoint`、`base url` 或 `模型地址`
- **将 API 地址改为**：`http://localhost:8787/v1`

或者通过配置文件（如果 JoyCode 支持）：

```json
{
  "joycode.ai.apiBaseUrl": "http://localhost:8787/v1"
}
```

### 步骤三：验证

```bash
# 在 JoyCode 中正常使用 AI 功能
# 另开终端查看压缩统计
curl http://localhost:8787/stats
```

### 注意事项

- JoyCode 的私有模型如果使用非标准 API 协议，可能不适用代理模式
- 配置后建议重启 JoyCode 使设置生效

---

## 实战四：Cursor + Headroom

```bash
# 方式一：wrap 命令（自动配置）
headroom wrap cursor

# 方式二：手动配置
# 打开 Cursor Settings → 搜索 "OpenAI Base URL"
# 设置为：http://localhost:8787/v1
```

## MCP 模式：给任何 MCP 客户端装压缩工具

如果你的 Agent 支持 MCP（Model Context Protocol），可以直接安装 Headroom 的 MCP 工具：

```bash
# 安装 MCP 工具
headroom mcp install

# 这会注册三个工具：
# - headroom_compress：压缩上下文
# - headroom_retrieve：检索原始内容（CCR）
# - headroom_stats：查看压缩统计
```

## 常用命令速查

```bash
# 安装
pip install "headroom-ai[all]"

# 启动代理
headroom proxy --port 8787

# 包装各种 Agent
headroom wrap claude              # Claude Code
headroom wrap codex               # OpenAI Codex
headroom wrap cursor              # Cursor
headroom wrap aider               # Aider
headroom wrap copilot             # GitHub Copilot CLI

# 查看统计
headroom perf                     # 运行基准测试
curl http://localhost:8787/stats  # 实时统计
curl http://localhost:8787/health # 健康检查

# MCP 工具
headroom mcp install              # 安装 MCP 工具

# 失败学习（自动生成改进建议）
headroom learn                    # 分析失败 session，写入 CLAUDE.md

# 配置
headroom config                   # 查看/修改配置
```

## FAQ

**Q: 压缩会影响代码生成质量吗？**

不会。基准测试显示 GSM8K 数学准确率不变（0.870），TruthfulQA 反而提升（+0.030），SQuAD v2 保留 97%。Headroom 压缩的是冗余上下文（重复日志、大型 JSON、搜索结果），不是核心语义。

**Q: 原始数据会丢失吗？**

不会。CCR（可逆压缩）机制保留所有原始内容在本地，LLM 需要时可通过 `headroom_retrieve` 工具检索回来。

**Q: 数据会发到云端吗？**

不会。Headroom 完全本地运行，数据不离开你的机器。唯一上报的是匿名统计（Token 数量、压缩比），可通过 `HEADROOM_TELEMETRY=off` 关闭。

**Q: 支持哪些模型提供商？**

Anthropic、OpenAI、AWS Bedrock、Azure、GCP Vertex 等所有主流提供商。

**Q: JoyCode 使用非标准 API 协议的模型能用吗？**

取决于模型的 API 协议。如果使用 OpenAI 兼容协议或 Anthropic 协议调用模型，Headroom 可以拦截并压缩。如果使用私有协议，需要额外适配。

**Q: 多个 Agent 可以同时用吗？**

可以。Headroom 代理支持并发，Claude Code、Codex、JoyCode 可以同时连接同一个代理实例，共享跨 Agent 记忆。

## 进阶：作为代码库集成

**Python**

```python
from headroom import compress

messages = [{"role": "user", "content": "分析这段代码..."}]
result = compress(messages, model="gpt-4o")
# result.messages 是压缩后的消息
# result.stats 包含压缩统计
```

**TypeScript**

```typescript
import { compress } from 'headroom-ai';

const result = await compress(messages, {
  model: 'gpt-4o',
  baseUrl: 'http://localhost:8787'
});
```

**SDK 包装**

```python
# Anthropic SDK
from headroom.integrations.anthropic import withHeadroom
client = withHeadroom(Anthropic())

# OpenAI SDK
from headroom.integrations.openai import withHeadroom
client = withHeadroom(OpenAI())
```

## 更多资源

- 📖 官方文档：https://headroom-docs.vercel.app/docs
- 💻 GitHub 仓库：https://github.com/chopratejas/headroom
- 💬 Discord 社区：https://discord.gg/yRmaUNpsPJ
- 🤗 Kompress 模型：https://huggingface.co/chopratejas/kompress-base
- 📊 社区节省数据：https://headroom-docs.vercel.app/docs/community-savings

> 本文档适用于 Headroom v0.22.x。如有更新请参考官方文档。

---

## 附录：一键安装脚本

以下脚本自动完成环境检查、安装、代理启动和验证全流程。保存为 `install-headroom.sh` 后执行即可。

```bash
#!/usr/bin/env bash
set -euo pipefail

# ============================================
# Headroom 一键安装脚本
# 自动完成：环境检查 → 安装 → 启动代理 → 验证
# ============================================

GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m'

info()  { printf "${GREEN}✅ %s${NC}\n" "$*"; }
warn()  { printf "${YELLOW}⚠️  %s${NC}\n" "$*"; }
error() { printf "${RED}❌ %s${NC}\n" "$*"; exit 1; }

PORT="${HEADROOM_PORT:-8787}"

echo "=========================================="
echo "  Headroom 一键安装脚本"
echo "=========================================="
echo ""

# ---- 1. 检查 Python 版本 ----
echo "📦 Step 1/5: 检查 Python 环境..."
if ! command -v python3 &>/dev/null; then
  error "未找到 python3，请先安装 Python 3.10+"
fi

PY_VERSION=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
PY_MAJOR=$(echo "$PY_VERSION" | cut -d. -f1)
PY_MINOR=$(echo "$PY_VERSION" | cut -d. -f2)

if [[ "$PY_MAJOR" -lt 3 ]] || [[ "$PY_MAJOR" -eq 3 && "$PY_MINOR" -lt 10 ]]; then
  error "Python 版本 $PY_VERSION 过低，需要 3.10+"
fi
info "Python $PY_VERSION"

# ---- 2. 安装 headroom-ai ----
echo ""
echo "📥 Step 2/5: 安装 headroom-ai..."
if command -v headroom &>/dev/null; then
  CURRENT_VER=$(headroom --version 2>/dev/null || echo "unknown")
  warn "headroom 已安装（$CURRENT_VER），跳过安装"
else
  pip install "headroom-ai[all]" --quiet
  info "headroom-ai 安装完成"
fi

# ---- 3. 启动代理服务器 ----
echo ""
echo "🚀 Step 3/5: 启动 Headroom 代理（端口 $PORT）..."

# 检查端口是否已被占用
if lsof -i :"$PORT" &>/dev/null; then
  warn "端口 $PORT 已被占用，尝试停止已有进程..."
  pkill -f "headroom.*proxy.*$PORT" 2>/dev/null || true
  sleep 2
fi

nohup headroom proxy --port "$PORT" > /tmp/headroom-proxy.log 2>&1 &
PROXY_PID=$!

# 等待代理就绪
echo "   等待代理启动..."
for i in $(seq 1 30); do
  if curl --fail --silent "http://localhost:$PORT/health" >/dev/null 2>&1; then
    info "代理已启动（PID: $PROXY_PID, 端口: $PORT）"
    break
  fi
  if [[ $i -eq 30 ]]; then
    error "代理启动超时，请检查 /tmp/headroom-proxy.log"
  fi
  sleep 1
done

# ---- 4. 运行健康检查 ----
echo ""
echo "🔍 Step 4/5: 运行健康检查..."
HEALTH=$(curl --silent "http://localhost:$PORT/health" 2>/dev/null || echo "{}")
if echo "$HEALTH" | python3 -c "import sys,json; d=json.load(sys.stdin); assert d.get('status')=='ok'" 2>/dev/null; then
  info "健康检查通过"
else
  warn "健康检查返回非预期结果，代理可能仍在初始化"
fi

# ---- 5. 打印配置指引 ----
echo ""
echo "📋 Step 5/5: Agent 配置指引"
echo "=========================================="
echo ""
echo "  Claude Code:"
echo "    headroom wrap claude"
echo ""
echo "  OpenAI Codex:"
echo "    headroom wrap codex"
echo ""
echo "  Cursor:"
echo "    headroom wrap cursor"
echo ""
echo "  其他 IDE（JoyCode / Windsurf / Continue 等）:"
echo "    手动将 API 地址设为 http://localhost:$PORT/v1"
echo ""
echo "  MCP 工具:"
echo "    headroom mcp install"
echo ""
echo "  查看压缩统计:"
echo "    curl http://localhost:$PORT/stats"
echo ""
echo "=========================================="
info "安装完成！Token 压缩已就绪。"
echo ""
echo "  停止代理: kill $PROXY_PID"
echo "  查看日志: tail -f /tmp/headroom-proxy.log"
echo ""
```

**使用方式：**

```bash
chmod +x install-headroom.sh
./install-headroom.sh
```

脚本会自动：

1. ✅ 检查 Python 版本（≥3.10）
2. ✅ 安装 headroom-ai（含所有依赖）
3. ✅ 启动代理服务器
4. ✅ 运行健康检查
5. ✅ 打印各 Agent 的配置指引