README

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

!DSH 小鲸鱼记账挂件

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

 ⚠️ Codex 版小鲸鱼已迁至独立仓库 → （已安装用户无需重装；详见下方「两条分支怎么选」）


 两条分支怎么选

本仓库现在只维护一条产品线（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 窗口、无独立网页） | ⚠️ 已迁出本仓库 | 新仓库 · 最新版下载 · 已安装用户无需重装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"）

 交互

- 🖱️ 拖拽 + 吸附：四边吸附区可自定义（按比例或像素），角落可组合；可关闭吸附自由摆放。顶部吸附默认值为 0，表示关闭；想开启请到「菜单 → 吸附与翻转 → 自定义」，选择「比例吸附」或「绝对吸附」，把上侧数值调为正值后点「确认」。上吸附以挂件盒中心进入吸附区为判据，大尺寸挂件需要相应扩大上侧区域；改回 0 可关闭顶部吸附（152）。
- 🔄 贴左吸附时整体水平镜像翻转（文字同步反向、带动画）
- 🧸 按压 Q 弹玩偶效果（按压时底部坐标不变）
- 🎚️ 主菜单：角色、大小滑块、音效与提示（这行只剩入口按钮「全局设置」，音效总开关已搬进面板）、气泡全局开关 + 「按压泡泡设置」、避让滚动条、吸附设置、隐藏菜单按钮、资源管理（含余额预警、今日预算、小鲸鱼记账）
- 🔊 提示与音效设置（主菜单 → 「音效与提示」→ 「全局设置」）：四个入口行 —— 按压音效（音效组、音量）、每轮消耗提示（冒泡提示、自动关闭秒数、任务结束音、提示音量）、提问提示、授权提示。入口行上就是该事件的总开关与当前值摘要（如 默认音效组 · 100%、自动关 180s · 叮～），点一行才展开该区的设置项（可同时展开多个）。每个音效都有独立音量，每行带「试听」；音效行左侧的 [✓] 决定该音效响不响（不响 = 仍可冒泡）。底栏 取消 / 恢复默认 / 保存 —— 面板内的改动只落内存，点「保存」才生效，点「取消」完整还原（「恢复默认」之后点取消同样能撤销）
- 🙈 可隐藏菜单按钮：隐藏后，电脑端右键鲸鱼、手机端长按鲸鱼约 1.5 秒唤出菜单
- 📱 移动端友好：鲸鱼可触摸拖动（自研触摸接管，不会把页面手势判成滚动导致拖不动）；泡泡编辑器支持长按 0.4 秒进入拖拽排序；去掉了浏览器默认的点击高亮方块

 泡泡系统（核心）

- 💬 点击序列：第一次点击显示"首次点击泡"，再点进入"再次点击"队列；队列可任意增删排序，还能把两泡并列为 A/B 加权选择（每轮按权重抽一个）
- 🔁 点按角色推进

Top issues

Discussions

Latest release

更新内容

- 修好：连续快点宠物时，它会一直扁着、不回弹（macOS 触控板连续轻点同样受影响）
- 其它：并入社区贡献 PR 243（@DenseFLoe）

升级：dsh plugin --profile web update dsh-whale-widget（或在插件市场里更新），然后重启 dsh web（桌面端请重开客户端 —— 本次宿主也变了，必须重启）；浏览器按 Ctrl+F5 硬刷新。


详细说明（点击展开）

 1. 连续快点宠物一直扁着（PR 243，@DenseFLoe；close 242）

- 现象：连续快速点击宠物时，它会一直保持压扁状态、不再回弹；macOS 触控板连续轻点同样受影响。
- 原因（上一版引入的回归）：为了让 macOS 触控板"轻点"（按下与松开落在同一帧、压扁动画根本看不见）看得见，上一版让每一次松开都按"最短 120ms"推迟回弹。而连续快点的间隔通常 小于 120ms —— 回弹还没到，就被下一次按下取消并重新排期 ⇒ 看起来一直扁着。
- 修法（换了思路，更彻底）：不再推迟回弹 ——
  - 松开时一律立即回弹（所以连续快点每次都真的回弹，从机制上不可能再"卡扁"）；
  - "同帧轻点看不见"改用补提交一帧压扁来解决：临时关掉过渡 → 再写一次压扁 → 强制一次 reflow（让浏览器真的把这一帧压扁提交出来）→ 还原过渡