前言¶
DeepSeek Harness (DSH) 桌面版开发者在使用 API 开发过程中，常需要频繁查看账户余额和今日 Token 消耗量。打开网页或主界面进行查询会增加操作成本。dsh-api-balance 插件通过一个独立的原生 Windows 窗口，将 API 状态实时悬浮在桌面角落，方便在编写代码的同时监控资源消耗。
插件定位¶
- 插件名称：dsh-api-balance
- 维护者：wwwwangpengggg
- 许可证：MIT
- 核心价值：在桌面角落浮出一个置顶小窗，实时显示 DeepSeek API 账户的余额，以及今天累计消耗的 token。
核心功能¶
- 桌面小窗：在桌面角落浮出无边框、半透明的置顶小窗，支持高 DPI 渲染，在 125% / 150% 缩放下不模糊。
- 实时数据：
- 实时显示 DeepSeek API 余额。
- 显示今日累计消耗的 token。
- 三页显示：
- 第 1 页：余额 + 今日累计消耗的 token（跨多次开关机累加）。
- 第 2 页：今日消费的金额（基于余额减少量估算）。
- 第 3 页：计费时段（显示当前是高峰期还是半价优惠时段，以及切换倒计时）。
- 交互与定制：
- 支持七套配色方案。
- 支持自定义背景图片（右键菜单切换，无需重启）。
- 点击金额区域可在三页间循环切换。
- 支持收进托盘，最小化主窗口不影响小窗。
安装与启用¶
前置条件¶
- Windows 10/11。
- 已安装 DSH 桌面版。
安装步骤¶
- 完全退出 DSH 桌面版：安装前必须完全退出 DSH 进程（任务管理器确认
DSH Desktop进程消失）。DSH 正在运行时安装会因 pnpm 锁定文件而报错。 - 执行安装命令：将插件安装进桌面版使用的 profile。
dsh plugin --profile desktop add git+https://github.com/wwwwangpengggg/dsh-api-balance.git
- 重新打开 DSH：安装完成后，重新打开 DSH 桌面版，小窗会自动出现在屏幕角落。
使用方式¶
- 开关小窗：在任意会话中输入
/balance命令，可以开启或关闭小窗。 - 托盘操作：双击托盘图标，或右键点击托盘图标选择「显示余额小窗」。
- 右键菜单：
- 刷新频率：支持 30秒 / 60秒 / 5分钟 三个档位。
- 页面切换：右键菜单内可直接切换查看第 1、2、3 页。
- 外观设置：在右键菜单中选择「外观」可切换七套配色或更换背景图片。
- 取消置顶：如需遮挡其他窗口，可取消置顶。
- 收起小窗：点击小窗右上角的
×不会关闭程序，而是将其收进托盘。真要退出需在托盘右键菜单中选择「退出小窗」。
计费时段说明¶
第 3 页显示当前的计费时段，帮助判断是按高峰价还是半价计算。
- 起算时间：计费时段的「今天」从早上 08:00 起算，而非自然日的 00:00。凌晨 08:00 前仍算作上一时段。
- 高峰与优惠：
- 高峰时段：北京时间周一至周五 09:00-12:00 与 14:00-18:00（法定节假日除外）。
- 优惠时段：其余全部时间（包括周末、节假日、午休 12:00-14:00）。
- 节假日判定：节假日判定基于 UTC 时间。插件内置了 2026 年的国务院法定节假日数据。如果提示未收录年份，则默认按「不排除节假日」处理，宁可显示高峰价也不误报优惠价。
API Key 配置¶
小窗需要读取 DeepSeek API Key。它按以下顺序查找：
- 环境变量
DEEPSEEK_API_KEY。 $DSH_HOME/.credentials.yaml文件中的同名键。
Key 不会经过 DSH 的 IPC 通信，也不会出现在任何命令行中，小窗进程直接读取文件，安全性较高。配置好 Key 后，点击小窗内的「刷新」按钮即可更新数据。
注意事项¶
- 今日消费估算：由于 DeepSeek API 只提供余额接口，不提供账单明细，今日消费金额是插件根据余额的减少量倒推估算的。充值金额不计入消费计算。
- 安装时机：务必在安装前完全退出 DSH，否则会报
ERR_PNPM_EPERM错误。 - 手动安装：如果网络环境无法使用 pnpm，可以手动 clone 仓库，编辑
package.json并创建 junction 链接，但官方推荐使用命令行安装。
