余额水杯 BugDesigner-Hy/dsh-whale-balance

Whale Balance · 余额水杯

English · 中文

English — 一个 DeepSeek Harness（DSH）插件，把账户余额变成鲸鱼标志里的水：水位按你设置的满杯金额填充，水面持续荡漾，悬停面板显示精确金额、消耗、剩余天数和充值链接。

中文 — 把 DeepSeek 账户余额显示成鲸鱼标志里上涨的水面：水位按你设置的满杯金额线性变化，水面持续荡漾；悬停面板给出精确金额、今日/近 7 天消耗、还能用几天，以及充值入口。

安装

从 npm 安装：

dsh plugin --profile desktop add dsh-whale-balance

直接从 GitHub 安装：

dsh plugin --profile desktop add "git+https://github.com/BugDesigner-Hy/dsh-whale-balance.git"

然后在插件页面启用 Whale Balance。插件也已收录在 Open Plugin Market —— 在 Discover → Add index source 下添加 https://dshopen.org/index.json，搜索 whale 或 balance 即可。

功能

- 右下角一个 46px 的浮动鲸鱼标志（shell.overlay）。可以拖到任意位置；位置会被记住，并限制在窗口内。
- 点击标志会展开成胶囊形，右侧是卡西欧风格 LCD 面板，显示实时总额：七段数码管数字、淡淡的残影段，金额变化时数字会短暂跳动。胶囊贴合金额宽度，不会预留一大片空白显示区。它朝空间充足的一侧展开 —— 默认向左；拖动后的胶囊如果右侧放不下，会保持右边缘、向左生长，而不是跑出窗口。再次点击收起；否则保持展开。
- 水位高度 = balance / full amount，封顶为满。满杯金额按币种分别设置，在面板的齿轮里配置。
- 鲸鱼轮廓内有两层漂移的波浪，标志整体还有 ±4° 的摆动，尾巴幅度最大。
- 余额来自账户监听流：登录、充值、退出会立即推送一帧。监听流不可用时回退到 60 秒轮询。
- 悬停面板：钱包总额，括号里是赠送份额（礼物图标 + 金额）；点击某个币种即可让它成为水杯的基准。还有今日和近 7 天消耗、剩余天数估算、低余额警告、刷新，以及 Top up。
- 点击标志只会展开或收起 LCD 面板 —— 不会跳转；充值有单独的链接。
- 低余额：水变琥珀色，标志边缘有柔和的呼吸光晕。阈值可以是金额，也可以是满杯金额的百分比。
- 容器、焦点环和文字只用主题 token；prefers-reduced-motion 会关闭波纹、摆动、呼吸光晕和加载动画。界面已本地化（英文 / 中文）。

设置

| 设置 | 默认值 | 说明 |
| Full amount | ¥100（USD $15） | 水杯满杯对应的可消费总额（充值 + 赠送）；设为 1000 则 1000 为上限 |
| Alert mode | amount | amount 或 percent |
| Alert threshold | ¥5（USD $1） | 低于此值时水变琥珀色，标志边缘柔和发光 |
| 百分比阈值 | 10% | 百分比模式下使用：阈值 = 满杯金额 × 百分比 |

满杯金额和金额阈值按币种分别保存（CNY / USD）；百分比是全局一个。所有数据都存在 localStorage 里，改完立即生效；恢复默认会还原全部默认值。

水位怎么算

- 线性：(充值 + 赠送) / 满杯金额，上限为 1。100 里充了 40，水位就填到 40%。
- 消耗数据来自插件在应用运行期间观察到的余额减少，所以只是估算，不是账单。账本把充值和赠送两个钱包合在一起算（平台先花赠送部分），今日和近 7 天两行始终显示——还没观察到数据时显示 0.00。
- 可用天数 = 可用总额（充值 + 赠送）÷ 按最近七天观察数据外推的日均消耗；历史不足一天时隐藏。

数据从哪来

浏览器读取的账号 Remote 和 设置 → 账号 是同一个：

ctx.get('remote').$stream({ name: 'account', open: (signal) => account.watch(signal) }) // live state
ctx.get('remote.account').getBalance({ version, locale, timezoneOffsetSeconds }) // balance

不保存 API key，插件也不发起任何外部网络请求。

限制

- 消耗历史和设置按来源存在 localStorage 里；桌面版换了端口就会重新开始收集。
- 只在应用运行时观察消耗，长时间离线不计入。

许可证

MIT © 2026 BugDesigner-Hy。鲸鱼路径来自 MIT 许可的 DSH 客户端基础组件（© DeepSeek）；见 LICENSE。

安装

从 npm：

dsh plugin --profile desktop add dsh-whale-balance

直接从 GitHub：

dsh plugin --profile desktop add "git+https://github.com/BugDesigner-Hy/dsh-whale-balance.git"

装好后到 插件 页确认「余额水杯」已启用。也可以在 发现 → 添加索引源 加入社区市场 https://dshopen.org/index.json，搜索 whale / 余额 找到它。

它在哪里

shell.overlay 里的一块 46px 悬浮徽标，默认在窗口右下角（距边 20px），不占布局、不遮挡滚动区域。

- 拖动：按住徽标可拖到任意位置，松手后记住坐标（窗口缩小时会自动收回可视区）。
- 点击展开：徽标展开成一条胶囊，右侧亮起电子表风格的 LCD 实时余额（七段数字、未点亮的「幽灵段」、金额变化时数字快速滚动一下），胶囊宽度随金额自适应，不多留空白；再点一次收回，不点就一直保持展开。默认贴着右边，所以是向左展开；如果拖到了别处，会先看右侧是否放得下，放不下就固定右边缘、向左展开，绝不越出窗口。全程不做任何跳转。
- 游动：鲸鱼以身体为轴微微摆动（约 ±4°），尾巴的摆幅最明显；prefers-reduced-motion 下停止。
- 悬停 / 键盘聚焦：在水杯上方展开面板（靠近窗口顶部时自动翻到下方，靠近左侧时改为左对齐）。
- 面板右上角的齿轮：切换到设置，改完立即生效并保存；Esc 先退出设置、再收起面板。

