ccswitch-hud

CC Switch + HUD — Claude Code 状态栏插件，实时显示 CC Switch 当前 Provider、模型名、账户余额，点击 Provider 名称即可跳转充值页面。

效果预览

「DeepSeek」· v4-pro · API剩余使用量 ██████████░░ 30.6% · 余额 ¥29.45 (≈ 6.63M tokens)
Context █████░░░░░ 45% · Usage ██░░░░░░░░ 25%

元素	说明
「DeepSeek」	可点击超链接（OSC 8），Ctrl+Click / Cmd+Click 跳转充值页面
v4-pro	当前活跃模型名
API剩余使用量 ██████░░░░ 30.6%	青色进度条，满值为用户设定的预算金额
余额 ¥29.45 (≈ 6.63M tokens)	实时余额 + 折算 token 数（保留 3 位有效数字，实时汇率换算）
Context / Usage 行	claude-hud 原版功能，完全保留

功能特性

• 实时余额查询：自动从 CC Switch 数据库读取 API Key，调用厂商官方 API 查询余额
  • ✅ DeepSeek — GET /user/balance
  • ✅ Kimi/Moonshot — GET /v1/users/me/balance
  • ✅ SiliconFlow — GET /v1/user/info
  • ✅ OpenRouter — GET /api/v1/credits
  • ⚠️ 智谱 GLM / 阿里百炼 / MiniMax — 无公开 REST API，显示「请查看控制台」
• 实时汇率：3 级降级（open.er-api.com → jsDelivr CDN → 硬编码兜底 7.0），4 小时缓存
• Token 折算：内置定价表 + 实时汇率，精确计算余额可购买的 token 数
• 售价准确：内置各厂商最新定价表（2026 年 6 月版），优先使用 CC Switch model_pricing 表数据
• 预算进度条：首次使用强制设置预算满值，青色进度条直观显示剩余比例
• 完整 claude-hud 功能：Context 条、Usage 用量、Tool 活动、Agent 状态、Todo 进度、Git 分支等全部保留
• 安全：API Key 仅从 CC Switch 本地数据库读取，仅用于向厂商官方 API 发起余额查询，禁止写入任何文件

系统要求

• Claude Code v1.0.80+
• Node.js 18+ (Windows: Node.js LTS)
• CC Switch 桌面版（本地运行中）

安装

方式一：从本地包安装（离线）

1. 将 ccswitch-hud-plugin 文件夹复制到 ~/.claude/plugins/cache/claude-community/ccswitch-hud/0.1.0/

2. 打开 Claude Code，运行：

/ccswitch-hud:setup

3. 重启 Claude Code

方式二：从 GitHub 安装（在线，待发布）

claude /plugin install ccswitch-hud

安装后运行：

/ccswitch-hud:setup

首次使用

重启 Claude Code 后，HUD 第一行会显示：

「DeepSeek」· v4-pro · 请运行 /ccswitch-hud:set-budget <金额> 设置预算

运行命令设置预算满值（进度条的参照值）：

/ccswitch-hud:set-budget 100

设置后，进度条立即生效：

「DeepSeek」· v4-pro · API剩余使用量 ██████████░░ 30.6% · 余额 ¥29.45 (≈ 6.63M tokens)

命令

命令	功能
/ccswitch-hud:setup	一键安装 statusLine 配置
/ccswitch-hud:configure	配置显示选项
/ccswitch-hud:set-budget <金额>	设置余额进度条满值（如 100 表示 100 元）

配置

配置文件位置：~/.claude/plugins/ccswitch-hud/config.json

{
  "language": "zh",
  "display": {
    "showCcswitch": true,
    "ccswitchShowTokens": true,
    "ccswitchBudget": 100
  }
}

配置项	默认值	说明
language	"zh"	语言（zh/en）
display.showCcswitch	true	是否显示 ccswitch 信息行
display.ccswitchShowTokens	true	是否显示 token 折算
display.ccswitchBudget	null	余额进度条满值（null=首次使用时强制提示设置）
display.ccswitchLowBalanceThreshold	10	余额低于此值时变红
display.ccswitchBalanceCacheMs	30000	余额缓存时间（毫秒）

注意：claude-hud 原有的全部配置项同样可用（showProject、showContextBar、showTools、showAgents 等），详见 claude-hud 文档。

支持的厂商

厂商	余额 API	充值 URL
DeepSeek	✅ REST	platform.deepseek.com/top_up
智谱 GLM	⚠️ 请查看控制台	open.bigmodel.cn/usercenter/proxy-mgmt
阿里百炼	⚠️ 请查看控制台	dashscope.console.aliyun.com/overview
MiniMax	⚠️ 请查看控制台	platform.minimaxi.com/user-center/basic-information/accountInfo
Kimi/Moonshot	✅ REST	platform.moonshot.cn/console/billing
SiliconFlow	✅ REST	cloud.siliconflow.cn/account/balance
OpenRouter	✅ REST	openrouter.ai/credits

架构

CC Switch (桌面客户端)
  └── ~/.cc-switch/cc-switch.db (SQLite)
        │
        ├── providers 表 → name, api_key, model, website_url
        ├── model_pricing 表 → input/output 定价
        └── settings.json → currentProviderClaude UUID
              │
              ▼
ccswitch-hud (statusLine, 每 ~300ms)
  ├── db-reader.js  → 解析 SQLite 文本（纯 JS，无原生依赖）
  ├── balance.js    → REST API 余额查询（仅白名单厂商域名）
  ├── exchange-rate.js → 实时汇率（3 级降级，免 key）
  ├── pricing.js    → 定价表 + token 折算
  └── render/lines/ccswitch.js → OSC 8 超链接 + 青色进度条渲染

常见问题

Q: 为什么智谱/百炼/MiniMax 显示"余额请查看控制台"？

A: 这些厂商没有提供公开的 REST 余额查询 API。你仍然可以点击 Provider 名称跳转充值，但余额需要登录控制台查看。

Q: 进度条没有出现？

A: 首次使用需要运行 /ccswitch-hud:set-budget <金额> 设置预算满值。

Q: 切换 Provider 后余额不更新？

A: HUD 每 ~300ms 自动刷新，切换后最多 300ms 就会显示新 Provider 的信息。

Q: 如何切换 Provider？

A: 在 CC Switch 桌面客户端中切换即可。切换后 HUD 会自动同步。

Q: API Key 会泄漏吗？

A: 不会。Key 仅从 CC Switch 本地数据库读取到内存中，仅向厂商官方 API 域名发起 HTTPS 请求，不写入任何文件，不打印到日志。

Q: 不影响 claude-hud 原有功能？

A: 不影响。ccswitch-hud 是 claude-hud 的超集（fork from v0.3.0），所有原有功能（Context、Usage、Tools、Agents、Todos、Git 等）完整保留。

License

MIT — 基于 claude-hud (Jarrod Watts, MIT License)

鸣谢

• claude-hud — 优秀的 Claude Code HUD 插件
• CC Switch — 跨平台 AI CLI 配置管理工具
• open.er-api.com — 免费汇率 API