前言¶
DeepSeek Harness (DSH) 的核心理念是「一切皆插件」。在使用 DSH 進行智能體編排或日常開發時，跟蹤 Token 消耗、計算成本以及診斷性能異常是常見需求。dsh-usage-board 是一個爲此場景設計的客戶端插件，旨在提供實時的用量監控與成本覈算。
這是什麼¶
dsh-usage-board 是一個專爲 DSH 設計的用量與成本可視化看板插件，由 zhm20001 維護。它解決了在長時間運行或複雜調用鏈中難以直觀查看資源消耗的問題，通過可視化界面將數據呈現出來。
核心功能¶
該插件具備以下核心能力：
- 實時監控：實時捕獲會話內的 Token 消耗、Step 耗時和異常指標。
- 歷史回溯：支持冷啓動增量回溯歷史全量會話。
- 關係分析：按 Sub-agent DAG 調用關係進行樹狀歸集與反向明細穿透。
- 零依賴架構：基於 Node.js 22.5+ 原生
node:sqlite構建，無運行時依賴。 - CQRS 架構：採用 CQRS 架構，以 DSH 會話文件爲只讀真相源，以 SQLite 數據庫爲可重建只讀視圖。
- 雙層讀模型：支持暖/熱雙層讀模型，利用 SQLite 和內存快照提升讀取性能。
- 成本洞察：支持 DeepSeek 官方餘額透傳與實時額度預測，並包含夜間/階梯價反事實節約計算。
- UI 掛載：三處無縫 UI 掛載，分別位於會話頁 Tab、側欄入口和全屏儀表盤。
安裝與啓用¶
啓用該插件需要滿足環境要求並執行安裝命令。
-
環境準備
確保安裝了 Node.js >= 22.5.0。 -
註冊插件
在插件目錄下執行以下命令將插件註冊至 DSH Web Profile：
dsh plugin --profile web add "$(pwd)"
- 啓動宿主
啓動 DSH Web 宿主：
dsh --profile web --port 3099
啓動後訪問 `http://127.0.0.1:3099` 即可使用該功能。首次啓動會進行冷啓動回溯，掃描全部歷史會話。
配置與數據¶
插件在運行時需要關注配置項與數據存儲路徑。
餘額查詢配置¶
若需查看 DeepSeek 官方餘額與實時額度預測，需配置 API Key：
* 方式一：在 DSH 的「設置 → 模型」中填入 DEEPSEEK_API_KEY。
* 方式二：在 ~/.dsh/.credentials.yaml 中寫入 Key（權限需設置爲 0600）。
注：餘額查詢是本插件唯一的外網請求，其餘處理均在本地執行。未配置 Key 時餘額卡片僅展示佔位符，不影響本地統計功能。
數據存儲路徑¶
插件維護兩處關鍵數據路徑：
* 真相源：~/.dsh/sessions/<projectKey>/<sessionId>/session.jsonl.zstd。這是 DSH 原始會話文件，只讀，不可刪除。
* 投影庫：~/.dsh/data/usage.sqlite。這是插件維護的 SQLite 索引與聚合庫，可安全重建。
使用與 API¶
插件提供了查詢接口，可用於嵌入式開發或腳本化操作。
查詢接口¶
通過 createEngine 創建引擎實例後，可調用以下查詢接口：
import { createEngine } from 'dsh-usage-board'
// ctx 爲結構化 HostContext，無需真實 Cordis 運行時
const engine = createEngine(ctx, { dbPath, sessionsRoot })
// 等待冷啓動/增量 Backfill 就緒
await engine.ready
// 查詢接口調用示例
const rollup = engine.query.getRollupBySession(rootSessionId)
// 其他查詢...
結語¶
dsh-usage-board 通過零依賴架構和 CQRS 設計，爲 DSH 用戶提供了輕量級且可靠的用量監控方案。對於需要精細化控制成本和診斷性能的開發者，這是一個實用的工具。
- 插件主頁：https://github.com/zhm20001/dsh-usage-board
- 生態目錄：https://www.skillhub.cn/plugins/zhm20001/dsh-usage-board
