dsh-whale-widget-plus

DSH 小鲸鱼挂件 Plus

DeepSeek Balance Whale Widget Plus · v0.6.8

DSH（DeepSeek Harness）右下角的常驻小鲸鱼挂件：余额、今日已用、每轮消耗、峰谷常驻徽标， 外加可自由编辑的泡泡、多套表情素材、提示音效，以及内置的 106 段透明动画桌宠。 支持 dsh web 与官方桌面客户端（Electron）。

本仓库是官方挂件 MeteorNOX/DeepSeek-Balance-Whale-Widget 的增强分支，由 louke6572 维护；桌宠动画来自 PC2005-cloud/dsh-pet（MIT）。来源与致谢见文末。

亮点

• 余额与记账：60 秒自动刷新；余额差 + 会话事件算今日已用；逐轮真实 usage 换算金额；明细保留 90 天、逐日汇总 365 天。
• 峰谷常驻徽标：峰/谷状态与倒计时无需点开气泡，贴在人物左下角；贴左吸附时自动换边。
• 桌宠（动画）角色形态：106 段 VP9-alpha 透明动画，双击缓冲交叉淡入；动作按分类下拉切换，可固定也可自动轮播；v0.6.3 起支持点击 Q 弹、弹簧拖拽、甩抛反弹、屏幕漫游、飞行积分、双击弹弓与多只分身。
• 泡泡编辑器：点击序列、并列加权、模块化排版、随机语句/随机图片、拖拽排序、模块库。
• 表情与音效：5 套表情素材包、情绪/眨眼/卖萌/疲惫；按压/每轮消耗/提问/授权四通道音效，每通道独立音量； 桌宠语音（点击/轻落/重摔）也作为音效组出现在「按压音效组」里；拖动与甩抛不播音效。
• 多厂商与扩展：33 家厂商额度模板、自定义 API 模型、火山 coding plan 额度、Codex 本地会话统计。

安装

安装规格里的包名是 dsh-whale-widget-plus。安装前先确认没有同名的旧版或官方版并存。

DSH Web（dsh web）

任选一种：

# npm（已发布时）
dsh plugin --profile web add dsh-whale-widget-plus

# 直接从 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，浏览器 Ctrl+F5 刷新。若之前装过同名插件，先执行 dsh plugin --profile web remove dsh-whale-widget-plus 再装，避免版本冲突。

官方桌面端（Electron）

桌面端读的是 desktop profile，不能用 --profile web；而 --profile desktop 会被 CLI 拒绝，这是设计如此。正确做法是在桌面客户端会话里让宿主内置的 plugin_manager 安装：

请使用当前桌面端内置的 plugin_manager 安装 dsh-whale-widget-plus。 先核对当前 profile、已安装来源与版本；按工具支持的方式完成后告诉我结果，并说明是否需要重启。

• 首次安装：工具返回 applied 不保证当前窗口已经渲染；没出现就完全退出客户端（含托盘）再打开。
• 升级：优先沿用同一来源通过内置工具更新；返回 restart-required 时完全退出再打开，然后核对实际版本。

升级与卸载

dsh plugin --profile web remove dsh-whale-widget-plus

升级时不要混用 npm、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。今日已用统一由「小鲸鱼记账」（余额差 + 会话事件）计算。

安全边界

1. 凭据只发往厂商模板里写死的端点。自定义地址默认拿不到凭据；确需自建网关时，在本机 打开面板，对该模型勾选「允许把凭据发送到自定义地址」。
2. 写请求只接受本机来源（127.0.0.1 / localhost / [::1]），否则 403；只读接口不受影响。 需要远端管理时用 DSHW_ADMIN_HOSTS=192.0.2.10:3080,myhost.lan 显式声明。
3. 接口地址不允许携带用户名密码；凭据名只允许字母、数字与下划线。 内网 / 回环地址默认拒绝（防 SSRF）；同样只有勾选「允许把凭据发送到自定义地址」的模型才放行。
4. 接口不再下发通配 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 会覆盖上一家的凭据。

