DSH 小鲸鱼记账挂件 · 铁盆鲸鱼娘版（DeepSeek Balance Whale Widget Bowl）

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

这是二开仓库：以 MeteorNOX/DeepSeek-Balance-Whale-Widget v0.3.18 为基座整体整合 —— 重复能力一律沿用原作者实现（含官方桌面端 Electron 适配、安全边界、记账内核、33 个厂商模板等），本仓库只在其上保留两处增量：顶碗 / 拿碗两套铁盆鲸鱼娘形象 与 钢管音效组。包名 dsh-whale-widget-bowl，插件 id 同名。

挂在哪里 · 怎么装

你要挂在哪	用哪个包	安装方式
DSH Web 界面右下角（dsh web）	本包（main）	dsh plugin --profile web add dsh-whale-widget-bowl（npm 已发布版）；或从本仓库装 dsh plugin --profile web add github:Witherwithwinter/DeepSeek-Balance-Whale-Widget-Bowl
官方桌面客户端（Electron）右下角	同一个包	⚠️ 不能用 --profile web（桌面端读的是 desktop profile，CLI 也拒绝 --profile desktop）—— 在桌面端会话里让 DSH 自己装，见下方「官方桌面端（Electron 客户端）请先看这一节」

⚠️ 与原版不能共存：本包的路由前缀与上游一致（/dsh-whale/），同一个 profile 里不要和上游 dsh-whale-widget 同时启用 —— 路由会撞车，两边还会各自改写同一批记账文件。要换成本包，先把上游那条从该 profile 的 dsh.profile.bundles 里去掉。

⚠️ 同一个包的两种安装方式（npm 名 / github:）二选一、别混用 —— 它们是同一个包名，先后安装会并存冲突。

⚠️ 上游另有一条 For-Codex 分支（Codex 桌面端口）；本仓库不维护它，需要请去上游。

本仓库增量（铁盆鲸鱼娘版）

内置角色：顶碗 / 拿碗

两套形象以上游「角色」系统的内置角色形式随包提供：出现在菜单的角色下拉里、不可删、可置顶、置顶状态持久保存；旧的 roles.json 在读取时会被兜底补回这两个角色（顺序在默认小鲸鱼之后）。

默认小鲸鱼	顶碗鲸鱼娘	拿碗鲸鱼娘
<img src="assets/DSniang1.png" width="200" alt="默认小鲸鱼"/>	<img src="assets/DSniang-bowl.png" width="200" alt="顶碗鲸鱼娘"/>	<img src="assets/DSniang-hold.png" width="200" alt="拿碗鲸鱼娘"/>
assets/DSniang1.png	assets/DSniang-bowl.png	assets/DSniang-hold.png

两套形象都是 1179×1179 正方形透明画布上的高分辨率切图，人物主体与默认形象按脸宽对齐（铁盆会虚增总高，勿按总高对齐）。想换成自己的图：覆盖同名 png 后重启 DSH 即可。

内置音效组：钢管

在「小黄鸭」「音效1」之外新增第三套内置预置组 钢管：assets/P1.mp3 = 按下（撞击 + 前段余音），assets/P2.mp3 = 松开（后段余音）。源素材里钢管只撞击一次，所以这样分段，避免按压与松开听感重复。除了按压 / 松开，它也出现在任务结束音 / 提问音 / 授权音的候选里。

特性

记账与显示

• 🐋 常驻自启：随 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"）

交互

…