在使用 DeepSeek Harness（DSH）進行智能體開發時，監控 Token 消耗與緩存效率是控制成本和優化性能的關鍵環節。手動解析 session.jsonl.zstd 文件以獲取統計信息既耗時又容易出錯。
下面介紹的 dsh-token-usage-xc 是一個由 xchannel1987 維護的插件，旨在提供實時、可視化的 Token 用量統計與趨勢分析。它支持按模型分桶展示、緩存命中率計算，並提供持久化存儲與 RPC 接口。
核心功能¶
實時用量統計¶
插件會在設置頁新增「今日 Token 用量」分區，實時展示按模型分桶的詳細數據，包括：
* 輸入 Token（uncachedInput）
* 輸出 Token（output）
* 緩存讀 Token（cacheRead）
* 緩存寫 Token（cacheWrite）
* 請求次數
緩存命中率分析¶
插件自動計算緩存命中率，公式爲：
cacheRead / (uncachedInput + cacheRead) × 100%
這有助於評估緩存策略的有效性。
7 日趨勢圖表¶
提供堆疊柱狀圖展示最近 7 日的 Token 消耗趨勢。支持日期切換以查看歷史數據，以及按模型篩選查看特定模型的消耗情況。
會話頂欄徽標（可選）¶
在設置中啓用「會話頂欄顯示今日總 Token」後，會話頁頂欄會顯示今日總 Token 徽標。
* 點擊徽標可快速查看明細。
* 支持 K/M/B 等簡化顯示，懸停查看精確值。
* 針對移動端（≤1023px）進行了排布優化，徽標位於倒數第二位，與後臺任務圖標互不遮擋。
數據持久化¶
數據按天落盤到本地文件，確保重啓不丟失。
* 存儲路徑：~/.dsh/storages/dsh-token-usage-xc/<YYYY-MM-DD>.json
* 策略：啓動時若早於插件加載會自動回填今日用量；舊數據會在 7 天后自動清理。
RPC 接口¶
插件提供 RPC 接口供其他插件調用，便於集成到更復雜的工作流中。
安裝與啓用¶
使用官方安裝命令添加插件：
dsh plugin --profile web add dsh-token-usage-xc
安裝完成後重啓 DSH，即可在設置頁看到新增的「今日 Token 用量」分區。
使用方法¶
-
查看今日用量
打開 DSH 設置，找到「今日 Token 用量」分區，查看按模型分桶的明細數據。 -
查看 7 日趨勢
在用量面板點擊「趨勢」標籤，查看堆疊柱狀圖，點擊日期可查看詳情，支持模型篩選。 -
啓用頂欄徽標
在設置中打開「會話頂欄顯示今日總 Token」，啓用徽標。點擊徽標可快速查看明細。
數據來源與統計口徑¶
- 數據來源：監聽
session/event事件的usage字段，按seq去重，確保每個 assistant/message 恰好一條。 - 總 Token 計算：
uncachedInput + cacheRead + cacheWrite + output。 - 歸檔規則：根據
event.time歸檔到YYYY-MM-DD。 - 兼容性：兼容 DSH 0.1.7-rc.1 或更高版本。
注意事項¶
- 插件僅計最終 usage，數據來源爲 session/event 事件。
- 插件以當前 DSH 進程權限運行，安裝前建議檢查源碼與許可證（MIT）。
總結¶
dsh-token-usage-xc 通過本地持久化和可視化圖表，解決了 DSH 中 Token 統計的痛點。無論是日常成本監控，還是分析緩存優化效果，該插件都能提供結構化的數據支持。
