token-optimizer

Token Optimizer

测量设置将上下文窗口用在何处，提出改进建议，应用用户批准的改动，然后重新测量。最终交付物是用户可以验证的优化前后对比，且每项改动都有备份。通过清理配置，通常可以释放窗口容量的 5-15%；如果压缩和缓存设置不适合用户的工作方式，释放的容量会更多。

Token Optimizer 自身的技能（token-optimizer、token-coach、token-dashboard、fleet-auditor、resume-checkpoint）就是测量层，因此无论它们运行得多么少，都不要将其列入任何未使用技能、归档或合并建议。

步骤 0：为此运行时选择正确的工作流

以下审计会读取并编辑 ~/.claude，除 Claude Code 以外的任何环境都不应以此为目标，因此在操作任何路径之前，先确定运行时。严格按以下顺序执行。

a. 环境检查（不会触碰任何文件；显式设置的 TOKEN_OPTIMIZER_RUNTIME 优先，并且会先检查 Claude 插件变量，再检查其他 OPENCODE_* 导出变量，顺序与 detect_runtime() 使用的顺序相同）：

if [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "claude" ] || [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "codex" ]; then
  :
elif [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "opencode" ]; then
  echo "Token Optimizer — OpenCode runtime detected."
elif [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "copilot" ]; then
  echo "Token Optimizer — GitHub Copilot runtime detected."
elif [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "cursor" ]; then
  echo "Token Optimizer — Cursor runtime detected."
elif [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "antigravity" ]; then
  echo "Token Optimizer — Google Antigravity runtime detected."
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}${CLAUDE_PLUGIN_DATA:-}" ]; then
  :
elif [ -n "${OPENCODE_BIN:-}${OPENCODE_CONFIG_DIR:-}${OPENCODE_DATA_DIR:-}${OPENCODE_CONFIG:-}${OPENCODE_CLIENT:-}" ]; then
  echo "Token Optimizer — OpenCode runtime detected."
elif [ -n "${COPILOT_HOME:-}${TOKEN_OPTIMIZER_COPILOT_HOME:-}" ]; then
  echo "Token Optimizer — GitHub Copilot runtime detected."
elif [ -n "${TOKEN_OPTIMIZER_CURSOR_HOME:-}" ]; then
  echo "Token Optimizer — Cursor runtime detected."
elif [ -n "${CURSOR_PROJECT_DIR:-}" ] && [ -n "${CURSOR_VERSION:-}" ]; then
  echo "Token Optimizer — Cursor runtime detected."
elif [ -n "${TOKEN_OPTIMIZER_ANTIGRAVITY_HOME:-}" ]; then
  echo "Token Optimizer — Google Antigravity runtime detected."
fi

输出内容	操作
"OpenCode runtime detected."	停止。遵循 references/opencode-workflow.md（Token Optimizer 在此作为原生插件运行）。
"Cursor runtime detected."	停止。遵循 references/cursor-workflow.md（它通过 Cursor hook 桥接运行）。
"GitHub Copilot runtime detected."	停止。遵循 docs/copilot.md 中的 Copilot 指引。
"Google Antigravity runtime detected."	停止。遵循 docs/antigravity.md。
无输出	继续执行 b。

b. 仅解析一次 $MEASURE_PY。 后续所有命令都使用它：

# Resolve measure.py to the NEWEST installed copy across channels so a stale
# plugin-cache copy never shadows a fresh install. find -L follows the
# install.sh symlink under ~/.claude/skills; cd -P resolves it before reading each
# copy's plugin.json for its version. find (not bare globs) never errors under zsh.
MEASURE_PY=""; _best_ver=""
while IFS= read -r _cand; do
  [ -f "$_cand" ] || continue
  _root="$(cd -P -- "$(dirname -- "$_cand")/../../.." 2>/dev/null && pwd)"
  _ver="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$_root/.claude-plugin/plugin.json" 2>/dev/null | head -1)"
  [ -n "$_ver" ] || _ver="0.0.0"
  if [ -z "$_best_ver" ] || [ "$(printf '%s\n%s\n' "$_ver" "$_best_ver" | sort -t. -k1,1n -k2,2n -k3,3n -k4,4n | tail -n1)" = "$_ver" ]; then
    _best_ver="$_ver"; MEASURE_PY="$_cand"
  fi
done <<EOF
$(find -L "$HOME/.claude/skills" "$HOME/.claude/plugins/cache" "$HOME/.claude/token-optimizer" "$HOME/.codex/skills" "$HOME/.codex/plugins/cache" "$HOME/.config/opencode/plugins" -type f -name measure.py -path '*token-optimizer*/scripts/measure.py' 2>/dev/null)
EOF
if [ -z "$MEASURE_PY" ]; then echo "[Error] measure.py not found. Is Token Optimizer installed?"; exit 1; fi

c. 权威检查关卡。 环境检查无法识别未设置相关变量就启动的 OpenCode；此步骤会扫描进程树：

python3 "$MEASURE_PY" report 2>&1 | head -1

