token-coach

Token Coach

围绕用户的 Token 用在了哪里、应该做哪些调整展开辅导对话，并以用户机器上测得的数据为依据。交付内容是一份简短、按优先级排列且经用户认可的行动计划。若要进行会修改其配置的全面审计，请转交给 token-optimizer。

Token Optimizer 自身的技能（token-optimizer、token-coach、token-dashboard、fleet-auditor、resume-checkpoint）属于测量层，因此无论运行频率多低，都不要将它们纳入任何未使用技能、归档或整合建议。

1. 收集数据

请先原样运行此命令。它会查找最新安装的副本，避免使用过时的插件缓存：

RUNTIME="${TOKEN_OPTIMIZER_RUNTIME:-}"
if [ -z "$RUNTIME" ]; then
  if [ -n "$CLAUDE_PLUGIN_ROOT" ] || [ -n "$CLAUDE_PLUGIN_DATA" ]; then
    RUNTIME="claude"
  elif [ -n "$OPENCODE" ] || [ -n "$OPENCODE_BIN" ] || [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then
    RUNTIME="opencode"
  elif [ -n "$CODEX_HOME" ]; then
    RUNTIME="codex"
  # Explicit config-dir env of another harness: same tier as Python's
  # detect_runtime() (above CLAUDECODE, which every Claude Code child inherits).
  elif [ -n "$HERMES_HOME" ]; then
    RUNTIME="hermes"
  elif [ -n "$COPILOT_HOME" ] || [ -n "$TOKEN_OPTIMIZER_COPILOT_HOME" ]; then
    RUNTIME="copilot"
  elif [ -n "$TOKEN_OPTIMIZER_CURSOR_HOME" ]; then
    RUNTIME="cursor"
  elif [ -n "$TOKEN_OPTIMIZER_ANTIGRAVITY_HOME" ]; then
    RUNTIME="antigravity"
  elif [ -n "$GROK_HOME" ] || [ -n "$TOKEN_OPTIMIZER_GROK_HOME" ]; then
    RUNTIME="grok"
  elif [ -n "$CLAUDECODE" ] || [ -n "$CLAUDE_CODE_ENTRYPOINT" ] || [ -n "$CLAUDE_CODE_SESSION_ID" ]; then
    RUNTIME="claude"
  elif [ -d "$HOME/.config/opencode" ] && [ ! -d "$HOME/.codex" ]; then
    RUNTIME="opencode"
  elif [ -d "$HOME/.codex" ]; then
    RUNTIME="codex"
  else
    RUNTIME="claude"
  fi
fi

# 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/cache" "$HOME/.config/opencode/plugins" -type f -name measure.py -path '*token-optimizer*/scripts/measure.py' 2>/dev/null)
EOF
if [ -z "$MEASURE_PY" ] || [ ! -f "$MEASURE_PY" ]; then echo "[Error] measure.py not found. Is Token Optimizer installed?"; exit 1; fi
export TOKEN_OPTIMIZER_RUNTIME="$RUNTIME"
# The coach files ship beside measure.py, so they are always the same version.
COACH_DIR="$(cd -P -- "$(dirname -- "$MEASURE_PY")/../../token-coach" 2>/dev/null && pwd)"
[ -d "$COACH_DIR/references" ] || echo "[Error] token-coach references not found beside $MEASURE_PY. Reinstall Token Optimizer."

然后收集以下数据；任何命令失败时都跳过（较旧的安装可能缺少某些命令）：

python3 "$MEASURE_PY" coach --json                      # snapshot, patterns, history, questions
python3 "$MEASURE_PY" quality current --json            # this session's quality score and issues
python3 "$MEASURE_PY" subagent-cache status --json      # Claude Code: subagent cache lifetime and its payoff
python3 "$MEASURE_PY" compact-advice --json             # Claude Code: would an earlier compact window pay off
python3 "$MEASURE_PY" recommendations --json            # Claude Code: the daily usage-recommendations record
[ "$RUNTIME" = "codex" ] && python3 "$MEASURE_PY" codex-doctor --project "$PWD" --json

辅导 JSON 中包含：snapshot（当前开销）、patterns_good 和 patterns_bad（包含详情和修复方法的命名模式）、history（过去 7 天与此前的数据对比：质量、会话时长、缓存命中率、评分分布、每次会话的成本、短会话与长会话、压缩差距、切换模型的会话占比）、deterministic_candidates（如果存在，即用户反复进行、可由脚本完成的工作），以及 Claude Code 上的 usage_recommendations（每日测量的记录：compact window 和 subagent cache lifetime 各一项；用户采纳先前建议且数据发生变化后，还会包含 wins）。各字段的含义以及可引用的数据见：references/quick-reference.md。

所有引用的数据都必须来自这些输出或快速参考。如果数据不足或命令没有返回结果，请如实说明，并根据用户提供的信息进行辅导；编造数据会损害用户对所有真实数据的信任。

2. 询问用户的目标

提出一个问题，并等待用户回答后再展示发现：

你今天的目标是什么？ a) 从一开始就高效使用 Token 地构建新内容 b) 现有配置运行缓慢，或上下文填充过快 c) 设计多 Agent 系统 d) 快速检查运行状况 e) 审查工作流或自动化：哪些步骤确实需要模型

