deepseek-balance-whale-widget 是什么？DSH 界面右下角的小鲸鱼余额挂件

DSH 小鲸鱼余额挂件（deepseek-balance-whale-widget）是 DeepSeek Harness（DSH）的界面插件，在 Web 界面右下角常驻一只小鲸鱼气泡图，实时显示 DeepSeek API 余额、今日已用与每轮对话消耗。

deepseek-balance-whale-widget 是什么？

DSH 小鲸鱼余额挂件解决「频繁手动查余额、估算用量」的麻烦：把 DeepSeek API 余额、今日已用和每轮对话消耗直接显示在 DSH 界面里。

DSH 小鲸鱼余额挂件（deepseek-balance-whale-widget，GitHub 仓库 meteornox/deepseek-balance-whale-widget）由 meteornox 维护，MIT 协议开源。以前要看一眼账户消耗，得离开 DSH 去 DeepSeek 控制台查询；装上挂件后，余额、今日已用和每轮对话消耗都直接显示在界面里。它随 DSH Web 界面每次打开自动出现（标准 DSH bundle 插件），默认只配置 DEEPSEEK_API_KEY 即可拉取余额，属于 DSH Plugin 生态里开箱即用的界面插件（来源）。

deepseek-balance-whale-widget 的核心功能有哪些？

DSH 小鲸鱼余额挂件的核心能力围绕「看一眼就知道账户花了多少」展开：实时余额、今日已用双模式、每轮对话消耗统计，再加上拖拽吸附与个性化音效台词。 这些能力全部来自官方 README（来源）：

• 常驻自启：随 DSH Web 界面每次打开自动出现，无需手动启动。
• 实时余额：每 60 秒自动刷新，点击鲸鱼手动刷新，余额变化时数字滚动动画，网络抖动时自动沿用最近余额而不报错。
• 今日已用双模式：小鲸鱼记账模式免令牌、用余额差值本地记账并跨天归档；实时·令牌模式调用平台用量接口、按峰谷定价换算。
• 每轮对话消耗统计：监听本机会话事件，每轮对话结束弹出精确消耗金额，可开关并自定义自动关闭时间。
• 拖拽吸附与镜像翻转：支持四边四分之一吸附，左吸附时整体水平镜像翻转，按压有 Q 弹玩偶效果。
• 汉堡菜单个性化：可调大小（0.6–2.5 倍）、切换音效与音量、选择用量模式、开关气泡与每轮消耗提示。

怎么安装与启用 deepseek-balance-whale-widget？

在 DeepSeek Harness 里安装 DSH 小鲸鱼余额挂件用官方插件命令一次完成，装完重启 dsh web 并刷新浏览器，右下角即可看到小鲸鱼。

1. 安装 DSH 小鲸鱼余额挂件：在 DSH 终端执行安装命令，把插件装进当前 profile：

dsh plugin --profile web add dsh-whale-widget

等待命令输出安装完成，之后插件会出现在 DSH 的插件管理页面里，可以直接在页面里更新。也可以从 GitHub 来源安装：

dsh plugin --profile web add github:meteornox/deepseek-balance-whale-widget

2. 启用并确认生效：安装完成后重启 dsh web，再刷新浏览器，右下角应出现小鲸鱼气泡。用配置转储命令确认插件已加载：

dsh --profile web --dump-config

输出里的 bundles 应包含 dsh-whale-widget；也可以访问 http://127.0.0.1:3080/dsh-whale/balance.json 确认返回含 totalBalance 的 JSON。

3. 更新插件：需要升级时重跑更新命令：

dsh plugin --profile web update dsh-whale-widget

4. 卸载插件：不再需要时用卸载命令移除：

dsh plugin --profile web remove dsh-whale-widget

以上命令形式与宿主文档一致，插件目标名 dsh-whale-widget 取自 README 与插件目录（来源）。

deepseek-balance-whale-widget 典型用法

DSH 小鲸鱼余额挂件装完即可用，日常主要动作是配置凭据、选择用量模式、调整菜单和验证挂件。

