余额状态条 yknBugs/dsh-balance-status

dsh-balance-status

在 DSH Web 界面底部状态行（x 轮 xx 步 · xx tok/s xx M tok · 缓存命中 xx%）之后追加一枚 DeepSeek 账户余额，左键单击弹出用量详情面板。

⟳ 1 轮 89 步 · 262 tok/s ⛁ 9.1M tok · 缓存命中 96% 余额 ¥32.49

左键单击余额 → 立即刷新一次并弹出面板（再点一次关闭，点空白处或 Esc 也可关闭）：

DeepSeek 余额 ───────────────────────── 余额 ¥32.49 充值 ¥32.49 赠送 ¥0.00 当前对话已用 ¥0.20 当前进程已用 ¥0.35 点击余额刷新 · 点击空白处或 Esc 关闭

不写任何会话历史、不画图、不做动画，就是一行状态文字加一个小面板。

前置条件

必须在 DSH 凭据里配置 DEEPSEEK_API_KEY（余额接口需要它）。没配也能装，状态行会显示 余额 未配置。使用方式见 DSH 设置里的凭据页，或直接编辑 $DSH_HOME/.credentials.yaml：

DEEPSEEK_API_KEY: sk-xxxxxxxx

可选：

- 走内部网关时设置 DEEPSEEK_BASE_URL（或用 DSH 设置里 llm-deepseek 的 baseURL），插件会自动跟随；否则用 https://api.deepseek.com。

安装

本机（打包成 tarball 安装：真实复制，推荐）

不要用 link:。link: 是符号链接，源码目录一旦移动或删除，插件就失效。正确做法是先打包再安装，
pnpm 会把文件真实复制进 profile 的 .pnpm 目录，装完之后源码目录放哪、删不删都不影响运行：

1) 在插件目录里打包（只包含 files 字段列出的文件）
cd <插件目录>
pnpm pack # 产出 dsh-balance-status-1.0.2.tgz（文件名随 package.json 的 version 变化）

2) 安装该 tarball
dsh plugin --profile web add file:<插件目录>\dsh-balance-status-1.0.2.tgz

装完重启 dsh web，再 F5 刷新浏览器。

直接复制整个 dsh-balance-status 目录到别的机器，把上面的路径换掉即可；本地 tarball 安装不需要联网。

升级（改了源码之后）

file: 依赖指向的是那一次打出来的 tarball 快照，改了源码必须重新打包并覆盖安装：

cd <插件目录>
pnpm pack
dsh plugin --profile web add file:<插件目录>\dsh-balance-status-1.0.2.tgz # 覆盖安装

然后重启 dsh web。

移动或删除本目录之后要注意什么：已装好的副本是独立复制，移动/删除本目录不影响它继续运行。
但 profile 里记录的依赖 spec 是 file:<本目录>\...tgz，所以之后再执行任何 dsh plugin add/remove/update 时 pnpm 会重新解析这个路径 —— 路径失效会让那次安装失败。因此移动目录后，请从新路径重新执行一次上面的 add 命令覆盖安装即可。

开发模式（可选，仅限本机调试）

想边改边看效果可以用链接安装，但必须记住它是符号链接：

dsh plugin --profile web add link:<插件目录绝对路径>

其他设备（从 Git 仓库安装）

把本目录推到一个 Git 仓库（仓库根目录就是本目录，即 package.json 所在层），然后：

dsh plugin --profile web add github:<用户名>/<仓库名>

如果 pnpm 提示拦截构建脚本，按提示在 %USERPROFILE%\.dsh\profiles\web\pnpm-workspace.yaml 的 allowBuilds 下加上本包名再重跑。

验证

dsh --profile web --dump-config | Select-String dsh-balance-status

浏览器 F5 后，状态行末尾应出现 余额 ¥xx.xx。

卸载

dsh plugin --profile web remove dsh-balance-status

重启 dsh web 后状态行恢复原样。

刷新策略

DeepSeek 的余额接口本身最多可能有 5 分钟延迟，所以刷得比这更勤只是白打接口。默认策略：

- 自动刷新：5 分钟一次（与数据延迟对齐，每小时约 12 次请求）。
- 点击余额：强制立即刷新一次，绕过一切缓存，同时开关详情面板。
- 宿主端另有 30 秒结果缓存，只为兜住同一瞬间的重复请求（多标签页等）；点击的强制刷新不受它影响。

想调整只改 lib/client.js 顶部一个常量，然后重新打包安装：

