dsh-usage-panel
给 DeepSeek Harness 提供侧栏常驻的用量面板:轮播显示 DeepSeek 官方账号(或手填的官方 API key)与各中转站(new-api 系)的余额、今日消耗,官方站点额外标注当前处于高峰还是空闲时段。
这是什么
DSH 本身不展示 API 用量。这个插件在左侧边栏底部嵌入一块面板,无需打开各站点后台即可查看余额与今日消耗。面板位于「记忆」这类入口之下、账号行(头像与用户名)之上,采用嵌入排版而非浮层覆盖。
- 官方站点:余额来自
https://api.deepseek.com/user/balance。若 DSH 已登录官方账号,无需填写 key,直接读取账号余额;也可以改为「手填 API key」,单独跟踪某一个 key。手填 key 属未验证路径(原因见「已知限制」)。 - 中转站:按 new-api 的接口形态读取配额与消费统计,支持多个站点并列轮播。
- 高峰/空闲:官方定价在工作日高峰时段为空闲时段的 2 倍,面板以「峰 / 闲」标记标出当前时段,悬停浮层中给出高峰与空闲的分账。
功能
| 能力 | 说明 |
|---|---|
| 侧栏常驻块 | 嵌入侧栏底部:位于底部入口之下、账号行之上,宽度与左缩进同相邻入口一致 |
| 多站点轮播 | 官方账号、多个官方 key、多个中转站可同时存在,按间隔轮播 |
| 不遮挡其它入口 | 面板占据侧栏内的实际位置;其它插件新增底部入口时向上排布,两者不重叠 |
| 余额 + 今日消耗 | 每个站点两行数字,未配置或出错时给出原因与入口 |
| 峰 / 闲字块 | 仅官方站点显示,颜色随主题自适应 |
| 悬停浮层 | 余额与今日消耗;中转站另有本月已用、本月起算日,官方另有高峰/空闲分账 |
| 手动刷新 | 点击面板上的时间即可立即刷新 |
| 设置浮层 | 增删站点、测试连接、显示开关、刷新间隔,全部在面板内完成 |
| 只存本机 | 令牌与 key 落在 ~/.dsh/usage-panel/config.json,不外发 |
侧栏布局与实现
嵌入式布局
自 0.1.2 起,面板不再以浮层形式覆盖在侧栏之上,而是占据侧栏底部的一个固定位置:位于「记忆」等底部入口之下、账号行(头像与用户名)之上,与相邻入口一样参与正常排版。
0.1.1 及更早版本使用浮层方案,停靠位置由单一参照点推算;当参照点位移或底部新增入口时会出现遮挡,被覆盖的入口无法点击。
嵌入方案的变化:
- 互不遮挡:其它插件在底部新增入口时,面板位置不随之移动,两者不会重叠。
- 位置稳定:窗口尺寸、主题切换、站点轮播均不影响停靠位置,面板始终位于账号行上方。
- 视觉一致:面板采用透明背景与无边框样式,左缩进与相邻入口一致;缩进值在每次布局时按「记忆」文字的起始位置实测得出,不写死像素值。
实现方式
改动全部位于插件内部,未修改 DSH 本身:
- 定位侧栏底部的账号行(含头像与用户名的行元素)。
- 在该行之前插入一个透明占位元素,高度等于面板自身高度;宿主布局会把占位下方的内容下移,形成面板所需空间。
- 面板绘制于占位区域,左右内边距按相邻入口文字的实际起始位置计算。
- 宿主重绘侧栏时占位可能被清除,插件每 900 毫秒检查一次并在缺失时补回。
已知影响
- 侧栏底部高度增加:约 56 像素(等于面板高度),会话列表可见行数相应减少。
- 依赖宿主侧栏结构:定位依赖账号行与底部入口的现有结构。若 DSH 大幅调整侧栏,插件可能无法定位,此时回退为「贴在『记忆』入口上方」的原有做法,功能不受影响,但位置可能不理想。
- 重排闪烁:上述第 4 步补回占位时理论上存在一次重排,正常使用中不易察觉。
- 不占用宿主入口位:面板未注册到 DSH 的插件入口表,因此不会与「记忆」「导入会话」等入口竞争位置,也不会因它们的增减而被挤出;相应地,它也不由宿主统一排版。
界面
截图取自真实桌面端窗口,站点名与令牌已打码。两张侧栏截图均为嵌入后的位置:面板位于「记忆」入口之下、账号行之上。
侧栏常驻块 · 官方站点(峰 字块表示当前处于高峰时段):
侧栏常驻块 · 中转站:
悬停展开 · 官方站点(余额、今日消耗,以及高峰与空闲分账):
悬停展开 · 中转站(今日与本月来自站点统计接口):
设置浮层(在面板内增删站点、测试连接、调整刷新间隔):
安装
需要已安装 DSH(桌面端或 @deepseek-ai/dsh 均可)。把本仓库目录作为插件包安装:
# 在 DSH 会话里让插件管理器安装本地目录(换成你的绝对路径)
plugin_manager action=install_bundle target="C:\path\to\dsh-usage-panel"
安装或卸载插件后,需完整退出并重启一次 DSH,否则侧栏不会显示该面板。原因:DSH 在进程启动时读取插件清单并注册插件的后端入口与前端资源;运行中的进程不会因重新安装而重建这份清单,仅刷新页面(Ctrl+R)同样无法加载新安装的代码。实测表现为:插件文件已在磁盘上,刷新页面后前端资源仍返回 404,侧栏对应位置为空。
生效规则:插件已安装且仅修改 client.js(界面部分)时,刷新页面(Ctrl+R)即可生效;修改 index.js(后端)或重新安装、卸载插件后,必须重启 DSH。
快速开始
- 左栏底部出现用量面板后,点击面板上的「设置」(尚未配置时显示「去设置」),或从
设置 → Usage 面板进入。 - 官方站点:默认「数据来源」为 DSH 已登录账号,处于登录状态即显示余额;如需单独跟踪某个 key,将来源改为「手填 API key」并填入 key。
- 添加中转站:填写站点地址(例如
https://<中转站域名>)与访问令牌。部分站点还需填写数字用户 ID(响应头New-Api-User),填写后可正常取数。 - 点击「测试连接」确认可读取余额后保存。
数据口径
官方站点
- 余额:
GET /user/balance,取balance_infos中人民币项。 - 今日消耗:本机采样推算。官方只提供余额接口,没有用量明细,因此插件记录余额随时间的变化,用「当日首个样本余额 − 当前余额」估算今日消耗,并按采样时刻判断该笔消耗落在高峰还是空闲时段。
- 因此:DSH 未运行的时段不计入统计,插件首次使用的当天从启动时刻起算。
- 端点与时段规则:高峰为北京时间周一至周五(不含法定节假日)
09:00-12:00、14:00-18:00,其余时间为空闲,空闲单价为高峰的一半。设置里的「今天算节假日」开关用于临时调整判定。
中转站(new-api 系)
- 余额:
GET /api/user/self的data.quota除以quota_per_unit(来自GET /api/status,默认 500000)得到基础金额;站点开启display_in_currency时再乘以usd_exchange_rate(默认 7),单位按人民币显示,否则按美元显示。 - 今日 / 本月已用:按优先级尝试三种接口,取到即止——
1.GET /api/data/self(区间汇总,直接给quota)
2.GET /api/log/self/stat(区间统计)
3.GET /api/log/self(明细列表逐条累加;单页被填满 100 条时视为统计不完整,不使用该结果) - 「本月起算」显示自然月首日,说明本月已用是从月初累计到现在,不会随账单日回退。
配置项
| 配置 | 位置 | 说明 |
|---|---|---|
| 刷新间隔 | 设置浮层 | 默认 300 秒,最小 60 秒 |
| 显示哪些站点 | 设置浮层 | 关闭后该站点不参与轮播 |
| 数据来源 | 官方站点卡片 | DSH 已登录账号 或 手填 API key |
| 用户 ID | 中转站卡片 | 站点要求 New-Api-User 时填写 |
| 今天算节假日 | 设置浮层 | 强制把今天按空闲时段计价 |
配置文件:~/.dsh/usage-panel/config.json(站点与令牌)、~/.dsh/usage-panel/samples.json(余额采样,保留 4 天)。
隐私与安全
- 所有请求只发往你在设置里填写的站点,以及
api.deepseek.com;没有第三方统计上报。 - 令牌只写本机配置文件,界面上只显示前三位与后四位(例如
abc…wxyz)。 - Windows 上
chmod 600不生效,配置文件的实际保护来自用户目录权限;插件仍会尝试设置,失败不影响使用。 - 插件提供的是本机只读诊断接口
GET /plugin/usage-panel/report,内容仅为版面几何信息,不含令牌。
已知限制
- 手填官方 API key 是未验证路径:官方目前只对外提供
/user/balance,本机没有可用的官方 key,这条分支未经实测。它是「已登录账号」之外的可选来源,遇到问题时先改回账号来源再排查。 - 官方今日消耗是采样估算,精度等于刷新间隔;插件未运行期间的消费不会被记录。
- 中转站只按 new-api 的接口形态适配。其他面板(如 one-api 的不同分支)字段不一致时可能需要改
index.js里的取数函数。 - 不做跨站汇总:侧栏按站点轮播,浮层只显示当前站点自己的数字(不同站点的余额与单位不可直接相加)。
- 只读取用量,不会触发任何计费操作。
- 嵌入定位通过读取 DSH 侧栏现有 DOM 结构实现,不属于官方接口。宿主调整侧栏结构后需要重新适配;表现为面板回退为贴在「记忆」入口上方,其余功能正常。
开发
index.js 插件后端:取数、采样、配置读写、本地 HTTP 接口
client.js 界面部分:侧栏常驻块、悬停浮层、设置浮层
cordis.patch.yml 装配入口
locale/ 中英文显示元数据
icon.svg 插件图标
docs/screenshots/ 真实截图
开发时的生效规则:只改 client.js → Ctrl+R 即可;改 index.js、或动过 package.json / cordis.patch.yml → 完整退出重启。
许可
MIT