dsh-usage-display：在 DeepSeek Harness Web 界面显示模型厂商余额与用量

在智能体开发流程中，API 余额或套餐用量的监控容易被忽视，直到出现欠费或配额耗尽才影响业务。现有的控制台或配置文件查看方式不够直观。dsh-usage-display 插件在 Web 界面的会话头部直接展示厂商的余额或用量信息，解决了这一痛点。

这是什么¶

这是一个会话头部用量徽标插件。由开发者 deluo 维护。它通过 host 进程从各家厂商官方接口取数并缓存，浏览器侧只读本地路由渲染，API key 始终保留在 host 侧，不会下发到浏览器。

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

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

核心功能¶

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

安装与启用¶

前置要求包括 Node.js 和 pnpm，以及 dsh CLI ≥ 0.1.0-rc.6。若使用 pnpm ≥ 10，需在 profile 的 pnpm-workspace.yaml 中配置 allowBuilds。

安装命令如下：

dsh plugin --profile web add github:deluo/dsh-usage-display

安装完成后，可在 Web 界面的 Settings → Plugins → “用量与余额” 中找到该插件并进行配置。

典型用法¶

插件默认配置见 cordis.patch.yml，用户可在 profile 或 home 级的 cordis.patch.yml 中覆盖（后应用层整行替换）。

DeepSeek 配置示例¶

dsh-usage-display:
  display:
    badgeStyle: 'auto'
    panelStyle: 'ring'
    showResetCountdown: true
  providers:
    deepseek:
      enabled: true
      routeIds: ['deepseek-official']
      apiKeyEnv: 'DEEPSEEK_API_KEY'
      baseURL: 'https://api.deepseek.com'
      badgeCurrency: 'CNY'
      warnBelow: 10
      criticalBelow: 5

MiniMax 配置示例¶

    minimax:
      enabled: true
      routeIds: ['minimax', 'minimax-cn', 'minimaxi', 'minimax-coding-plan', 'minimax-token-plan']
      apiKeyEnv: 'MINIMAX_API_KEY'
      baseURL: 'https://api.minimaxi.com'
      badgeMetric: '5h'
      resetTimeStyle: 'countdown'
      warnAbovePercent: 80
      criticalAbovePercent: 90

智谱 GLM 配置示例¶

    zhipu:
      enabled: true
      routeIds: ['zai-coding-cn', 'zai-coding', 'zai', 'glm', 'zhipu', 'bigmodel', 'zhipuai']
      apiKeyEnv: 'ZHIPU_API_KEY'
      baseURL: 'https://open.bigmodel.cn'
      authStyle: 'raw'
      badgeMetric: '5h'
      resetTimeStyle: 'countdown'
      warnAbovePercent: 80
      criticalAbovePercent: 90

展示偏好配置¶

  display:
    badgeStyle: 'auto' # auto | text | ring | bar
    panelStyle: 'ring' # text | ring | bar
    showResetCountdown: true

适用场景与注意¶

该插件适合需要同时管理 DeepSeek、MiniMax、智谱 GLM 等多家厂商配额的开发者。

注意：插件以 host 进程权限运行，API key 由 host 凭证服务解析，不会暴露给浏览器。在 Windows 环境下进行源码安装时，路径必须使用正斜杠（如 D:/Code/...），反斜杠会被解析成非法包名。安装前应检查源码与许可证。

结尾¶

dsh-usage-display 提供了在 DSH Web 界面下直观监控厂商余额与用量的能力，通过 host 端取数与浏览器端渲染分离的设计保证了 API Key 的安全。更多详情请参考 GitHub 仓库或插件目录。