DSH 铁盆鲸鱼娘挂件（DeepSeek Balance Whale Widget Bowl）

English README

DeepSeek Harness（DSH）Web 界面右下角的常驻挂件：小鲸鱼气泡图 + DeepSeek API 余额 + 今日已用 + 每轮对话消耗，并且泡泡内容可以完全自定义（点击序列、模块化排版、并列加权出泡、随机语句/随机图片）。标准 DSH bundle 插件，dsh plugin 一键安装，无需任何会话令牌。

本仓库是 MeteorNOX/DeepSeek-Balance-Whale-Widget（v0.3.0）的二次开发版 铁盆鲸鱼娘版：功能与原版保持一致（重复能力均沿用原作者实现），在此基础上新增：

• 🎭 两套内置铁盆鲸鱼娘形象：「顶碗」（头顶铁盆）与「拿碗」（手端铁盆），与默认鲸鱼娘一起出现在菜单「角色」下拉里，选择置顶持久化、重启保持
• 🔊 钢管音效（经典金属管落地声：按下=撞击"哐"，松开=余音"嗡……"），作为「音效组」的第三套内置预设，同样可用于任务结束音

特性

记账与显示

• 🐋 常驻自启：随 DSH Web 界面每次打开自动出现（标准 DSH bundle 插件）
• 🎭 三套形象：默认（原版鲸鱼娘）/ 顶碗 / 拿碗，菜单「角色」下拉即点即换、📌置顶持久保存
• 💰 余额：60 秒自动刷新 + 点击鲸鱼手动刷新；余额变化时数字滚动动画；瞬时网络抖动自动沿用最近余额不报错
• 📊 今日已用（小鲸鱼记账）：不需要任何令牌。每次观测余额后按余额差值记账（跨天自动归零归档；逐轮明细保留 90 天或最多 2 万条、逐日归档保留 365 天，超期数据归档到 .dshw-usage-archive.json）；余额差不可用（充值/退款/无基准）时用会话事件的金额合计兜底
• 💬 每轮对话消耗：监听 DSH 本机会话事件，按模型真实 usage（input / cache / output / reasoning tokens）换算金额，每轮结束弹出消耗泡泡；可开关、自动关闭秒数可设（0 = 不自动关闭），泡泡内容可自定义（模块化，金额用 {cost} 引用），入口：菜单 → 每轮消耗提示 → 「自定义提示」
• ⛰️ 峰谷定价：工作日高峰 9:00–12:00、14:00–18:00（北京时间），其余空闲；2026-08-23 起周末全天谷价。峰谷模块支持状态文字、倒计时、"梁文峰谷 / !?强强?! / 简洁"等多种样式
• 📒 用量记录窗口：今日模型消费、近 7 天、全部记录；模型占比条；按日期展开逐条明细（含时间与金额）；支持按日期或模型名搜索；模型名带友好标注（deepseek-flash → DeepSeek-V4.1-Flash，旧名标注"同 V4.1 Flash"）

交互

• 🖱️ 拖拽 + 吸附：四边吸附区可自定义（按比例或像素），角落可组合；可关闭吸附自由摆放
• 🔄 贴左吸附时整体水平镜像翻转（文字同步反向、带动画）
• 🧸 按压 Q 弹玩偶效果（按压时底部坐标不变）
• 🎚️ 主菜单：大小滑块、音效开关/音量、峰值文案、泡泡开关、每轮消耗开关 + 「自定义提示」（每轮消耗内容 / 自动关闭秒数 / 任务结束音效）、吸附设置、角色/资源管理、自定义泡泡、余额预警、今日预算
• 🙈 可隐藏菜单按钮：隐藏后，电脑端右键鲸鱼、手机端长按鲸鱼约 1.5 秒唤出菜单
• 📱 移动端友好：鲸鱼可触摸拖动（自研触摸接管，不会把页面手势判成滚动导致拖不动）；泡泡编辑器支持长按 0.4 秒进入拖拽排序；去掉了浏览器默认的点击高亮方块

泡泡系统（核心）

• 💬 点击序列：第一次点击显示"首次点击泡"，再点进入"再次点击"队列；队列可任意增删排序，还能把两泡并列为 A/B 加权选择（每轮按权重抽一个）
• 🔁 点按角色推进队列（可选，在「自定义泡泡」窗口里开）：开启后点一下角色＝往后推进一项（第 1→2→3…，走到最后一项再点收起泡泡，下次点按从第 1 项重新开始）；关闭时是原来的行为 —— 点角色回到"首次点击泡"。设置只在这个窗口里，随窗口的「保存」一起生效
• 🧩 模块化内容：一个泡泡由若干模块按行组成，支持类型
  • 文本、超链接
  • 随机语句（多条句子带权重，每次显示抽 1 条且不连续重复）
  • 图片/动图（从泡泡图库选，独占一整行）
  • 随机图片（多张图带权重，抽 1 张且不连续重复，同样独占一行）
  • 余额数值、今日已用、峰谷时段（内置数值，内容自动获取，可调占位符与样式）
• 🎨 逐模块样式：字体（含自定义字体）、字号、加粗/斜体/下划线、纯色或跑马灯渐变配色、底色；文本与随机语句支持悬浮快捷编辑
• 🖐️ 拖拽排版：桌面端原生拖拽、移动端长按拖拽；模块可并入某行首/尾、可拆行、整行可排序；每行最多 6 个模块、泡泡最多 6 行，图片类模块独占一行且一个泡泡只允许一个
• 📚 模块库：把常用模块"另存"进库，之后在任意泡泡里点击或拖入复用

提醒

• 🔔 余额预警：余额低于设定值时弹提醒，内容可编辑（含图片/随机图片模块）
• 💸 今日预算：今日已用达到设定金额时弹提醒，内容同样可编辑
• 💬 每轮消耗提示：一轮对话结束后弹消耗泡泡，内容同样可编辑（模块化，金额用 {cost}）；内容、自动关闭秒数与任务结束音效都在菜单 → 每轮消耗提示 → 「自定义提示」里设置
• 三者都支持自动关闭秒数设置；气泡模式不可用时自动退化为居中卡片（卡片内也会渲染图片模块）

音效 / 角色 / 图片

• 🔊 按压 & 松开音效：内置「小黄鸭」「音效1」「钢管」三套预置；也可导入音频片段并自由组合成自定义音效组（槽位可留空 = 该事件静音）
• 🎵 任务结束音：一轮回复完成时播放；内置两个预设音效 —— 默认 Minecraft·经验球（assets/minecraft-exp-orb.wav）与 A（assets/task-end-a.wav），也可选任意片段或音效组
• ✂️ 音频片段管理：导入时可视化裁剪、试听；资源管理窗口统一查看/试听/删除
• 🐳 自定义角色：上传自己的鲸鱼图片（图库管理，可回退默认）；本版额外内置「顶碗鲸鱼娘」「拿碗鲸鱼娘」两套形象，不可删除、可置顶
• 🖼️ 泡泡图库：内置 petpet、money1 两张图，也可上传 png/gif，供图片/随机图片模块使用

自定义 API（多厂商余额 / 额度）

除内置的 DeepSeek 余额外，可在「小鲸鱼记账 → 模型」里添加任意厂商；每个模型独立配置余额预警 / 今日预算 / 额度：

…