在 DeepSeek Harness (DSH) 的开发或使用过程中，频繁切换标签页或手动访问控制台来查询 API 余额会增加操作成本。dsh-balance-whale 作为一个客户端插件，直接在 DSH 的 Web 界面右下角提供悬浮窗口，用于实时展示 DeepSeek API 的剩余额度。
这是一个由 chenpengye 维护的轻量级组件。它不依赖任何外部图片资源，通过手绘 SVG 渲染鲸鱼娘图标，并提供实时的余额状态反馈。插件的核心价值在于将余额查询集成到本地开发环境，同时通过架构设计确保 API Key 的安全性。
核心功能¶
- 悬浮展示与状态反馈：右下角显示鲸鱼娘图标及当前余额。图标旁有一个状态点，绿色代表有余额，橙色代表无余额。
- 交互详情卡片：点击图标可展开卡片，显示可用状态、各币种总余额、充值明细、赠送明细、最后更新时间以及手动刷新按钮。
- 自动刷新与缓存：每 60 秒自动请求一次最新数据。Host 进程端设有 30 秒缓存，防止频繁调用官方接口导致限流。
- 安全机制：API Key 仅在 Host 进程中从凭据库读取，绝不传输至浏览器。查询接口仅监听本机回环请求，拒绝非本地访问。错误信息经过分类处理，不透传上游接口的原始响应体。
安装与启用¶
该插件是 Cordis bundle，未发布至 npm，需从源码安装。
- 克隆仓库并构建：
git clone https://github.com/chenpengye/dsh-balance-whale.git
cd dsh-balance-whale
pnpm install && pnpm build
- 将插件注册到 Web 配置文件目录：
cd ~/.dsh/profiles/web
pnpm add /absolute/path/to/dsh-balance-whale -w
- 在
cordis.patch.yml中添加插件 ID：
- insert:
- id: dsh-balance-whale
name: dsh-balance-whale
- 重启
dsh web（或触发 HMR 热加载）并硬刷新浏览器页面。
典型用法¶
无需额外配置。插件会自动复用 DSH 凭据库中保存的 DEEPSEEK_API_KEY（即“设置 -> 模型”中配置的 Key）。安装完成后，右下角即可看到鲸鱼娘图标。
适用场景与注意¶
适合需要在本地开发过程中快速监控 API 额度且注重隐私的开发者。插件以当前 DSH 进程的权限运行，Key 永远不会离开本地机器。默认配置下，查询路由拒绝非回环请求。建议在安装前检查源码与许可证。
该插件通过本地轮询和安全的 Key 管理方式，为 DSH 用户提供了便捷且安全的余额监控入口。项目代码托管在 GitHub，遵循 MIT 协议。
