DSH 小鲸鱼记账挂件（DeepSeek Balance Whale Widget）

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

⚠️ Codex 版小鲸鱼已迁至独立仓库 → https://github.com/Yang-huai406/Codex-Whale-Public（已安装用户无需重装；详见下方「两条分支怎么选」）

两条分支怎么选

本仓库现在只维护一条产品线（main，同一个包同时支持 DSH Web 与官方桌面客户端）。按你要挂在哪里选：

你要挂在哪	用哪条分支	安装方式
DSH Web 界面右下角（就是这个 README 描述的插件）	main（默认分支）	dsh plugin --profile web add dsh-whale-widget（推荐，装 npm 已发布版）；也可以从本仓库装 dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget，但那样装的是 main 当前状态、不跟随已发布版本
官方桌面客户端（Electron）右下角	main（同一个包）	⚠️ 不能用 --profile web（桌面端读的是 desktop profile，CLI 也拒绝 --profile desktop）—— 在桌面端会话里让 DSH 自己装，见下方「官方桌面端（Electron 客户端）请先看这一节」
Codex 桌面应用（跟随 Codex 窗口、无独立网页）	⚠️ 已迁出本仓库	新仓库 · 最新版下载 · 已安装用户无需重装<br>Codex 版迁移公告：本次迁移保留了开发历史、历代版本与作者贡献，并清理了旧图片中的非必要元数据（贡献者致谢见文末「致谢」）。后续更新、问题反馈与版本发布都在新仓库；反馈问题时请注明版本、系统和复现步骤，勿上传密钥、完整配置或未脱敏日志。

⚠️ 两条线互不兼容：Codex 版不能用 dsh plugin … add 装进 DSH 网页，本仓库的插件也不能在 Codex 桌面里运行。

⚠️ 安装方式二选一、别混用（npm 名 / github:）—— 它们是同一个包名，先后安装会并存冲突；已经是 github: 装的，要换 npm 名请先 dsh plugin --profile web remove dsh-whale-widget。

特性

记账与显示

• 🐋 常驻自启：随 DSH Web 界面每次打开自动出现（标准 DSH bundle 插件）
• 💰 余额：60 秒自动刷新 + 点击鲸鱼手动刷新；余额变化时数字滚动动画；瞬时网络抖动自动沿用最近余额不报错。两种取数方式，API key 优先：① DSH 凭据里的 DEEPSEEK_API_KEY；② DSH 账号登录态 —— 通过「设置 → 账号与余额」登录了 DeepSeek 账号、又没配 API key 时自动使用（不需要去 platform 建 key）
• 📊 今日已用（小鲸鱼记账）：不需要任何令牌。余额下降按观测累计为消费，余额上升（充值 / 赠金）单独记录、不会冲掉已有消费；检测到余额增加会提示「待核对余额调整」，可在「小鲸鱼记账 → DeepSeek（内置）→ 设置 → 余额校正」按实际累计到账金额与非调用扣减校正 —— 「已观测消费」与「余额校正」都是 DeepSeek 账户口径（由该 API key 的余额观测得出，不含其它厂商；「本机模型费用」才是所有模型的本地估算）（逐轮明细保留 90 天或最多 2 万条、逐日归档保留 365 天，超期数据归档到 .dshw-usage-archive.json）；金额按 8 位小数记账、显示保留两位
• 💬 每轮对话消耗：监听 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 弹玩偶效果（按压时底部坐标不变）
• 🎚️ 主菜单：角色、大小滑块、音效与提示（这行只剩入口按钮「全局设置」，音效总开关已搬进面板）、气泡全局开关 + 「按压泡泡设置」、避让滚动条、吸附设置、隐藏菜单按钮、资源管理（含余额预警、今日预算、小鲸鱼记账）
• 🔊 提示与音效设置（主菜单 → 「音效与提示」→ 「全局设置」）：四个入口行 —— 按压音效（音效组、音量）、每轮消耗提示（冒泡提示、自动关闭秒数、任务结束音、提示音量）、提问提示、授权提示。入口行上就是该事件的总开关与当前值摘要（如 默认音效组 · 100%、自动关 180s · 叮～），点一行才展开该区的设置项（可同时展开多个）。每个音效都有独立音量，每行带「试听」；音效行左侧的 [✓] 决定该音效响不响（不响 = 仍可冒泡）。底栏 取消 / 恢复默认 / 保存 —— 面板内的改动只落内存，点「保存」才生效，点「取消」完整还原（「恢复默认」之后点取消同样能撤销）
• 🙈 可隐藏菜单按钮：隐藏后，电脑端右键鲸鱼、手机端长按鲸鱼约 1.5 秒唤出菜单
• 📱 移动端友好：鲸鱼可触摸拖动（自研触摸接管，不会把页面手势判成滚动导致拖不动）；泡泡编辑器支持长按 0.4 秒进入拖拽排序；去掉了浏览器默认的点击高亮方块

泡泡系统（核心）

…