面板内容

| 区域 | 内容 |
| 标题行 | 标题 + 齿轮（设置）+ 刷新（读取时旋转） |
| 金额 | 各币种可用总额；赠送部分紧跟在后面，括号内以礼物图标 + 金额显示；点币种把它设为水位基准 |
| 统计 | 今日消耗、近 7 天消耗、约可用天数 |
| 提醒 | 低于阈值时出现琥珀色提示 |
| 底部 | 「去充值」+ 上次更新时间 |

设置（默认值可直接用）

| 设置 | 默认 | 说明 |
| 满杯金额 | ¥100（USD 为 $15） | 水位到顶对应的可用总额（充值 + 赠送）。设成 1000，就以 1000 为满杯 |
| 提醒方式 | 金额 | 可选「金额」或「百分比」 |
| 提醒阈值 | ¥5（USD 为 $1） | 低于该金额时水体转琥珀、徽标外缘持续微微发光（呼吸感） |
| 百分比阈值 | 10% | 当提醒方式为百分比时，阈值 = 满杯金额 × 该比例 |

满杯金额与金额阈值按币种分别保存（CNY / USD 各一套），百分比是全局一个；恢复默认 一次还原全部。设置保存在浏览器 localStorage，修改后立即生效，无需重启。

水位怎么算

- 水位：线性，(充值 + 赠送) / 满杯金额。满杯填 100、可用总额 40 就是四成高；超过满杯金额则封顶为满。
- 低余额：可用总额（充值 + 赠送）低于你设置的金额阈值，或低于满杯金额的百分比，即触发提醒。
- 「可用天数」用观察到的近 7 天消耗外推日均（历史不足 7 天按已观察天数等比外推，不足 1 天则不显示），分子是「充值 + 赠送」的可用总额，只是趋势参考。
- 消耗完全来自本插件观察到的余额变化（只在应用运行时记录），是估算；把它当作趋势，不要当作账单。统计把「充值余额 + 赠送余额」合在一起算（平台先扣赠送），今日与近 7 天两行始终显示，尚未观察到扣费时显示 ¥0.00 并附一行说明。

数据来源

浏览器端读取本应用已挂载的账户 Remote：

ctx.get('remote').$stream({ name: 'account', open: (s) => account.watch(s), ... }) // 实时状态
ctx.get('remote.account').getBalance({ version, locale, timezoneOffsetSeconds }) // 余额

即「设置 → 账户」页用的同一条通道。登录、充值、退出都会推一帧，水位随即更新；流不可用时自动退化为每 60 秒轮询，读取失败或服务未就绪时每 5 秒重试，页面隐藏时不发请求、重新可见时立刻刷新。

插件本身不保存 API Key、不发任何外部网络请求。

可调常量（client.js 顶部）

| 常量 | 默认 | 含义 |
| REFRESH_MS | 60000 | 轮询回退的刷新间隔 |
| RETRY_MS | 5000 | 未就绪/失败时的重试间隔 |
| FALLBACK_FULL | { CNY: 100, USD: 15 } | 各币种满杯金额的默认值 |
| FLOOR_LOW | { CNY: 5, USD: 1 } | 各币种金额阈值的默认值 |
| DEFAULT_PERCENT | 10 | 百分比阈值的默认值 |
| DAY_MS | 86400000 | 统计窗口单位 |
| WATER / WATER_LOW | 蓝 / 琥珀 | 水体与水面高光配色 |

主题与可访问性

- 容器、文字、边框只用 --dsw-alias-* 主题变量，跟随明暗主题；只有水体是美术配色。
- 徽标是真正的 ：可聚焦、有含金额与低余额提示的 aria-label；面板关闭时用 visibility 隐藏，不会进入 Tab 顺序。
- 数字输入框在失焦或回车时才提交，允许中途清空；Esc 在输入框内只还原输入，不关闭面板。
- 面板不挡鼠标：只有打开时才接收指针事件，并有一段透明桥接区域，鼠标从徽标移进面板不会闪断。
- 尊重 prefers-reduced-motion：关闭波纹漂移、水位过渡、低余额呼吸光与刷新旋转。
- 文案走客户端 locale 服务（内置 en / zh）。

已知限制

- 消耗统计与设置存放在浏览器 localStorage（按 origin）。如果桌面端每次启动换端口，这些数据会重新积累。
- 「可用天数」依赖已观察到的消耗，长时间不用时消耗为 0，该项不显示。

文件

| 文件 | 作用 |
| index.js | Host 半侧：空座位，不注册任何资源 |
| client.js | 浏览器半侧：水位徽标、拖动、面板、设置、余额与消耗统计 |
| cordis.patch.yml | 插入 balance-vessel 这一行 |
| locale/en.json、locale/zh.json | 插件管理器里的标题与说明 |
| icon.svg | 原创图标（水面与鲸尾），非官方商标素材 |
| LICENSE | MIT |

鲸鱼轮廓路径取自本应用自带的品牌标志（@deepseek-ai/dsh-client-ui-primitives，MIT，© DeepSeek），其余图形与动效为原创。

许可证

MIT © 2026 BugDesigner-Hy。仓库里的鲸鱼路径来自同样以 MIT 分发的 DSH 客户端素材，署名见 LICENSE。