dsh-balance-whale 🐳

A floating DeepSeek API balance widget for DeepSeek Harness (dsh). A cute whale-girl (鲸鱼娘) icon floats at the bottom-right corner of the dsh web GUI, showing your remaining DeepSeek API balance — click to expand details (total / topped-up / granted) with a manual refresh.

Security first: the API key is resolved from the dsh credential store on the Host side only and never reaches the browser. The browser just polls a same-origin, loopback-only route that returns an aggregated, sanitized balance payload.

---

为 DeepSeek Harness（dsh）打造的余额查询悬浮框插件： 右下角一只可爱的鲸鱼娘 🐳 悬浮显示 DeepSeek API 剩余余额，点击展开详情（总余额 / 充值 / 赠送），支持手动刷新。

安全设计：API key 只在服务端（Host 进程）从 dsh 凭据库读取，永不进入浏览器；浏览器只轮询一个 同源、仅限本机访问的路由，拿到的是脱敏后的余额数据。

Features / 功能

• 🐳 鲸鱼娘悬浮按钮（手绘 SVG，无外部资源），实时显示余额 + 状态点（绿=有余额 / 橙=无余额）
• 📋 点击展开卡片：可用状态、各币种总余额 / 充值 / 赠送明细、更新时间、刷新按钮
• ⏱ 每 60 秒自动刷新（Host 侧另有 30s 缓存，防止刷爆官方接口）
• 🔒 key 不出服务端、路由仅本机回环可访问、错误分类返回（不透传上游响应体）

Install / 安装

The plugin is a cordis bundle. It is not published to npm — install it from this repo.

git clone https://github.com/chenpengye/dsh-balance-whale.git
cd dsh-balance-whale
pnpm install && pnpm build      # produces lib/index.js + lib/client.js

Then register it into your dsh profile (e.g. web):

cd ~/.dsh/profiles/web
pnpm add /absolute/path/to/dsh-balance-whale -w

Add the patch entry to ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: dsh-balance-whale
      name: dsh-balance-whale

Restart dsh web (or, if the HMR watcher is active, delete-and-recreate the patch file to hot-reload) and hard-refresh the browser page (Cmd+Shift+R).

中文：克隆本仓库 → pnpm install && pnpm build → 在 ~/.dsh/profiles/<name> 下 pnpm add <路径> -w → 在 cordis.patch.yml 里加上面的 insert 条目 → 重启 dsh web 或触发 HMR 热加载 → 硬刷新页面即可看到右下角鲸鱼娘。

Usage / 使用

• The API key comes from the dsh credential store (DEEPSEEK_API_KEY), the same one saved in Settings → Models. No extra configuration needed.
• API key 复用 dsh 凭据库中的 DEEPSEEK_API_KEY（设置 → 模型 里保存的那个），无需额外配置。

Configuration / 配置项

Host-side config (defaults shown), overridable in the profile config:

Key	Default	Description
apiKeyRef	DEEPSEEK_API_KEY	credential reference resolved on the Host
baseUrl	https://api.deepseek.com	upstream; HTTPS only (loopback HTTP allowed for tests)
timeoutMs	10000	upstream request timeout
cacheMs	30000	Host-side response cache
allowRemote	false	when false, non-loopback requests are rejected with 403

Security / 安全

• Credentials never leave the Host process; the browser sees only the aggregated balance.
• The route rejects non-loopback requests (allowRemote: false by default).
• Errors are classified (INVALID_API_KEY, RATE_LIMITED, UPSTREAM_TIMEOUT, …) — no upstream body passthrough.
• Responses are no-store + nosniff.

License

MIT — see LICENSE.