前言¶
在 DeepSeek Harness（DSH）Web 界面里，常驻一个挂件来显示余额、今日已用和每轮对话消耗，是个常见需求。原版 MeteorNOX/DeepSeek-Balance-Whale-Widget 提供了基础功能，在此基础上 TuWeiZhi 做了增强 fork：增加了「空闲自动说话」和「随机语句洗牌袋」两个功能，其余保持与上游一致。
这是什么¶
tuweizhi/dsh-whale-widget 是 DSH Web 界面右下角的余额小鲸鱼挂件，包名为 @tuweizhi/dsh-whale-widget。它显示 DeepSeek API 余额、今日已用、每轮对话消耗，并支持完全自定义的泡泡内容（文本、余额、图片、随机语句等）。
核心功能¶
余额与记账¶
- 常驻自启：随 DSH Web 界面每次打开自动出现
- 余额：60 秒自动刷新 + 点击鲸鱼手动刷新；余额变化时数字有滚动动画；瞬时网络抖动会沿用最近余额，不报错
- 两种取数方式：① DSH 凭据里的
DEEPSEEK_API_KEY；② DSH 账号登录态（设置 → 账号与余额） - 今日已用：余额下降时按观测累计为消费；余额上升（充值 / 赠金）单独记录，不会冲掉已有消费；充值增加时会提示「待核对余额调整」，可在「小鲸鱼记账 → DeepSeek（内置）→ 设置 → 余额校正」里校正
- 每轮对话消耗：监听 DSH 会话事件，按模型真实 usage（input / cache / output / reasoning tokens）换算金额，每轮结束弹出消耗泡泡；可开关、自动关闭秒数可设（0 = 不自动关闭）
峰谷定价¶
工作日高峰 9:00–12:00、14:00–18:00（北京时间），其余空闲；2026-08-23 起周末全天谷价。峰谷模块支持状态文字、倒计时、”梁文峰谷 / !?强强?! / 简洁”等多种样式。
泡泡系统¶
- 点击序列：第一次点击显示”首次点击泡”，再点进入”再次点击”队列；队列可任意增删排序，还能把两泡并列为 A/B 加权选择
- 点按角色推进队列：在「自定义泡泡」窗口里开启后，点一下角色往后推进一项；关闭时点角色回到”首次点击泡”
- 模块化内容：文本、超链接、随机语句（多条带权重，每次显示抽 1 条且不连续重复）、图片/动图、随机图片（多张带权重，抽 1 张且不连续重复）、总余额、赠金、充值余额、今日已用、峰谷时段、对话名
- 逐模块样式：字体（含自定义字体）、字号、加粗/斜体/下划线、纯色或跑马灯渐变配色、底色
- 拖拽排版：桌面端原生拖拽、移动端长按拖拽；模块可并入某行首/尾、可拆行、整行可排序；每行最多 6 个模块、泡泡最多 6 行；图片类模块独占一行且一个泡泡只允许一个
- 模块库：把常用模块”另存”进库，之后在任意泡泡里点击或拖入复用
交互与音效¶
- 拖拽 + 吸附：四边吸附区可自定义（按比例或像素），角落可组合；可关闭吸附自由摆放；顶部吸附默认值为 0，表示关闭
- 水平镜像翻转：贴左吸附时整体水平镜像翻转，文字同步反向、带动画
- 压按 Q 弹玩偶效果：按压时底部坐标不变
- 主菜单：角色、大小滑块、音效与提示、气泡全局开关 + 「按压泡泡设置」、避让滚动条、吸附设置、隐藏菜单按钮、资源管理
- 提示与音效设置：四个入口行（按压音效、每轮消耗提示、提问提示、授权提示）；每个音效都有独立音量；每个音效行左侧的
[✓]决定该音效响不响（不响 = 仍会冒泡提示）；音效行上就是该事件的「总开关」与「当前值摘要」 - 隐藏菜单按钮：隐藏后，电脑端右键鲸鱼、手机端长按鲸鱼约 1.5 秒唤出菜单
自定义 API¶
除内置的 DeepSeek 余额外，可在「小鲸鱼记账 → 模型」里添加任意厂商；每个模型独立配置余额预警 / 今日预算 / 额度。提供 34 个厂商模板，可直接查到余额或额度，或手动配置 HTTP 接口。
安装与启用¶
从本仓库安装：
dsh plugin --profile web add github:TuWeiZhi/dsh-whale-widget
本机开发安装：
dsh plugin --profile web add link:<本仓库绝对路径>
从 npm 安装：
dsh plugin --profile web add @tuweizhi/dsh-whale-widget
已装过上游 npm 版的，需先 dsh plugin --profile web remove dsh-whale-widget 再装。
DSH 没有官方插件市场，「发现」标签页只列你自己添加的索引源。本 fork 维护了一份索引：
- 插件页 → 「实验性插件」→ 更多 → 启用「自定义插件市场」
- 发现 → 索引源 → 添加
https://raw.githubusercontent.com/TuWeiZhi/dsh-plugins-index/main/index.json - 在「发现」里选中本插件 → 安装
典型用法¶
空闲自动说话¶
在「自定义泡泡」窗口底部有「空闲自动说话」开关。开启后，当 DSH 界面空闲时会自动弹出泡泡说话。也可以手改 .dshw-bubble.json 的 autoSay 节。
随机语句洗牌袋¶
在泡泡内容里添加「随机语句」模块，可以配置多条句子及其权重。插件会按权重随机选择，一轮内不会连续重复出现同一条。
适用场景与注意¶
适合需要在 DSH Web 界面右下角常驻显示余额、今日已用、每轮对话消耗，并且希望完全自定义泡泡内容的用户。
插件以当前 DSH 进程权限运行。安装前应检查源码与许可证。
结尾¶
这个插件为 DSH 增加了一个可定制、可交互的小鲸鱼挂件，把余额显示和自定义泡泡结合起来，适合需要可视化监控使用情况的开发者。更多详情见插件目录页和 GitHub 仓库。
