第 11 期：HUD 数据来源深度解析

本期核心：理解 HUD 的数据从哪来，才能精准排错。

---

11.1 三大数据来源

数据来源	位置	更新频率	包含内容
stdin JSON	Claude Code 通过管道传入	~300ms	模型名、上下文、token 明细、费用、用量
Transcript JSONL	~/.claude/projects/<path>/<session-id>.jsonl	实时	工具调用、agent 活动、todo 列表、累计 token
Context Cache	~/.claude/plugins/claude-hud/context-cache/<hash>.json	HUD 写（3秒 TTL）	stdin 的快照，用于兜底

---

11.2 stdin JSON 结构

Claude Code 每 ~300ms 调一次 statusLine 命令，通过 stdin 传入：

{
  "transcript_path": "~/.claude/projects/.../session-id.jsonl",
  "cwd": "/Users/eric/work/teachagent",
  "model": { "id": "claude-opus-4-7", "display_name": "Opus 4.7" },
  "context_window": {
    "context_window_size": 200000,
    "total_input_tokens": 67000,
    "used_percentage": 33,
    "current_usage": {
      "input_tokens": 318,
      "output_tokens": 59,
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 66368
    }
  },
  "cost": { "total_cost_usd": 0.42 },
  "rate_limits": {
    "five_hour": { "used_percentage": 25, "resets_at": 1777532000000 },
    "seven_day": { "used_percentage": 60 }
  }
}

---

11.3 stdin 字段与 HUD 渲染对应关系

stdin 字段	HUD 渲染
model.display_name	[Opus 4.7]
context_window.used_percentage	上下文条百分比
context_window.current_usage	(输入: 318, 缓存: 66k)
cost.total_cost_usd	$0.42
rate_limits.five_hour	用量条

---

11.4 Transcript Cache 结构

HUD 解析 transcript JSONL 后缓存：

{
  "version": 3,
  "data": {
    "tools": [{ "name": "Read", "target": "package.json", "status": "completed" }],
    "agents": [{ "type": "Explore", "description": "Research...", "status": "completed" }],
    "todos": [{ "content": "Fix auth bug", "status": "in_progress" }],
    "sessionTokens": {
      "inputTokens": 218486,
      "outputTokens": 4832,
      "cacheReadTokens": 1047488
    }
  }
}

---

11.5 sessionTokens vs current_usage

	sessionTokens（transcript）	current_usage（stdin）
范围	会话累计所有轮次	单次 API 请求
更新时机	每轮结束后	每次 statusLine 刷新
用途	Session Tokens 独立行	Identity 行的 token breakdown

---

11.6 Context Cache 兜底机制

HUD 将 stdin 的 context_window 快照持久化。当 stdin 偶尔不传数据（如 Claude Code 短暂闪烁 0%），HUD 从缓存恢复。

缓存 key = sha256(transcript_path)，确保不同会话不互相覆盖。

---

下期预告：第 12 期带你实战排错——Token 明细不显示时的完整诊断流程。