dsh-balance-tasks：DeepSeek Harness 餘額與任務數估算插件

前言¶

DeepSeek Harness（DSH）採用插件化架構，擴展功能依賴社區貢獻。在開發或使用 DSH 過程中，直接查看總餘額無法判斷剩餘任務數。Bil812 提供的 dsh-balance-tasks 插件解決了這一問題，它在右下角展示實時餘額、峯谷檔位以及基於歷史消耗估算的剩餘任務數。

核心功能¶

該插件提供以下核心能力：

懸浮卡顯示：在界面右下角懸浮卡片，實時顯示賬戶總餘額、當前峯谷檔位及切換倒計時。
任務數估算：基於歷史平均消耗（包含上下文增量、輸出 Token、緩存命中情況），估算當前餘額還能跑多少個任務。
峯谷計價：支持峯谷時段計價（UTC 峯時段 01:00–04:00、06:00–10:00，谷時價格 = 峯時價格 / 2）。
數據持久化：賬本數據持久化存儲，支持重啓後自動恢復。
接口訪問：提供 RESTful API，允許外部程序查詢餘額和任務數。

安裝與啓用¶

安裝前，請確保已在 設置 → 模型 中配置了 DEEPSEEK_API_KEY。插件會複用該 Key，不會出本機。

執行以下命令安裝插件：

dsh plugin --profile web add github:Bil812/dsh-balance-tasks

安裝完成後，重啓 dsh web 即可生效。

配置模型價格¶

插件需要配置模型價格才能正確計算。在 設置 → 插件 → balance-tasks（或直接編輯 $DSH_HOME/settings.yaml）中配置 balance-tasks.models 列表。

配置項包含模型 ID、是否顯示以及峯谷價格。內置默認模型爲 deepseek-v4-flash、deepseek-v4-pro 和 deepseek-v4-flash-vision-exp。

示例配置如下：

balance-tasks:
  models:
    - { model: deepseek-v4-flash, show: true }
    - { model: deepseek-v4-pro, show: true }
    - { model: deepseek-v4-flash-vision-exp, show: true }
    # 自定義模型配置
    - model: deepseek-v5-xxx
      show: true
      peak: { miss: 4.0, hit: 0.15, out: 12.0 }
      offpeak: { miss: 2.0, hit: 0.08, out: 6.0 }

數據口徑與邏輯¶

插件通過複用 llm/stream 的 usage 數據，與官方賬單口徑保持一致。計費價格與 dsh-conversation-cost 一致，包含輸入 miss、緩存 hit 和輸出 out 三種計費方式。

剩餘任務數計算：
採用“統一口徑”計算。從當前上下文 ctx 開始，累加估算下一任務的價格，直到餘額耗盡。公式如下：
下一任務價格 = 平均新增上下文(delta)×miss + 當前上下文(ctx)×hit + 平均輸出(outAvg)×out

峯谷判定：按調用發生時刻判定，2026-08-17 00:00 北京時間起生效。
存儲位置：聚合賬本存儲在 $DSH_HOME/storages/balance-tasks.json。數據每 10 秒節流並僅在變動時原子寫入，每次啓動自動全量讀取恢復。
適用範圍：估算僅對 CNY 餘額生效；無歷史用量時顯示“暫無用量記錄”。

API 接口¶

插件提供 RESTful API 用於查詢餘額和任務數。

獲取餘額數據：

GET /api/balance-tasks

強制刷新余額：

GET /api/balance-tasks?refresh=1

返回的 JSON 包含 balance（餘額）、tier（檔位）、stats（總統計）以及 perModel（各模型詳情，含 remainingTasks、avgTokensPerTask、nextTaskCost 等）。

卸載¶

如需卸載，執行以下命令：

dsh plugin --profile web remove dsh-balance-tasks