功能

记账与显示

• 余额：60 秒自动刷新，点击鲸鱼可手动刷新；余额变化带数字滚动；瞬时网络抖动沿用最近值。
• 今日已用（小鲸鱼记账）：余额下降计为消费，余额上升单独记为充值/赠金，不会冲掉消费； 出现「待核对余额调整」时可在记账面板用「余额校正」补录实际到账金额。
• 每轮消耗：读取本机会话 turn/end 的真实 usage（input / cache / output / reasoning）， 换算金额并弹泡泡；金额按 8 位小数记账，显示保留两位。
• 用量记录：今日消费、近 7 天、全部记录、模型占比、按日展开明细，支持按日期或模型名搜索。
• 模型名标注：deepseek-flash 显示为 DeepSeek-V4.1-Flash，旧名自动归并到同一模型。

峰谷时段显示（v0.4.3 起）

峰/谷状态字 + 距下一时段倒计时外移到人物左下角，不点气泡也能看到；与人物底边对齐， 贴左吸附时自动换到人物右侧。状态字样式可选：峰/谷、梁文峰/梁文谷、高峰/低谷、自定义。

主菜单「峰谷显示」可选三种方式（v0.6.0 起）：

选项	行为
常驻徽标（默认）	左下角常驻；气泡内不重复显示
气泡内	隐藏徽标，恢复上游原版：点开气泡时显示配置里的峰谷/倒计时模块
隐藏	徽标与气泡内都不显示

选择保存在 localStorage 的 dshw-pbmode，修改后立即生效，刷新后保持。 倒计时带描边框，与状态字严格等高，颜色随峰/谷自动红/绿切换。

桌宠（动画）角色形态（v0.5.0 起，v0.6.3 补全物理交互）

在「角色」里选「桌宠（动画）」即可切换，随包带 106 段 VP9-alpha .webm； 双层 video 交叉淡入，换段不出现空白帧。

v0.6.7 起两种形态共用同一个「桌面控制台」菜单（416px 单面板，浅色 Precision Slate 风格）， 不再有「按钮入口 + 独立设置面板」的分裂结构。自上而下：

区块	内容
头部	标题 + 版本徽标（点版本号打开「关于 / 自检」）；滚动时固定在顶部
形态	小鲸鱼 / 桌宠 分段控件，当前形态高亮
大小	1–20 级滑块 + 可编辑数值框（右上角）
快捷开关	避让滚动条（默认关闭＝贴边；开启后在卡片内展开「宽度 px」）/ 屏幕漫游（仅桌宠）/ 隐藏菜单栏
交互与视窗吸附	峰谷状态下拉、吸附与翻转（自定义）、角色位置「一键复位」（仅桌宠）
提示与音效调度	主音量滑块（全局增益）+ 按压/消耗/提问/授权四路胶囊（显示百分比或「静音」）+ 对应 Tab
动作与待机	仅桌宠，折叠卡；13 个分类下拉（待机 / 转向 / 拖拽 / 点击回应 / 移动 / 小动作 / 玩耍 / 吃什么 / 时节 / 文字 / 余额档位 / 碎碎念 / 工作状态），3 列紧凑网格
表情与台词	仅小鲸鱼；眨眼开关、表情包版本（自动 + 第一～第五版）、表情、台词
分身设置	仅桌宠，折叠卡；开启分身开关、数量步进器（最多 3 只）、分身动作、分身 1/2/3 大小
通用设置	两种形态都显示：气泡开关、徽标样式、自定义峰谷文字、导入角色、按压泡泡设置、资源管理、火山额度
底栏	恢复默认 / 完成（吸底）；下方固定「小鲸鱼记账」入口

