DSH 小鲸鱼挂件 Plus
DeepSeek Balance Whale Widget Plus · v0.7.2
DSH（DeepSeek Harness）右下角的常驻小鲸鱼挂件：余额、今日已用、每轮消耗、峰谷常驻徽标，
外加可自由编辑的泡泡、多套表情素材、提示音效，以及内置的 106 段透明动画桌宠。
支持 dsh web 与官方桌面客户端（Electron）。
本仓库是官方挂件 MeteorNOX/DeepSeek-Balance-Whale-Widget 的增强分支，由
louke6572 维护；桌宠动画来自 PC2005-cloud/dsh-pet（MIT）。来源与致谢见文末。
DSH 小鲸鱼挂件
亮点
- 余额与记账：60 秒自动刷新；余额差 + 会话事件算今日已用；逐轮真实 usage 换算金额；
明细保留 90 天（或最多 2 万条），逐日汇总保留 365 天。
- 峰谷常驻徽标：峰/谷状态与倒计时无需点开气泡，贴在人物左下角；贴左吸附时自动换边。
- 桌宠（动画）角色形态：106 段 VP9-alpha 透明动画，双层 video 缓冲交叉淡入；
13 个动作分类下拉，可固定也可自动轮播；v0.6.3 起支持点击 Q 弹、弹簧拖拽、甩抛反弹、
屏幕漫游、飞行积分、双击弹弓与多只分身；v0.6.9 起支持双形态共存（小鲸鱼与桌宠同时显示）。
- 泡泡编辑器：点击序列、并列加权、模块化排版、随机语句/随机图片、拖拽排序、模块库。
- 表情与音效：5 套表情素材包、情绪/眨眼/卖萌/疲惫；按压/每轮消耗/提问/授权四通道音效，每通道独立音量；
桌宠语音（点击/轻落/重摔）也作为音效组出现在「按压音效组」里；拖动与甩抛不播音效。
- 多厂商与扩展：34 套内置额度/用量模板（含自定义、OpenAI 兼容与本地端点）、
自定义 API 模型、火山 coding plan 额度、Codex 本地会话统计。
安装
直接安装规格：github:louke6572/dsh-whale-widget-plus（原样整条复制，不能只写包名）。
安装前先确认没有同名的旧版或官方版并存。
直接安装（Web 与桌面端通用）
本包尚未发布到 npm（npm view dsh-whale-widget-plus 会 404），所以在安装入口里只输入裸包名
dsh-whale-widget-plus 是装不上的。请把下面这条 GitHub 规格原样粘进安装入口 ——
Web 端 CLI 的 add 参数、桌面端插件管理页的安装输入框、或让内置 plugin_manager 安装时给的 spec，三者通用：
github:louke6572/dsh-whale-widget-plus
也接受完整仓库 URL：https://github.com/louke6572/dsh-whale-widget-plus。
npm 上没有 dsh-whale-widget-plus 这个包（npm view 会 404），所以裸包名永远装不上，
不要去试。上面的 GitHub 规格就是本项目的官方安装方式，Web 与桌面端通用。
Agent 一键安装（推荐）
把这一句复制给任意能执行命令的 Agent（DSH 内置 plugin_manager、Claude Code、Codex 等）即可：
帮我安装 DSH 插件 github:louke6572/dsh-whale-widget-plus
规格必须写成 GitHub 形式：npm 上没有 dsh-whale-widget-plus，裸包名装不上。
DSH Web（dsh web）
# 直接从 GitHub（推荐）
dsh plugin --profile web add github:louke6572/dsh-whale-widget-plus
# 本地仓库 / 完整资源包（link: 为软链，源目录不能移动）
dsh plugin --profile web add link:D:\Plugins\dsh-whale-widget-plus
安装后重启 dsh web，在它打印的 URL 上打开页面并 Ctrl+F5 刷新。
若之前装过同名插件，先执行 dsh plugin --profile web remove dsh-whale-widget-plus 再装，避免版本冲突。
GitHub 来源不要锁旧 commit：v0.6.8 及更早的提交里没有 assets/pet-video/（106 段动画），
装上去桌宠会提示素材缺失。
官方桌面端（Electron）
桌面端读的是 desktop profile，这个 profile 由桌面客户端独占，CLI 直接操作会被拒绝：
error: profile "desktop" is managed exclusively by the Electron application
正确做法是在桌面客户端会话里让宿主内置的 plugin_manager 安装：
请使用当前桌面端内置的 plugin_manager 安装 github:louke6572/dsh-whale-widget-plus。
先核对当前 profile、已安装来源与版本；按工具支持的方式完成后告诉我结果，并说明是否需要重启。
- 首次安装：工具返回
applied 不保证当前窗口已经渲染；没出现就完全退出客户端（含托盘）再打开。
- 升级：优先沿用同一来源通过内置工具更新；返回
restart-required 时完全退出再打开，然后核对实际版本。
升级与卸载
dsh plugin --profile web remove dsh-whale-widget-plus
升级时不要混用 GitHub、本地目录两种来源；先在插件管理页或 CLI 里移除旧来源，再按同一来源安装。
用户数据（记账、泡泡配置、自定义素材）都在 $DSH_HOME 下，卸载插件不会删除它们。
凭据与安全
余额取数
两种方式，API key 优先，账号登录态兜底：
DEEPSEEK_API_KEY：在 DSH 凭据服务里配置，用于请求 GET https://api.deepseek.com/user/balance。- DSH 账号登录态：在「设置 → 账号与余额」登录 DeepSeek 后，没有 API key 时会自动改用 DSH
的账号服务（充值钱包 + 赠金），插件不接触账号令牌。两种方式的账本按账户标识分开。
不需要 DEEPSEEK_PLATFORM_TOKEN。今日已用统一由「小鲸鱼记账」（余额差 + 会话事件）计算。
访问控制（三层信任栅栏）
所有 /dsh-whale/* 路由共用同一入口校验，按顺序是：
- 插件自带的轻量校验（永远先跑）：Host 必须是回环权威（
127.0.0.0/8、localhost、::1）
或 DSHW_TRUSTED_HOSTS 里显式声明的；Sec-Fetch-Site: cross-site 一律拒；
带 Origin 时必须与 Host 同源（Origin: null 的桌面端 file:// 放行）。
- 委托宿主栅栏：DSH 的
connection.requestRejection 可用时交给它判（它带浏览器鉴权，未认证返回 401）；
它抛异常按拒绝处理，不会静默放行。
- 宿主不支持时（旧版 DSH 没有这个方法）：只靠第 1 层，并在插件加载时打一条醒目 warn。
这时若 DSH 部署在非回环地址（反代/局域网），用
DSHW_TRUSTED_HOSTS=192.0.2.10:3080,myhost.lan 声明。
写请求（POST/PUT/PATCH/DELETE）还必须来自本机回环，否则 403；只读接口不受影响。
需要远端管理时显式声明 DSHW_ADMIN_HOSTS（逗号分隔，可带端口，默认空）。
凭据外发边界
- 凭据只发往厂商模板里写死的端点。自定义地址默认拿不到凭据；确需自建网关时，在本机
打开面板，对该模型勾选「允许把凭据发送到自定义地址」。
- 接口地址不允许携带用户名密码；凭据名只允许字母、数字与下划线。
内网 / 回环地址默认拒绝（防 SSRF）；同样只有勾选「允许把凭据发送到自定义地址」的模型才放行。
- 不下发通配 CORS（没有
Access-Control-Allow-Origin: *）：只对同源 / 本机 file://
（官方桌面端，Origin: null）回显；跨站请求一律 403。所有响应带 X-Content-Type-Options: nosniff。
其它厂商凭据（按需配置）
| 凭据名 | 用途 |
|---|
OPENROUTER_API_KEY | OpenRouter 余额 |
MOONSHOT_API_KEY | Kimi / Moonshot 大陆站余额（CNY） |
MOONSHOT_INTL_API_KEY | Kimi / Moonshot 国际站余额（USD） |
SILICONFLOW_API_KEY | 硅基流动模型探活 |
ARK_API_KEY | 火山方舟模型探活 |
ZHIPU_API_KEY | 智谱订阅额度 / Coding 端点 |
OPENCODE_GO_API_KEY | OpenCode Go 订阅额度 |
CUSTOM_API_KEY | 自定义 HTTP / OpenAI 兼容中转站 |
换厂商时确认「凭据名」跟着模板变化，否则新 key 会覆盖上一家的凭据。
按需配置的入口在控制台「厂商额度」卡里：点「+ 添加模型」选厂商模板并填 API key，点「模型与凭据」改所选模型的
设置 / 凭据 / 额度。没配厂商模型时挂件只显示 DeepSeek 余额，不会请求任何其它厂商端点。
功能
记账与显示
- 余额：60 秒自动刷新，点击鲸鱼可手动刷新；余额变化带数字滚动；瞬时网络抖动沿用最近值。
- 今日已用（小鲸鱼记账）：余额下降计为消费，余额上升单独记为充值/赠金，不会冲掉消费；
出现「待核对余额调整」时可在记账面板用「余额校正」补录实际到账金额。
- 每轮消耗：读取本机会话
turn/end 的真实 usage（input / cache / output / reasoning），
换算金额并弹泡泡；金额按 8 位小数记账，显示保留两位。
- 用量记录：今日消费、近 7 天、全部记录、模型占比、按日展开明细，支持按日期或模型名搜索。
- 模型名标注：
deepseek-flash 显示为 DeepSeek-V4.1-Flash，旧名 deepseek-v4-flash、
deepseek-v4-flash-vision-exp 自动归并到同一模型。
峰谷时段与计价（2026-08-17 起）
峰/谷状态字 + 距下一时段倒计时外移到人物左下角，不点气泡也能看到；与人物底边对齐，
贴左吸附时自动换到人物右侧。状态字样式可选：峰/谷、梁文峰/梁文谷、高峰/低谷、自定义。
- 高峰 = 工作日 9:00–12:00、14:00–18:00（北京时间），其余时段按谷价。
- 2026-08-23 00:00 起：周六/周日全天谷价。
- 2026-09-19 起：调休上班的周末、以及中国法定节假日全天，也按谷价（只维护「放假」日期表）。
主菜单「峰谷显示」可选三种方式（v0.6.0 起）：
| 选项 | 行为 |
|---|
| 常驻徽标（默认） | 左下角常驻；气泡内不重复显示 |
| 气泡内 | 隐藏徽标，恢复上游原版：点开气泡时显示配置里的峰谷/倒计时模块 |
| 隐藏 | 徽标与气泡内都不显示 |
选择保存在 localStorage 的 dshw-pbmode，修改后立即生效，刷新后保持。
桌宠（动画）角色形态（v0.5.0 起，v0.6.3 补全物理交互）
在「角色」里选「桌宠（动画）」即可切换，随包带 106 段 VP9-alpha .webm；
双层 video 交叉淡入，换段不出现空白帧。渲染端不支持 VP9-alpha 时会回退普通角色并提示。
v0.7.1 起两种形态共用同一个「桌面控制台」菜单（336px 紧凑面板，白毛玻璃 + 深蓝主色的新版设计），
层级、间距与描边按新稿重排，不再有「按钮入口 + 独立设置面板」的分裂结构：
| 区块 | 内容 |
|---|
| 头部 | 小鲸鱼 / 桌宠 / 共存 三段页签（三种形态互斥：点单形态即退出共存，点共存则两只同时显示）+ 标题 + 固定 / 关闭按钮 |
| 底栏 | 恢复默认 / 版本号（点开「关于 / 自检」）/ 保存配置 |
| 呈现与位置 | 大小滑块 + 数值框（小鲸鱼 1–20 级、桌宠 4–20 级 / 40%–200%；停在角色身上滚轮也能缩放）；开关组：屏幕漫游（仅桌宠）、避让滚动条（默认关闭＝贴边，开启后展开「宽度 px」）、提示气泡、隐藏菜单；下拉组：吸附与翻转、初始位置「回到右下角」（仅桌宠）、峰谷显示、徽标样式；仅桌宠另有底部三列：分身数量（关闭 / 1–3 只）、分身动作（含自动随机 / 跟随主宠）、分身大小 |
| 动作与待机 | 仅桌宠，默认折叠；展开后只有一个 动作与分类 按钮：点开是分类菜单（每项带 ›，悬停/点击展开右侧动作子菜单，与原版 dsh-pet 右键菜单一致），点动作只播一次，播完回随机链。待机不再支持指定某一段，默认就是全部动作随机轮播 |
| 表情与台词 | 仅小鲸鱼；表情包版本（自动 + 第一～第五版）、表情、台词、眨眼 |
| 提示与音效 | 默认折叠，点标题行展开；展开后一次给全：主音量滑块、按压/消耗/提问/授权四路胶囊（可直接调音量/静音）、各场景细化配置（音效组、文案、自动关闭等） |
| 厂商额度（选装） | 默认折叠，点标题行展开：气泡里是否显示厂商额度开关、所选厂商模型下拉、「+ 添加模型」与「模型与凭据」入口、火山 coding plan 额度开关（默认关闭，开启后才请求附属插件 volc-usage） |
| 角色与资源 | 一行四格：导入角色、按压泡泡、资源管理 |
| 碎碎念与对话 | 仅桌宠；人设、自动碎碎念开关与间隔、「说一句」、对话窗口与清空记忆 |
区块顺序按使用频率排列：呈现与位置（含桌宠分身三列）→（桌宠）动作与待机 /（小鲸鱼）表情与台词 →
提示与音效 → 角色与资源 → 厂商额度（选装）→（桌宠）碎碎念与对话。
形态专属的项（含屏幕漫游、动作与待机、分身三列、初始位置、碎碎念）在另一种形态下自动收起，不会留下空块。
控制台整体宽 336px、高度按视口自适应（最高 512px），内容超出时内部滚动；
滚动条 4px 半透明，不会顶出屏幕。
v0.6.8 修复：分身动作选过分类后切不回「自动随机」；首次进入默认差一条滚动条宽度（看起来在「避开滚动条」）；
配置里已开启避让时首进不生效（要手动开关一次）；小鲸鱼形态下三列快捷开关被整行隐藏；开关关闭态拇指不复位（看起来永远是开）。
v0.6.9 修复：未配置单价模型的每轮用量气泡把旧版像素字号当成字号档位，文字被放大 2–4 倍、数字与 tok 被拆成两行，
泡泡撑到超出视口；现按标准消耗气泡的层级（8 / 24 / 2 档）渲染，并让「1082.1k tok」保持单行。
v0.6.9 重做双形态共存：开关在「小鲸鱼 / 桌宠」两种形态下都常驻显示。开启后小鲸鱼留在主挂件、桌宠成为独立实例
（固定在自己屏幕位置），两只各自可点击、可拖动、可调大小、右键各自打开对应形态的菜单页，互不牵连。
开启共存期间，顶部分段只切换控制台当前编辑的形态页（「大小」滑块按页分别调小鲸鱼挂件 / 桌宠独立大小），
不会关闭共存；只有手动关掉「双形态共存」才会按当前选中的形态切回单一形象。
桌宠位置与大小单独保存在 dshw-pet-pos / dshw-pet-scale，窗口缩放只做屏幕内夹取。
共存时桌宠的甩抛以松手点为落地基准（可停在小鲸鱼上方等任意高度，不会被重力一路拉回屏幕底边），
弹弓（双击第二下按住拖）仍按「甩出去」落到屏幕底边。
v0.7.2 更新：
- 修复共存形态下开关菜单小鲸鱼横移：关菜单末尾原本会补一次贴边检测（snapCheck），
贴边结果只改内存位置、不写回 localStorage 锚点；下次打开菜单时的配置补读又把旧锚点套回来，
表现为「开菜单小鲸鱼往边上滑一段、关菜单又跳回去」。现在贴边结果同步落盘，
菜单打开期间的配置补读不再重排挂件位置，关菜单也不再触发贴边。
- 修复共存形态下点击眨眼 / 按压闭眼丢失：表情层入口原先只看「桌宠是否启用」，
共存时桌宠启用但小鲸鱼仍然可见，表情层被整体关掉了；现在仅在「桌宠独占」形态下让位，
共存时小鲸鱼的素材包眨眼、按压闭眼、点击表情照常生效，进入共存时立即贴回当前帧。
- 发布链路：CI「检查版本是否已发布」改为从 package.json 读包名（原先写死上游包名
dsh-whale-widget，版本号撞车时会误判已发布并跳过发版）。
v0.7.1 更新：
- 控制台菜单换成新版紧凑设计：整块菜单按新稿重做 —— 336px 白毛玻璃面板、深蓝主色、8.5–12px 的小字号层级、
分区标题 + 细描边卡片；开关缩成 20×12 轨道、下拉改为「左标签 + 右值」的隐形覆盖式自绘控件，
底栏改为「恢复默认 / 保存配置」。通用开关与桌面位置合并为一张「呈现与位置」卡（大小、
避让滚动条、隐藏菜单、提示气泡、峰谷显示、吸附与翻转、徽标样式、初始位置「回到右下角」）；
「双形态共存」从卡片里移到顶部，成为第三个形态页签（
小鲸鱼 / 桌宠 / 共存，三者互斥），
桌宠的「分身数量 / 动作 / 大小」收进该卡底部三列（数量下拉选「关闭」即收起全部分身），
并按形态顺序排布：呈现与位置 →（桌宠）动作与待机 /（小鲸鱼）表情与台词 →
提示与音效 → 角色与资源 → 厂商额度 →（桌宠）碎碎念与对话。
「提示与音效」整卡默认折叠（不再只折叠细化配置），展开后音量、四路胶囊与各场景细化配置一次全给；
桌宠「动作与待机」、选装「厂商额度」同样默认收起，所有折叠卡统一“整卡收起 / 整卡展开”。
版本号从头部移到页脚中间（恢复默认 / 版本 / 保存配置），点版本号仍可打开「关于 / 自检」；
「动作与待机」改成一个「动作与分类」级联按钮（分类 → 动作），栏位默认显示「全部动作随机」；
级联浮层的长列表不再被 flex 压缩叠字。
- 待机不再卡在同一段：旧实现把待机动画循环 25–45 秒、播完才重新掷骰，看起来像“选完就一直重复一个”。
现按原版 dsh-pet 的 once 语义：待机也作为普通一段播一次，播完立刻进入下一次随机，动作/待机/分类都会正常轮换；
旧的「指定待机动画」入口一并移除（默认全部动作随机）。
- 滚动条全部透明：控制台内的菜单、级联浮层、文本域统一隐藏滚动条轨道与滑块（滚轮/触控板滚动不受影响）。
- 关菜单时一并收起浮层：打开下拉后不选择、直接点菜单外关闭菜单，重开时之前的下拉/级联浮层不会再残留。
- 共存下互撞不再带偏小鲸鱼：桌宠与分身互撞时，反作用力原本会写回主挂件（root）的位置，
共存时主挂件是小鲸鱼、桌宠是独立实例，于是角落里的小鲸鱼会跟着一起抖；现按独立实例分流，
只有非共存（桌宠就在挂件里）才推动 root。
- 菜单打开期间暂停位移互动：打开控制台时主动停止漫游 / 甩抛 / 分身巡游，并在菜单打开期间拒绝新的位移，
避免角色在菜单旁继续走导致菜单反复贴边闪动。
- 动作与待机重新梳理：删除“只在本分类里随机”的中间态。每个分类下拉的第一项统一是
全部动作随机（取消指定动作 → 回到所有动画一起轮播），其余项才是指定动作（反复播这一段）；
待机那栏同样有「全部动作随机」（会一并清掉指定待机动画）。旧版存在 localStorage 的
“分类固定”（
{type:'category'}）在加载时自动作废，不会再出现“切回自动随机后只剩刚点过的分类”。
- 厂商额度改为选装：新增「厂商额度」卡（默认折叠、点标题行展开；气泡显示开关 + 厂商模型下拉 +「+ 添加模型」/「模型与凭据」入口 +
火山 coding plan 额度开关）。气泡显示默认关闭，打开后自动把所选厂商模型的额度行追加进泡泡，
关闭即移除 —— 只在下一次渲染时注入，不写进你的泡泡配置，泡泡编辑器里的模块保持原样。
火山额度也改为默认关闭：关闭时整行隐藏、完全不请求
volc-usage 附属插件，开启后才拉起并每 120 秒刷新一次。
三项配置沿用同一套落盘链路（.dsh-size.json 的 vendorQuotaOn / vendorQuotaModel / volcQuotaOn），
「恢复默认」会一并回到全关。
- 滚轮缩放角色：鼠标停在角色身上（按命中轮廓判定，透明留白处不触发）向上滚放大、向下滚缩小，
一格走一档、与「大小」滑块档位一致（小鲸鱼页 1–20 / 桌宠页 4–20），到上下限自动停住；
触控板小增量累积够一格距离才走一档，滚动停顿超过 400ms 重新起算。共存时按指针所在的那只角色缩放
（先判上层独立桌宠、再判小鲸鱼），互不牵连；拖动/飞行中不缩放，
Ctrl/⌘+滚轮留给浏览器页面缩放，
菜单里的滚轮仍归菜单自己。缩放结果沿用各自的保存链路（setScale 落盘 / dshw-pet-scale）。
- 共存下调桌宠大小，分身不跟着变：分身尺寸的基准在共存态读错了变量（读的是挂件形态的
petFitH，
共存时它恒为 0），现按当前形态取 petStandFitH / petFitH，并在主宠尺寸重算后统一重排分身（以脚底为基准，
不会越缩越往下坠）。
- 桌宠素材缺失改为明确指引：
/dsh-whale/pet-animations.json 在素材缺失时不再返回 ok:true + 空数组，
而是 ok:false + error:"pet-assets-missing" + （ / / ）+ + ；
前端 toast 与控制台直接给出「装最新版 / 素材该放哪个目录」的可执行步骤。
同时修掉「素材缺失过一次后再点桌宠会进入空白桌宠」的缓存短路问题。
「提示与音效调度」的四个 Tab：
- 按压：音效组下拉、新建音效组、试听、点按角色快捷关闭提示气泡。
- 消耗：任务结束音（开关 + 音效下拉 + 试听）、气泡提示卡片、自定义文案、自动关闭时间（3s / 5秒 / 10s / 常驻）、子智能体完成时不提示。
- 提问 / 授权：音效（含「静音（不播放）」项）、试听、提示音量（0–200%）、冒泡提醒、编辑文案。
桌宠菜单要点：
-
动作与待机：13 个分类各一个下拉；选择具体动作即固定循环，自动随机 只在该分类内轮播。
-
漫游与位置：屏幕漫游为开关、回到初始位置为「一键复位」。
-
分身：勾选「开启分身」 + 数量步进器、分身动作、分身 1/2/3 大小；关闭开关即全部收回。
-
每个分类下拉里的 自动随机 = 只在该分类内轮播；选中具体动作 = 固定循环。
-
「待机」只有「待机呼吸休闲」一项；选它会清掉固定项、回到待机语义。
-
固定项与自定义待机保存在浏览器 localStorage（dshw-pet-pin / dshw-pet-idle），刷新和重启后保持。
-
贴左吸附时整体镜像；带文字的台词动作会反向抵消镜像，画面文字始终正读，峰谷徽标也不会被人物遮挡。
-
小鲸鱼 / 桌宠都支持右键角色打开同一个主菜单，再右键一次关闭；隐藏菜单按钮后仍然有入口（手机端长按约 1.5 秒）。
菜单打开时气泡自动淡出，避免与下拉互相遮挡。
v0.6.3 补齐的 dsh-pet 原版能力
- 点击 Q 弹：点角色立刻垂直压扁再回弹（底部锚定）；
prefers-reduced-motion 时自动跳过。
- 弹簧拖拽：拖动不再是硬跟手，位置以过阻尼弹簧追赶指针（K=200 / C=30），抹平高频抖动。
- 甩抛与反弹：松手速度超过 500px/s 即甩出——重力 1400px/s²、四边反弹（恢复系数 0.78）、
地面摩擦与静止判定；落地按冲击速度触发 Q 弹与语音。
- 屏幕漫游：移动类动画（螃蟹走路等）会按动画时长横向走 60–150px，到边界自动停在原地；
开启后每 25–45 秒会主动插一段走动（即使固定了某个动作也会走完再回到固定动作），不会"开了没效果"；
漫游/甩抛结束后落点作为自由位置保存（
localStorage 的 dshw-pos）。
- 分身与碰撞：最多同屏 3 只，独立动画链、独立位置；可单独点击/拖拽/甩抛
（点击与主宠一样有按压音效和 Q 弹回应，消息气泡会出现在所点的那只分身上方；
右键任意分身直接打开主菜单，菜单出现在右键位置上方，不必再去找主宠），
主宠与分身、分身之间会按法线弹开并互相撞飞。
碰撞采用「位置分离 + 动量交换 + 每对 500ms 冷却」，不会出现多只重叠后无限互撞的鬼畜循环。
数量与位置分别保存在
dshw-pet-clones / dshw-pet-clone-pos。
- 分身动作可调：「分身动作」可选择自动随机、跟随主宠当前动画，或固定在
转向 / 拖拽 / 移动 / 点击回应 / 小动作 / 玩耍 / 吃什么 / 时节 / 文字 / 余额档位 / 碎碎念 / 工作状态
某一类内轮播；下拉即生效，选择保存在
dshw-pet-clone-pin。
- 分身大小可调：每只分身单独一行「分身N大小」（跟随主宠 / 40%~120%，默认 78%），
以脚底为基准缩放并自动夹回视口；碰撞盒与命中区随尺寸同步，保存在
dshw-pet-clone-scale-<序号>（follow = 跟随主宠）。
- 大小联动：选择「跟随主宠」后分身与主宠同尺寸；调整主宠「大小」时，
所有分身会一起重算（固定百分比按新主宠尺寸等比缩放，跟随模式直接同尺寸）。
- 点击积分：飞行中（速度 ≥ 400px/s）按下角色瞬间爆发粒子，并弹出
+N 分数卡片
（分数 = 速度/100 × 462/角色尺寸，越快/越小分越高）；本次不再重复播放普通点击回应。
- 双击弹弓：320ms 内第二次按住角色并拖动，松手时按拉距的反方向弹射；
力度只由拉距决定、不设手速上限，弹射后仍复用重力/反弹/落地 Q 弹。
- 回到初始位置：清除飞行/漫游状态，主宠回右下角，分身依次排到它左侧。
泡泡编辑器
- 点击序列：首次点击、再次点击队列可任意增删排序；两项可并列成 A/B 加权选择。
- 模块化内容：文本、超链接、随机语句（带权重、防连抽）、图片/动图、随机图片、总余额、赠金、
充值余额、今日已用、峰谷时段、对话名；每条支持独立字体、字号、颜色、跑马灯、底色。
- 排版：桌面原生拖拽、移动端长按拖拽；每行最多 6 个模块，泡泡最多 6 行；图片模块独占一行。
- 模块库：常用模块另存后可在任意泡泡复用。
- 手写
.dshw-bubble.json 是全量替换：items 就是整条序列；写坏或想恢复，删掉该文件即可。
未知 kind、modules 非数组或并列无候选时，宿主会忽略该文件并在日志里给出原因。
表情素材包
随包提供 5 套素材（assets/v1 ~ v5），每套由 pack.json 自描述。菜单里可切换素材包、
手动锁定表情；支持情绪映射（连点生气、悬停害羞、空闲失落）、空闲眨眼、随机卖萌，
以及当前模型额度 ≥90% 时的疲惫表情。自定义素材包放到 $DSH_HOME/whale-expressions/<id>/。
音效与提示
- 四个入口：按压音效、每轮消耗提示、提问提示、授权提示。
- 每个音效有独立开关、独立音量和试听；入口行显示当前摘要，点开才展开设置。
- 音效组内置 小黄鸭、音效1、小黄鸭-卟呲卟呲、冰冰冰、哼不理你了、Q弹、委屈；
后五者都是单段短音，只占按压槽（松开留空，不会同一次点按重复响）。
- 面板内改动只落内存，点「保存」才生效；「恢复默认」后点取消仍可撤销。
- 任务结束音内置
A 与 Minecraft·经验球；可导入自定义音频片段。
- 桌宠语音（v0.6.4 起）：点击主宠/分身播当前「按压音效组」的按压音（默认小黄鸭，选
冰冰冰 即播冰冰冰）；
拖动与甩抛保持安静；轻落 Q弹、重摔 委屈（均可作为音效组单独选用）。
音量跟随「按压音量」，总开关跟随音效总开关。
火山 coding plan 额度
plugins/volc-usage/ 是独立附属插件，读取 $DSH_HOME/.credentials.yaml 里的
VOLCES_ACCESS_KEY_ID / VOLCES_SECRET_ACCESS_KEY（支持多账号），显示方舟额度并在余量不足时
把推理 key 切到余量最大的账号。只做 DeepSeek 可以不装。
自定义 API 与 Codex
- 自定义 API 模型：支持厂商模板、凭据名、接口字段、自定义单价、额度与用量累计；密钥不写入配置文件。
- Codex 本地统计：可选读取
~/.codex/sessions，按天/模型聚合本机 Codex 用量；只读本地文件，不含凭据。
本仓库与官方的关系
本仓库基于官方 MeteorNOX/DeepSeek-Balance-Whale-Widget（v0.4.2），保留其全部能力，并额外提供：
- 峰谷时段常驻徽标（官方在气泡内，本仓库外移）。
- 桌宠（动画）角色形态与分类动作下拉（内置
dsh-pet 动画链）。
- 桌宠物理交互：点击 Q 弹、弹簧拖拽、甩抛/重力反弹/地面摩擦、屏幕漫游、多只分身与碰撞（v0.6.3）。
- 双形态共存（小鲸鱼与桌宠同时显示，各自独立位置/大小/交互）（v0.6.9）。
- 5 套表情素材包、自定义角色/泡泡图库/音频资源管理。
- 火山 coding plan 额度附属插件。
- 更完整的 CI 审计（路由安全、设置死键、并列候选、泡泡配置语义）。
Codex 版小鲸鱼已迁至独立仓库 Codex-Whale-Public，
本仓库只维护 DSH Web 与官方桌面客户端。已安装 Codex 版的用户无需重装。
目录与数据
dsh-whale-widget-plus/
├── package.json # DSH bundle 元数据（dsh.bundle.patch / dsh.client）
├── icon.png # 插件列表图标
├── cordis.patch.yml # 插件挂载声明
├── lib/
│ ├── index.js # 宿主侧：路由、记账、音效/图片/角色服务
│ ├── client.js # 客户端生命周期
│ └── accounting.mjs # 记账内核（定点金额 + 观测/校正）
├── assets/
│ ├── whale-widget.js # 前端挂件本体（宿主按 mtime 热读取）
│ ├── console.html # 桌面控制台页面（iframe 加载，precompiled Tailwind）
│ ├── pet-video/ # 106 段桌宠透明动画
│ ├── v1 ~ v5/ # 表情素材包（各含 pack.json）
│ └── DSniang1.png 等 # 角色图、音效、泡泡图
├── plugins/volc-usage/ # 火山 coding plan 额度附属插件
├── tools/ # CI 审计与冒烟脚本
└── whale-widget-prompt.md # 完整规格与二次开发提示
运行时数据默认在 $DSH_HOME（通常是 ~/.dsh）：
| 文件 / 目录 | 用途 |
|---|
.dshw-size.json | 外观与开关（缩放、音量、吸附、每轮消耗关闭秒数等） |
.dshw-usage.json | 记账账本、余额观测/校正、用量与音效设置 |
.dshw-bubble.json | 泡泡点击序列与模块库（手写即全量替换） |
.dshw-api.json | 自定义 API 模型注册表（不含密钥） |
.dshw-usage-archive.json | 超过保留期的明细与逐日归档 |
.dshw-codex.json | Codex 本地统计缓存（不含凭据） |
whale-roles/ whale-audio/ whale-bubble-imgs/ whale-expressions/ | 自定义角色、音频、泡泡图、表情包资源 |
验证
dsh --profile web --dump-config | Select-String -Pattern "whale"
# 端口以 dsh web 启动时打印的 URL 为准，下面假设是 3080
curl http://127.0.0.1:3080/dsh-whale/balance.json
curl http://127.0.0.1:3080/dsh-whale/widget.js
curl http://127.0.0.1:3080/dsh-whale/pet-animations.json
/dsh-whale/balance.json → {ok, totalBalance, currency, todayUsage}/dsh-whale/widget.js → 前端挂件本体/dsh-whale/pet-animations.json → 桌宠动画清单：素材在位时 {ok:true, animations:[...]}；
素材缺失时 {ok:false, error:"pet-assets-missing", reason, dir, hint}（见「常见问题」）- 浏览器
Ctrl+F5 后右下角出现挂件
全部 36 个 /dsh-whale/* 路由共用三层信任栅栏（见「访问控制」）。不带会话凭据的裸 curl
返回 401（伪造 Host 为 403）是预期行为，不代表接口坏了；写请求还必须是本机来源。
常见问题
- 挂件不出现：确认安装规格是
github:louke6572/dsh-whale-widget-plus（不是裸包名，
裸包名在 npm 上不存在）；dsh --profile web --dump-config
能看到它；重启 dsh web 后刷新。桌面端确认装在 desktop profile，并完全退出客户端再打开。
- npm 装不上：本包未发布 npm（404），这不是故障。请用
github:louke6572/dsh-whale-widget-plus
或本地 link: 安装。
- 桌宠提示「素材未安装」：说明安装包里没有
assets/pet-video/（v0.6.8 及更早的 GitHub 提交确实没带这 106 段），
先重装最新版 github:louke6572/dsh-whale-widget-plus（不要锁旧 commit）；
仍缺就把 106 段 .webm 放进插件目录的 assets/pet-video/ 再刷新。
想看宿主判定原因：curl http://127.0.0.1:<dsh web 端口>/dsh-whale/pet-animations.json 会回 reason 与 dir。
- 余额报「未配置 DEEPSEEK_API_KEY」：配置 API key，或在「设置 → 账号与余额」登录 DeepSeek 账号。
- 保存设置报 403：写操作只能在运行 DSH 的本机、用
127.0.0.1 打开时进行；远端管理用 DSHW_ADMIN_HOSTS 声明。
- 提示「该地址不是内置端点，已拒绝发送凭据」：自定义网关需在本机面板对该模型勾选「允许把凭据发送到自定义地址」。
- 今日已用显示
--：等待一次成功的余额观测；统计从该时刻开始，之前的消费不计入。
- 今日已用与官网不一致：核对同一账户、同一币种、同一区间；充值与消费同区间时用「余额校正」补录到账金额。
- 每轮消耗/任务结束音不出现：在「音效与提示 → 全局设置」展开「每轮消耗提示」，确认左侧开关与音量；一轮完整结束才结算。
- 等待提问/授权的气泡关不掉：点一下气泡即可收起；也可在音效面板底部开启「点按角色关闭提示气泡」。
- 隐藏了菜单按钮：电脑端右键角色，手机端长按约 1.5 秒。
- 改了前端不生效：
assets/whale-widget.js、assets/console.html 按 mtime 热读取，硬刷新即可；
改 lib/index.js 必须重启 dsh web。
定价表
金额按 CNY / 百万 tokens，格式为 [空闲, 高峰]。高峰 = 工作日 9:00–12:00、14:00–18:00
（北京时间），空闲价为高峰的一半；周末、调休上班的周末与法定节假日全天按空闲价（2026-08-23 / 09-19 起）。
| 模型 | 缓存命中 | 缓存未命中 | 输出 |
|---|
deepseek-flash（V4.1-Flash） | 0.02 / 0.04 | 1 / 2 | 4 / 8 |
deepseek-v4-pro（V4 Pro） | 0.15 / 0.30 | 4.5 / 9.0 | 13.5 / 27.0 |
旧名 deepseek-v4-flash、deepseek-v4-flash-vision-exp 仍按 Flash 价计费。
开发与维护
lib/index.js（宿主）、lib/client.js（生命周期）、lib/accounting.mjs（记账内核）、
assets/whale-widget.js（前端）、assets/console.html（控制台）。宿主改动需重启 dsh web，前端改动硬刷新即可。- 本地联调：
dsh plugin --profile web add link:.。
- 脚本（
tools/）：
node tools/ci-audit.mjs --no-pack：路由安全 / README 路由条数 / 打包可运行 / CI 覆盖 / 动态 HTML 来源。node tools/ci-audit-selftest.mjs：上面那套审计自身的用例。node tools/check-dead-settings.mjs：设置键的死键检查（运行时读点 + 契约表）。node tools/expr-smoke.mjs：表情包清单/路由/配置键冒烟（mock 宿主，不联网）。node tools/z-layer-audit.mjs、tools/bubble-config-audit.mjs、tools/choice-options-audit.mjs：分层/泡泡/并列候选专项。
- 完整规格与视觉参数见
whale-widget-prompt.md。
致谢
两个插件的原作者
本分支
- louke6572：本仓库（Plus 分支）的维护者，负责峰谷常驻徽标、
桌宠集成与分类动作下拉、镜像/布局修复、资源包与 CI 审计等增强。
社区贡献
许可证
代码基于 MIT License，详见 LICENSE。
assets/ 下的美术素材、动图与音效不在 MIT 覆盖范围内，按「原样」随插件分发，仅供运行本插件使用；
逐项来源、元数据清理与权利主张方式见 PROVENANCE.md。
