API 用量状态栏 yunshu-iii/dsh-api-usage-meter

dsh-api-usage-meter

DSH Harness 桌面端插件：在窗口底部常驻一条状态栏，显示 DeepSeek API 的剩余余额和 token 用量，点击展开明细卡片。

配套插件：dsh-wallpaper-theme —— 整窗壁纸与分级磨砂玻璃外观。

状态栏

它是什么

给 DSH Harness 的窗口底部加一条 30px 常驻状态栏：

● 余额 ¥12.38 │ 今日 1555.26万 tokens │ 本会话 1191.38万 tokens 更新于 22:16:21

点一下展开明细卡片，按 输入 / 输出 / 缓存命中 / 合计 四列，分别看 今日 / 本会话 / 累计 三行，外加总余额、充值余额、赠送余额、今日消耗（估算）和「刷新」按钮。

余额偏低时状态栏会变色（可配阈值），余额接口失败时其余统计照常显示并给出错误提示。

安装

方式一：命令行（推荐）

桌面端
dsh plugin --profile desktop add github:yunshu-iii/dsh-api-usage-meter

Web 端
dsh plugin --profile web add github:yunshu-iii/dsh-api-usage-meter

装完重启 Harness 生效。profile 名以本机 ~/.dsh/profiles 下的目录为准。

方式二：插件页

侧栏 插件 → 添加插件 → 安装第三方插件，选择本仓库（或先用 git clone 到本地，再用「本地目录」安装）。

也可以先安装 dsh-plugin-market，在市场里搜「usage」一键装。

数据口径

- 余额：Host 进程内请求 GET https://api.deepseek.com/user/balance，取 balance_infos。
API Key 由 credentials 服务解析（默认引用 DEEPSEEK_API_KEY），只在 Host 进程内使用；浏览器只拿到聚合后的数字，任何响应里都不含密钥。
- token：读本机会话日志（$DSH_HOME/sessions）里的 assistant/message 用量，分输入 / 输出 / 缓存命中 / 缓存写入四项。
首次安装会一次性回填历史会话（约几秒），之后只扫描新增或有变化的日志，并按每条会话的事件序号去重。
- 今日消耗是估算：以当天第一次读到的余额为基线，减去当前余额；当天充值后重置为 0。
- 本地统计 ≠ 官方账单：其他设备、其他客户端、其他工具的用量不会出现在这里。

配置

在 profile 的 cordis.patch.yml 里覆盖本行配置即可（所有键都可省略）：

- id: api-usage-meter
name: dsh-api-usage-meter
config:
refreshIntervalMs: 60000 # 余额刷新间隔 lowBalanceThreshold: 5 # 低于该值状态栏变黄 lowBalanceCritical: 1 # 低于该值状态栏变红 currency: CNY # 多币种账户时选择显示哪一种 apiKeyRef: DEEPSEEK_API_KEY balanceUrl: https://api.deepseek.com/user/balance sessionRoot: null # 默认 $DSH_HOME/sessions backfill: true # 是否回填历史会话

存储与隐私

- 用量状态存在 $DSH_HOME/api-usage-meter/state.json（按天、按会话、按序号水位），刷新页面或重启应用都不会重复计数。
- 快照路由只响应 GET，拒绝非回环 Host 与跨源 Origin，响应带 cache-control: no-store。
- 不联网上报、不写会话、不注入提示词，不增加模型 token 开销。

兼容性

- 面向 DSH Harness 桌面端（Windows / macOS / Linux）；Web 宿主同样可用。
- 需要 DSH 0.2 内核与 Node.js >= 20。

已知限制

- 状态栏是窗口级槽位，「本会话」跟随当前选中的会话；没有打开会话时显示「—」。
- 余额不是逐 token 实时：最快 15 秒一次，且每轮对话结束后触发一次合并刷新。
- 回填只读本地日志；被删除的会话其用量仍留在累计数里（历史快照语义）。

目录结构

| 文件 | 作用 |
| index.js | Host 半区：读取凭据、查询余额、聚合 token 用量、注册 GET /api-usage-meter/snapshot |
| lib/logs.js | 读取会话日志（独立 Zstandard 帧拼接格式，按帧头扫描边界） |
| client.js | Client 半区：注册 shell.bottom 槽位，每 3 秒轮询快照并渲染状态栏与详情卡片 |
| cordis.patch.yml | 向当前 profile 插入本插件行 |

License

MIT © yunshu-iii