- Language
- JavaScript
- Branch
- main
cordisdeepseekdeepseek-harnessdeveloper-toolsdshdsh-plugindsh-pluginsfloating-widget
DSH Web 界面右下角的小鲸鱼余额挂件：实时显示 DeepSeek API 余额、今日已用（差额记账或按峰谷定价），可拖拽吸附与个性化。
$ dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-WidgetRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
这是一个常驻 DSH Web 界面右下角的小鲸鱼余额挂件，每隔 60 秒自动拉取 DeepSeek API 余额并显示当日消费金额。它通过余额差值自动记账，或读取平台令牌按峰谷定价实时换算，让你在不打开 DeepSeek 后台的情况下随时掌握账户消耗。
node:fs、node:path、node:os、node:url）与全局 fetch、AbortSignal.timeout，无第三方 npm 包dsh.bundle.patch（cordis.patch.yml）声明插入 Web profile；宿主侧注册 6 条 webServer 路由 + tapIndex 注入客户端脚本到 index.htmllib/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 凭据里点几下就能配好；进阶玩法（实时令牌、峰谷定价）按需开启。
D:/TestBox/deepseek/... 作为图片 / 音效 / 账本文件的降级兜底（lib/index.js:17-22、lib/index.js:44-50），对非 Windows 用户无影响但会出现在 fallback 候选列表里Authorization 头手工复制（README.md:110-111），DeepSeek 没有公开该令牌的官方获取流程assets/DSniang1.png），气泡由代码 SVG 绘制；如需换图需保证透明背景 cut-out，否则需要同步调整几何参数（README.md:136）PRICING）以源码常量形式硬编码（lib/index.js:67-74），DeepSeek 调整定价后需要修改源码并发布新版本lib/index.js:1167-1191 的差值逻辑），这意味着如果充值与消费在同一天交错，最终的当日用量可能与实际消费有出入