前言¶
用 DeepSeek Harness（DSH）跑智能体、写代码、调 API，最怕两件事：余额不知不觉见底，用量到底花了多少却得切出去查平台。DSH 的 Web 界面本身专注对话与工具编排，账户信息并不常驻眼前。社区里 MeteorNOX 维护的 DeepSeek Balance Whale Widget（包名 dsh-whale-widget）把一只会 Q 弹的小鲸鱼娘挂在界面右下角：余额、今日已用、每轮对话消耗都能就地看见，打开界面自动启用。该插件在 GitHub 上已有约 884 星，是客户端类 DSH 插件里关注度较高的一款。
本文基于 SkillHub 插件目录页 与 GitHub 仓库 README 核实后整理，供你在 DSH 环境里安装试用。
这是什么¶
DSH 小鲸鱼余额挂件 是标准 DSH bundle 插件：随 DSH Web 界面每次打开，在右下角常驻显示 DeepSeek API 余额，并附带今日用量与每轮对话消耗统计。维护者为 MeteorNOX，开源协议为 MIT，当前包版本 0.2.10。
它解决的核心痛点很直接：不用反复打开 DeepSeek 平台查余额，也不用凭感觉估算今天烧了多少 token；信息嵌在 DSH 界面里，和开发流程同屏可见。
需要说明的是：DSH 社区插件目录（如 SkillHub）由社区维护，与 DeepSeek / 幻方无官方从属关系；安装前建议自行阅读源码与许可证，插件以当前 dsh 进程权限运行。
核心功能与亮点¶
根据官方 README，挂件主要能力如下：
- 常驻自启：标准 DSH bundle 插件，打开 Web 界面即出现，无需每次手动加载。
- 余额监控：每 60 秒自动刷新；点击鲸鱼可手动刷新；余额变化时有数字滚动动画；短时网络抖动会沿用最近一次余额，避免界面报错刷屏。
- 今日已用（两种模式）：
- 小鲸鱼记账（默认，推荐）：仅需DEEPSEEK_API_KEY，通过观测余额差值本地记账（.dshw-usage.json），跨天自动归零归档，免平台会话令牌。
- 实时·令牌（可选）：配置DEEPSEEK_PLATFORM_TOKEN后，调用平台用量接口，按峰谷定价换算今日已用（2026-08-23 起周末全天按谷价）。 - 每轮对话消耗：监听本机会话事件，每轮对话结束后弹出本轮消耗金额（基于真实 usage，非估算）；可在菜单中开关，并自定义自动关闭秒数。
- 交互与视觉：支持拖拽与四边四分之一吸附；左吸附时整体水平镜像翻转；按压有 Q 弹玩偶效果；悬停右上角汉堡菜单可调大小（0.6–2.5 倍）、音效、音量、用量模式等。
- 随机台词与音效：点击气泡可切换随机台词段（含峰谷提示、卖萌吐槽等），5 秒自动收起；按压/松手可选小黄鸭或音效包（缺失 mp3 时静默降级）。
安装与启用¶
方式 A：从 GitHub 安装（推荐）¶
无需本地克隆，一条命令即可：
dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget
说明：
- 安装成功后插件会出现在 DSH 插件管理页面，之后可在页面内更新，不必重复敲命令。
- 若网络需代理，可先设置环境变量再执行安装命令。
- 安装完成后重启
dsh web，浏览器 F5 刷新。
方式 B：本地链接安装¶
在仓库根目录（package.json 所在目录）执行：
dsh plugin --profile web add link:.
注意：仓库根目录本身就是插件包，不要写成 link:.\dsh-whale-widget（该子目录不存在，会导致装成普通依赖而非插件）。
方式 C：npm 发布后安装¶
dsh plugin --profile web add dsh-whale-widget
卸载¶
dsh plugin --profile web remove dsh-whale-widget
配置与典型用法¶
必需凭据¶
在 DSH 凭据服务中配置 DEEPSEEK_API_KEY（拉取 api.deepseek.com/user/balance 必需）。未配置时余额区域会提示未配置密钥。
DEEPSEEK_PLATFORM_TOKEN 为可选：不配置时「今日已用」自动使用默认的「小鲸鱼记账」模式，开箱即用。
用量模式选择¶
在挂件汉堡菜单 → 用量 中切换：
- 小鲸鱼记账：零额外配置，账本写入
$DSH_HOME/.dshw-usage.json，保留约 30 天归档。若 DSH 关闭期间有消耗，可能漏记；追求精确可改用令牌模式。 - 实时·令牌：需在浏览器登录 platform.deepseek.com，从开发者工具 Network 中复制
usage/by_api_key/amount请求的Authorization值，配置为DEEPSEEK_PLATFORM_TOKEN，重启dsh web后选用该模式。
验证安装是否成功¶
dsh --profile web --dump-config | Select-String -Pattern "whale"
curl http://127.0.0.1:3080/dsh-whale/balance.json
curl http://127.0.0.1:3080/dsh-whale/widget.js
预期：dump-config 输出中可见 dsh-whale-widget；balance.json 返回 200 且含 totalBalance；浏览器刷新后右下角出现小鲸鱼挂件。
每轮对话消耗¶
该功能直接监听 DSH 本机会话事件，按模型真实 usage 与内置峰谷定价表换算金额，不需要 DEEPSEEK_PLATFORM_TOKEN。在菜单中勾选「每轮对话后自动显示消耗金额」即可；一轮对话须完整结束（turn/end）才会结算弹出。
适用场景与注意事项¶
适合谁：
- 日常用 DSH Web 界面开发、调试智能体的开发者；
- 需要随时盯 DeepSeek API 余额、避免突然断服的用户；
- 希望在同屏看到「今天花了多少」「这一轮对话花了多少」的用量敏感型团队。
注意事项：
- 权限与安全：插件与 DSH 同进程运行，会读取你配置的 API Key；安装前请阅读 源码 与 MIT 许可证，确认符合你的安全策略。
- 平台令牌时效：
DEEPSEEK_PLATFORM_TOKEN来自平台网页会话，重新登录后可能需要重新获取。 - 定价表维护：峰谷定价写在
lib/index.js的PRICING常量中，DeepSeek 调价时需自行跟进更新。 - 常见问题：挂件不出现 → 确认
dsh plugin add成功、dump-config含dsh-whale-widget、已重启dsh web并刷新；今日已用显示--→ 记账模式需先完成一次余额观测（60 秒内自动）；无声音 → 检查assets/*.mp3是否在包内，或接受静默降级。
结尾¶
如果你已经在 DSH 里泡了很久，却总要切出去看余额，这只右下角的小鲸鱼娘值得一试：安装命令简单，默认记账模式几乎零配置，交互细节（拖拽吸附、Q 弹、数字滚动）也把「盯余额」这件事做得不那么枯燥。