v0.6.8 修复：分身动作选过分类后切不回「自动随机」；首次进入默认差一条滚动条宽度（看起来在「避开滚动条」）； 配置里已开启避让时首进不生效（要手动开关一次）；小鲸鱼形态下三列快捷开关被整行隐藏；开关关闭态拇指不复位（看起来永远是开）。

「提示与音效调度」的四个 Tab：

• 按压：音效组下拉、新建音效组、试听、点按角色快捷关闭提示气泡。
• 消耗：任务结束音（开关 + 音效下拉 + 试听）、气泡提示卡片、自定义文案、自动关闭时间（3s / 5秒 / 10s / 常驻）、子智能体完成时不提示。
• 提问 / 授权：音效（含「静音（不播放）」项）、试听、提示音量（0–200%）、冒泡提醒、编辑文案。

桌宠菜单要点：

• 动作与待机：13 个分类各一个下拉；选择具体动作即固定循环，自动随机 只在该分类内轮播。

• 漫游与位置：屏幕漫游为开关、回到初始位置为「一键复位」。

• 分身：勾选「开启分身」 + 数量步进器、分身动作、分身 1/2/3 大小；关闭开关即全部收回。

• 每个分类下拉里的 自动随机 = 只在该分类内轮播；选中具体动作 = 固定循环。

• 「待机」只有「待机呼吸休闲」一项；选它会清掉固定项、回到待机语义。

• 固定项与自定义待机保存在浏览器 localStorage（dshw-pet-pin / dshw-pet-idle），刷新和重启后保持。

• 面板高度按视口自适应（最高 700px），超出时面板内部滚动，滚动条透明；不会顶出屏幕。

• 贴左吸附时整体镜像；带文字的台词动作会反向抵消镜像，画面文字始终正读，峰谷徽标也不会被人物遮挡。

• 小鲸鱼 / 桌宠都支持右键角色打开同一个主菜单，再右键一次关闭；隐藏菜单按钮后仍然有入口。菜单打开时气泡自动淡出，避免与下拉互相遮挡。

v0.6.3 补齐的 dsh-pet 原版能力

• 点击 Q 弹：点角色立刻垂直压扁再回弹（底部锚定）；prefers-reduced-motion 时自动跳过。
• 弹簧拖拽：拖动不再是硬跟手，位置以过阻尼弹簧追赶指针（K=200 / C=30），抹平高频抖动。
• 甩抛与反弹：松手速度超过 500px/s 即甩出——重力 1400px/s²、四边反弹（恢复系数 0.78）、 地面摩擦与静止判定；落地按冲击速度触发 Q 弹（轻落 ~0.8、重砸 ~0.55）。
• 屏幕漫游：移动类动画（螃蟹走路等）会按动画时长横向走 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，保留其全部能力，并额外提供：

• 峰谷时段常驻徽标（官方在气泡内，本仓库外移）。
• 桌宠（动画）角色形态与分类动作下拉（内置 dsh-pet 动画链）。
• 桌宠物理交互：点击 Q 弹、弹簧拖拽、甩抛/重力反弹/地面摩擦、屏幕漫游、多只分身与碰撞（v0.6.3）。
• 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 热读取）
│   ├── pet-video/            # 106 段桌宠透明动画
│   ├── v1 ~ v5/              # 表情素材包
│   └── DSniang1.png 等        # 角色图、音效、泡泡图
├── 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/	自定义角色、音频、泡泡图资源

验证

dsh --profile web --dump-config | Select-String -Pattern "whale"
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 → 桌宠动画清单
• 浏览器 Ctrl+F5 后右下角出现挂件

