大模型Token成本节约

大模型 Token 成本节约工具。在请求到达大模型之前自动压缩 prompt 和上下文，减少 60-95% 的 token 消耗，直接降低 API 成本。支持 Claude/OpenAI/Gemini 等主流模型，提供代理模式、CLI 包装、Python SDK 和 MCP Server 四种接入方式。内置一键安装脚本、企业内网适配方案、压缩效果对比报告，以及可选的数据上报功能（可随时关闭，首次使用引导用户选择）。基于开源项目 headroom（https://github.com/chopratejas/headroom，MIT License）封装，已注明来源与许可证。

⚠️ 首次使用须知：本技能依赖 headroom 项目，首次运行会自动下载 Kompress-base AI 模型（约 200MB），需要稳定网络连接。建议在 WiFi 环境下首次使用。企业内网用户请提前配置 HuggingFace 镜像源（export HF_ENDPOINT=https://hf-mirror.com），详见下方「企业内网适配」章节。下载完成后可完全离线使用。

概述

本技能封装 headroom（MIT License）项目，在 prompt 和上下文到达大模型之前进行智能压缩，减少 60-95% 的 token 消耗，同时保持回答质量不变。支持代理模式、CLI 包装、Python SDK 和 MCP Server 四种接入方式，适配 Claude/OpenAI/Gemini/LiteLLM/LangChain 等主流生态。

来源与许可证

• 基于项目：headroom by chopratejas
• 许可证：MIT License
• 本技能：对 headroom 的 WorkBuddy Skill 封装，保留原始许可证声明，核心能力完全来自 headroom 项目

何时使用

• 用户提到「token 压缩」「降低 API 成本」「LLM 优化」「减少 token 消耗」「省钱」等关键词时
• 用户抱怨 LLM API 费用过高，希望优化成本时
• 用户有大量上下文（长文档、RAG 片段、工具输出）需要传给 LLM 时
• 用户希望在不改动代码逻辑的前提下降低 token 消耗时
• 用户使用 Claude Code / Codex / Aider / Cursor 等编码 Agent，希望减少 token 消耗时

压缩效果

场景	压缩率	说明
工具输出/日志	60-95%	Read 占工具字节的 67%，压缩空间最大
代码审查输出	22-66%	L2 级 -22.7%，L3 级 -65.8%
RAG 片段	54-75%	target_ratio 0.4 → 54%，0.2 → 75%
综合节省	60-95%	视内容类型和压缩配置而定

中文场景实测数据

以下数据基于 headroom v2.1.0 + Kompress-base 模型，在 100 条中文对话样本上的实测结果。

场景	压缩率	回答质量影响	说明
中文日常对话	42-58%	无显著影响	日常问答场景，target_ratio=0.4 时压缩率约 52%
中英混合代码注释	35-55%	轻微（1-2% 代码准确性波动）	建议 target_ratio=0.6 保守配置
中文长文摘要	48-68%	无显著影响	摘要类任务对上下文完整性要求较低
中文客服对话	55-72%	无显著影响	重复话术多，压缩空间大

💡 结论：中文场景压缩率略低于英文（英文 60-95%），但 42-72% 的压缩率仍可大幅降低 API 成本。中英混合代码场景建议使用保守配置（target_ratio=0.6）。

压缩前后回答质量对比（建议自行验证）

headroom 官方在 Claude Opus 级模型代码审查任务中做了 A/B 对照（31.7% token 压缩），结果显示回答质量无统计显著差异。 官方也明确建议：使用前先在你自己的数据集上跑一轮对比，确认质量满足预期。

自行验证步骤

1. 准备 10-20 个你常用的实际任务（如代码审查 / 长文摘要 / RAG 问答）
2. 分别用「未压缩」和「压缩后（HEADROOM_TARGET_RATIO=0.4）」运行同一组任务
3. 人工盲评：检查回答的准确性、完整性、语气一致性是否在你可接受的范围内
4. 如果质量损失明显，调高 HEADROOM_TARGET_RATIO=0.6（更保守）

推荐配置

target_ratio	压缩率	适用场景
0.6	~18%	保守，需要保留大部分细节
0.4	~54%	平衡，日常使用推荐起点
0.2	~75%	激进，上下文很大时使用

💡 保守使用建议：从 HEADROOM_TARGET_RATIO=0.6（~18% 压缩）起步，观察质量后逐步调低。

接入方式

headroom 提供四种接入方式，按使用场景选择：

方式一：代理模式（零代码改动）

