dsh-balance · 模型余额悬浮窗

模型账户余额悬浮窗插件 for DeepSeek Harness Web GUI（dsh-web-ui 插件生态）。

右下角悬浮展示模型账户余额（每 60 秒自动刷新），可拖动、收起、关闭；设置页位于「设置 → 插件 → 模型余额悬浮窗」，带「显示余额悬浮窗」总开关。支持 DeepSeek / 硅基流动 / Moonshot / OpenRouter 余额接口（按 baseURL 域名自动识别）。

A floating model-account balance monitor for the DeepSeek Harness Web GUI: a draggable bottom-right card auto-refreshing every 60s, with a master show/hide switch on its Plugins-settings page. Supports DeepSeek / SiliconFlow / Moonshot / OpenRouter balance endpoints (auto-detected from the configured base URL).

功能 · Features

• 💰 余额悬浮窗 · Floating balance card（右下角，可拖动）：总余额大字 + 充值/赠送明细 + 更新时间；⟳ 手动刷新、– 收起成小胶囊、× 关闭（留一枚 ¥ 胶囊随时唤回）。Draggable card with total balance, breakdown lines, refresh / collapse / close buttons.
• 🔄 实时刷新 · Auto refresh：每 60 秒自动查询，结果 host 侧缓存 30 秒，不频繁打接口。Polls every 60s; results cached 30s host-side.
• 🔌 总开关 · Master switch：「设置 → 插件 → 模型余额悬浮窗」里可一键关闭/开启悬浮窗，设置持久化到 ~/.dsh/balance/settings.json。One-click show/hide on the Plugins-settings page, persisted locally.
• 🔐 密钥安全 · Credential safety：余额查询全部走 host 端 fetch；API key 可在设置页直接填写（存于 ~/.dsh/balance/settings.json，接口只回传脱敏预览），或经 credentials 服务解析（环境变量 → ~/.dsh/.credentials.yaml → .env），永不下发到浏览器。Balance fetch runs on the host; the key can be entered in the settings page (stored locally, masked in responses) or resolved through the credentials seam — it never reaches the browser.
• 🌐 多服务商 · Multi-provider：DeepSeek /user/balance、硅基流动 /v1/user/info、Moonshot /v1/users/me/balance、OpenRouter /api/v1/credits；其他域名明确提示不支持。Unsupported hosts fail with a clear message.
• 💾 零运行时依赖 · Zero runtime dependencies：host 半体纯 Node，浏览器半体纯 React，无需构建（lib/ 即发布产物）。No build toolchain.

安装 · Install

# 安装到 web profile（dsh 插件市场 / dsh CLI）
# Install into the web profile (dsh plugin market / dsh CLI)
dsh plugin --profile web add github:Mystery-God/dsh-balance
# 或直接改 profile 的 package.json / bundles 后 pnpm install
# Or edit the profile's package.json deps + bundles, then pnpm install

安装后重启 dsh web，即可在「设置 → 插件 → 模型余额悬浮窗」中配置。 Restart dsh web, then configure it at Settings → Plugins → 模型余额悬浮窗.

工作原理 · How it works

lib/index.js   — host 半体：~/.dsh/balance/settings.json（浮窗总开关）+ /api/dsh-balance/* 路由（设置读写、余额查询）+ agent 公告
lib/client.js  — 浏览器半体：设置页（settings.plugins.tab，总开关+余额预览）+ 悬浮卡片（shell.overlay）+ 60s 轮询
cordis.patch.yml — bundle patch：把插件行注入 profile 组合

• 路由带 loopback + same-origin 围栏（与 dsh-ssh 一致），LAN 暴露的部署不会对外提供这些接口。Routes carry a loopback + same-origin fence; LAN-exposed deployments never serve them.
• 设置页与悬浮窗共享一份内存 store，开关切换即时生效。Both surfaces share one in-memory store — the switch takes effect immediately.

开发 · Development

node scripts/build.mjs   # 把 src/ 复制为 lib/（无编译步骤）· copies src/ → lib/
node scripts/test.mjs    # host 路由冒烟测试（mock 余额接口，临时 DSH_HOME）· host route smoke test

本仓库无 TypeScript / 无打包器：src/ 是手写源码，lib/ 是发布产物（需提交，dsh 插件市场校验安装包时要求入口文件存在）。No TypeScript, no bundler: src/ is the hand-written source, lib/ is the shipped artifact (committed).

License

MIT

---

纯中文版：README.zh.md