余额胶囊 azkbzxf/dsh-account-balance-pill

dsh-account-balance-pill

DeepSeek Harness (DSH) 插件，在输入框底栏显示已登录 DeepSeek 账户的剩余余额。底栏就是消息框下方那行统计信息，已经有 N turns · M steps、tokens/s、token 用量和上下文圆环。

[welcome icon] 余额 ¥12.34 [stats] 1 轮 160 步 · 254 tok/s [usage] 10.9M tok · 缓存命中 98% (ring) 9%

胶囊显示每种币种的可消费总余额（充值 + 赠送），例如 余额 ¥17.34。悬停时展开总额，拆成充值和赠送两部分，显示上次刷新时间，并提示点击可刷新。

- 包名：dsh-account-balance-pill
- 形态：一个 DSH bundle，由 dsh.bundle.patch 插入的 Host 行加上 Web Client 部分；无依赖，无构建步骤
- 渲染：在槽位 conversation.composer.dock 中注册一个条目（id account-balance），与内置的 activity、usage 胶囊并排
- 数据：DSH 自带的账户 Remote（ctx.get('remote.account').getBalance(...)，与 Settings → Account 面板调用相同）。插件不存任何数据，不读凭据文件，也不自行发起网络请求。

安装

从 GitHub 安装到你使用的配置档：

dsh plugin --profile <profile> add github:azkbzxf/dsh-account-balance-pill

新添加的 bundle 会在运行中的实例上激活（Host 行立即生效，Client 部分热加载进已打开的页面）。替换已安装的副本需要重启 DSH，才能加载新的客户端构建。

在 DSH Desktop 里也可以用插件管理器：

{ "action": "install_bundle", "target": "D:\\path\\to\\dsh-account-balance-pill" }

卸载：

dsh plugin --profile <profile> remove dsh-account-balance-pill

显示规则

| 账户状态 | 底栏 |
| 已登录且有余额 | 钱包图标 + 余额 ¥12.34；悬停提示显示充值 / 赠送明细、最后更新时间，以及点击刷新的提示 |
| 未登录，或没有账户授权（Remote 返回 null） | 什么都不显示，没有占位符，也不报错 |
| 读取失败（离线、host 拒绝） | 保留上次已知的值，变暗表示已过期；如果从未读到过值，则保持隐藏 |
| 币种 | CNY 用 ¥，USD 用 $；充值和赠送按币种合并，CNY 在前 |

金额截断到分，与官方 Settings 页面一致，胶囊显示的钱永远不会多于实际可用金额；千位分组。0 显示 ¥0.00，不足一分显示 <¥0.01。

刷新时机

1. 胶囊挂载时立即刷新；
2. 页面可见时每 30 s 刷新一次（隐藏时跳过，重新可见时补读一次）；
3. 一轮对话结束后 1.5 s 刷新（sessionStats 投影的 steps 变化时）；
4. 窗口重新获得焦点或页面重新可见时刷新（仅当数据超过 15 s 未更新）。
5. 只要一个延迟加载的账号 Remote 出现；
6. 点击时。

同一时间只有一个请求在途，请求之间至少间隔 3 s，失败后按指数退避，从 4 s 起，最长到 60 s，之后自动恢复。

Compatibility / 兼容性

- 面向 DSH Web GUI（DSH Desktop 与 dsh web 共用的浏览器界面），已在 DSH Desktop 2.0.18、客户端 0.2.1-rc.2 上验证。
- 只使用受支持的扩展点：列表插槽 conversation.composer.dock 和随包提供的账号 Remote。它从不替换或修改现有 UI，从不读取其他插件的 DOM 或样式，从不向 document.body 追加节点。
- 样式只用 Harness 主题 token（--dsw- / --dsh-），因此浅色/深色主题和字号变化都会继承。所有可见文本都走 DSH 客户端 locale 服务（zh/en），跟随界面语言。
- 每个依赖都是可选的：没有账号 Remote → 插件照常加载并保持隐藏；读取失败时保留上一个值；渲染失败由只作用于这一条目的错误边界捕获，dock 的其余部分不受影响。
- 账号服务通过服务注册表读取（ctx.get('remote.account')），因为 ctx.remote.account 属性链只能从显式声明该依赖的上下文里读取。
- package.json 导出 "./package.json"，因为 DSH 的客户端模块组合要通过这个导出定位包清单，并且 dsh.bundle.patch 行的 name 与包名一致。
- Host 半边是空操作：不注册任何凭据、网络客户端、工具或会话资源。

Configuration / 可调参数

轮询间隔可以全局覆盖（毫秒，限制在 5 s – 1 h）：

window.__DSH_ACCOUNT_BALANCE__ = { intervalMs: 60000 };

Development / 开发

test/harness.mjs 是离线冒烟测试：它用桩实现的 React/document/locale/slots/remote 加载 client.js，断言插槽注册、locale 命名空间、请求元数据、格式化、隐藏/过期状态和定时器计数。

node test/harness.mjs client.js

文件地图：client.js —— 客户端半边（胶囊、store、格式化、样式）；index.js —— 空操作的 Host 半边；cordis.patch.yml —— 打包补丁；locale/{en,zh}.json —— 插件列表的显示元数据；icon.svg —— 图标素材。

Known limitations / 已知限制

- 余额来自 DeepSeek 账号平台，最多有几秒延迟，不是账本实时值。
- dock 行只在会话的输入区可见时渲染（随包插槽的既有行为）。
- 如果登录状态下平台持续失败，插件会持续退避，并在首次失败时打一条控制台警告；它从不弹对话框。

License

MIT。