nickkkkkk123123/dsh-whale-girl

鲸鱼娘·灵动挂件 —— 一个会卖萌、会记账、会弹跳的 DSH 桌面挂件。

在 DSH Desktop 右下角显示一只鲸鱼娘，实时展示 DeepSeek 余额、用量与上下文占用，支持拖动、甩抛弹跳、中键弹弓抛掷、彩蛋气泡与右键菜单。

功能

• 🖼️ 鲸鱼娘立绘 —— 图片内嵌进脚本（量化压缩至 46KB），无网络依赖，任何环境都能显示
• 💰 余额 / 用量 —— 实时显示 DeepSeek 余额、今日用量、上轮对话消耗，余额跌破预警线自动气泡提醒
• 📊 上下文占用 —— 进度条显示当前会话上下文占用（对齐 DSH 显示），≥90% 主动提醒开新会话
• ⏱ 峰谷提醒 —— 判断当前时段为用量高峰还是低谷
• 💬 彩蛋气泡 —— 点击触发随机台词/彩蛋；空闲 2~5 分钟还会自己开口说一句（说话即唤醒动画，说完继续省电）
• 🖱 右键菜单 —— 切换音效、开关显示模块、切换 API 提供方、调节弹弓力度与毛玻璃强度、省电模式开关、恢复默认位置
• 🎵 音效 —— 可爱合成音 / 鸭叫 可切换（mp3 内嵌，无网络依赖）
• 🤸 甩抛弹跳 —— 快速甩出后在窗口内弹跳，撞边抖动画 + 音效
• 🎯 中键弹弓抛掷 —— 按住中键拖动，挂件跟随并绘制蓝色水滴连接线，松手沿原位置方向弹射（力度与拉开距离成正比，可在菜单调节）
• 🍃 省电模式 —— 空闲 60 秒自动暂停漂浮动画并停用毛玻璃（交互立即恢复），降低常驻 GPU/CPU 占用
• 🧊 毛玻璃强度 —— 进度条底板模糊度 0~16 可调，0 为关闭（更省资源）
• 🫧 底板透明度 —— 进度条底板与右键菜单透明度 0~80% 可调（默认 18%），拉得越高越透，透出页面背景
• 🖼 信息面板 —— 浮窗显示时间/日期/CPU/内存，默认跟随角色；角色快速移动或直接拖动时脱钩独立（撞边界/角色反弹、几秒后回归角色下方），跟随距离阈值右键菜单可调

安装

# 从 GitHub Release 安装（含 tgz 安装包，推荐）
dsh plugin add nickkkkkk123123/dsh-whale-girl

# 或本地源码目录 link 依赖后加入 profile bundles

配置

挂件配置保存在 ~/.dsh/.whale-girl-config.json（可用右键菜单可视化修改，也可直接编辑文件）：

{
  "soundMode": "cute",
  "showProgress": true,
  "showBubble": true,
  "showBalance": true,
  "showPeak": true,
  "slingPower": 20,
  "ecoMode": true,
  "frost": 4,
  "panelOpacity": 0.82,
  "lowBalance": 10
}

字段	说明
soundMode	cute 可爱合成音 / duck 鸭叫
showProgress	是否显示上下文进度条
showBubble	是否显示彩蛋/随机台词气泡
showBalance	是否在详情里显示余额
showPeak	是否显示峰谷提醒
slingPower	中键弹弓发射力度系数（5~60，松手速度 = 拉开距离 × 系数）
ecoMode	省电模式：空闲 60 秒暂停漂浮动画并停用毛玻璃
frost	毛玻璃强度 0~16（进度条底板 blur 像素，0=关闭）
panelOpacity	底板不透明度 0.2~1（内部存储；菜单滑块按「透明度 = 1 − 该值」显示，默认 0.82 即透明度 18%；作用于进度条底板与右键菜单）
lowBalance	余额预警线（元），余额低于该值时气泡提醒充值，0=关闭预警

API 提供方切换

右键鲸鱼娘 → API 提供方 菜单区会列出所有已配置的提供方（内置 DeepSeek 官方 + settings.yaml 中声明的 llm-pi-ai.providers / llm-openai-compatible.providers），并显示各自的余额（平台无公开余额 API 时显示"余额未知"）。点击某项即切换默认模型路由（写入 agent-default-model，新会话生效）。

• 余额查询：已知平台专用 API（DeepSeek / 硅基流动）优先，否则按 baseURL 自动探测常见余额端点，都没有则显示"余额未知"。
• 切换模型：优先用该 provider 在配置里声明的第一个模型，未声明时回退到内置映射。

中键弹弓与省电