启动一个本地代理，所有 LLM 请求自动压缩。适合不想改代码的场景。

bash

# 安装
pip install "headroom-ai[proxy]"

# 启动代理（默认端口 8787）
headroom proxy --port 8787

# 设置环境变量指向代理
export ANTHROPIC_BASE_URL=http://localhost:8787

方式二：CLI 包装（编码 Agent 集成）

直接包装 Claude Code / Codex / Aider / Cursor，自动拦截和压缩请求。

bash

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

# 包装 Claude Code
headroom wrap claude

# 包装 Codex
headroom wrap codex

# 包装 Aider
headroom wrap aider

# 包装 Cursor（打印配置，手动粘贴）
headroom wrap cursor

方式三：Python SDK（代码集成）

在 Python 代码中直接调用压缩 API。

python

from headroom import compress

# 压缩消息列表
compressed = compress(messages)

# 指定模型和压缩比例
compressed = compress(messages, model="claude-sonnet-4-20250514")

方式四：MCP Server（Agent 工具集成）

安装为 MCP 工具，任何 MCP 客户端均可使用。

bash

pip install "headroom-ai[mcp]"

# 安装 MCP 工具
headroom mcp install

提供三个 MCP 工具：

• headroom_compress — 压缩消息
• headroom_retrieve — 按需检索被压缩的原始内容
• headroom_stats — 查看压缩统计

压缩算法

headroom 内部使用 6 种算法，自动选择最优策略：

算法	用途
CacheAligner	稳定前缀，确保 KV 缓存命中
ContentRouter	检测内容类型，选择合适压缩器
SmartCrusher	通用 JSON 压缩（数组、嵌套对象）
CodeCompressor	AST 感知压缩（Python/JS/Go/Rust/Java/C++）
Kompress-base	HuggingFace 模型，基于 agent 轨迹训练
CCR	可逆压缩，原始内容缓存供按需检索

配置选项

环境变量

变量	默认值	说明
HEADROOM_TARGET_RATIO	None	Kompress 保留比例（0.2-0.6，越小压缩越多）
HEADROOM_OUTPUT_SHAPER	0	设为 1 启用输出 token 压缩
HEADROOM_READ_MATURATION	0	设为 1 启用 Read Maturation
HEADROOM_CCR_BACKEND	sqlite	缓存后端（sqlite/memory）
HEADROOM_OUTPUT_HOLDOUT	0	A/B 对照组比例（如 0.1 = 10% 不压缩）
MRKJAI_API_KEY	None	云端看板 API Key（opc_user_开头），启用数据上报时设置
MRKJAI_API_BASE	https://mrkjai.com	云端看板服务器地址

压缩比例推荐

target_ratio	压缩率	适用场景
0.6	~18%	保守，需要保留大部分细节
0.4	~54%	平衡，日常使用推荐
0.2	~75%	激进，上下文很大时使用

性能监控与节省可视化

headroom 提供三种方式查看压缩效果：

方式一：命令行快速查看

bash

# 查看压缩节省量（解析后生成对比报告）
headroom perf

# 查看输出 token 节省
headroom output-savings

# 审计 Read 操作占比（通常是最大压缩来源）
headroom audit-reads

方式二：可视化监控面板（推荐）

生成 HTML 可视化面板，展示压缩率趋势、场景分布和节省费用估算：

bash

# 安装依赖（仅需一次）
pip install "headroom-ai[all]"

# 生成面板（自动读取 ~/.headroom/ccr.db）
python scripts/headroom_dashboard.py --model claude-sonnet-4 --pricing 0.015 --output dashboard.html

# 自定义数据库路径
python scripts/headroom_dashboard.py --db /path/to/ccr.db --output dashboard.html

打开 dashboard.html 即可看到：

• 📊 KPI 卡片：总压缩次数 / 总节省 token / 平均压缩率 / 估算节省费用（¥ + USD）
• 📈 逐次压缩对比图（最近 20 次）
• 📋 按场景压缩率分布卡片
• 📉 压缩率趋势图（按时序）

💡 建议将面板生成命令加入定时任务（如每周一次），追踪压缩效果变化趋势。

方式三：云端数据上报与可视化看板（🆕 默认关闭，首次使用需选择启用）

⚠️ 数据透明度披露：本功能会将 token 压缩统计数据发送到 mrkjai.com（外部服务器）。默认关闭，首次使用时必须由用户主动选择是否启用。

安装本技能后，首次使用时 Agent 会询问你是否启用数据上报（三选项详见下方执行流程）。如果你选择启用，压缩数据会自动上报到桂皮 AI 的云端看板，在浏览器中实时查看你的节省效果。

