dsh-api-usage-meter：DSH 窗口底部常驻余额与 token 用量监控

前言¶

在 DSH Harness 桌面端开发或使用 DeepSeek API 时，通常会关心两个问题：账户里还剩多少钱，以及当前会话用了多少 token。官方接口只在控制台或网页端显示，桌面端没有直观入口。dsh-api-usage-meter 把这些信息放到窗口底部状态栏，常驻展示，点击可展开明细卡片。

它是什么¶

这是 DSH Harness 的一个客户端插件，由维护者 yunshu-iii 开发。插件在窗口底部添加一条 30px 高度的状态栏，显示 DeepSeek API 的剩余余额与今日、本会话的 token 用量。点击状态栏会弹出明细卡片，列出输入/输出/缓存命中/合计四列，以及今日/本会话/累计三行，还显示总余额、充值余额、赠送余额和今日消耗估算。

核心功能¶

状态栏常驻显示
- 30px 高度的窗口级状态栏，位于底部。
- 默认格式示例：

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

点击展开明细卡片，支持按输入/输出/缓存命中/合计四列，以及今日/本会话/累计三行查看。

余额与 token 统计
- 余额：Host 进程内请求 GET https://api.deepseek.com/user/balance，取 balance_infos。API Key 由 credentials 服务解析（默认引用 DEEPSEEK_API_KEY），仅在 Host 进程内使用，浏览器端只拿到聚合数字，响应中不包含密钥。
- Token：读本机会话日志（$DSH_HOME/sessions）里的 assistant/message 用量，分为输入/输出/缓存命中/缓存写入四项。首次安装会一次性回填历史会话（约几秒），之后只扫描新增或有变化的日志，并按每条会话的事件序号去重。
- 今日消耗：以当天第一次读到的余额为基线，减去当前余额；当天充值后重置为 0。这是估算值，不等同于官方账单。
交互与阈值
- 余额低于阈值时状态栏变色（可配阈值）。
- 余额接口失败时，其他统计照常显示并给出错误提示。
- 状态栏是窗口级槽位，「本会话」跟随当前选中的会话；没有打开会话时显示「—」。

安装与启用¶

方式一：命令行（推荐）

# 桌面端
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」一键安装。

配置¶

在 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 秒一次，且每轮对话结束后触发一次合并刷新。
回填只读本地日志；被删除的会话其用量仍留在累计数里（历史快照语义）。

适用场景¶

希望在 DSH 窗口底部常驻查看余额与 token 用量的开发者或使用者。
需要快速掌握当前会话与今日用量，以便控制成本或调整策略的场景。

注意：插件以当前 dsh 进程权限运行，安装前建议查看源码与许可证。

总结¶

dsh-api-usage-meter 把 DeepSeek API 的余额与 token 用量从网页端拉到桌面端状态栏，点击即可展开明细卡片。它通过 Host 进程内请求余额接口、本地会话日志统计 token，并支持阈值变色与多币种配置，适合需要在 DSH 桌面端实时监控 API 开销的用户。

目录页：https://www.skillhub.cn/plugins/yunshu-iii/dsh-api-usage-meter
GitHub：https://github.com/yunshu-iii/dsh-api-usage-meter