• 中键弹弓：按住鼠标中键拖动挂件（自动屏蔽浏览器中键滚轮），原位置与挂件间绘制蓝色水滴连接线；松手时挂件沿「原位置 → 当前」的反方向弹回（橡皮筋手感），速度 = 拉开距离 × slingPower，撞边弹跳 + 音效复用甩抛物理。
• 省电模式：挂件交互（按下/划过/菜单）会刷新空闲计时，60 秒无交互后自动暂停漂浮动画、停用毛玻璃底板（:hover 立即恢复）；菜单可关闭该模式。毛玻璃强度 frost 调到 0 或开启省电都能显著降低常驻渲染开销。

占用实测（回应"桌宠一定吃资源"的刻板印象）

所有数字均为这台机器上的实测值，不是估算：

项目	数据	说明
安装包	346KB	立绘经 palette 量化压缩（1081KB → 46KB）后整体 -90%
额外进程	0 个	挂件是 DSH Web UI 内的一个 DOM 节点，不开新进程、不装 Helper
空闲 CPU 影响	约 0.6%	同口径 A/B：65 秒空闲窗口内，漂浮动画开/关的整机 CPU 增量差仅 0.15 秒
空闲 GPU	省电模式自动归零	空闲 60 秒停止逐帧合成调度，交互瞬间恢复

测量方法：重启 DSH 后等待 80 秒（越过省电阈值），对全部 DSH 进程取 TotalProcessorTime，测 65 秒窗口增量，省电开/关各测一轮取差值。动画的渲染成本主要在 GPU 合成器的逐帧调度（省电模式已消除），CPU 侧几乎免费——"桌宠 = Electron 大户"的印象对本插件不成立。

说明（v0.3.x）：上表为信息面板关闭（默认）时的空闲实测。信息面板开启（时间/系统资源 + 毛玻璃 infoFrost + 物理跟随/碰撞循环）会额外占用 CPU/GPU，强度取决于 infoFrost（模糊半径，0=关闭，见菜单"面板模糊"）与是否开启 pauseOnThinking（DSH 输出/思考时暂停信息面板物理，默认开）。建议：面板模糊调低（或 0）+ 开 pauseOnThinking 可明显降低该额外占用。上表 0.6% 等为信息面板关闭时的值；信息面板开启时的具体数值可实测（本页不虚标）。

实测（2026-08-30，v0.3.6，DSH 2.0.3 + 多插件环境）：信息面板关≈70.2% 单核 / 开≈70.9% 单核，差值 ≈0.7% 单核——信息面板开启本身增量极小（说明 transform 定位 / 物理减负 / pauseOnThinking 已生效）。注意：该环境 DSH 2.0.3 + 多后台插件（dsh-dafeiyu-helper 等）的整体空闲基线约 70% 单核，与上表 0.6%（0.2 系精简、无这些后台插件）相差大——0.6% 仅适用于当时精简场景；实际占用取决于 DSH 版本 / 后台插件数量。

已知问题：DSH 流式输出时挂件卡顿

现象：agent 输出长文字（流式）时，挂件（及同页 UI）在相邻 token 之间会卡顿，输出完毕立即恢复流畅。

问题真正所在：不在本插件。DSH 前端（官方 deepseek-ai/deepseek-harness，DSH Desktop 通过 submodule 引入）在流式输出时每收到一个 token 就整体重建当前 assistant 消息（assistant.ts 的 updateChunk 每 chunk 复制 blocks + 重新渲染整条消息），占用主线程；本挂件与它同页面/同主线程，被连带卡住。虚拟列表已解决长会话整体渲染，但**"流式每 token 全量重建当前消息"是剩余瓶颈**。

本插件已做的缓解：thinking（DSH 输出/思考）时暂停信息面板物理循环（省主线程，可通过菜单开关）；transform 定位（不触发 layout reflow）；信息面板物理循环减负。根治在 DSH 的流式渲染层（该问题已反馈给 DSH Desktop 作者，见其 issue）；挂件自身不产生该卡顿。

数据链路（为什么不用 fetch）

DSH Desktop 的 webserver 会对不带 renderer 认证头的子资源请求返回 403（包括 fetch、<img>、<audio>、<script>）。因此：

• 图片 / 音效：内嵌为 data URL，完全不走网络请求
• 数据：宿主通过 webserver/index-inject 向主页面顶层注入桥接脚本，脚本用带认证的 fetch 拉取 /dsh-whale-girl/api/state，再通过 postMessage 广播给挂件（slots 组件运行在 iframe/隔离上下文，其自身 fetch 不带认证会被拦）

这也是 dsh-whale-widget 数据同样获取不到（只显示余额，不显示上下文）的原因——普通 fetch 在 DSH Desktop 拿不到 host 数据。

余额 key

余额通过 credentials.resolve('DEEPSEEK_API_KEY') 读取，需在 DSH 中配置 DEEPSEEK_API_KEY（与 dsh-whale-widget 一致）。

开发

pnpm install
pnpm build     # 打包 host (lib/index.js) + client (lib/client.js)
pnpm test      # 运行测试

License

MIT