DeepSeek-Balance-Whale-Widget README

The project's README from github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget. As one markdown file: README.md.

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

DSH 小鲸鱼余额挂件

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

特性

目录结构

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：直接从 GitHub 安装（推荐）

无需本地克隆，一条命令安装：

dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget

说明：

方式 B：本地安装（从当前仓库）

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

dsh plugin --profile web add link:.

说明：

方式 C：发布到 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 安装（任选一种来源）：
   首选，直接从 GitHub 安装（无需本地克隆，装完可在插件管理页面里更新）：
     dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-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

从旧手动安装升级

如果你之前按旧方式手动安装过（复制 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

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

[]

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

用量模式使用教程

必需的凭据

两种用量模式

挂件的「今日已用」有两种模式，在菜单 → 用量中选择：

① 小鲸鱼记账（推荐，默认）—— 完全不需要额外配置

鲸鱼娘自己用余额差值记账：每次观测到余额下降就把差值累加到当天用量，跨天自动归零归档（保留 30 天）；观测币种发生变化时只重置基准、不记差值（防止多币种账户切换污染账本）。只要配好了 DEEPSEEK_API_KEY 就能用，开箱即用。

② 实时·令牌（可选）—— 需要 DEEPSEEK_PLATFORM_TOKEN

鲸鱼娘直接调用 DeepSeek 平台用量接口，按峰谷定价实时换算今日已用，精确到每小时的 token 用量。

令牌在哪获取：

  1. 浏览器打开并登录 https://platform.deepseek.com
  2. 按 F12 打开开发者工具 → 切到 Network（网络） 标签
  3. 在平台页面点击「用量」或刷新页面，找到名为 usage/by_api_key/amount 的请求
  4. 点开该请求 → Request Headers（请求标头） → 复制 Authorization 的值（形如 Bearer eyJ... 的一长串）
  5. 把整段值（含 Bearer 前缀或只要后面的 token 部分均可）配置为 DSH 凭据 DEEPSEEK_PLATFORM_TOKEN：
    # 在 DSH 凭据服务中设置，例如编辑 $env:USERPROFILE\.dsh\.credentials.yaml
# DEEPSEEK_PLATFORM_TOKEN: <你复制的令牌>
  6. 重启 dsh web，在菜单 → 用量里选择「实时·令牌」

说明：

每轮对话消耗（无需任何凭据）

「每轮对话消耗统计」直接监听 DSH 本机会话事件，按模型真实 usage 换算金额（与今日已用同一套峰谷定价表），不需要 DEEPSEEK_PLATFORM_TOKEN。

验证

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
curl http://127.0.0.1:3080/dsh-whale/last-turn.json

常见问题

开发与维护

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

许可证

本项目基于 MIT License 开源，详见 LICENSE。

DeepSeek-Balance-Whale-Widget (MeteorNOX/DeepSeek-Balance-Whale-Widget)

animation
Searching Database…

5.2K ·GitHub
DeepSeek-Balance-Whale-Widget
What is this?A tiny whale mascot widget that sits in the bottom-right corner of the DSH (DeepSeek Harness) web interface, showing your DeepSeek API balance, today's spending, and a popup after every chat turn showing how much that turn cost.
Is this a standalone app or a plugin for something else?It's a standard DSH plugin package, not a standalone app — it only runs inside the DSH web interface and is installed/removed through the 'dsh plugin' command.
How do I install the whale widget into DSH?You add it through DSH's plugin manager (e.g. 'dsh plugin --profile web add' pointing at this repo or a local link), then restart 'dsh web' and refresh the browser (F5) for it to appear.
What do I need before this will show my balance?You need an existing DSH (DeepSeek Harness) installation and a DEEPSEEK_API_KEY configured in DSH's credentials — that alone is enough for the default balance/usage tracking mode.
Is the default usage tracking perfectly accurate?No — the default 'whale accounting' mode infers today's spend from observed drops in your balance, so any usage that happens while DSH is closed gets missed; for exact figures you need the optional platform session token mode.
What exactly does the whale show when I click it?Clicking its speech bubble cycles through random lines (balance, today's usage, peak/off-peak pricing hints, mini animations, or teasing comments), weighted at random, and the bubble auto-closes after about 5 seconds.
Can I drag it around the screen?Yes, you can drag it to any of the four edges where it snaps into a quarter-position, and when snapped to the left side it mirrors itself horizontally (text included) with an animation.
Do I need the DeepSeek platform session token?No, it's optional. Without it the widget uses free balance-drop accounting; the token just unlocks a more precise real-time usage mode with peak/off-peak pricing from DeepSeek's own usage API.
Can I customize its size or sounds?Yes, hovering over the whale reveals a hamburger menu with a size slider (0.6x-2.5x), sound effect toggle and volume, usage mode switch, peak/off-peak hint text style, and popup auto-close timing.
What are similar projects?dsh-cost-meter, token-monitor, oh-dsh, dsh-damage-pulse, dsh-usage-stats, dsh-desktop, EAC-Desktop, awesome-deepseek-harness-plugins
Which topics is it in?usage-tracking, dsh-plugins, cost-tracking, cordis, widget, token-usage, drag-and-drop, webui, dsh, dsh-plugin, deepseek-harness, deepseek
Creator
MeteorNOX
Size
30.2 MB
Stars
5.2K
Updated
CommitOct 11Releasev0.4.2Oct 11
Age
2mo
Commits · 90 Days