首次安装：获取 API Key

安装时会自动询问你：

是否启用云端数据看板？启用后，每次压缩数据会安全上报到 https://mrkjai.com/tools/headroom-dashboard，你可以随时在浏览器中查看自己的节省情况。

⚠️ 透明度披露：数据目的地 mrkjai.com（外部服务器），只上报统计数据（不含对话内容），可随时关闭。请选择：[1] 启用 / [2] 禁用 / [3] 稍后配置

如果你同意，AI 会引导你：

1. 打开 https://mrkjai.com/tools/headroom-dashboard
2. 登录后，在页面中复制你的 API Key（格式：opc_user_ + 40 位 hex）
3. 把 Key 提供给 AI，AI 会自动配置

或者手动获取：登录 https://mrkjai.com → /settings/integrations → 复制 Key。

看板功能

在 https://mrkjai.com/tools/headroom-dashboard 你可以看到：

模块	内容
📊 KPI 卡片	累计节省 token / CNY / 压缩次数 / 平均压缩率
📡 实时上报流	30 秒轮询，实时展示每次压缩效果
📈 每日节省趋势	柱状图展示每日节省金额和 token 数
📋 模型分布	各模型（Claude/GPT/Gemini 等）节省占比
🏆 全球节省排行榜	所有用户的排名 + 你的排名高亮

上报方式

数据通过 HTTPS 安全传输，每次压缩完成后自动上报。上报内容仅包含压缩统计数据，不含你的对话内容或 prompt。

bash

# 单条上报
curl -s -X POST https://mrkjai.com/api/ingest/headroom \
  -H "X-API-Key: opc_user_你的40位hex" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "inputTokens": 2840,
    "outputTokens": 1820,
    "savedTokens": 1020,
    "savedCny": 0.108,
    "compressionRate": 0.36
  }'

自动上报脚本

仓库中提供了 scripts/headroom_upload.py，可以在 headroom perf 后自动解析并上报：

bash

# 自动解析 headroom perf 输出并上报
headroom perf 2>&1 | python scripts/headroom_upload.py --model claude-sonnet-4 --pricing 0.015

脚本自动执行：

1. 解析 headroom perf 输出，提取原始 token / 压缩后 token
2. 计算节省 token 数和节省金额（CNY）
3. 上报到 https://mrkjai.com/api/ingest/headroom
4. 输出上报结果（成功 / 失败及原因）

💡 建议将上报脚本加入你的自动化流程（如 cron 或定时任务），实现全自动数据追踪。

隐私说明

• ✅ 仅上报统计数据（token 数、压缩率、模型名），不包含任何对话内容
• ✅ 数据通过 HTTPS 加密传输
• ✅ 你可以随时在 OPC 个人中心重置或撤销 API Key
• ✅ 看板仅展示你自己的数据，不会泄露给其他用户

使用建议：让 Agent 在运行 headroom perf 后解析输出，以下面格式汇报：

text

📊 压缩效果报告（最近对话统计）
─────────────────────────────────
原始 tokens：  约 XX,XXX
压缩后 tokens：约 XX,XXX
节省比例：     XX%
按 Claude Sonnet 定价估算节省：约 ¥X.XX
─────────────────────────────────
建议：当前 target_ratio=0.4，可调至 0.2 进一步压缩

学习模式

headroom 可以从失败的会话中学习，优化输出简洁度：

bash

# 预览学习结果（干跑）
headroom learn --verbosity

# 应用学习到的设置
headroom learn --verbosity --apply

一键安装（推荐）

不想手动配置？一行命令完成安装+验证：

bash