1. 配置 DEEPSEEK_API_KEY（必需）：在 DSH 的凭据服务中配置 DeepSeek API 密钥，用于拉取余额（api.deepseek.com/user/balance）：

# 例如编辑 ~/.dsh/.credentials.yaml
# DEEPSEEK_API_KEY: <你的 DeepSeek API 密钥>

配好后挂件会自动拉取余额，今日已用默认使用记账模式。

2. 选择今日用量模式：在汉堡菜单的「用量」里选择。默认小鲸鱼记账模式免令牌、开箱即用；需要精确到每小时的实时用量时，配置 DEEPSEEK_PLATFORM_TOKEN（DeepSeek 平台网页会话令牌）并切换到实时·令牌模式：

# DEEPSEEK_PLATFORM_TOKEN: <Bearer eyJ... 平台网页会话令牌>

该令牌不是 sk- 开头的 API key，重新登录平台网页后可能失效，需要重新获取。

3. 个性化设置：悬停鲸鱼右上角打开汉堡菜单，调节大小（0.6–2.5 倍）、切换音效（小黄鸭 / 音效1）与音量、选择峰谷提示文案、开关气泡与每轮消耗提示；点击气泡可切换随机台词，再点一次关闭。

4. 验证挂件生效：确认右下角出现小鲸鱼，并检查余额接口返回：

curl http://127.0.0.1:3080/dsh-whale/balance.json

应返回含 totalBalance 与 todayUsage 的 JSON（来源）。

deepseek-balance-whale-widget 常见问题与排错

DSH 小鲸鱼余额挂件装好后遇到「挂件不出现」「今日已用显示 --」等常见问题时，先按下面的症状对号入座排查。

1. 挂件不出现：症状是重启并刷新后右下角没有小鲸鱼。原因是安装未成功或 DSH 没加载到 bundle。解决：运行 dsh --profile web --dump-config 确认 bundles 里有 dsh-whale-widget，重启 dsh web 后再 F5 刷新浏览器。

2. 今日已用显示 --：症状是余额正常但今日已用是占位符。记账模式下是还没跑过首次余额观测，等 60 秒内自动完成即可；实时·令牌模式下则需要先配置 DEEPSEEK_PLATFORM_TOKEN。

3. 提示「未配置 DEEPSEEK_API_KEY」：症状是余额区域显示未配置密钥。原因是凭据缺失。解决：在 DSH 凭据服务中配置 DEEPSEEK_API_KEY 后重启，余额即可正常拉取。

4. 每轮消耗不显示：症状是对话结束后没有消耗金额泡泡。原因是菜单「每轮对话后自动显示消耗金额」未勾选，或一轮对话没有完整结束。解决：在汉堡菜单勾选开关，并确保一轮对话完整结束（turn/end）再结算（来源）。

适用场景与注意

DSH 小鲸鱼余额挂件适合所有想在 DSH 里随时看到账户消耗的 DeepSeek 用户，尤其适合需要控制成本、按轮次核对消耗的场景。

适用场景：高频使用 DeepSeek API、需要控制预算的开发者；希望每轮对话结束即知道花了多少钱的人；喜欢把界面工具轻量化、可视化的人。挂件随浏览器窗口自动缩放，文字位置与字号和图片联动，开箱即用。

注意事项：默认记账模式依赖「观测到余额下降」累计，DSH 关闭期间的消耗会漏记，需要精确请用实时·令牌模式；平台会话令牌在重新登录平台网页后可能失效，需要重新获取；移动了本地源码目录时必须重新执行安装命令再重启；音效文件缺失时静默降级为无声，不影响功能（来源）。

项目链接

DSH 小鲸鱼余额挂件是 meteornox 维护的 MIT 开源项目。 插件详情页：DSH 小鲸鱼余额挂件插件详情。

本页是基于该插件官方 README 独立重写的导读——权威文档和最新变更请以源头为准：meteornox/deepseek-balance-whale-widget。插件是安装时就在你机器上运行的第三方代码；收录不代表背书——安装前请自行审阅源码。