前言¶
在 DeepSeek Harness（DSH）里长时间跑对话时，余额、今日消费和缓存命中往往分散在不同界面或插件里；若再叠加一个桌面角色挂件，右下角容易叠出两套悬浮 UI。社区维护者 Guzi2005 的 dsh-whale-combo 把 dsh-whale-widget 的鲸鱼娘与 dsh-damage-pulse 的计费数据合并到同一套浮层：一张深色毛玻璃状态卡，外加从角色头顶向上发射的深蓝扣费弹幕。本文按 README 与仓库元数据说明其定位、能力与安装方式。
这是什么¶
dsh-whale-combo 是 DSH 的 Web 插件（npm 包名 dsh-whale-combo，当前版本 1.0.6，许可证 MIT）。界面挂在 shell.overlay 浮层，用原生 React 渲染；可在 DSH 插件页启用、停用或卸载。
在 SkillHub 目录中归类为「联网工具」；仓库 GitHub 星标为 0（以目录页展示为准）。本插件是界面层，不包含鲸鱼娘素材或 damage-pulse 源码，数据通过同源只读 HTTP 接口合并，不新增外部网络请求。
核心功能¶
毛玻璃状态卡¶
卡片锚定在鲸鱼娘头部右上方，使用冻结锚点，角色呼吸动画不会带动卡片抖动。视觉为 backdrop-filter 模糊、约 26% 透明底色，以及高光与阴影；尾巴为独立玻璃块，整体不画外描边，避免与小尾巴接缝出现拼接线。
卡面展示三组指标与右侧峰/谷徽章：
- 钱包图标：余额（薄荷绿，
¥） - 柱状图：今日消费（白色）
- 数据库：缓存命中率（浅蓝）
- 峰/谷：玻璃徽章，峰为红字红底，谷为绿字绿底；悬停有北京时间口径说明
「本轮消耗」放在整卡悬停提示中，不占卡面。鲸鱼娘 ☰ 菜单内提供「毛玻璃透明度」滑杆（10%–80%），复用 whale-widget 的菜单行与滑杆组件；偏好写入浏览器本地，拖动时卡片会弹出一次以便预览。
扣费弹幕¶
每次计费从鲸鱼娘头顶向上发射深蓝色弹幕（未命中的一条为灰色）。金额 21px、未命中 25px，标签 13px，字重 900；队列发送、互不重叠，右对齐且「−」号成列。动画使用 cubic-bezier(.2,.72,.3,1) 缓动。事件流按 seq 游标增量读取，每条扣费只播放一次，不回放。
与上游插件的分工¶
默认隐藏 damage-pulse 自带的悬浮卡，避免双份界面；Ctrl+Alt+D 可临时显示原卡。
左键点击鲸鱼娘开/关合并气泡；点击气泡刷新数据；右键气泡、Esc 或点空白处关闭气泡。
☰ 菜单在 whale-widget 基础上做了精简与增强：角色改为一行 36px 小方块缩略图，点击切换，末尾「＋」沿用上游导入流程；内置预设 DeepSeek bot、长征 bot（透明背景，首次运行自动导入）。另含 LET ME GO 开关：开启后从前端会话 DOM 增量读取流式输出文本，用纯前端算法截取 ≤5 个英文单词或汉字的短句（优先 Let me 开头），以扣费弹幕同款样式发射，默认关闭，不额外消耗 token。
若未安装 dsh-whale-widget，界面退化为右下角 ¥ 小圆钮开合气泡。若未安装 dsh-damage-pulse，余额/今日/缓存/弹幕显示 --，峰谷仍可按北京时间本地计算。
数据合并规则¶
| 字段 | 主来源 | 回退 |
|---|---|---|
| 余额 | damage-pulse GET /api/token-monitor/balance?provider=deepseek-account |
whale-widget /dsh-whale/balance.json |
| 今日消费 | damage-pulse GET /api/token-monitor/today-spend |
whale-widget todayUsage |
| 本轮消费 | whale-widget /dsh-whale/last-turn.json |
最近一条扣费事件金额 |
| 缓存命中率 | damage-pulse GET /api/token-monitor/usage-summary?range=today |
-- |
| 峰/谷 | whale-widget balance.json.isPeak |
本地北京时间（工作日 9–12、14–18） |
| 弹幕 | damage-pulse GET /api/token-monitor/charge-events?since=<seq>（约 1s 轮询） |
— |
安装与启用¶
先安装依赖插件，再安装本包。将 <profile> 换成你实际使用的 DSH profile 名。
# 1) 依赖（如果还没装）
dsh plugin --profile <profile> add dsh-whale-widget dsh-damage-pulse
# 2) 本插件（npm）
dsh plugin --profile <profile> add dsh-whale-combo
完成后刷新页面或重开 DSH 客户端。卸载时在 Plugin Manager 移除本 bundle 即可。
README 还说明可从本地目录通过 link:<绝对路径> 或「设置 → 插件 → 安装本地包」安装；本文不展开 clone 步骤。
典型用法¶
- 确认 dsh-whale-widget 与 dsh-damage-pulse 已启用，再启用 dsh-whale-combo。
- 在右下角找到鲸鱼娘，左键打开合并气泡，核对余额、今日、缓存与峰谷。
- 发起会产生扣费的对话，观察头顶深蓝扣费弹幕是否与事件一致。
- 需要对照 damage-pulse 原悬浮卡时，按
Ctrl+Alt+D临时显示。 - 在 ☰ 菜单调整角色、大小、毛玻璃透明度、音效，或按需开启 LET ME GO 歌词弹幕。
集成上，鲸鱼角色节点依赖 dsh-whale-widget 0.4.x 的 .dshwv-root .dshwv-img；上游大版本若改动类名或菜单文案，需同步本插件 client.js 中的选择器与注入逻辑。
适用场景与注意¶
适合已经在用鲸鱼娘挂件和 damage-pulse、希望右下角只保留一套可视化计费界面的 DSH 用户。卡片配色按设计稿固定，不使用 DSH 主题 token；z-index 高于鲸鱼娘与弹幕层，避免被角色遮挡。
DSH 插件在当前 harness 进程权限下运行，安装前应自行查看 GitHub 仓库 源码与 MIT 许可证。鲸鱼娘美术与 damage-pulse 各自保留原作者版权与许可，本仓库不复制其素材。
社区插件目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系；「一切皆插件」是 DSH 生态的常见做法，本介绍不代表官方背书。
