第 2 期：安装与版本说明
💡 进群学习加 wx: agentupdate
(申请发送: agentupdate)
(申请发送: agentupdate)
本期核心：从零到 HUD 显示只需三步命令，但不同平台有不同的坑。
2.1 前置条件
- Claude Code v1.0.80+
- macOS/Linux: Node.js 18+ 或 Bun
- Windows: Node.js 18+
2.2 三步安装
在 Claude Code 会话内依次运行：
Step 1：添加 marketplace
/plugin marketplace add jarrodwatts/claude-hud
Step 2：安装插件
/plugin install claude-hud
Step 3：配置 statusline
/claude-hud:setup
完成。HUD 立即出现，无需重启。
2.3 Linux 特别说明
Linux 上 /tmp 通常是独立 tmpfs 文件系统，安装会报错：
EXDEV: cross-device link not permitted
修复：设置 TMPDIR 后启动 Claude Code：
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
然后在该 session 内执行安装命令。
2.4 Windows 特别说明
如果 setup 提示找不到 JavaScript 运行时：
winget install OpenJS.NodeJS.LTS
重启 shell 后重新运行 /claude-hud:setup。
2.5 版本说明
claude-hud 有三个版本号来源，容易混淆：
| 来源 | 版本格式 | 说明 |
|---|---|---|
| Claude Code 插件市场 | 0.1.0 |
/plugin install claude-hud 安装的版本 |
| GitHub Releases | 0.0.1 – 0.0.12 |
源码发布版本，功能逐步增加 |
| npm Registry | 1.0.0 / 1.1.0 |
npm 发布版本，2026-03-10 发布 |
本教程基于 v0.1.0（插件市场版本）。通过 /plugin install claude-hud 直接安装，最简单。
v0.1.0 vs npm v1.1.0
| v0.1.0（插件市场） | npm v1.1.0 | |
|---|---|---|
| 安装方式 | /plugin install claude-hud |
npm install -g claude-hud |
| 上下文条 + 用量显示 | ✅ | ✅ |
配置系统 + /claude-hud:configure |
✅ | ✅ |
| 多行布局（expanded/compact） | ✅ | ✅ |
中文标签（language: "zh"） |
✅ | ✅ |
| 工具/Agent/Todo 显示 | ✅ | ✅ |
| 颜色自定义 + 自定义标语 | ✅ | ✅ |
| 缓存倒计时 | ✅ | ✅ |
| Git 状态 | ✅ | ✅ |
| 会话 Token 统计 | ✅ | ✅ |
插件市场版本功能完整，无需从 npm 单独安装。
功能演进里程碑
| 版本 | 新增功能 |
|---|---|
| v0.0.4 | 配置系统 + /claude-hud:configure 交互式配置 |
| v0.0.6 | 多行布局（expanded mode） |
| v0.0.7 | 重新设计默认两行布局 + setup 引导 |
| v0.0.9 | Usage API 可靠性提升 + Windows 修复 |
| v0.0.10 | 颜色覆盖、自定义标语、会话名称 |
| v0.0.12 | 中文标签、费用显示、会话 Token 统计 |
下期预告：第 3 期详解 HUD 的默认两行布局——你看到的每一个字符代表什么。