余额胶囊 reg4916/dsh-plugin-balance-badge

dsh-plugin-balance-badge

在 DeepSeek Harness 里始终显示 DeepSeek 账户余额。侧边栏顶部窗口条上有个小胶囊，显示的 Topped-up balance 与 Settings → Account 一致，并且会自动保持最新。

侧边栏窗口条上的余额胶囊

⬤ ⬤ ⬤ ⌄
● ██ $16.59 ← the balance pill (macOS window strip)
🐋 deepseek HARNESS
⊕ Новая сессия

功能

- 数字与 Settings → Account 一致 —— 读取的是 DeepSeek 账户 Remote，不是某个服务商单独的 API。
- 自动刷新：加载时刷新一次；页面可见时每 60 秒刷新；窗口重新获得焦点时立即刷新；存储的账户凭据变化时（登录、登出、授权轮换）立即刷新。点胶囊可手动刷新。
- 网络出问题时自动退避：读取失败后依次在 15 秒、30 秒、60 秒后重试，最长 120 秒，避免故障期间仍按正常频率轮询。成功一次即重置。
- 看得见的新鲜度：提示框显示 Updated 11:34 PM (5 min ago)，相对时间部分会持续更新，不额外发请求。
- 状态如实呈现：加载中显示 …，未登录或不可用时显示 --，刷新失败则显示上次已知金额并附「已过期」提示 —— 绝不假装成 0。
- 赠送余额单独显示在提示框里（仅当为正时），与 Settings → Account 完全一致；不会加到充值金额上。
- 多语言（en / ru / zh），样式使用 Harness 主题 token，跟随当前主题和语言。
- 默认无障碍：金额是 polite live region，变化时会被朗读；胶囊保留焦点环和描述性的 aria-label。
- 纯展示：没有工具，没有配置，也没有自己的 Host 服务。

要求

- DeepSeek Harness 0.2.x，且 DeepSeek 账户功能可用（就是渲染 Settings → Account 的那个功能）。
- macOS 桌面版上胶囊位于窗口条；Web/Windows/Linux 外壳上则放在侧边栏底部的 Settings 行旁边。

安装

从 npm 安装（预构建，推荐）

dsh plugin --profile <profile> add dsh-plugin-balance-badge

npm 安装是预构建的：不用下载仓库，不用 allowBuilds 审批，商店页面还会显示下载量。只有要固定到尚未发布的 commit 时，才用下面的 GitHub 方式。

从 GUI 安装（Desktop 和 Web）

设置 → 插件 → 添加插件，然后粘贴下面任意一条：

dsh-plugin-balance-badge
github:reg4916/dsh-plugin-balance-badge
github:reg4916/dsh-plugin-balance-badge#v1.0.2

Desktop 应用自己管理配置档，所以这里（或者用智能体调用 plugin_manager 工具）是它支持的路径。

用智能体（plugin_manager 工具）

让智能体执行 install_bundle，目标填 dsh-plugin-balance-badge（或 GitHub 规格 github:reg4916/dsh-plugin-balance-badge）。它会安装包、选中 bundle，并在配置档的 HMR 可用时通过 HMR 应用。

从命令行（非托管配置档）

dsh plugin --profile <profile> add dsh-plugin-balance-badge

手动（开发）

git clone https://github.com/reg4916/dsh-plugin-balance-badge.git
in your profile package.json: "dsh-plugin-balance-badge": "link:/abs/path/to/clone"
and append "dsh-plugin-balance-badge" to "dsh.profile.bundles"
ln -s /abs/path/to/clone <profile>/node_modules/dsh-plugin-balance-badge

如果配置档的 HMR 没在运行，重启一次应用；之后改动客户端插件，运行中的页面会直接生效。

卸载

从配置档 package.json 里删掉依赖项和 bundle 名，删掉 node_modules/dsh-plugin-balance-badge（如果你手动改过 lockfile，还要删掉对应的 importer 条目），然后重启应用。

工作原理

| 部分 | 细节 |
| 数据 | ctx.remote.account.getState()（本地读取凭据）→ 仅在已登录时调用 ctx.remote.account.getBalance({ version, locale, timezoneOffsetSeconds }) |
| 宿主链路 | accountController → deepseekAccount → 平台 GET /api/v0/users/get_user_summary（normal_wallets / bonus_wallets） |
| 位置（macOS） | frame 插槽 shell.overlay，入口 balance-badge，固定在窗口标题栏、红绿灯按钮旁边 |
| 位置（其他平台） | sidebar.footer.action，在设置旁边（随侧栏自适应） |
| 渲染 | 用页面模块表里的普通 React，不引入 @deepseek-ai/ |
| 刷新 | 每个插件共用一个轮询器（单飞、最短 15 s、丢弃过期结果、页面隐藏时暂停、读取失败时 15→120 s 退避） |

这个模块是给 Harness 模块表用的浏览器产物（window.__ModuleLoader__.load({ id, factory })），外加一行空的 Host（index.js = export function apply() {}）。

开发

node test/contract.test.mjs # loads client.js with a stubbed page and asserts
registration, live data flow, formatting and states

发布

npm login # once per machine
npm publish # unscoped name, publishes as public 1.x

publish.yml 也会从 GitHub Actions 发布，带 npm provenance，需要仓库密钥 NPM_TOKEN（npm automation token）；从 Actions → publish → Run workflow 运行。保持包的 repository 字段指向这个仓库——registry 靠它把 npm 包关联到条目。

├── package.json # dsh.bundle.patch + dsh.client manifest
├── cordis.patch.yml # 把 balance-badge 行插入配置档层栈 ├── index.js # 宿主端（不含宿主服务） ├── client.js # 浏览器端：词典、样式表、轮询器、胶囊 ├── locale/{en,ru,zh}.json ├── icon.svg ├── test/contract.test.mjs ├── CONTRIBUTING.md / SECURITY.md └── .github/ # issue 与 PR 模板、CI（test.yml）、发布工作流

调参：client.js 里的 POLL_MS、MIN_GAP_MS、RETRY_BASE_MS、RETRY_MAX_MS、RELATIVE_TICK_MS。

更新日志

见 CHANGELOG.md。目录条目和插件市场都指向最新发布的版本，所以 dsh plugin --profile <profile> add dsh-plugin-balance-badge 装上的永远是那里描述的发布版。

插件把 DeepSeek 账户余额显示成一个小「胶囊」，放在窗口顶栏、紧挨控制按钮（macOS）——就是 设置 → 账户 里那个 Topped-up balance*。它会自己刷新：启动时、每 60 秒、窗口重新获得焦点时、切换账号时；点一下强制刷新，悬停显示赠送余额和上次刷新距今多久（「5 分钟前」）。读取失败时，下一次请求往后推（15 → 30 → 60 → 120 秒），免得平台出故障时还猛敲。安装：设置 → 插件 → Add plugin → dsh-plugin-balance-badge。

贡献与安全

欢迎提 bug 和 pull request——开发流程和基本规则见 CONTRIBUTING.md。安全问题请按 SECURITY.md 私下报告，不要发到公开 issue。

许可证

MIT