dsh-token-stats - 本地 Token 統計與成本分析插件

前言¶

DeepSeek Harness（DSH）採用插件化架構。開發者在調試或長期使用過程中，常需要追蹤跨會話的 Token 消耗情況與費用成本。本插件在 DSH 的設置頁新增「Token 統計」分區，並提供常駐懸浮小窗。它不依賴外部服務，完全通過讀取本地會話日誌聚合數據，實現零模型消耗的用量監控。

核心功能¶

常駐懸浮小窗¶

界面右下角默認停靠一個懸浮小窗，用於隨時查看今日用量。

1. 四種形態

   • 吸附態：貼邊細條，僅顯示運行狀態點與豎排今日數字。
   • 摺疊態：小橫條，顯示名稱、齒輪、狀態點與今日數字。
   • 懸浮態：完整卡片，包含摺疊態內容、熱力圖與圖例。
   • 完整歷史面板：獨立浮層，展示全年熱力圖與彙總指標。

2. 交互方式

   • 懸停：吸附態下懸停可預覽，摺疊/懸浮態下懸停方塊可查看當日輸入/輸出/緩存明細。
   • 雙擊：吸附態展開爲懸浮態；懸浮態雙擊退回摺疊態。
   • 拖動與縮放：拖動卡片任意位置可移動，拖右下角把手可調整大小。
   • 全年曆史：鼠標停在標題欄約 160ms 可展開完整歷史面板。
   • 點擊方塊：選中日期後，主數字切換爲當日值，標籤更新，並出現「回今天」按鈕。

3. 運行狀態

   • 有會話運行時，卡片外框呈現藍色呼吸效果；系統開啓「減少動態效果」時降級爲常亮藍框。
   • 小窗會自動停靠邏輯：窗口未最大化時自動最小化爲吸附態，最大化時恢復爲完整卡片。

設置頁分區¶

設置頁中的「Token 統計」分區提供完整的用量分析。

1. 頂部指標卡

   • 連續天數：當前連續使用天數 / 最長連續天數。
   • 累計 Token：隨頁籤週期取值（每日/每週/每月/累計）。
   • 峯值 Token、最長單輪耗時：隨頁籤和區塊聯動。

2. Token 活動熱力圖

   • 支持每日/每週/每月/累計四個時間頁籤。
   • 未用時段顯示空心方塊，有用量時段按實際用量四分位自適應填色。
   • 懸停方塊可查看該時段明細氣泡。

3. 模型用量分佈

   • 展示模型行與環形餅圖。
   • 顯示緩存命中率（口徑與 OpenAI 一致）。
   • 懸停模型行可查看輸入/輸出/緩存明細。

4. 性能時序

   • 展示用時、工具調用次數與耗時、首字時間（TTFT）、輸出速度。

費用估算¶

點擊「費用單價配置」可設置模型單價。

1. 基本單價

   • 每個模型可配置輸入、輸出、緩存讀、緩存寫四項單價（單位：貨幣/每百萬 token）。
   • 支持指定幣種，各幣種分別合計。

2. 時段單價（峯谷價）

   • 可添加多個價格檔，每個檔包含四項單價與綁定的時間段。
   • 支持跨零點時間段（如 22:00～06:00）。
   • 支持按星期指定生效範圍。

3. 歷史價

   • 記錄歷代價格，按生效起始日計算某日費用。

4. 共享定價

   • 同一定價條目可套用多個模型 key。

套餐配額與預算告警¶

1. 套餐配額

   • 支持設置適用範圍（全部模型/Provider前綴/指定模型）與計量單位（調用次數/Token量/費用）。
   • 按模型細分額度，彙總行顯示總使用率。

2. 預算告警

   • 支持設置日預算（費用或 Token 雙口徑）。
   • 超標當天熱力圖方塊帶紅圈，頂部顯示告警條。

會話下鑽¶

點擊熱力圖方塊後，展示該時間區塊消耗最高的會話（Top 10）。

1. 主 / 子代理視圖
   • 綜合：只列主會話，子代理摺疊。
   • 全部：主/子平鋪混合。
   • 主對話：僅列主會話。
   • 子對話：僅列子代理會話。
2. 會話明細
   • 顯示會話名（工作區/UUID 或標題）。
   • 懸停顯示完整目錄名與輸入/輸出/緩存明細。
   • 提供一鍵複製會話名稱與 ID 按鈕。

導出¶

1. 導出 CSV：日序列逐日一行，帶 UTF-8 BOM。
2. 導出 JSON：包含 totals, days, models，支持雙幣種費用。

安裝與前置條件¶

1. 環境要求

   • DSH 版本需 >=0.1.7-alpha.1
   • Node.js 版本需 >=22.15

2. 數據依賴

   • 插件依賴本地會話日誌：$DSH_HOME/sessions/**/session.l.zstd（舊格式）與 session.v3.jsonl.zstd（新格式）。
   • 配置文件位於：$DSH_HOME/token-stats.cfg.json。

3. 安裝方式

   • 將插件代碼放置到 DSH 的插件目錄中（具體路徑取決於 DSH 的配置，通常爲 ~/.dsh/plugins/ 或類似結構）。

典型用法¶

1. 查看今日用量：鼠標懸停在右下角的懸浮小窗上，查看今日數字。
2. 切換日期：雙擊懸浮小窗展開，點擊熱力圖中的方塊查看特定日期的用量。
3. 配置單價：點擊懸浮小窗標題欄的齒輪圖標，或進入設置頁的「Token 統計」分區，配置模型的輸入、輸出及緩存單價。
4. 查看模型分佈：在設置頁查看各模型的用量佔比及緩存命中率。
5. 導出數據：在設置頁點擊「導出 CSV」或「導出 JSON」按鈕，保存統計數據。

注意事項¶

1. 零模型消耗：插件在運行時不會註冊任何工具或發起 LLM 調用，所有數據均爲讀取本地日誌。
2. 實時性：數據更新爲秒級準實時，受日誌落盤延遲影響，有數秒延遲。
3. 首次解析：首次安裝或無緩存時打開分區，需全量解析歷史日誌，耗時約半分鐘。
4. 配置文件：費用配置（定價、套餐、顏色）最終寫入 $DSH_HOME/token-stats.cfg.json，直接編輯該文件並刷新頁面即可生效。