dsh-usage-display

在 dsh Web 界面显示模型厂商余额 / 套餐用量的会话头部徽标插件。host 进程从各家厂商官方接口取数并缓存，浏览器侧只读本地路由渲染；API key 始终留在 host，不会下发到浏览器。

内置三家厂商，按多厂商适配器架构组织，新增厂商只需实现一个 adapter：

厂商	`providerId`	展示内容
DeepSeek	`deepseek`	多币种账户余额（granted / topped-up 拆分）
MiniMax	`minimax`	Token Plan 配额（5 小时窗口与周窗口）
智谱 GLM	`zhipu`	Coding Plan 配额（5h、周限额、工具用量三个百分比）

效果预览

设置页（Settings → Plugins → “用量与余额”）可按通用显示 / DeepSeek / MiniMax / 智谱 GLM 分区调整展示偏好与告警阈值，保存后立即生效：

设置页“用量与余额”

特性

会话头部用量徽标：展示当前模型对应厂商的主指标，点击展开明细面板并支持手动刷新。
可配置告警阈值：余额低于阈值、配额用量超过阈值时，徽标状态点与进度条按 warn（黄）/ critical（红）两级染色。
可配置进度可视化：percent 类指标在徽标与面板中支持文本、环形图、条形图三种形态（display.panelStyle），徽标可用 auto 按指标类型自动选择。
设置页热更新：Settings → Plugins → “用量与余额”页可即时调整展示偏好与告警阈值，保存后 host 重建运行时并重新取数，无需重启；接入类字段仍走 cordis 配置。
真正产生模型调用后自动取数：turn/start 与 turn/end 各全量刷新一次，切换模型时只定向刷新新选中的厂商。
host 刷新落定后通过 SSE 通知浏览器重读本地缓存；浏览器绝不直连厂商 API。
每家厂商独立缓存与故障隔离：一家失败不影响其他家，失败时保留上次成功值并标注更新时间。
凭证只以引用名出现在配置中，每次取数由 dsh 凭证服务实时解析，轮换后下次请求即生效。

前置要求

Node.js（与运行中的 dsh 相同的版本即可）
pnpm
dsh CLI ≥ 0.1.0-rc.6

安装

从源码安装（开发）


## 配置

