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 倉庫或插件目錄。