前言¶

在 DSH 里跑 dsh web 时，模型调用会消耗 DeepSeek 账户余额。常见做法是偶尔打开控制台或单独脚本查余额，和当前工作界面脱节；若把 API Key 塞进前端页面，又违背「密钥不进浏览器」的基本习惯。

下面介绍社区插件 dsh-plugin-balance-hud（维护者 jxboop，分类：客户端）：在 DSH Web 的叠加层上常驻一颗可拖动的余额徽章，Host 进程持有密钥并查询官方余额接口，浏览器只轮询同源裁剪后的 JSON。

这是什么¶

一句话：常驻 DSH Web 界面上的余额徽章（注册在 shell.overlay 座位，id 为 deepseek-balance-core），Host 半边定时查账户余额，浏览器半边渲染成「能量核心」样式。

插件仓库：https://github.com/jxboop/dsh-plugin-balance-hud
社区目录页：https://www.skillhub.cn/plugins/jxboop/dsh-plugin-balance-hud（独立站点，与 DeepSeek / 幻方无官方从属关系）

核心功能¶

展示与交互¶

• 徽章：旋转锥形能量环、脉动核心，旁侧实时余额（青紫渐变数字，刷新时滚动过渡）。
• 能量条：贴在徽章底部，随余额伸缩变色——充足为青、≤ ¥10 琥珀、≤ ¥1 赤红。
• 全息面板：点击徽章展开，显示放大余额、API 可用状态、赠送与充值占比、上次同步时刻、手动刷新；点外部或按 Esc 收起。
• 轮询：收起时约 45 秒一次，面板展开时约 15 秒一次。
• 读取失败：保留最后一次已知余额，核心进入灰暗 error 态，状态行标红并说明原因（不假装数据仍新鲜）。

拖动与靠边收缩¶

• 按住徽章拖动，松手停住；位置钳在视口内（四周留 10px），刷新后仍记住位置（localStorage 键 dsh-plugin-balance-hud:pos、dsh-plugin-balance-hud:tuck）。
• 松手时若离某边 ≤ 30px，自动缩进该边，只留约 22px 在屏幕内；点露出边缘可展开回原位。右缘有半透明 › 把手，可手动缩向最近一边。
• 收缩/展开为 320ms 缓动；prefers-reduced-motion 下关闭动效。配色跟随 DSH 主题变量，深浅色主题均可读。

装好后默认在右下角（README 写明位于小舞桌宠上方），可拖到任意位置。

Host / Browser 分工与密钥¶

API Key 不进入浏览器。 浏览器只请求同源 /plugin/balance-hud/balance，得到裁剪后的余额字段。

凭据解析顺序：

1. credentials Cordis 服务（若 composition 已挂载）；
2. 回退到 $DSH_HOME/.credentials.yaml 中 refs.DEEPSEEK_API_KEY。

解析结果按 KEY_CACHE_MS 缓存；上游 401/403 时会强制重新解析再重试，轮换密钥不必重启进程。

成功响应示例（字段以 README 为准）：

{ "ok": true, "isAvailable": true, "source": "credentials", "at": 1730000000000,
  "balances": [{ "currency": "CNY", "total": 8.14, "totalText": "8.14", "granted": 0, "toppedUp": 8.14 }] }

失败时 { "ok": false, "reason": "nokey|auth|network|shape|internal", "message": "…" }，message 为短中文说明，不含上游响应体与密钥。

余额上游为 DeepSeek 官方 GET /user/balance；base URL 依次尝试 https://api.deepseek.com 与 https://api.deepseek.com/v1。

安装与启用¶

环境要求¶

peerDependencies 声明 @deepseek-ai/cordis 为 4.0.2。DSH 主目录默认按 $DSH_HOME → ~/.dsh 推断。

安装步骤¶

官方 README 给出的安装方式为克隆仓库后执行安装脚本（脚本幂等）：

git clone https://github.com/jxboop/dsh-plugin-balance-hud.git
node dsh-plugin-balance-hud/install.mjs

PowerShell（5.1 不支持 &&，用分号）：

git clone https://github.com/jxboop/dsh-plugin-balance-hud.git; node .\dsh-plugin-balance-hud\install.mjs

脚本会：把插件放到 <DSH 主目录>/plugin-src/dsh-plugin-balance-hud；在 <profile>/node_modules 建链接（Windows 为 junction，无需管理员）；只修改 <profile>/package.json 的 dsh.profile.bundles；并打印重启指引。

常用参数：

node install.mjs --profile web            # 指定 profile（默认 web）
node install.mjs --dsh-home D:\dsh-home    # 自定义 DSH 主目录
node install.mjs --source ./本地目录        # 从本地目录安装（改代码时用）
node install.mjs --help

必须重启 dsh web：bundle 列表与宿主路由仅在进程启动时装载，热加载覆盖不到新装的插件。

1. Ctrl+C 停掉 dsh web，再执行 dsh web
2. 浏览器 Ctrl+Shift+R 硬刷新

卸载¶

node dsh-plugin-balance-hud/uninstall.mjs           # 移除链接与 bundles 注册，保留插件目录
node dsh-plugin-balance-hud/uninstall.mjs --purge   # 连同插件目录删除

同样需要重启 dsh web 生效。

典型用法与自检¶

日常使用：启动 dsh web 并硬刷新后，在界面右下角（或你拖放后的位置）查看余额；需要明细时点击徽章打开全息面板，可手动刷新。

开发或改包后可在仓库根目录跑自检：

node test/run.cjs

README 说明五项检查覆盖语法、dsh.client 与 bundle 契约、Host 路由与密钥不泄漏、Client 渲染与轮询、拖动手势与靠边收缩等行为。

挂载由 cordis.patch.yml 插入 host row，inject: [webServer] 为必需项；缺少时路由不会注册，浏览器可能一直显示「信号中断」。

适用场景与注意¶

适合：长期在 DSH Web 里调试智能体、希望余额常驻视野、又不想让 DeepSeek API Key 出现在浏览器网络面板或前端代码里的开发者。

务必知晓：

• 插件以当前 dsh web 进程权限运行，安装前请自行阅读源码与 MIT 许可证。
• 余额路由为 exact 精确匹配，无鉴权，仅暴露账户余额数值、不含凭据。若 Web 服务监听 0.0.0.0 且在不可信网络可达，应在前置代理限制 /plugin/balance-hud/balance 等路径。
• 凭据文件回退会读 $DSH_HOME/.credentials.yaml；请在可信环境中配置密钥。

结尾¶

dsh-plugin-balance-hud 把 DeepSeek 余额查数放在 Host、展示放在 Browser：右下角（或可拖动）的科技风能量核心，靠边可收缩，密钥留在 Node 进程。需要安装细节与动效说明时，以仓库 README 为准。

• 目录页：https://www.skillhub.cn/plugins/jxboop/dsh-plugin-balance-hud
• GitHub：https://github.com/jxboop/dsh-plugin-balance-hud