前言¶
DeepSeek Harness 的投影緩存主要用於展示，數據可能滯後或覆蓋不全。對於需要精確覈算成本或監控使用量的場景，直接讀取會話日誌是更可靠的選擇。dsh-token-ledger 正是基於這個需求開發，它不依賴投影緩存，而是直接解析本地會話日誌，提供基於本地日期的每日 Token 消耗統計。
是什麼¶
這是一個由 doremifaso12345 維護的插件，用於監控 DeepSeek Harness 的每日 token 消耗。它提供設置頁卡片、輸入框徽標、聊天命令和模型工具四個入口，幫助用戶直觀地瞭解 Token 使用情況。
核心功能¶
儀表盤與數據視圖¶
儀表盤展示四個互不重疊的用量桶，全部基於 Provider 真實上報值：
* 未緩存輸入：未命中前綴緩存的輸入。
* 緩存讀取：命中緩存的輸入。
* 緩存寫入：寫入緩存的輸入。
* 輸出：補全輸出（已含 reasoning，不重複計）。
除此之外，還提供以下指標：
* 合計：四者之和。
* 緩存命中率：計算公式爲 緩存讀取 / (未緩存輸入 + 緩存讀取 + 緩存寫入)。
* 累計 Token 數：全部歷史四桶之和。
* 峯值 Token 數：單日最高值。
* 最長聊天時長：定義爲“連續活動時長”，即相鄰事件間隔不超過 30 分鐘的累積時間，而非首尾時間差。
* 活動熱力圖：GitHub 貢獻圖樣式，展示 52 周 × 7 天的消耗情況。
* 工具排行：按調用次數和成功率排序。
交互入口¶
- 設置頁卡片：設置 → Token 賬本。支持選擇 7/14/30/90/180/365 天窗口，支持一鍵導出 CSV（帶 BOM）。
- 輸入框徽標：顯示今日合計（如
1.23M）與近 7 天累計，每 60 秒刷新，懸停顯示明細。 - 聊天命令：通過
/tokens命令快速查看報表。 - 模型工具：
token_usage工具，允許 Agent 直接查詢用量數據。
安裝¶
插件無需構建，直接通過命令安裝。請確保使用正確的 Profile 名稱（默認爲 web）。
dsh plugin --profile web add github:doremifaso12345/dsh-token-ledger
安裝後請重啓 dsh web。
典型用法¶
聊天命令¶
在聊天框中使用以下命令：
* /tokens：查看近 7 天的日報表與總覽。
* /tokens 30：查看近 30 天的數據。
* /tokens today：只看今日數據。
* /tokens csv [days]：導出 CSV 到 harness home。
* /tokens help：查看幫助。
模型工具¶
調用 token_usage 工具，傳入 days 和 includeSessions 參數。
環境與依賴¶
運行環境¶
- Node.js：必須滿足
^22.15.0 || >=23.8.0。此版本範圍包含了 Node 內置zlib.zstdDecompressSyncAPI，用於解壓多幀 zstd 會話日誌。如果版本過低（如 23.0–23.7），插件會直接報錯，避免顯示錯誤的 0 數據。 - DeepSeek Harness：目標版本
0.1.5-rc.2。 - 數據源：
<DSH_HOME>/sessions/<workspace>/<session>/session.v3.jsonl.zstd。插件會自動處理多幀 zstd 容器，並復刻官方投影的語義（如重試場景下的摺疊計費）。
配置¶
在 cordis.patch.yml 中可調整：
- insert:
- id: dsh-token-ledger
name: 'dsh-token-ledger'
config:
enabled: true # 總開關
cacheTtlMs: 5000 # 結果緩存時間（毫秒）
root: null # 顯式指定 harness home
注意事項¶
- 零第三方依賴：插件僅使用 Node 內置模塊，不依賴
@deepseek-ai/*包，這意味着宿主版本升級時，只要不破壞契約依賴，插件仍能正常工作。 - 數據完整性：如果
sessions目錄不存在或日誌解壓失敗，儀表盤會顯示空數據，不會靜默報錯。 - 契約依賴：安裝前請確保宿主已掛載
commands、tools、webServer等服務，否則部分入口將不可用。
總結¶
dsh-token-ledger 提供了一套完整的 Token 消耗監控方案，從數據源（會話日誌）到展示形式（儀表盤、熱力圖、導出）都經過了針對性設計。它解決了投影緩存可能缺失或不準確的問題，適合需要精細化管理和成本覈算的開發者使用。
