dsh-deepseek-balance：DSH 側邊欄餘額與計費時段監控

前言¶

在使用 DeepSeek API 進行開發或部署智能體時，實時掌握賬戶餘額以及當前處於計費週期的哪個階段（高峯/空閒），有助於進行成本控制。DeepSeek Harness（DSH）支持通過插件擴展功能，dsh-deepseek-balance 正是爲此設計的 Web 側邊欄插件。

插件概覽¶

該插件由開發者 Jianwen-Xu 維護，採用 MIT 許可證。它通過組合包（bundle）的形式掛載到 DSH Web 的側邊欄，提供餘額展示、計費時段判斷及倒計時功能。

核心功能¶

餘額與幣種顯示：展示總餘額及貨幣單位，懸停可查看贈送餘額與充值餘額明細。
計費時段判斷：本地計算北京時間。週一至週五 09:00–12:00、14:00–18:00 爲高峯時段，其餘時間爲空閒時段（價格爲高峯價的一半）。
倒計時：徽標顯示距下一次時段切換的剩餘時間。
狀態指示：顯示賬戶狀態點（綠=正常、黃=不可用、紅=讀取失敗、藍=加載中）。
自適應佈局：側邊欄收起時，顯示爲單個錢包圖標加右下角狀態點，懸停顯示完整信息。

安裝與啓用¶

使用官方安裝命令將插件加入指定的 profile：

dsh plugin --profile web add github:Jianwen-Xu/dsh-deepseek-balance

注意 pnpm 版本：如果使用 pnpm >= 10 從 GitHub 安裝，首次執行 add 可能會因默認拒絕執行 git 依賴的構建腳本而失敗。此時需要在該 profile 的 pnpm-workspace.yaml 中添加 allowBuilds 配置：

allowBuilds:
  dsh-deepseek-balance: true

配置與使用¶

插件按優先級解析 API Key：
1. 憑據服務 ctx.credentials.resolve('DEEPSEEK_API_KEY')（推薦，可在 Web 的 Models 設置頁保存，或寫入 ~/.dsh/.credentials.yaml）。
2. 進程環境變量 DEEPSEEK_API_KEY。

若 API Key 缺失，接口會返回 {"ok":false,"code":"no-api-key"}，UI 顯示紅色狀態點。

接口說明¶

插件提供 GET 接口查詢餘額與狀態：

GET /deepseek-balance?refresh=1

響應示例：

{
  "ok": true,
  "isAvailable": true,
  "display": { "currency": "CNY", "totalBalance": "17.49", "grantedBalance": "0.00", "toppedUpBalance": "17.49" },
  "peakHour": false,
  "peakLabel": "空閒",
  "nextLabel": "高峯",
  "nextSwitchAt": 1789347657403,
  "fetchedAt": 1789125085432
}

注意事項¶

本地開發：本地 checkout 源碼後，需要手動運行 pnpm build 生成 lib/ 目錄，否則安裝無法生效。
時區處理：插件內部將時間平移 8 小時再讀取 UTC 字段，結果與宿主時區無關，確保北京時間的準確性。
緩存與刷新：接口響應帶有 Cache-Control: no-store 頭，手動刷新需在 URL 後加 ?refresh=1。

源碼與目錄¶

插件源碼位於 GitHub：https://github.com/Jianwen-Xu/dsh-deepseek-balance。