deepseek-balance-whale-widget

DSH 小鲸鱼余额挂件（DeepSeek Balance Whale Widget）

DeepSeek Harness（DSH）Web 界面右下角的常驻余额挂件：小鲸鱼气泡图 + DeepSeek API 余额 + 今日已用，每次打开界面自动启用。本项目是标准 DSH 插件包，可通过 dsh plugin 安装/卸载。

特性

• 🐋 常驻自启：随 DSH Web 界面每次打开自动出现（标准 DSH bundle 插件）
• 💰 余额：60 秒自动刷新 + 点击鲸鱼手动刷新；余额变化时数字滚动动画；瞬时网络抖动自动沿用最近余额不报错
• 📊 今日已用：两种模式任选（见下），显示今日消耗金额
  • 小鲸鱼记账（推荐，免令牌）：不需要任何会话令牌，鲸鱼娘每次观测余额后用余额差值自动记账（.dshw-usage.json，跨天自动归零归档）
  • 实时·令牌：填入平台会话令牌后直接调用平台用量接口，按峰谷定价（空闲 9:00–12:00 与 14:00–18:00 之外 / 高峰 9–12 与 14–18 点）实时换算今日已用
• 🖱️ 拖拽 + 四边四分之一吸附（左/右/上/下，角落可组合）
• 🔄 左吸附时整体水平镜像翻转（文字同步反向、带动画）
• 🧸 按压 Q 弹玩偶效果（按压时底部坐标不变）
• 🎚️ 汉堡菜单（悬停鲸鱼右上角出现）：大小滑块（0.6–2.5 倍，尺寸记忆）、音效切换（小黄鸭 / 音效1）、音量调节、用量模式选择
• 🔊 音效：按压/松手音效（可选包内 mp3，缺失时静默降级）
• 💬 随机台词：点击气泡切换随机台词段（6 组加权随机，含峰谷提示/今日已用/卖萌吐槽），再点一次关闭；气泡总显示 5 秒自动收起
• 📐 随浏览器窗口自动缩放；文字位置/字号与图片联动

目录结构

dsh-whale-widget/
├── package.json          # DSH bundle 插件元数据
├── README.md             # 本文件
├── cordis.patch.yml      # 插件挂载声明
├── lib/
│   └── index.js          # 宿主侧插件本体
├── assets/
│   ├── DSniang1.png      # 小鲸鱼本体（cut-out，气泡由代码绘制）
│   ├── Ya1.mp3 / Ya2.mp3 # 小黄鸭音效（可选）
│   └── D1.mp3 / D2.mp3   # 音效1（可选）
└── whale-widget-prompt.md # 完整规格/维护提示词

安装

方式 A：本地开发安装（当前项目）

在项目根目录（DeepSeek-Balance-Whale-Widget-main）执行：

dsh plugin --profile web add link:.\dsh-whale-widget

说明：

• dsh plugin 会把参数转发给 pnpm，并在成功后自动把 dsh-whale-widget 加入 dsh.profile.bundles
• 使用 link: 会在 profile 的 node_modules 里链接到当前源码目录，方便继续改代码
• 安装完成后重启 dsh web，再 F5 刷新浏览器
• 如果之后移动了源码目录，必须重新到新的项目根目录执行一次：

  dsh plugin --profile web add link:.\dsh-whale-widget
  

  因为 link: 记录的是源目录的绝对路径；移动后旧链接会失效。若提示已存在/冲突，可先 dsh plugin --profile web remove dsh-whale-widget 再重新 add。

方式 B：发布到 npm 后安装

如果你把这个包发布到 npm：

cd dsh-whale-widget
npm publish

然后任意机器上安装：

dsh plugin --profile web add dsh-whale-widget

卸载

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

从旧手动安装升级

如果你之前按旧方式手动安装过（复制 whale-balance.mjs + 改 cordis.patch.yml），先清理：

$web = "$env:USERPROFILE\.dsh\profiles\web"

Remove-Item "$web\whale-balance.mjs" -ErrorAction SilentlyContinue
Remove-Item "$web\whale-balance.cjs" -ErrorAction SilentlyContinue
Remove-Item "$web\DSniang1.png" -ErrorAction SilentlyContinue
Remove-Item "$web\DSniang02.png" -ErrorAction SilentlyContinue

然后编辑 $web\cordis.patch.yml，删除这段旧补丁：

- insert:
    - id: whale-balance-widget
      name: ./whale-balance.mjs?v=1

如果里面只有这段，直接改成：

[]

清理后再执行上面的安装命令。

凭据与用量模式

• 余额：需要 DEEPSEEK_API_KEY（在 DSH 凭据服务中配置），用于 api.deepseek.com/user/balance
• 实时·令牌模式：需要 DEEPSEEK_PLATFORM_TOKEN（平台会话令牌，从浏览器 DevTools 的用量请求 Authorization 头获取），用于 platform.deepseek.com/api/v0/usage/by_api_key/amount
• 小鲸鱼记账模式（默认）：不需要平台令牌，鲸鱼娘用余额差值自动记账，跨天自动归档

验证

dsh --profile web --dump-config | Select-String -Pattern "whale"

curl http://127.0.0.1:3080/dsh-whale/image.png
curl http://127.0.0.1:3080/dsh-whale/balance.json
curl http://127.0.0.1:3080/dsh-whale/size.json

• /dsh-whale/image.png → 200 image/png
• /dsh-whale/balance.json → 200，含 {"ok":true,"totalBalance":...,"currency":"CNY","todayUsage":...}
• /dsh-whale/size.json → GET 返回 {scale,sound,vol,soundSet,usageMode}；PUT 写入
• 浏览器 F5 后右下角出现挂件

常见问题

• 挂件不出现：确认 dsh plugin add 成功；dsh --profile web --dump-config 里能看到 dsh-whale-widget；重启 dsh web 后 F5。
• 图片不显示：确认 assets/DSniang1.png 在插件包内，且没有把旧文件放在 profile 里占用了同名路由。
• 余额报「未配置 DEEPSEEK_API_KEY」：去 DSH 配置凭据。
• 今日已用显示 --：记账模式下需要先跑一次余额观测（60 秒内自动完成）；令牌模式需要配置 DEEPSEEK_PLATFORM_TOKEN。
• 没有声音：确认 assets/*.mp3 在包内；若不想带音效文件，静默降级为无声音。
• 本地开发改了代码不生效：使用 link: 安装时，修改源码后重启 dsh web（ESM 模块缓存）；如果用已发布版本，需要 npm publish 新版本后 dsh plugin --profile web update dsh-whale-widget。
• 自定义图片：气泡由代码绘制（SVG），鲸鱼本体为 cut-out PNG，放在右下角 59.45%；换图需保证透明背景 cut-out，否则按 whale-widget-prompt.md 调整几何参数。

开发与维护

完整规格、视觉参数、架构结论和生成提示词见 whale-widget-prompt.md。修改文字位置、颜色、动画、吸附逻辑、台词组或定价表时参考该文件。