第 12 期：排错实战 — Token 明细不显示

本期核心：来自真实会话的排错经验，手把手带你定位 Token 明细不显示的根因。

---

12.1 现象

HUD 显示上下文条和百分比，但没有 (输入: xxx, 缓存: xxx) 明细。

---

12.2 诊断步骤

Step 1：确认配置

cat ~/.claude/plugins/claude-hud/config.json

检查：

• showTokenBreakdown 不为 false（默认 true）
• showSessionTokens 为 true

Step 2：检查 contextCriticalThreshold

Token breakdown 只在 context >= contextCriticalThreshold 时显示。默认 85%。

// 降低阈值，让明细更早显示
{ "display": { "contextCriticalThreshold": 30 } }

Step 3：检查数据是否存在

ls -lt ~/.claude/plugins/claude-hud/context-cache/ | head -3
cat ~/.claude/plugins/claude-hud/context-cache/<最新文件>.json | python3 -m json.tool

如果 current_usage 为 null → Claude Code 没有传此数据（非原生 Claude 模型可能不支持）。

Step 4：检查 session tokens 数据

ls -lt ~/.claude/plugins/claude-hud/transcript-cache/ | head -3

如果 sessionTokens 存在且 total > 0，但 HUD 不显示 → 可能是多行截断。

Step 5：排除多行截断

Expanded 布局多行输出，session tokens 行在最后。窄终端可能截断。

解决：关掉不重要的元素：

{
  "display": {
    "showSessionName": false,
    "showClaudeCodeVersion": false,
    "showMemoryUsage": false,
    "showOutputStyle": false
  }
}

---

12.3 诊断决策树

Token 明细不显示
│
├─ identity 行无 (in/cache)?
│  ├─ contextCriticalThreshold 太高（默认 85%）
│  │  └─ 降低到 30
│  ├─ current_usage 为 null
│  │  └─ 非 Claude 原生模型
│  └─ showTokenBreakdown = false
│     └─ 改为 true
│
└─ session tokens 行不存在?
   ├─ showSessionTokens = false → 改为 true
   ├─ transcript cache 无 sessionTokens → 会话刚开始
   └─ 多行截断 → 关闭不重要元素或切 compact

---

12.4 非原生模型兼容性

数据	原生 Claude	ZAI 等兼容平台
上下文百分比	✅	✅
Token 明细	✅	⚠️ 可能缺失
用量限制	✅	❌
费用估算	✅	⚠️ 可能为 0

HUD 有 context-cache 兜底：即使 stdin 偶尔缺数据，从上次完整快照恢复。

---

下期预告：第 13 期讲解 Session 与 Session History——理解会话的生命周期与数据存储。