任何包含 "... runtime detected." 的输出行都表示应停止，并遵循上表中该运行时对应的文件。对于 Codex（TOKEN_OPTIMIZER_RUNTIME=codex 或 Codex 环境），遵循 references/codex-workflow.md。Claude Code 则继续执行下文。

审计（Claude Code）

按顺序完成这些阶段，并逐项勾选；跳过的阶段应保留在列表中，并标注为 skip: <reason>。

- [ ] 0. Setup            references/phase0-setup.md
- [ ] 1. Parallel audit   references/agent-prompts.md
- [ ] 2. Synthesis        references/agent-prompts.md (Synthesis Agent)
- [ ] 3. Present, then wait for the user's decision   references/presentation-workflow.md
- [ ] 4. Implement the approved changes               references/implementation-playbook.md
- [ ] 5. Verify and report before/after               references/agent-prompts.md (Verification Agent)

0. 设置。 检测上下文窗口、预检查、备份、协调文件夹（COORD_PATH）、钩子检查、守护进程、智能压缩。然后，仅当 python3 "$MEASURE_PY" keepwarm-consent-status 返回 should_ask: true 时，才严格按照 references/keepwarm-consent.md 操作；这会花费用户的钱，因此其中的措辞和命令顺序都是固定的。

1. 并行审计。 在一条消息中分派 6 个 Agent，每个都提供 COORD_PATH 及其在 references/agent-prompts.md 中的提示词。他们负责收集和计数，因此使用能力足够的最低成本模型；综合分析才是需要判断力的环节。

Agent	写入	检查内容
CLAUDE.md	audit/claudemd.md	大小、重复、分层、缓存结构
MEMORY.md	audit/memorymd.md	大小、与 CLAUDE.md 的重叠
技能	audit/skills.md	数量、frontmatter 开销、重复项
MCP	audit/mcp.md	延迟加载的工具、故障或未使用的服务
命令	audit/commands.md	数量、菜单开销
设置和高级项	audit/advanced.md	钩子、规则、设置、@imports、缓存生命周期、压缩窗口

输出文件缺失时，应将其记录为缺口，而不是停止。 2. 综合分析。 让一个 Agent 使用可用的最强模型，读取所有审计文件，并写入 {COORD_PATH}/analysis/optimization-plan.md。如果失败，则提供原始审计文件。

3. 展示。 按照展示工作流的说明生成仪表板并展示发现结果，然后等待：

python3 "$MEASURE_PY" dashboard --coord-path "$COORD_PATH"

4. 实施。 仅实施用户批准的内容，每次更改一项，并遵循操作手册（操作 4A-4P：CLAUDE.md、MEMORY.md、技能、文件排除、MCP、钩子、缓存、规则、设置、描述、精简指令、模型路由、智能压缩、质量检查、版本感知优化、智能路由）。模板位于 examples/ 中。还应结合测量数据提供以下选项：

• python3 "$MEASURE_PY" recommendations：基于每日测量得出的使用建议（压缩窗口、子 Agent 缓存生命周期），每项均附用户自己的数据；当状态为 recommend 时，还会提供准确命令。逐字转达这些内容；Token Optimizer 只提供建议，绝不会设置这两个键中的任何一个。
• python3 "$MEASURE_PY" subagent-cache status / compact-advice：每项建议背后的单次测量详情。两者都是基于用户自身历史记录得出的估算；由用户自行决定。
• 可由脚本而非模型完成的重复工作：转交给 token-coach，目标 e。

5. 验证。 验证 Agent 重新测量并计算节省量。展示更改前后的数据，然后说明如何保持这些习惯。

如果验证数据比基线更差，则找出导致问题的更改，从备份中恢复对应文件，然后返回步骤 4。

更改用户设置的规则

这些规则用于保护用户不易恢复的工作：

• 每次更改前都要备份，并在应用前展示差异。
• 应归档，绝不删除；归档位置应在技能目录之外，以免加载归档内容。
• 归档技能、MCP 服务或 deny rule 前，先检查依赖关系，并先说明副作用。
• 优先使用项目级 deny rule，而非全局规则。
• 除非用户批准具体更改，否则不要改动用户自己的设置值。
• 引用测量数据（token 数和占窗口比例）。将节省量表述为上下文预算；只有在 measure.py 计算出金额时，才提供美元金额。

参考资料

需求	阅读
Codex、Cursor、OpenCode 工作流	references/codex-workflow.md、references/cursor-workflow.md、references/opencode-workflow.md
设置详情、Keep-Warm 同意	references/phase0-setup.md、references/keepwarm-consent.md
Agent 提示词、令牌流转方式	references/agent-prompts.md、references/token-flow-architecture.md
展示发现结果	references/presentation-workflow.md
实施步骤、检查清单	references/implementation-playbook.md、references/optimization-checklist.md、examples/
CLI 命令、会话连续性、错误	references/cli-reference.md、references/session-continuity.md、references/error-recovery.md

面向 Claude Opus 5.5、Sonnet 5.5 以及 Codex 上的 GPT-5.6 编写并经过验证。