DSH 小鲸鱼挂件 Plus

DeepSeek Balance Whale Widget Plus · v0.6.8

DSH（DeepSeek Harness）右下角的常驻小鲸鱼挂件：余额、今日已用、每轮消耗、峰谷常驻徽标， 外加可自由编辑的泡泡、多套表情素材、提示音效，以及内置的 106 段透明动画桌宠。 支持 dsh web 与官方桌面客户端（Electron）。

本仓库是官方挂件 MeteorNOX/DeepSeek-Balance-Whale-Widget 的增强分支，由 louke6572 维护；桌宠动画来自 PC2005-cloud/dsh-pet（MIT）。来源与致谢见文末。

亮点

• 余额与记账：60 秒自动刷新；余额差 + 会话事件算今日已用；逐轮真实 usage 换算金额；明细保留 90 天、逐日汇总 365 天。
• 峰谷常驻徽标：峰/谷状态与倒计时无需点开气泡，贴在人物左下角；贴左吸附时自动换边。
• 桌宠（动画）角色形态：106 段 VP9-alpha 透明动画，双击缓冲交叉淡入；动作按分类下拉切换，可固定也可自动轮播；v0.6.3 起支持点击 Q 弹、弹簧拖拽、甩抛反弹、屏幕漫游、飞行积分、双击弹弓与多只分身。
• 泡泡编辑器：点击序列、并列加权、模块化排版、随机语句/随机图片、拖拽排序、模块库。
• 表情与音效：5 套表情素材包、情绪/眨眼/卖萌/疲惫；按压/每轮消耗/提问/授权四通道音效，每通道独立音量； 桌宠语音（点击/轻落/重摔）也作为音效组出现在「按压音效组」里；拖动与甩抛不播音效。
• 多厂商与扩展：33 家厂商额度模板、自定义 API 模型、火山 coding plan 额度、Codex 本地会话统计。

安装

安装规格里的包名是 dsh-whale-widget-plus。安装前先确认没有同名的旧版或官方版并存。

DSH Web（dsh web）

任选一种：

# npm（已发布时）
dsh plugin --profile web add dsh-whale-widget-plus

# 直接从 GitHub
dsh plugin --profile web add github:louke6572/dsh-whale-widget-plus

# 本地仓库 / 完整资源包（link: 为软链，源目录不能移动）
dsh plugin --profile web add link:D:\Plugins\dsh-whale-widget-plus

安装后重启 dsh web，浏览器 Ctrl+F5 刷新。若之前装过同名插件，先执行 dsh plugin --profile web remove dsh-whale-widget-plus 再装，避免版本冲突。

官方桌面端（Electron）

桌面端读的是 desktop profile，不能用 --profile web；而 --profile desktop 会被 CLI 拒绝，这是设计如此。正确做法是在桌面客户端会话里让宿主内置的 plugin_manager 安装：

请使用当前桌面端内置的 plugin_manager 安装 dsh-whale-widget-plus。 先核对当前 profile、已安装来源与版本；按工具支持的方式完成后告诉我结果，并说明是否需要重启。

• 首次安装：工具返回 applied 不保证当前窗口已经渲染；没出现就完全退出客户端（含托盘）再打开。
• 升级：优先沿用同一来源通过内置工具更新；返回 restart-required 时完全退出再打开，然后核对实际版本。

升级与卸载

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

升级时不要混用 npm、GitHub、本地目录三种来源；先在插件管理页或 CLI 里移除旧来源，再按同一来源安装。 用户数据（记账、泡泡配置、自定义素材）都在 $DSH_HOME 下，卸载插件不会删除它们。

凭据与安全

余额取数

两种方式，API key 优先，账号登录态兜底：

• DEEPSEEK_API_KEY：在 DSH 凭据服务里配置，用于请求 GET https://api.deepseek.com/user/balance。
• DSH 账号登录态：在「设置 → 账号与余额」登录 DeepSeek 后，没有 API key 时会自动改用 DSH 的账号服务（充值钱包 + 赠金），插件不接触账号令牌。两种方式的账本按账户标识分开。

不需要 DEEPSEEK_PLATFORM_TOKEN。今日已用统一由「小鲸鱼记账」（余额差 + 会话事件）计算。

安全边界

1. 凭据只发往厂商模板里写死的端点。自定义地址默认拿不到凭据；确需自建网关时，在本机 打开面板，对该模型勾选「允许把凭据发送到自定义地址」。
2. 写请求只接受本机来源（127.0.0.1 / localhost / [::1]），否则 403；只读接口不受影响。 需要远端管理时用 DSHW_ADMIN_HOSTS=192.0.2.10:3080,myhost.lan 显式声明。
3. 接口地址不允许携带用户名密码；凭据名只允许字母、数字与下划线。 内网 / 回环地址默认拒绝（防 SSRF）；同样只有勾选「允许把凭据发送到自定义地址」的模型才放行。
4. 接口不再下发通配 CORS（Access-Control-Allow-Origin: * 已移除）：只对同源 / 本机 file:// （官方桌面端，Origin: null）回显；跨站请求一律 403。所有响应带 X-Content-Type-Options: nosniff。

其它厂商凭据（按需配置）

凭据名	用途
OPENROUTER_API_KEY	OpenRouter 余额
MOONSHOT_API_KEY	Kimi / Moonshot 大陆站余额（CNY）
MOONSHOT_INTL_API_KEY	Kimi / Moonshot 国际站余额（USD）
SILICONFLOW_API_KEY	硅基流动模型探活
ARK_API_KEY	火山方舟模型探活
ZHIPU_API_KEY	智谱订阅额度 / Coding 端点
OPENCODE_GO_API_KEY	OpenCode Go 订阅额度
CUSTOM_API_KEY	自定义 HTTP / OpenAI 兼容中转站

换厂商时确认「凭据名」跟着模板变化，否则新 key 会覆盖上一家的凭据。

功能

记账与显示

• 余额：60 秒自动刷新，点击鲸鱼可手动刷新；余额变化带数字滚动；瞬时网络抖动沿用最近值。
• 今日已用（小鲸鱼记账）：余额下降计为消费，余额上升单独记为充值/赠金，不会冲掉消费； 出现「待核对余额调整」时可在记账面板用「余额校正」补录实际到账金额。
• 每轮消耗：读取本机会话 turn/end 的真实 usage（input / cache / output / reasoning）， 换算金额并弹泡泡；金额按 8 位小数记账，显示保留两位。
• 用量记录：今日消费、近 7 天、全部记录、模型占比、按日展开明细，支持按日期或模型名搜索。
• 模型名标注：deepseek-flash 显示为 DeepSeek-V4.1-Flash，旧名自动归并到同一模型。

峰谷时段显示（v0.4.3 起）

…