全部 35 个 /dsh-whale/* 路由都接入了 DSH 浏览器信任栅栏。不带会话凭据的裸 curl 返回 401（伪造 Host 为 403）是预期行为，不代表接口坏了；写请求还必须是本机来源。

常见问题

• 挂件不出现：确认安装规格是 dsh-whale-widget-plus；dsh --profile web --dump-config 能看到它；重启 dsh web 后刷新。桌面端确认装在 desktop profile，并完全退出客户端再打开。
• 余额报「未配置 DEEPSEEK_API_KEY」：配置 API key，或在「设置 → 账号与余额」登录 DeepSeek 账号。
• 保存设置报 403：写操作只能在运行 DSH 的本机、用 127.0.0.1 打开时进行；远端管理用 DSHW_ADMIN_HOSTS。
• 提示「该地址不是内置端点，已拒绝发送凭据」：自定义网关需在本机面板对该模型勾选「允许把凭据发送到自定义地址」。
• 今日已用显示 --：等待一次成功的余额观测；统计从该时刻开始，之前的消费不计入。
• 今日已用与官网不一致：核对同一账户、同一币种、同一区间；充值与消费同区间时用「余额校正」补录到账金额。
• 每轮消耗/任务结束音不出现：在「音效与提示 → 全局设置」展开「每轮消耗提示」，确认左侧开关与音量；一轮完整结束才结算。
• 等待提问/授权的气泡关不掉：点一下气泡即可收起；也可在音效面板底部开启「点按角色关闭提示气泡」。
• 隐藏了菜单按钮：电脑端右键角色，手机端长按约 1.5 秒。
• 改了前端不生效：assets/whale-widget.js 按 mtime 热读取，硬刷新即可；改 lib/index.js 必须重启 dsh web。

定价表

金额按 CNY / 百万 tokens，格式为 [空闲, 高峰]。高峰 = 工作日 9:00–12:00、14:00–18:00 （北京时间），空闲价为高峰的一半；2026-08-23 起周末全天谷价。

模型	缓存命中	缓存未命中	输出
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（前端）。宿主改动需重启 dsh web，前端改动硬刷新即可。
• 本地联调：dsh plugin --profile web add link:.。
• CI：node tools/ci-audit.mjs --no-pack 会检查路由安全、README 路由条数、设置死键、 并列候选和泡泡配置语义；node tools/check-dead-settings.mjs 可单独运行。
• 完整规格与视觉参数见 whale-widget-prompt.md。

致谢

两个插件的原作者

• 月匠（MeteorNOX）：官方挂件 DeepSeek-Balance-Whale-Widget 原作者。余额、记账、峰谷定价、泡泡编辑器、音效与安全边界等基础能力均来自该项目。
• PC2005-cloud：dsh-pet 作者（MIT）。本仓库内置的 106 段透明动画、动画链与桌宠交互素材来自该项目。

本分支

• louke6572：本仓库（Plus 分支）的维护者，负责峰谷常驻徽标、 桌宠集成与分类动作下拉、镜像/布局修复、资源包与 CI 审计等增强。

社区贡献

• Codex 端口迁移：Yang-huai406；macOS 适配：@1llysviel。
• 安全与记账：B 站「星丶白羽莲」报告凭据外带风险；@0Sakura721 定位换 key 分本问题；@yybai25 提供账号态余额规格； @Yang-huai406 设计充值记账修复方案。
• 功能与适配：@Jy-EggRoll（提问/授权提示）、 @VaeKaras（下载管理器抢音效）、 @MengLs1620（桌面端生效方式）、 @ELFsay（OpenCode Go 额度）、QQ 群友（提示音量与冒泡开关死键分析）。
• 历史合并 PR：@ztzpro（插件包结构）、 @under-the-ocean（自动发布 npm）、 @21253soursweetlemon（gif 降级、位置记忆）、 @fangbm（多币种、周末谷价、Release 流程）、 @xiaolinnnnnnn（Tauri 桌面端）。

许可证

代码基于 MIT License，详见 LICENSE。

assets/ 下的美术素材、动图与音效不在 MIT 覆盖范围内，按「原样」随插件分发，仅供运行本插件使用； 逐项来源、元数据清理与权利主张方式见 PROVENANCE.md。