默认配置见 [cordis.patch.yml](https://github.com/deluo/dsh-usage-display/blob/f77ff1989b02e065920743def2452f4f2dac156e/cordis.patch.yml)，用户可在 profile 或 home 级的
`cordis.patch.yml` 中覆盖（后应用层整行替换）：

```yaml
dsh-usage-display:
  display:
    badgeStyle: 'auto' # auto | text | ring | bar；徽标上的进度形态
    panelStyle: 'ring' # text | ring | bar；面板里 percent 指标的形态
    showResetCountdown: true # 徽标配额文案是否带“距重置”倒计时
  providers:
    deepseek:
      enabled: true # 关闭后显示“已停用”，不再取数
      routeIds: ['deepseek-official'] # dsh provider 路由 id → 本插件 providerId（providerId 自动补入）
      apiKeyEnv: 'DEEPSEEK_API_KEY' # 凭证引用名，不是 key
      baseURL: 'https://api.deepseek.com'
      badgeCurrency: 'CNY' # 徽标主币种；账户无此币种时保持接口返回顺序
      warnBelow: 10 # 余额低于此值 → warn；'off' 关闭
      criticalBelow: 5 # 余额低于此值 → critical；'off' 关闭
    minimax:
      enabled: true
      routeIds: ['minimax', 'minimax-cn', 'minimaxi', 'minimax-coding-plan', 'minimax-token-plan']
      apiKeyEnv: 'MINIMAX_API_KEY' # 只存引用名，key 由 host 运行时解析
      apiKeyAliases:
        [
          'MINIMAX_TOKEN_PLAN_API_KEY',
          'MINIMAX_CODING_PLAN_API_KEY',
          'MINIMAX_CODING_API_KEY',
          'MINIMAX_CN_API_KEY',
          'MINIMAX_API_KEY',
          'MINIMAX_API_TOKEN',
        ]
      baseURL: 'https://api.minimaxi.com' # 含 minimaxi.com 走国内站，否则走 api.minimax.io
      badgeMetric: '5h' # 徽标主指标：5h | weekly
      resetTimeStyle: 'countdown' # 重置时间：countdown 倒计时 | time 本地时间点
      warnAbovePercent: 80 # 用量超过此百分比 → warn；'off' 关闭
      criticalAbovePercent: 90 # 用量超过此百分比 → critical；'off' 关闭
    zhipu:
      enabled: true
      routeIds: ['zai-coding-cn', 'zai-coding', 'zai', 'glm', 'zhipu', 'bigmodel', 'zhipuai']
      apiKeyEnv: 'ZHIPU_API_KEY'
      apiKeyAliases:
        [
          'ZAI_CODING_CN_API_KEY',
          'ZAI_CODING_API_KEY',
          'GLM_API_KEY',
          'ZAI_API_KEY',
          'BIGMODEL_API_KEY',
        ]
      baseURL: 'https://open.bigmodel.cn'
      authStyle: 'raw' # 'raw' | 'bearer'
      badgeMetric: '5h' # 徽标主指标：5h | weekly | tools
      resetTimeStyle: 'countdown' # 重置时间：countdown 倒计时 | time 本地时间点
      warnAbovePercent: 80 # 用量超过此百分比 → warn；'off' 关闭
      criticalAbovePercent: 90 # 用量超过此百分比 → critical；'off' 关闭

公共字段：

字段	类型	默认	说明
`enabled`	`boolean`	`true`	关闭后徽标显示“用量已停用”，不再取数
`routeIds`	`string[]`	`[]`	dsh provider 路由 id → 本插件 providerId，用于模型切换联动；`providerId` 本身总会自动加入映射

展示偏好（插件级 display）：

字段	类型	默认	说明
`badgeStyle`	`'auto' \| 'text' \| 'ring' \| 'bar'`	`'auto'`	徽标进度形态；`auto` 对 percent 指标用迷你条形图、金额保持纯文本
`panelStyle`	`'text' \| 'ring' \| 'bar'`	`'ring'`	面板中 percent 指标的形态
`showResetCountdown`	`boolean`	`true`	徽标配额文案是否带“距重置”倒计时

DeepSeek 专属：

字段	类型	默认	说明
`routeIds`	`string[]`	`['deepseek-official']`	DeepSeek 官方 harness 适配器上报的 provider 路由 id；`deepseek` 作为 providerId 仍会自动加入
`apiKeyEnv`	`string`	`DEEPSEEK_API_KEY`	凭证引用名，请求 `GET {baseURL}/user/balance` 时使用
`baseURL`	`string`	`https://api.deepseek.com`	余额接口前缀
`badgeCurrency`	`string`	`CNY`	徽标主币种（按接口返回的 `currency` 匹配，大小写不敏感）；无此币种时保持接口顺序
`warnBelow`	`number \| 'off'`	`10`	余额低于此值徽标变黄
`criticalBelow`	`number \| 'off'`	`5`	余额低于此值徽标变红

智谱专属：

字段	类型	默认	说明
`apiKeyEnv`	`string`	`ZHIPU_API_KEY`	首选凭证引用名
`apiKeyAliases`	`string[]`	见上	首选未配置时按顺序回退；指向模型适配器已在用的引用名即可直接复用其 key
`baseURL`	`string`	`https://open.bigmodel.cn`	实际请求 host 按域名路由：含 `bigmodel.cn` → `open.bigmodel.cn`，否则 `api.z.ai`
`authStyle`	`'raw' \| 'bearer'`	`'raw'`	首选鉴权头风格；401/403 自动换另一种重试，非法值在配置层直接报错
`badgeMetric`	`'5h' \| 'weekly' \| 'tools'`	`'5h'`	徽标主指标
`resetTimeStyle`	`'countdown' \| 'time'`	`'countdown'`	重置时间展示：`countdown` 显示紧凑倒计时（如 `2h13m`、`2d3h`）；`time` 显示本地时间点（如 `15:30`、`明天 08:30`）
`warnAbovePercent`	`number \| 'off'`	`80`	用量超过此百分比徽标变黄
`criticalAbovePercent`	`number \| 'off'`	`90`	用量超过此百分比徽标变红

MiniMax Token Plan 专属：

字段	类型	默认	说明
`routeIds`	`string[]`	`['minimax', 'minimax-cn', 'minimaxi', 'minimax-coding-plan', 'minimax-token-plan']`	dsh provider 路由 id → 本插件 providerId
`apiKeyEnv`	`string`	`MINIMAX_API_KEY`	首选凭证引用名
`apiKeyAliases`	`string[]`	多个 Token Plan / Coding Plan / CN 别名	首选未配置时按顺序回退
`baseURL`	`string`	`https://api.minimaxi.com`	区域识别基准地址；含 `minimaxi.com` 走国内站，否则走 `api.minimax.io`
`badgeMetric`	`'5h' \| 'weekly'`	`'5h'`	徽标主指标
`resetTimeStyle`	`'countdown' \| 'time'`	`'countdown'`	重置时间展示形态
`warnAbovePercent`	`number \| 'off'`	`80`	用量超过此百分比徽标变黄
`criticalAbovePercent`	`number \| 'off'`	`90`	用量超过此百分比徽标变红

warn* / critical* 配反（如 warnBelow 小于 criticalBelow）时按更严格的方向归一；全部设为 'off' 关闭该厂商的告警染色。

配置里从不出现 key 本身。apiKeyEnv / apiKeyAliases 都是凭证引用名，host 每次取数时经 ctx.credentials.resolve() 解析：进程环境优先，其次 $DSH_HOME/.credentials.yaml （Models 页 / dsh credentials set 写入），再以项目与用户的 .env 回退。模型侧已配置的智谱 key 可以直接复用——把 apiKeyEnv 指向模型适配器所用的引用名（dsh web --dump-config 可查到）；托管存储里的 key 变更下次取数即生效，进程 env 的快照在启动时冻结。

使用

打开会话后，头部操作区出现用量徽标：DeepSeek 显示余额金额，MiniMax 与智谱显示配额窗口的已用百分比与重置时间；命中告警阈值时状态点与进度条变黄/红。
徽标左侧的状态点只在纯文本/金额模式与异常状态时出现；有迷你条形图或环形图时颜色信息已由图形表达，状态点自动隐藏。
点击徽标展开当前模型对应厂商的明细面板，含状态、指标明细（金额行 / 配额表）、更新时间与“刷新”按钮；配额指标按 display.panelStyle 渲染为环形图、条形图或纯数字表格。手动刷新会等待真实取数落定。
MiniMax 与 GLM 配额重置时间都支持两种形态：countdown 显示 2h13m / 2d3h 等倒计时，time 显示 15:30、明天 08:30、周三 08:30 等本地时间点。
在 Settings → Plugins → “用量与余额”页按“通用显示 / DeepSeek / MiniMax / 智谱 GLM”分区，保存后立即生效。该页写入的是用户设置文档；enabled / routeIds / apiKeyEnv / baseURL / authStyle 等接入类字段不在此暴露，仍在 cordis.patch.yml 中维护。
切换模型时徽标高亮立即跟随（读模型选择目录 store）；取数仍由轮次事件驱动，切换后尚未发消息时展示的是缓存快照。
当前模型的厂商未接入（routeIds 未覆盖）时徽标进入中性态显示“其他厂商”，面板列出全部已接入厂商。
每家厂商有五态：loading / ok / unconfigured / disabled / error；失败时展示上次成功值并标注原更新时间。

安装

说明文档

dsh-usage-display

效果预览

特性

前置要求

安装

从源码安装（开发）

使用