Token 优化指南

pip install "headroom-ai[all]"    # Python 3.10+，推荐
# 或 npm install headroom-ai

headroom perf                     # 查看节省
headroom dashboard                # 代理运行时开面板

企业网络 SSL 拦截见 Corporate / SSL 章节。

headroom mcp install
# 工具：headroom_compress / headroom_retrieve / headroom_stats

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

输出塑形：减少模型寒暄与 routine 步骤上的深度 thinking（代理侧，无需改业务代码）。

• LeanCTX — 门控注入源（哪些进上下文）
• Headroom / RTK — 压缩已进入上下文的内容
• Tokscale — 观测三者叠加后的真实用量

三省接入：作为 Agent 中间件或上下文层，与 Cursor Rules / Claude Code / Codex 的 MCP 工具链并列部署；详见仓库 README 与 examples/。

所有 Agent 统一走 Headroom 代理 1–2 周后再调参，不要上来就拉满压缩。

# 代理运行中或 wrap 会话结束后
headroom perf              # 汇总节省与近期趋势
headroom stats             # 更细的统计（亦可 MCP：headroom_stats）
headroom output-savings    # 输出侧节省（含置信区间）
headroom dashboard         # 可视化面板（需 proxy 在跑）

重点盯 3 个指标（可用 Tokscale 交叉验证账单）：

• 单任务平均 Token 成本
• 任务首次成功率（无需返工的比例）
• 返工率（修偏方向、重跑测试/检索的次数）

• CI/CD / Agent 巡检：流水线默认高压缩（日志/测试输出为主）
• 人工核心开发：临时 bypass 或关 OUTPUT_SHAPER
• Mac 加速：export HEADROOM_EMBEDDER_RUNTIME=pytorch_mps，压缩嵌入几乎不拖慢代理
• 敏感路径：项目 .contextignore / 全局 ~/.claude/.contextignore 硬排除审计文件

按此跑 2–4 周，编码账单常见降 40–60%，且返工率不应明显上升。若某栈（Go 微服务调试、Java 大仓重构）要更细参数，以 headroom perf + holdout 实测为准，再微调。

1. 安装 RTK（见 官方安装，Rust 单二进制）。
2. 初始化 Cursor hook：

rtk init -g --agent cursor

重启 Cursor。Hook 通过 preToolUse 自动把 git status 改写为 rtk git status。

局限：内置 Read/Grep 工具不走 shell hook；大文件请用 rtk read / rtk grep 或 shell 等价命令。

# macOS / Linux / WSL / Git Bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex

安装器会写入 Cursor Rules，实现会话级简洁输出。手动触发：/caveman；压规约：/caveman-compress CLAUDE.md（对 .cursor/rules 同理）。

npx tokscale@latest
# 或 npm i -g tokscale

Cursor 需从浏览器导出会话 Cookie 后登录（非解析 ~/.cursor 本地库）：

tokscale cursor login
tokscale cursor sync

在 cursor.com 开发者工具 → Cookies 复制 WorkosCursorSessionToken。详见 Tokscale Cursor 文档。

项目级：.cursor/mcp.json · 全局：~/.cursor/mcp.json（版本不同可能为 Settings → MCP）。浏览器与 mcprune 示例见下文 MCP 章节。

rtk init -g
# 重启 Claude Code

自动安装 PreToolUse hook，Bash 命令透明改写。与 Cursor 相同：Read/Grep/Glob 内置工具不经过 hook。

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

支持 hook 自动激活；/caveman-stats 看本会话节省量；/caveman-compress 压缩 CLAUDE.md / 项目记忆文件。

alexgreensh/token-optimizer（专题高星）— 上下文工程插件：智能压缩、Dashboard、MCP/技能瘦身等。

/plugin marketplace add alexgreensh/token-optimizer
/plugin install token-optimizer@alexgreensh-token-optimizer
# 会话内：/token-optimizer

安装后建议在 /plugin 中对该 Marketplace 开启 auto-update。

编辑 ~/.claude.json 或项目 .mcp.json 的 mcpServers。mcprune / caveman-shrink 配置见 #mcp。

rtk init -g --codex          # 项目级 AGENTS.md
rtk init -g --global --codex # 用户级 ~/.codex/AGENTS.md

依赖模型遵循 AGENTS.md 中的 RTK 指令（规则级集成，非 guaranteed hook）。

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --only codex

或全量安装后写入 AGENTS.md。用 codex-tokens-compress 生成高密度 AGENTS.md 规则段。

squeez — Rust 零依赖，支持 Claude Code / Codex CLI / Copilot CLI 等，Bash 最高约 95% 压缩 + MCP。

# 见仓库 README 按宿主安装 hook；Codex 侧重 ~/.codex/AGENTS.md 软约束 + bash 管道

同 token-optimizer 的 Codex 原生插件，TUI 内 /plugins 安装。Dashboard 默认 http://localhost:24843/token-optimizer。

1. 克隆并安装：

git clone https://github.com/hamr0/mcprune.git
cd mcprune && npm install && npx playwright install chromium

写入 MCP 配置（路径换成你的绝对路径）：

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/path/to/mcprune/mcp-server.js", "--mode", "auto"]
    }
  }
}

可选 --headless；模式 act（操作）/ browse（读文档）/ auto。

{
  "mcpServers": {
    "fs-compact": {
      "command": "npx",
      "args": [
        "caveman-shrink",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/your/project"
      ]
    }
  }
}

将任意上游 MCP 包一层；压缩 description 等 prose 字段，工具语义不变。

• 默认无障碍树，禁止为读文字先截图（画布/验证码除外）
• 每任务 ≤1 次全量 browser_snapshot，之后用 ref 点击
• 电商/表单用 mcprune act；文档站用 browse
• 单步页面感知预算建议 ≤ 6000 tokens
• 能 API / fetch 就不开浏览器