前言¶
DeepSeek Harness（DSH）通過插件生態擴展功能。對於開發者或使用者而言，在多會話場景下實時監控 Token 消耗與費用是一項基礎需求。現有的日誌記錄往往難以直觀展示單次會話的成本結構。dsh-token-usage 旨在解決這一問題，它直接嵌入到側邊欄中，提供可視化的用量卡片。
插件簡介¶
本插件由 vector-sunlight 維護，採用 MIT 許可證。它作爲一個 DSH Web 插件，在 dsh-better-sidebar 右側欄註冊「⚡ Token 用量」標籤頁，按會話獨立統計當前會話的 Token 用量與費用。
核心功能¶
- 按會話獨立統計：切換會話時自動複用或新建專屬窗口，統計互不串擾。
- 詳細 Token 統計：支持緩存命中、緩存未命中、緩存寫入、輸出、推理 tokens 的分別統計。
- 緩存命中率可視化：提供緩存命中率進度條，顏色從深紅漸變至松石綠，直觀反映緩存優化效果。
- 峯谷分時計價：基於北京時間（UTC+8）判定高峯與低谷時段。高峯時段爲 9:00-12:00 和 14:00-18:00，其餘爲低谷。每條用量按發生時刻所在時段計價。
- 官網價格同步：Host 啓動時自動抓取 DeepSeek 官網定價頁，解析雙幣種（USD/CNY）及高峯/低谷兩套價格，每 6 小時自動刷新；同步失敗時會回退至內置價格並顯示警告。
- 高精度計費：費用精確到兩位小數，主幣種隨界面語言顯示（中文 ¥ / 英文 $）。
安裝與啓用¶
安裝前請確保已安裝 dsh-better-sidebar 插件（版本 >= 0.12.0）。一鍵安裝腳本會自動檢測並處理依賴。
官方安裝命令¶
在終端執行以下命令添加插件：
dsh plugin --profile web add github:vector-sunlight/dsh-token-usage
依賴處理¶
插件通過 peerDependencies 聲明瞭 dsh-better-sidebar 依賴。安裝腳本會自動檢測該依賴，若未安裝會明確提示並詢問是否自動安裝。
啓動後操作¶
安裝完成後，需重啓 DSH 進程（例如 pm2 restart dsh-web 或直接重啓 dsh web），並在瀏覽器中進行硬刷新（Ctrl+F5 或 Cmd+Shift+R），以確保插件和依賴正確加載。
功能說明¶
計量重置規則¶
爲了保持數據的準確性，插件設定了重置機制：
* 上下文壓縮後重置：當會話觸發上下文壓縮（compaction/end）時，計量數據會重置。
* 一週清零：如果距最後一條記錄已滿一週且無新記錄，舊計量會自動清零並重新開始。
價格同步機制¶
插件在 Host 端運行時，會抓取 DeepSeek 官網的定價頁。它會解析模型在不同時段（高峯/低谷）的價格，並據此計算費用。卡片頂部會實時顯示當前的北京時間（含月日）。
技術實現¶
插件採用 Host 與 Client 分離的架構設計：
* Host 半 (lib/index.js)：作爲 ESMod 模塊運行，負責註冊 /token-usage/api/usage JSON 路由，處理會話持久日誌、解析官網價格及分段計價邏輯。
* Client 半 (lib/client.js)：負責向 betterSidebar 註冊標籤頁，並每 3 秒輪詢 Host 路由以獲取最新數據並更新界面。
注意事項¶
- 依賴要求：必須安裝並啓用
dsh-better-sidebar（>= 0.12.0），否則插件無法顯示。 - 權限說明：插件以當前 DSH 進程的權限運行，安裝前建議檢查源碼與許可證。
- 數據源：價格同步依賴網絡訪問官網，若網絡環境受限可能導致回退至內置價格。
總結¶
dsh-token-usage 提供了從緩存命中率到峯谷計費的完整成本監控方案，適合需要在 DSH 側邊欄中直觀管理 Token 使用量的開發者。更多細節可參考目錄頁或源碼倉庫。