var REFRESH_MS = 300000 // 自动刷新间隔；设为 0 = 完全关闭自动刷新，只在点击时查询

改完记得 pnpm pack + 重新 add 那个 tarball，再重启 dsh web。

两个用量数字怎么算的

采用余额差值记账，不依赖任何价格表，因此 DeepSeek 调价也不会算错：

- 当前进程已用 ＝ 自 dsh web 进程启动后第一次观测到余额起，余额下降部分的累计；重启进程即归零。
- 当前对话已用 ＝ 自该会话第一次观测到余额起，余额下降部分的累计；开新对话（新 sessionId）即归零，F5 刷新页面不会丢。
- 充值造成的余额上升不会记成负数，只是把基准点抬高。
- 全部只存在于宿主进程内存中，绝不写入会话记录，以保证会话日志格式的向后兼容。代价是重启后这些用量数字永久消失（这是刻意接受的取舍）。
已知限制：余额接口是 0.01 元粒度且可能有延迟，小额消耗要攒到 1 分钱才体现。另外多个对话同时开着时，两个会话各自按自己的基准计算，会互相包含对方的消耗（余额记账法的固有限制）。

实现说明

| 半边 | 文件 | 职责 |
| 宿主 | lib/index.js | 解析凭据与端点、调用 GET {baseURL}/user/balance（30 秒缓存）、维护两个内存账本、注册 /dsh-balance-status/balance 只读 JSON 路由 |
| 浏览器 | lib/client.js | 预构建 bundle，向 conversation.composer.dock 注册余额按钮、向 shell.overlay 注册详情面板，5 分钟轮询 + 点击强制刷新 |

几个刻意的实现选择：

- 浏览器半边是预构建产物：DSH 的 client-modules 直接按字节提供 exports["./client"]，不做转换，所以该文件必须保持 window.__ModuleLoader__.load({ id, factory }) 工厂格式，并且只 require 平台种子模块（react）。改它之后要重启 dsh web 生效，不需要任何构建步骤。
- 状态行对齐靠"结构相等"，不靠补偿像素：余额按钮逐条照抄自带状态药丸（ui-chat 的 StatsPills.module.css）的 padding: 1px 8px、line-height 与字号表达式，因此两者盒子高度恒等；行内用 align-items: center 对齐，顶边自然重合。自带状态行把纵向内边距放在自己身上（0.1.5-rc.x）还是放在父级 dock 上（0.1.7-rc.2），都不需要改这里的数字。
- 面板样式逐条照搬自带状态浮窗（ui-chat 的 stat-dialog.module.css）：var(--dsw-specific-menu) 背景 加 backdrop-filter: var(--dsw-menu-backdrop-filter)、var(--dsw-elevation-prominent) 阴影、var(--dsw-radius-lg) 圆角、12/18 字号行高、dl/dt/dd 网格，保证与「缓存命中」浮窗观感一致。自 0.1.7-rc.2 起菜单是"半透明填充 + 背景模糊"的材质，--dsw-specific-menu 指向带 alpha 的 --dsw-menu-surface-fill，两者必须成对出现，只抄背景不抄模糊就会真的变成透明面板。
- 关闭面板不用全屏遮罩：遮罩会吃掉滚轮事件导致无法浏览对话，改为 document 上的 mousedown / keydown 监听。
- 余额查询走宿主进程的 fetch，浏览器半边只访问本地只读路由，密钥永远不进浏览器。

安全提示

/dsh-balance-status/balance 会返回账户余额（不含密钥）。它由 DSH 的 Web 服务器提供，沿用 DSH 自身的鉴权与监听地址；请保持 DSH 监听在 127.0.0.1，不要把它直接暴露到公网。

兼容性

按 DSH 0.1.7-rc.2 编写（0.1.5-rc.x 亦可运行），依赖以下稳定契约：

- 插槽 conversation.composer.dock（自带状态行的位置）与 shell.overlay（框架级浮层）；
- 宿主服务 webServer、credentials、settings；
- 主题变量 --dsw-specific-menu、--dsw-elevation-prominent、--dsw-alias-*、--dsh-content-font-size-secondary。

若将来自带状态行的内边距或插槽键变化，只需相应调整 lib/client.js 顶部 PILL_CSS 里的对齐规则。

来源与许可

MIT。余额接口（GET /user/balance）与「余额差值记账」思路参考了开源项目 DeepSeek-Balance-Whale-Widget（MIT）。
本插件只保留其核心取数与记账逻辑，去掉了挂件、音效、拖拽与动画，改为挂在状态行上的一行文字。