dsh-token-usage-panel：DeepSeek Harness 用量面板

前言¶

DeepSeek Harness（DSH）爲本地 LLM 開發提供了運行環境，但開發者在使用過程中需要實時掌握模型調用的成本與用量。dsh-token-usage-panel 插件在 DSH 對話區下方提供了一個狀態條和明細麪板，用於展示逐次調用的 token 與花費、峯谷計價信息、餘額查詢以及日曆熱力圖。

核心功能¶

狀態條¶

狀態條固定在輸入卡下方，用於展示核心數據。無論屏幕寬度如何變化，會話、今日、餘額三項始終常駐。當空間不足時，次要數字會被壓縮，峯谷倒計時在任何檔位下都保持完整顯示。

狀態條示例：

會話 ¥0.561 · 15.9M   今日 ¥0.561 · 15.9M ............ 餘額 ¥3.44   谷價 · 21h02m   明細 ▴

點擊“明細”按鈕會在輸入卡上方展開一個面板，包含四個頁籤：

逐次調用：展示每一次模型調用的詳情，包括時間、模型、未命中/緩存命中/輸出 token、峯谷時段及花費。支持按本會話、今日、近 30 天或全部切換，並附合計行與分頁加載。
日曆熱力圖：提供 13/26/39/53 周的滾動格子，按當日花費分色。鼠標懸停可查看日期、花費、調用次數及 token 數量。
餘額：顯示充值餘額、贈送餘額及最近觀測時間。支持手動刷新，並提供“今日餘額實扣”與“今日表價估算”的對比。
設置：配置狀態條開關、熱力圖默認週數、緩存寫入計價口徑、餘額刷新間隔、單價表、峯時段及法定節假日。

峯谷計價¶

插件支持峯谷計價功能。默認規則如下：
* 峯時段：工作日 09:00-12:00 和 14:00-18:00（北京時間）。
* 谷時段：其餘時段，包括週末全天與中國法定節假日全天。
* 單價表：默認從本地已裝的 dsh-whale-widget 讀取，也可在設置中手動維護。

數據持久化¶

所有用量數據會持久化存儲至 $DSH_HOME/usage-panel/ledger.json，賬本默認保留 400 天，上限 5 萬條。

HTTP 路由¶

插件提供了只讀的 HTTP 路由，可用於排查數據來源：
* GET /dsh-usage-panel/snapshot.json?sessionId=：獲取狀態條所需的所有數據。
* GET /dsh-usage-panel/calls.json?scope=&sessionId=&limit=&offset=：獲取逐次調用明細。
* GET /dsh-usage-panel/heatmap.json?weeks=：獲取日曆熱力圖數據。
* GET/POST /dsh-usage-panel/config.json：讀取或修改配置。
* GET/POST /dsh-usage-panel/balance.json：讀取或強制刷新余額。

安裝與啓用¶

使用 DSH CLI 進行安裝：

dsh plugin --profile desktop add dsh-token-usage-panel

如果需要進行本地開發或修改代碼即時生效，可使用 link 安裝方式：

dsh plugin --profile desktop add link:<本目錄絕對路徑>

安裝後，可在 設置 → 插件 中開關該插件。關閉後狀態條會立即消失，但已有的賬本數據會保留。

注意事項¶

估算 ≠ 賬單：面板顯示的表價估算受緩存命中判定、贈送額度及優惠活動影響，不替代平臺官方賬單。
餘額可用性：餘額功能僅在賬號登錄模式下可用。使用 API Key 直連時，賬號服務返回空，面板將顯示不可用。
歷史數據：賬本只從插件安裝之後開始記錄，不會回填歷史數據。
契約依賴：插件依賴未公開的 DSH 契約（如 __ModuleLoader__、slot props 等），DSH 升級後若失效需要配合修復。
節假日維護：節假日表默認內置 2026 年數據，次年公佈後需在設置中手動補充。
數據來源：餘額觀測值僅在有餘額可讀且面板打開時存在。

許可證¶

MIT