如果用户的请求已说明目标，则跳过此问题。

3. 加载目标所需内容

目标	阅读	示例参考
a、b	references/coach-patterns.md、快速参考	examples/coaching-session-new-project.md（a）、examples/coaching-session-heavy-setup.md（b）
c	references/agentic-systems.md、快速参考	examples/coaching-session-agentic.md
d	仅阅读快速参考	无，保持快速
e	references/deterministic-stages.md	无

对于 a、b 和 c，还要阅读 references/coaching-scripts.md，了解各类对话通常如何进行。所有路径均位于 $COACH_DIR 下。示例展示了语气和节奏；具体内容应由用户的数据决定。

4. 指导

这是一场对话。先指出一两个发现，再提一个问题；之后由用户主导。

• 先谈最痛的问题。 会话质量评分低于 70 时，先说这个（“质量评分是 100 分中的 58 分，过时的工具结果占用了 40K 个 token”）。否则，恶化的趋势比静态数字更值得优先讨论：质量下滑、会话变长、缓存命中率降低。
• 用用户的数据，并点明模式。 “47 个技能每次启动都要耗费约 4,700 个 token，这就是‘50 个技能陷阱’”很有说服力；“技能会耗费 token”则不然。
• 用一句话解释原理，让建议适用于本技能未列出的情况。例如：在会话中途切换模型会丢弃提示词缓存，因此应在开始时选好模型；在子 Agent 中使用更便宜的模型没问题，因为它有自己的上下文。
• 子 Agent 缓存。 即使使用订阅，子 Agent 也有 5 分钟缓存。Token Optimizer 会根据这位用户的对话记录衡量 1 小时是否划算，并给出建议（不会替用户设置密钥）；报告 subagent-cache status 测得的结果和 advice: 行，包括对这位用户的使用模式而言回报为负的情况。同一结论也会记录在每日的 usage_recommendations 记录中，供仪表板的“根据你的实际使用情况”部分读取。
• 压缩窗口。 将 compact-advice 呈现为根据用户自身历史记录得出的估算，并列出成本与质量，再给出它打印的命令。提前压缩可以在之后每轮对话中节省缓存读取 token，但也有丢失早期指令的风险，因此由用户决定。每日的 usage_recommendations 记录也会包含提炼后的 recommend/keep 结论。
• 使用建议。 当 usage_recommendations 包含 recommend 项时，应优先介绍：这是今天测得的结论，且已确认数据充足。当 wins 非空时，指出“自你做出更改以来”的测量变化，并引用两个数字；绝不要声称该变化是由更改导致的。
• 目标 e，或任何时候 deterministic_candidates 非空： 按步骤梳理工作流，并依据确定性阶段参考，将每一步归入“输入决定输出，因此用纯代码”或“需要判断，因此用模型”。
• Codex 用户只听 Codex 术语：AGENTS.md、Codex 记忆、balanced Codex hooks、推理力度和模型选择器、compact 提示词指南。Claude 模型名称和 CLAUDE.md 对他们毫无意义。

像一位博学的朋友那样交流。通常进行两到四轮对话；优先跟进用户的问题，不必拘泥于任何脚本。

5. 商定行动计划

最后列出三到五项按影响排序的行动。每项都要有加粗名称、说明要做什么的一行文字、预计节省及其估算依据，并标注是快速见效还是需要深入调整。适用时包括：

• Claude Code 质量低于 70：python3 "$MEASURE_PY" setup-smart-compact。Codex：TOKEN_OPTIMIZER_RUNTIME=codex python3 "$MEASURE_PY" codex-install --project .
• 质量低于 50：继续工作前先运行 /compact 或 /clear。
• 从模型迁移到脚本的步骤，并为每一步注明实现机制（钩子、脚本、定时任务）。

然后根据数据检查计划：每个数字都必须能追溯到命令输出或快速参考，而且任何操作都不得触及 Token Optimizer 自身的技能。修正不符合要求的内容，并在发送前再次检查。

如果用户希望代为实施更改，请提供 /token-optimizer；如果用户想观察趋势，请提供仪表板（python3 "$MEASURE_PY" dashboard；Codex 用户则引用它打印的 Dashboard: 行，绝不能引用记忆中的路径）。

保持唤醒（Claude Code，仅询问一次）

制定计划后，运行 python3 "$MEASURE_PY" keepwarm-consent-status。只有在 should_ask 为 true 时，才严格遵循 references/keepwarm-consent.md：这会花费用户的钱，因此措辞和命令顺序都是固定的。

针对 Claude Opus 5.5 和 Sonnet 5.5，以及在 Codex 上的 GPT-5.6 编写并验证。