DSH Web 界面右下角的小鲸鱼余额挂件：实时显示 DeepSeek API 余额、今日已用（差额记账或按峰谷定价），可拖拽吸附与个性化。
- 语言
- JavaScript
- 分支
- main
安装
$ dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程
对话式安装
帮我安装 DeepSeek Harness 插件 MeteorNOX/DeepSeek-Balance-Whale-Widget：先查看仓库 https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget.git 确认安全性，然后执行安装命令并验证插件加载成功。
把这段指令粘贴给 DSH Web GUI 里的助手，由它代你完成安装与验证。
一句话定位
这是一个常驻 DSH Web 界面右下角的小鲸鱼余额挂件，每隔 60 秒自动拉取 DeepSeek API 余额并显示当日消费金额。它通过余额差值自动记账，或读取平台令牌按峰谷定价实时换算，让你在不打开 DeepSeek 后台的情况下随时掌握账户消耗。
核心能力
- 自动显示 DeepSeek API 账户余额，60 秒刷新一次，点击鲸鱼可立即手动刷新；余额数字带滚动动画
- 通过余额差值自动累计今日消费，跨天自动归零并保留 30 天历史，无需平台令牌
- 可选「实时·令牌」模式：读取平台会话令牌后，按峰谷定价（9–12 / 14–18 高峰，价高 6 倍）实时换算当日消费
- 鼠标拖拽可移动位置，松手后自动吸附到屏幕四边中点（左/右/上/下）；吸附到左边时整体水平镜像翻转，文字同步反向
- 点击鲸鱼显示当前时段（高峰/空闲）与今日已用；点击气泡切换 6 组加权随机台词（含卖萌 / 吐槽 / 峰谷提示），5 秒后自动收起
- 汉堡菜单调节大小（0.6–2.5 倍）、音效（小黄鸭 / 音效1）、音量、用量模式；可选按压 / 松手音效
技术实现
- 语言: JavaScript（ESM）
- 关键依赖: 仅使用 Node 内置模块（
node:fs、node:path、node:os、node:url）与全局fetch、AbortSignal.timeout，无第三方 npm 包 - 架构模式: 标准 DSH bundle 插件，通过
dsh.bundle.patch（cordis.patch.yml）声明插入 Web profile；宿主侧注册 6 条 webServer 路由 +tapIndex注入客户端脚本到index.html - 入口文件:
lib/index.js（同时包含宿主侧 Node 逻辑与内嵌的浏览器端WIDGET_JS字符串）
适用场景
DeepSeek API 重度用户希望在打开 DSH Web 时一眼看到当前余额与当天消费，避免反复登录 DeepSeek 控制台。普通用户用默认的「小鲸鱼记账」模式就能掌握大致花费；愿意配置平台令牌的用户可切到「实时·令牌」模式拿到精确的峰谷分摊费用。适合长跑任务、Agent 长时间运行、多会话并发时作为消费监控仪表。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 未声明 | 标准 DSH bundle 插件，需 Web profile 加载；cordis.patch.yml 中以 dsh-whale-widget 为挂载点 |
| Node.js | ≥ 18 | 源码使用了原生 fetch、AbortSignal.timeout、node:fs 等内置 API；DSH 实际运行通常 ≥ 22 |
| 平台 | 跨平台 | 仅读写 JSON / PNG / MP3 文件，无原生模块；源代码中保留了几条 Windows 开发机硬编码路径（D:/TestBox/deepseek/...）作为旧版降级兜底 |
| 原生模块 | 无 | 不依赖任何原生 Node 扩展 |
| 凭据 | — | DEEPSEEK_API_KEY（必填）用于拉取余额；DEEPSEEK_PLATFORM_TOKEN（可选）用于「实时·令牌」模式 |
安装方式
dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget
配置项
挂件本身的偏好通过 Web 界面右上角汉堡菜单调节并自动持久化到 ~/.dshw-size.json，无需手写配置文件：
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 挂件大小 | 数字滑块（0.6–2.5） | 鲸鱼图标的整体缩放比例，记忆到本地 | 1.5 |
| 音效开关 | 开关 | 按压 / 松手时是否播放音效 | 开启 |
| 音效类型 | 枚举（小黄鸭 / 音效1） | 选择哪一套音效文件 | 小黄鸭 |
| 音量 | 数字滑块（0–1） | 音效播放音量 | 0.9 |
| 用量模式 | 枚举（小鲸鱼记账 / 实时·令牌） | 「今日已用」的计算方式 | 小鲸鱼记账 |
凭据通过 DSH 凭据服务（ctx.credentials.resolve）注入，插件不落盘：
| 凭据 | 是否必填 | 用途 |
|---|---|---|
DEEPSEEK_API_KEY | 必填 | DeepSeek 官方 API Key，用于拉取余额 |
DEEPSEEK_PLATFORM_TOKEN | 可选 | DeepSeek 平台会话令牌，仅「实时·令牌」模式需要 |
常见问题
Q: 需要先配置什么才能看到余额？
A: 必须先在 DSH 凭据服务中配置 DEEPSEEK_API_KEY（DeepSeek 官方 API Key），否则余额区域会显示「未配置 DEEPSEEK_API_KEY」。
Q: 「今日已用」默认显示的是什么模式？
A: 默认是「小鲸鱼记账」模式，不需要任何平台令牌——挂件每次观测到余额下降就把差值累加到当天用量，跨天自动归零并归档。如果想要更精确的数字，可在汉堡菜单切到「实时·令牌」模式并填入 DEEPSEEK_PLATFORM_TOKEN。
Q: 拖动后挂件跑到屏幕中间怎么办？
A: 把鲸鱼拖到屏幕左 / 右 / 上 / 下四边任一中点附近，松手后会自动吸附到对应边；中间区域则停留在你松手的位置。吸附到左边时整体水平翻转，文字也同步反向。
Q: 没声音怎么办？
A: 检查 assets/Ya1.mp3、Ya2.mp3、D1.mp3、D2.mp3 是否随包发布。音频文件缺失时插件会静默降级为无声音（不会报错）。
Q: 本地改了源码不生效？
A: ESM 模块有缓存，改完源码后需要重启 dsh web。如果用的是已发布的 npm 版本，改完需要 npm publish 升版本再 dsh plugin --profile web update dsh-whale-widget。
Q: 余额会保留多久的历史？
A: 「小鲸鱼记账」模式下，.dshw-usage.json 最多保留最近 30 天的每日消费历史，超出后自动清理最早的记录。
Q: 网络抖动时挂件会报错吗？
A: 不会。余额接口对网络错误和 5xx 做了 1 次重试，瞬时抖动时会沿用最近一次成功获取的余额，并把响应标记为 stale=true，前端继续显示旧值而不是报错。
Q: 这个插件会保存我的 API Key 吗？
A: 不会。Key 始终只从 DSH 凭据服务（ctx.credentials.resolve）读取，插件内部既不缓存也不落盘；账本文件 .dshw-usage.json 只存余额差值与日期，不含任何敏感凭据。
上手难度
入门 — 安装即用，唯一必填项 DEEPSEEK_API_KEY 在 DSH 凭据里点几下就能配好；进阶玩法（实时令牌、峰谷定价）按需开启。
已知问题与限制
- 源代码里硬编码了 Windows 开发机路径
D:/TestBox/deepseek/...作为图片 / 音效 / 账本文件的降级兜底（lib/index.js:17-22、lib/index.js:44-50），对非 Windows 用户无影响但会出现在 fallback 候选列表里 - 「实时·令牌」模式依赖 DeepSeek 平台会话令牌，需要从浏览器 DevTools 的用量请求
Authorization头手工复制（README.md:110-111），DeepSeek 没有公开该令牌的官方获取流程 - 鲸鱼本体图片为固定 cut-out PNG（
assets/DSniang1.png），气泡由代码 SVG 绘制；如需换图需保证透明背景 cut-out，否则需要同步调整几何参数（README.md:136） - 价格表（
PRICING）以源码常量形式硬编码（lib/index.js:67-74），DeepSeek 调整定价后需要修改源码并发布新版本 - 「小鲸鱼记账」模式仅在「余额下降」时累加差值，同一天内账户充值或退款导致的余额上升不会被记录为负值（
lib/index.js:1167-1191的差值逻辑），这意味着如果充值与消费在同一天交错，最终的当日用量可能与实际消费有出入
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-widgetlink:记录的是源目录的绝对路径；移动后旧链接会失效。若提示已存在/冲突，可先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→ 200image/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。修改文字位置、颜色、动画、吸附逻辑、台词组或定价表时参考该文件。
收录徽章
[](https://deepseek-plugin.org/plugins/MeteorNOX/DeepSeek-Balance-Whale-Widget)把这段 markdown 粘贴到你的 GitHub README，链接回本插件详情页。徽章只声明已被本站收录，不代表安全认证。