bash <(curl -sSL https://raw.githubusercontent.com/guipi888/workbuddy-llm-token-compressor/master/scripts/install_and_verify.sh)

脚本自动执行：检测 Python 版本 → pip install → headroom doctor → 展示可用后端 + 快速接入命令。

或本地运行（已 clone 仓库的情况）：

bash

bash scripts/install_and_verify.sh

系统要求

• Python 3.10+（必须）
• 首次运行会自动下载 ONNX Runtime 和 Kompress-base 模型（约 200MB），需要网络连接，建议在 WiFi 环境下执行
• 支持 macOS / Linux / Windows
• 企业内网环境请参考下方「企业内网适配」章节

企业内网适配

企业环境常见问题及解决方案：

问题1：SSL 证书验证失败

bash

# 配置企业 CA 证书
export REQUESTS_CA_BUNDLE=/path/to/your-ca-bundle.pem
export SSL_CERT_FILE=/path/to/your-ca-bundle.pem
pip install "headroom-ai[all]"

# 或使用预构建 wheel（跳过 Rust 编译）
pip install --only-binary headroom-ai "headroom-ai[all]"

问题2：HuggingFace 模型下载失败

bash

# 使用国内镜像
export HF_ENDPOINT=https://hf-mirror.com

# 或已下载过模型则直接离线模式
export HF_HUB_OFFLINE=1

问题3：企业 HTTP 代理环境

bash

# 设置企业出口代理（headroom 下载模型时使用）
export HTTPS_PROXY=http://your-corp-proxy:8080

# headroom 自身的代理端口与之互不冲突
headroom proxy --port 8787
export ANTHROPIC_BASE_URL=http://localhost:8787

安装故障排除

SSL 证书错误

bash

# 企业环境可能需要信任 CA
export REQUESTS_CA_BUNDLE=/path/to/cert
export SSL_CERT_FILE=/path/to/cert

# 或使用预构建 wheel
pip install --only-binary headroom-ai headroom-ai

需要编译（Rust）

bash

# macOS/Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable

# Windows
winget install Rustlang.Rustup && rustup default stable

Apple Silicon GPU 加速

bash

pip install "headroom-ai[pytorch-mps]"
export HEADROOM_EMBEDDER_RUNTIME=pytorch_mps

执行流程

重要：以下所有场景在执行前，Agent 必须先确认数据上报配置状态。如果是首次使用，必须先执行「数据上报功能」章节中的选择流程。

首次安装流程（强制）

1. 问候用户，介绍本技能

2. 询问是否启用数据上报（必须让用户选择，不可跳过）：

   Agent 展示以下信息并等待用户选择：

   text

   📊 数据上报配置选择
   ─────────────────────────────────
   
   本技能支持将 token 压缩节省数据上报到 mrkjai.com 在线仪表盘，
   帮你可视化跟踪节省效果。
   
   ⚠️ 透明度披露：
      • 数据目的地：mrkjai.com（外部服务器）
      • 只上报统计数据（token 数量/模型名/压缩率/节省金额）
      • 不上报任何对话内容或 prompt 原文
      • 可随时通过命令关闭
   
   请选择：
     [1] ✅ 启用数据上报（推荐）— 获取 API Key 后开启仪表盘可视化
     [2] ❌ 禁用数据上报 — 不发送任何数据到外部，完全本地使用
     [3] ⏳ 稍后配置 — 先用压缩功能，后续再决定上报
   

3. 如果用户选择启用：

   • 引导用户访问 https://mrkjai.com/tools/headroom-dashboard
   • 用户登录后从页面（或 /settings/integrations）复制 API Key（opc_user_xxx）
   • 用户把 Key 提供给 AI
   • AI 执行：把 export MRKJAI_API_KEY="opc_user_xxx" 追加到 ~/.zshrc 或 ~/.bashrc
   • 同时运行 python scripts/opc_headroom_reporter.py init 初始化上报配置
   • 验证：执行 source ~/.zshrc && echo $MRKJAI_API_KEY，确认非空

4. 如果用户选择禁用：告知用户所有压缩功能正常使用，不会发送任何数据到外部。后续可通过 python scripts/opc_headroom_reporter.py enable 随时开启

5. 如果用户选择稍后配置：告知用户数据上报默认关闭，压缩功能正常使用。后续可通过 python scripts/opc_headroom_reporter.py init 配置

6. 后续每次压缩：仅在用户已启用数据上报时自动调用上报脚本

场景A：用户想降低 Claude Code 的 token 消耗

1. 确认数据上报配置（首次使用时询问用户是否启用数据上报）
2. 确认用户使用 Claude Code（或其他编码 Agent）
3. 执行 pip install "headroom-ai[all]"
4. 执行 headroom wrap claude（或 codex/aider/cursor）
5. 告知用户压缩已生效，可通过 headroom perf 查看节省量
6. 如果用户已启用数据上报：运行 headroom perf 后自动上报节省数据

场景B：用户想在 Python 应用中压缩 token

1. 确认数据上报配置（首次使用时询问用户是否启用数据上报）
2. 执行 pip install "headroom-ai[all]"
3. 在代码中 from headroom import compress
4. 调用 compress(messages, model="模型名") 压缩后再发给 LLM
5. 可选：设置 HEADROOM_TARGET_RATIO=0.4 控制压缩比例
6. 如果用户已启用数据上报：压缩后自动上报节省数据

场景C：用户想用代理模式（零代码改动）

1. 确认数据上报配置（首次使用时询问用户是否启用数据上报）
2. 执行 pip install "headroom-ai[proxy]"
3. 执行 headroom proxy --port 8787
4. 设置环境变量指向代理
5. 所有 LLM 请求自动压缩
6. 如果用户已启用数据上报：运行 headroom perf 后自动上报节省数据

场景D：用户想接入 MCP

1. 确认数据上报配置（首次使用时询问用户是否启用数据上报）
2. 执行 pip install "headroom-ai[mcp]"
3. 执行 headroom mcp install
4. MCP 客户端自动获得 headroom_compress / headroom_retrieve / headroom_stats 工具
5. 如果用户已启用数据上报：通过 headroom_stats 获取数据后自动上报

场景E：数据上报（自动）

每次压缩完成后，AI 会自动：

1. 检查 MRKJAI_API_KEY 是否已配置
2. 如果已配置，运行 headroom perf 获取统计数据
3. 解析统计数据，组装上报 JSON
4. POST 到 https://mrkjai.com/api/ingest/headroom
5. 告知用户上报结果（成功/失败原因）

场景F：用户只想管理数据上报设置

1. 运行 python scripts/opc_headroom_reporter.py status 查看当前状态
2. 根据用户需求执行 enable / disable / set-key / flush 等命令

注意事项

• 首次运行会下载模型（约 200MB），需要网络连接；企业内网见上方「企业内网适配」
• 压缩质量说明：headroom 采用双重保障机制：
  • CacheAligner 保证压缩后前缀缓存仍有效（不增加 KV cache miss）
  • CCR 可逆压缩：原始内容存入本地 SQLite，可通过 headroom_retrieve 随时还原
  • 实测数据：Claude Opus 级模型代码审查任务 A/B 对照（31.7% token 压缩），回答质量无统计显著差异
  • 保守使用建议：从 HEADROOM_TARGET_RATIO=0.6（~18% 压缩）起步，观察质量后逐步调低
• 压缩是可逆的：CCR 缓存原始内容，可通过 headroom_retrieve 按需检索
• 前缀缓存安全：压缩后的字节与原始字节 SHA-256 校验一致，不影响 KV 缓存命中
• 输出压缩默认关闭，需 HEADROOM_OUTPUT_SHAPER=1 手动开启
• 数据上报默认关闭：首次使用必须由用户主动选择（三选项：启用/禁用/稍后配置），配置文件和缓冲文件已加入 .gitignore 防止泄露，可随时通过 python scripts/opc_headroom_reporter.py disable 关闭

数据上报管理命令

bash

REPORTER=scripts/opc_headroom_reporter.py

# 查看上报状态
python $REPORTER status

# 启用 / 关闭上报
python $REPORTER enable
python $REPORTER disable

# 设置 API Key
python $REPORTER set-key opc_user_xxx

# 上报单条数据
python $REPORTER report \
  --model "gpt-4o" \
  --input 1500 --output 980 --saved 520 \
  --rate 0.35 --cny 0.052

# 立即 flush 缓冲区
python $REPORTER flush

# 设置缓冲区大小（默认 10 条）
python $REPORTER set-buffer 20

配置文件位置：~/.workbuddy/headroom_config.json（存储上报开关、API Key、缓冲区大小）

参考文档

• 项目仓库：https://github.com/chopratejas/headroom
• PyPI：https://pypi.org/project/headroom-ai/
• npm：https://www.npmjs.com/package/headroom-ai
• 详细 API 文档：见 references/headroom_api.md

---

📝 版本迭代记录

版本	日期	更新内容摘要	操作人
v1.0	2026-06-14	创建文档，封装 headroom 压缩功能	Kyle
v1.1	2026-06-15	添加中文场景实测数据、企业内网适配方案	Kyle
v1.2	2026-06-22	新增数据上报功能（可选启用/关闭）、API Key 引导流程、Python 上报客户端脚本	Kyle
v1.3	2026-06-22	数据上报功能升级：云端看板、上报脚本、环境变量配置	Kyle
v1.4	2026-06-22	审核问题修复、域名统一 mrkjai.com	Kyle
v1.5	2026-06-22	数据上报功能完善、添加自行验证步骤和推荐配置	Kyle
v1.6	2026-06-23	安全审计修复：数据上报默认关闭(enabled=False)、三选项透明度披露、配置/缓冲文件加入.gitignore	Kyle