前言¶
DeepSeek Harness (DSH) 採用插件化架構，旨在通過模塊化擴展提升開發與調試效率。在使用 DSH 進行智能體開發時，精確掌握 API 調用成本、追蹤每日餘額變動是剛需。dsh-balance-pie 插件提供可視化的餘額監控與歷史數據記錄，幫助開發者快速定位消耗異常，避免超支。
插件簡介¶
該插件由 f1yan9 維護，定位爲 DSH 網頁端的客戶端插件。它通過一個可拖拽的懸浮餅圖展示每日初始餘額、真實項目消耗及剩餘餘額，並提供 GitHub 風格的歷史熱力圖與每日表格，實現餘額的實時監控與歷史回溯。
核心功能¶
1. 懸浮餅圖與交互¶
插件在 DSH 網頁端右下角顯示一個懸浮餅圖，直觀展示“今日初始餘額”、“真實消耗”和“剩餘餘額”三個維度的數據。
* 交互操作：支持拖拽餅圖以調整位置；鼠標懸停在扇區上可查看詳細數據；提供最小化按鈕（—）、設置按鈕（⚙）、刷新按鈕（↻）以及充值圖標按鈕。
* 側邊欄自適應：當側邊欄摺疊時，組件會變爲條形圖（展開時爲水平條形圖，在窄軌道時顯示爲垂直條形圖+餘額），點擊側邊欄可展開餅圖。
2. 真實消耗計算¶
插件直接基於餘額的實際減少來計算消耗，而非單純估算。
* 分攤邏輯：消耗金額會按估算的用量分攤至各個項目。
* 自動處理：充值和退款操作會被自動識別並計入計算，確保數據反映真實的賬戶變動。
3. 充值檢測與一鍵充值¶
插件支持自動檢測充值行爲，並在檢測到充值後更新余額基線。同時提供一鍵跳轉至官方充值頁面的按鈕，方便用戶快速操作。
4. 歷史數據記錄¶
插件提供完整的消耗歷史記錄功能：
* 可視化：GitHub 風格的每月熱力圖，無記錄的日期顯示爲白色。
* 表格：按日期顯示的詳細表格，包含日期、花費和剩餘餘額。
5. 本地持久化¶
所有狀態數據存儲在本地，包括初始餘額和今日的充值總額。同日重啓 DSH 後，這些狀態會自動恢復。
安裝與啓用¶
在確保已安裝 DeepSeek Harness (DSH) 並配置好 API Key 的前提下，使用以下命令安裝該插件：
dsh plugin --profile web add github:f1yan9/dsh-balance-pie
安裝完成後，重啓 DSH 網頁端並打開界面，懸浮餅圖將出現在右下角。如需卸載，可執行：
dsh plugin --profile web remove dsh-balance-pie
典型用法¶
- 監控餘額：在 DSH 網頁端查看右下角的懸浮餅圖，拖動可調整位置，懸停查看詳情。
- 查看歷史：點擊懸浮餅圖上的設置圖標（⚙），進入「Balance」設置中心，切換至歷史頁面查看熱力圖和表格。
- 充值操作：當檢測到餘額不足或手動充值時，點擊充值圖標直接跳轉至官方充值頁面。
配置參數¶
插件支持通過設置中心的「Balance」面板或 DSH Profile 的 cordis.patch.yml 文件進行配置。常用參數如下：
| 參數名 | 描述 | 默認值 |
|---|---|---|
pollIntervalMs |
餘額查詢間隔 | 10000 ms |
pricesJson |
各模型非高峯期單價（每百萬 Token） | deepseek-v4-flash 預設 |
peakMultiplier |
峯時價格倍率 | 2 |
language |
界面語言（auto 自動跟隨 DSH） |
auto |
displayCurrency |
顯示貨幣（轉換後） | auto (賬戶貨幣) |
fxRatesJson |
人民幣對目標貨幣匯率 JSON | {"USD":0.14,"EUR":0.13,"GBP":0.11,"JPY":20,"KRW":190} |
topUpUrl |
充值頁面 URL | 官方充值頁 |
注意事項¶
- 消耗計算：插件統計的是真實的餘額減少量，項目金額是按估算用量分攤的。如果發現消耗與賬單不符，可在設置中校準價格。
- 數據恢復：初始餘額和今日狀態僅在本地持久化，同日重啓後可恢復。
- 充值延遲：充值檢測依賴於下一次輪詢（默認 10 秒），已花費的歷史充值無法 retro-fix。
- 數據存儲：歷史數據存儲在
$DSH_HOME/dsh-balance-pie/目錄下，包含每日狀態文件和 90 天保留期的 JSONL 日誌文件。 - 許可證：該插件採用 MIT 許可證開源。
總結¶
dsh-balance-pie 插件通過可視化的餅圖和歷史熱力圖，爲 DSH 用戶提供了清晰的餘額監控手段。它支持真實消耗計算、自動充值檢測及本地持久化，適合需要在開發過程中精細管理 API 成本的用戶。
