MeteorNOX/DeepSeek-Balance-Whale-Widget · 上手攻略

仓库：MeteorNOX/DeepSeek-Balance-Whale-Widget
链接：https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget
分类：dsh-plugin / 界面增强
作者：Tom
更新：2026-08-23

是什么

DeepSeek-Balance-Whale-Widget（DSH 小鲸鱼挂件）是 DeepSeek Harness（DSH）Web 界面的右下角常驻余额气泡组件。以一只卡通小鲸鱼娘的形态实时显示 DeepSeek 账户余额、今日消耗金额，以及每轮对话的具体 token 费用。零配置即可随 DSH Web 自动启动，属于标准 DSH bundle 插件包。

解决什么问题

DeepSeek API 按量计费，用户在频繁使用 DSH 对话时很难直观感知余额消耗。DeepSeek 后台网页需要手动刷新才能看到数字，而小鲸鱼挂件常驻界面右下角，每 60 秒自动刷新余额，余额变动时数字以滚动动画呈现，让你Coding 过程中不必切换页面就能掌握账户状态。

快速安装

前提：已有 DSH（DeepSeek Harness）环境，且 pnpm 可用。

# 在 DSH Web profile 安装（从 GitHub 仓库直接安装）
dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget

# 本地仓库链接安装（已克隆仓库的情况）
cd /path/to/DeepSeek-Balance-Whale-Widget
dsh plugin --profile web add link:.

# 验证是否安装成功
dsh --profile web --dump-config | grep whale

安装后重启 DSH Web，然后按 F5 刷新浏览器，右下角应出现小鲸鱼。

⚠️ 注意：不要写成 dsh plugin --profile web add link:./dsh-whale-widget，仓库根目录本身就是插件包，不是 dsh-whale-widget/ 子目录。

核心用法

凭据配置

挂件需要配置 DeepSeek API Key（用于拉取余额）：

DEEPSEEK_API_KEY = sk-xxxxxxxxxxxx   # 必需，从 api.deepseek.com 获取
DEEPSEEK_PLATFORM_TOKEN = Bearer eyJ...  # 可选，平台会话令牌，用于"实时·令牌"用量模式

配置方式：通过 DSH 凭据服务（ctx.credentials.resolve）注入，插件本身不落盘存储。

两种用量模式

模式	是否需要令牌	说明
小鲸鱼记账（默认）	否	余额差值自动记账，跨天自动归零，零配置
实时·令牌	需要 `DEEPSEEK_PLATFORM_TOKEN`	调用平台用量接口，按 DeepSeek 峰谷定价表精确换算

峰值时段：工作日 9:00–12:00、14:00–18:00（2026-08-23 起周末全天按谷价）。峰谷定价表硬编码在 lib/index.js 顶部 PRICING 常量，调价时需手动修改该常量。

菜单配置（汉堡菜单）

鼠标悬停鲸鱼右上角呼出菜单，可调节：

大小：0.6–2.5 倍滑块，记忆到 ~/.dshw-size.json
音效：按压/松手音效（小黄鸭 / 音效1），可选 mp3 文件（缺失静默降级）
音量：0–1 滑块
用量模式：记账 or 令牌
每轮对话消耗：开关 + 自动关闭秒数（填 0 不自动关闭）

API 验证端点

# 查看挂件是否正常
curl http://127.0.0.1:3080/dsh-whale/balance.json
# 返回 {"ok":true,"totalBalance":...,"currency":"CNY","todayUsage":...}

curl http://127.0.0.1:3080/dsh-whale/last-turn.json
# 返回最近一轮对话消耗 {"seq","turn","amount","tokens"}

curl http://127.0.0.1:3080/dsh-whale/image.png
# 返回小鲸鱼 PNG 图片

卸载

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

若之前手动安装过旧版（whale-balance.mjs），需先清理 ~/.dsh/profiles/web/ 下的旧文件，并从 cordis.patch.yml 中删除旧补丁段，再重新 add。

典型适用场景

日常 DSH 重度用户：每次打开 DSH Web 自动看到余额，不需要专门打开 DeepSeek 后台
多轮对话消耗追踪：每轮对话结束后弹出精确 usage 换算金额（非估算）
预算管控：今日已用金额一目了然，防止意外超支
开发者调试：快速感知 token 消耗规律，辅助优化 prompt

坑与注意

⚠️ DSH 关闭期间的消耗会漏记：小鲸鱼记账模式依赖"余额下降差值"，DSH 未运行时若 DeepSeek 账户有其他消费，这部分不会记入当天用量。精确计量需用令牌模式。

⚠️ DEEPSEEK_PLATFORM_TOKEN 有效期有限：这是平台网页会话令牌，重新登录后可能失效，需要重新获取。每次配置后留意是否报"未授权"。

⚠️ 图片不显示的排查：确认 assets/DSniang1.png 在插件包内，且 profile 目录没有旧版同名文件占用路由。

⚠️ macOS 签名警告：下载的 exe/dmg 未经过系统签名，首次运行会有 Gatekeeper 和"允许应用修改 Discord"两次弹窗，点"打开"即可，并非软件损坏。

⚠️ Discord 更新后插件失效：macOS 上 Discord 更新会替换整个 .app，injection 丢失，需重新打开 GoLiveBypass 激活。Windows 端 standalone 尝试自动处理。

与同类对比

方案	平台	特色	局限
DeepSeek 后台网页	Web	官方权威	需手动刷新，不直观
DeepSeek-Balance-Whale-Widget	DSH Web 插件	常驻右下角，动画美观，两种记账模式	仅限 DSH 用户
Codex-Usage-Ball	DSH 插件	OpenAI Codex 专用	不支持 DeepSeek
手动 cron + 通知脚本	任意	完全可控	需手写，界面粗糙

小鲸鱼挂件是 DeepSeek 用户体验最顺滑的余额监控方案，与 DSH 本身深度整合，不引入额外界面。

一句话推荐结论

在 DSH 上重度使用 DeepSeek 的用户，必装——零门槛、零配置，随 DSH 自启，余额一目了然，再也不怕不知不觉烧光余额。

⚠️ 关键未核实项：DeepSeek 峰谷定价表的具体数字（lib/index.js 中 PRICING 常量）需以 DeepSeek 官方最新定价页为准，2026-08-23 之后调价请自行核对。