前言¶
DeepSeek Harness (DSH) 採用插件化架構，允許開發者擴展核心功能。在進行智能體開發或長時間運行任務時，追蹤 Token 消耗、精確計費以及管理預算是常見需求。dsh-billing 插件旨在解決這些問題，它提供了一套完整的賬本系統，支持持久化存儲、官方餘額同步以及峯谷計價策略。
核心功能¶
該插件主要提供以下能力：
-
持久化賬本
所有費用記錄存儲在$DSH_HOME/storages/dsh-billing/ledger.json中。寫入採用原子操作並帶有防抖機制，確保數據一致性。 -
精確計費
插件監聽llm/stream瀑布鏈尾的 usage 塊，捕獲每次模型調用的實際消耗。成本計算公式（單位：美元 / 1M tokens）爲：
成本 = 未命中輸入 × cacheMiss + 輸出 × output + (緩存讀 + 緩存寫) × cacheHit
賬本金額恆以美元存儲，展示幣種默認爲人民幣（匯率固定爲 7.2）。 -
官方餘額與預算
利用有效的 API Key 調用官方接口查詢賬戶餘額。餘額數據按refreshMinutes緩存，支持手動強制刷新。預算管理提供預警（≥80%）和超支（≥100%）提示，但僅提醒不阻止調用。 -
峯谷計價
支持峯谷時段計價，時間窗口由官方同步維護（默認生效時間 2026-08-16 16:00 UTC，峯時窗口爲 UTC 01:00-04:00 和 06:00-10:00）。插件在啓動時會自動同步官方價格表。 -
會話統計與歷史
在會話統計行展示實時估算費用，在側邊欄和設置頁展示今日/本月/累計彙總。歷史記錄按保留天數（默認 180 天）修剪，並按天彙總。
安裝與啓用¶
安裝插件需要 Node.js ≥ 20 以及已安裝 DeepSeek Harness CLI。
- 執行以下命令從 GitHub 安裝：
dsh plugin --profile web add github:mahiro6/dsh-billing
或使用本地路徑（開發調試時推薦）：
dsh plugin --profile web add link:<本倉庫絕對路徑>
- 安裝完成後，必須重啓
dsh web服務才能使插件生效：
dsh web
配置與使用¶
插件配置主要持久化在 ledger.json 文件中。除 budget 外，大部分配置項（如貨幣符號、匯率、價格表、峯谷時間）均由插件自動維護或固定默認值，不建議手動修改。
- 預算配置：可在界面設置頁修改，包含啓用狀態、額度、週期（今日/本月/累計/自定義）。
- 餘額查詢：點擊界面中的“刷新余額”按鈕可強制重新查詢，該操作不依賴定時器，由客戶端觸發。
- 價格同步：插件啓動時會自動抓取官方定價頁。若需跳過啓動時的同步（例如離線環境），可設置環境變量
DSH_BILLING_SKIP_STARTUP_SYNC=1。
技術實現與限制¶
- 運行機制：插件不依賴 Cordis 的 Service 或 Context 運行時類，僅使用 Node.js 內置模塊及特定依賴，與宿主共享同一運行時實例。
- 數據精度：會話統計行的費用爲當前檔位的估算值；今日/月度/累計費用以賬本爲準。
- 價格覆蓋：官方價格同步操作會替換整個模型集，官方頁面不存在的舊模型會被移除。
- 權限要求：餘額查詢需要有效的 API Key 且能訪問
api.deepseek.com；API Key 僅發送至官方域名。
總結¶
dsh-billing 爲 DeepSeek Harness 提供了從微觀（單次調用）到宏觀（賬戶預算）的完整成本控制視角。對於需要精細化運營和成本監控的開發者，該插件提供了可靠的解決方案。
