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，其余空闲；2026-08-23 起周末全天按谷价）实时换算今日已用
• 💬 每轮对话消耗统计：监听本机会话事件，每轮对话结束后弹出本轮消耗金额（精确 usage，非估算）
  • 菜单可开关「每轮对话后自动显示消耗金额」；「自动关闭时间」可自定义秒数（填 0 表示不自动关闭）
  • 消耗金额泡泡显示期间，余额变动不弹普通泡泡
• 🖱️ 拖拽 + 四边四分之一吸附（左/右/上/下，角落可组合）
• 🔄 左吸附时整体水平镜像翻转（文字同步反向、带动画）
• 🧸 按压 Q 弹玩偶效果（按压时底部坐标不变）
• 🎚️ 汉堡菜单（悬停鲸鱼右上角出现）：大小滑块（0.6–2.5 倍）、音效切换（小黄鸭 / 音效1）、音量调节、用量模式、峰谷提示文案（默认 / 梁文峰谷 / !?强强?!）、气泡开关、每轮消耗开关与自动关闭时间
• 🔊 音效：按压/松手音效（可选包内 mp3，缺失时静默降级）
• 💬 随机台词：点击气泡切换随机台词段（加权随机，含峰谷提示/今日已用/gif 动图/卖萌吐槽），再点一次关闭；气泡总显示 5 秒自动收起
• 📐 随浏览器窗口自动缩放；文字位置/字号与图片联动

目录结构

dsh-whale-widget/
├── package.json          # DSH bundle 插件元数据
├── README.md             # 本文件
├── cordis.patch.yml      # 插件挂载声明
├── lib/
│   └── index.js          # 宿主侧插件本体
├── assets/
│   ├── DSH2.png          # README 顶部展示图
│   ├── DSniang1.png      # 小鲸鱼本体（cut-out，气泡由代码绘制）
│   ├── DSniang02.png     # 备用整图（兼容旧版手动安装路径）
│   ├── rua.gif           # 随机台词 gif（可选）
│   ├── Ya1.mp3 / Ya2.mp3 # 小黄鸭音效（可选）
│   └── D1.mp3 / D2.mp3   # 音效1（可选）
└── whale-widget-prompt.md # 完整规格/维护提示词

安装

方式 A：本地安装（推荐，从当前仓库）

在仓库根目录（DeepSeek-Balance-Whale-Widget，即 package.json 所在目录）执行：

dsh plugin --profile web add link:.

说明：

• dsh plugin 会把参数转发给 pnpm，并在成功后自动把 dsh-whale-widget 加入 dsh.profile.bundles
• link:. 表示链接当前目录（仓库根目录本身就是插件包）。如果你复制了仓库到别处，用绝对路径：

  dsh plugin --profile web add link:D:\你的路径\DeepSeek-Balance-Whale-Widget
  

• ⚠️ 不要用 link:.\dsh-whale-widget——仓库里没有 dsh-whale-widget/ 子目录，这样会安装成普通依赖而非插件，重启后挂件不出现
• 安装完成后重启 dsh web，再 F5 刷新浏览器
• 如果之后移动了源码目录，必须重新执行一次 dsh plugin --profile web add link:.<新路径>。若提示已存在/冲突，先 dsh plugin --profile web remove dsh-whale-widget 再重新 add

方式 B：发布到 npm 后安装

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

给 AI 的安装说明（用 dsh 辅助安装时，直接复制给 AI）

如果你希望让另一个 DSH / AI 助手帮你安装，把下面这段发给它即可：

请帮我安装插件 dsh-whale-widget，来源是 GitHub 仓库 MeteorNOX/DeepSeek-Balance-Whale-Widget。

步骤：
1. 确保 pnpm 可用（没有就先：npm install -g pnpm）
2. 在 Web profile 安装：
   dsh plugin --profile web add dsh-whale-widget
   如果要从本地仓库链接安装（例如本地克隆的仓库根目录），则用：
   dsh plugin --profile web add link:.<仓库绝对路径>
   （注意：仓库根目录就是插件包，不要写成 link:.\dsh-whale-widget 这种带子目录的路径）
3. 如果报 pnpm 阻止构建脚本（allowBuilds 相关），在 C:\Users\<用户名>\.dsh\profiles\web\pnpm-workspace.yaml 的 allowBuilds 下加对应的包 key，然后重跑
4. 重启 dsh web，然后 F5 刷新浏览器

安装后验证：
- dsh --profile web --dump-config 应该能看到 dsh-whale-widget 在 bundles 里
- curl http://127.0.0.1:3080/dsh-whale/balance.json 应返回 200 JSON（含 totalBalance）
- curl http://127.0.0.1:3080/dsh-whale/widget.js 应返回 200 JS

另外请检查 DSH 凭据里是否配置了 DEEPSEEK_API_KEY（没有就提示用户配置；DEEPSEEK_PLATFORM_TOKEN 可选，不配也能用默认的记账模式）。

关于令牌（安装后必读）

默认不需要任何令牌。 安装后只需配置 DEEPSEEK_API_KEY（拉取余额必需），「今日已用」会自动使用默认的小鲸鱼记账模式（余额差值本地记账），开箱即用。

「实时·令牌」模式用到的 DEEPSEEK_PLATFORM_TOKEN（DeepSeek 平台网页会话令牌）是可选的，仅在你想要更精确的实时用量换算时才需要配置。获取方式见下方「用量模式使用教程」。

卸载

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

从旧手动安装升级

…