第 10 期：最佳实践与常见问题

本期核心：一份经过实战检验的 HUD 配置模板 + 一套常见问题的快速排查手册。

---

10.1 推荐配置（开发者）

{
  "language": "zh",
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "context", "usage", "promptCache", "environment", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true,
    "pushWarningThreshold": 5
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showSpeed": true,
    "showPromptCache": true,
    "showTokenBreakdown": true,
    "showSessionTokens": true,
    "contextCriticalThreshold": 30,
    "contextValue": "both",
    "promptCacheTtlSeconds": 300
  }
}

---

10.2 上下文管理黄金法则

法则	做法
盯住上下文条	黄色时开始精简，红色时立即 /clear
避免排错雪球	3-4 轮没进展就 clear
定期清缓存	长会话中间 /clear 一次
精简 system 注入	CLAUDE.md 压缩、claude-mem 控制加载数量
用 subagent	大任务给 subagent，主会话上下文不受影响

---

10.3 常见问题

Q：HUD 不显示

• 检查 Claude Code 版本 ≥ v1.0.80
• 重启 Claude Code
• 运行 /claude-hud:setup 重新配置
• 检查 ~/.claude/settings.json 中 statusLine 配置

Q：Git 状态缺失

• 确认在 git 仓库中
• 检查 gitStatus.enabled 不为 false

Q：工具/Agent/Todo 行不显示

• 默认隐藏，需在配置中启用 showTools / showAgents / showTodos
• 且只在有活动时才显示

Q：配置不生效

• 检查 JSON 语法错误（无效 JSON 静默回退默认值）
• 删除 config.json，重新运行 /claude-hud:configure

Q：之前正常后来消失

• 插件更新后可能需要重新 /claude-hud:setup

---

10.4 缓存优化实战

场景 1：Cache TTL 快过期

Cache TTL: 2m 18s    ← 还剩 2 分钟缓存就过期

做法：在缓存过期前发一条消息（哪怕只是"继续"），System Prompt + CLAUDE.md + 对话历史全部缓存命中，省 ~90% 输入 Token 费用。

场景 2：刚执行了 /clear

Cache TTL: -          ← 缓存已清空
Context ██░░░░░░░░ 12%   ← 上下文很低

做法：/clear 后缓存全部失效，第一轮会重新写入缓存。新会话会很快重建缓存。

---

10.5 完整配置速查

功能	配置键	默认
语言	language	en
布局	lineLayout	expanded
路径层级	pathLevels	1
上下文条	display.showContextBar	true
上下文格式	display.contextValue	percent
Token 明细	display.showTokenBreakdown	true
Token 明细阈值	display.contextCriticalThreshold	85
用量	display.showUsage	true
费用	display.showCost	false
速度	display.showSpeed	false
工具	display.showTools	false
Agent	display.showAgents	false
Todo	display.showTodos	false
缓存倒计时	display.showPromptCache	false
Git 状态	gitStatus.enabled	true

---

下期预告：第 11 期深入 HUD 数据来源——stdin JSON、Transcript JSONL、Context Cache 三大数据管道的完整解析。