前言¶
在基於 DeepSeek Harness（DSH）開發智能體、編排 Workflow 或處理長上下文時，每次模型調用的 Token 消耗與成本往往分散在日誌和會話歷史裏，難以快速評估模型表現、緩存效率與預算。DSH 本身不提供全局用量聚合與成本覈算能力，需要額外插件來統一統計與呈現。
插件定位¶
dsh-metrics 是專爲 DeepSeek Harness 打造的輕量級插件，通過捕獲宿主內部的所有模型調用事件，將 Token 消耗實時聚合並在 Web 側邊欄提供交互式看板。它按模型/供應商/項目/會話統計調用與緩存命中，並接入 OpenRouter 公開價目表進行成本估算。插件由 zdt3476 維護，分類爲聯網工具。
核心能力¶
- 全量調用追蹤：通過雙通路捕獲覆蓋所有
assistant/message會話事件，並通過 waterfall 補齊會話標題生成、記憶壓縮等獨立調用的 Token 消耗。 - 多維切片透視：在看板中按模型、供應商、工作區項目與會話自由切換與排序下鑽，長列表支持容器內滾動與表頭吸頂。
- 指標卡組：請求總數（含成功率/成功/失敗）與 Token 總數（構成內聯）兩張主卡，配合 RPM、TPM、緩存率、成本四張卡，每張卡疊加迷你趨勢線；支持今天/24 小時/3 天/7 天/30 天/全部六檔時間範圍。
- 成本覈算（OpenRouter 單價）：自動拉取 OpenRouter 公開價目表並緩存 24 小時，按輸入/輸出/緩存讀/緩存寫/推理分別計價；缺價格的模型會顯式提示而不是按 0 計算。
- 真實 RPM / TPM：賬本內置最近 90 分鐘的分鐘級計數，RPM/TPM 爲最近 60 分鐘的實際牆鐘速率。
- Token 活動熱力圖：以「星期 × 自然周」排布，頂部標註月份，直觀展示每週使用規律。
- 供應商明細：按供應商列出請求數、Token、成本與佔比條。
- 模型用量環形圖：環形佔比 + 右側圖例榜（模型、用量、佔比），支持「按用量/按調用」兩種口徑切換。
- 多模型趨勢圖：單張折線圖按模型分組，配圖例與懸停明細，時間軸自動稀疏刻度避免擁擠。
- 緩存命中率審計：精準統計
cacheRead與新輸入的配比，清晰呈現 Prompt 緩存命中效果。 - 離線日誌自動回掃：首次安裝或數據重建時，支持通過原生
zstd解壓磁盤會話歷史（.jsonl.zstd），即使離線或無持久化服務也能完整恢復歷史統計。 - 賬戶餘額實時展示：在面板頂部實時展示當前登錄用戶餘額與代金券贈金，支持直達官方用量頁面。
- 輕量安全與原子存儲：本地存儲採用寫入防抖與臨時文件原子重命名機制，避免 I/O 阻塞並防止半寫入損壞；純本地運行，不攜帶憑據，絕不向第三方上傳任何數據。
安裝與啓用¶
方式一：命令行一鍵安裝（推薦）¶
dsh plugin --profile web add @zdt3476/dsh-metrics
也可以直接裝源碼（無需 NPM）：
dsh plugin --profile web add github:zdt3476/dsh-metrics
方式二：通過 DSH 插件管理器¶
在 DSH 控制台中直接執行：
plugin_manager install_bundle @zdt3476/dsh-metrics
方式三：手動配置 Profile¶
在你的 DSH Profile（如 ~/.dsh/profiles/web/package.json）中添加依賴：
{
"dsh": {
"profile": {
"bundles": ["@zdt3476/dsh-metrics"]
}
},
"dependencies": {
"@zdt3476/dsh-metrics": "^1.0.3"
}
}
並在當前 Profile 的 cordis.patch.yml 中聲明加載：
- insert:
- id: dsh-metrics
name: '@zdt3476/dsh-metrics'
重啓 DSH 後，側邊欄左側工具欄即會出現 用量監控 圖標。首次載入看板會自動執行歷史會話日誌回掃，無感補齊過往全部調用數據。
統計口徑與計算公式¶
| 指標字段 | 含義 | 說明 / 計算公式 |
|---|---|---|
| 調用次數 (Calls) | 模型請求總次數 | 按 (sessionId, turn, step) 嚴格去重累加 |
| 輸入 (Input Tokens) | 未命中緩存的新輸入量 | 模型消耗的新上下文 Token 數 |
| 緩存讀 (Cache Read) | 命中緩存的輸入量 | 上下文 Prompt 緩存成功複用的 Token 數 |
| 緩存寫 (Cache Write) | 寫入緩存的輸入量 | 首次加載寫入緩存的 Token 數 |
| 輸出 (Output Tokens) | 模型最終生成的回覆 Token | 包括代碼、思考內容與最終文本 |
| 推理 (Reasoning) | 深度思考/推導 Token | 具備推理能力模型（如 R1）的思維鏈 Token 消耗 |
| 總量 (Total Tokens) | 單次調用涉及的所有 Token | 適配器上報值或各項 Token 之和 |
| 緩存命中率 (Hit Rate) | 輸入層緩存複用效率 | CacheRead / (CacheRead + Input) |
配置說明¶
插件所有配置均開箱即用。若需自定義，可在 cordis.patch.yml 中覆蓋：
- id: dsh-metrics
config:
flushDelayMs: 2000 # 磁盤寫入防抖延遲（毫秒）
snapshotCacheMs: 3000 # 聚合快照緩存時間（毫秒）
retentionDays: 400 # 歷史按天分桶保留天數（0 爲不裁剪）
maxSessions: 500 # 會話明細最大保留記錄數
maxTrendSeries: 6 # 趨勢圖展示的前 N 大模型曲線數
trackAccount: true # 是否讀取登錄賬號餘額（只讀）
autoUpdate: true # 是否裝配自更新檢查
watchFiles: false # 開發環境文件變動熱重載
HTTP 服務接口¶
插件在宿主 Web 服務中內置了只讀接口與管理通道：
| 請求方法 | 接口路徑 | 功能說明 |
|---|---|---|
GET |
/api/dsh-metrics/summary |
獲取最新多維聚合快照（前端看板數據源） |
GET |
/api/dsh-metrics/flush |
立即強制執行防抖落盤，並返回最新快照 |
GET |
/api/dsh-metrics/version |
查看當前運行版本、構建標識與倉庫信息 |
GET |
/api/dsh-metrics/update/check |
檢查 GitHub Release 最新版本狀態 |
POST |
/api/dsh-metrics/reload |
觸發插件進程內熱重載（重新加載磁盤代碼） |
本地開發與測試¶
本項目採用現代 TypeScript 開發流程：
# 1. 安裝依賴
pnpm install
# 2. 執行靜態類型檢查與全量單元測試
pnpm test
# 3. 運行構建（輸出至 lib/）
pnpm run build
# 4. 監聽測試
pnpm run test:watch
適用場景與注意¶
適合需要集中監控 DeepSeek Harness 模型調用成本與效率的開發者與團隊，尤其是使用多模型、多供應商、多項目時，便於快速識別高消耗路徑與優化緩存策略。
插件以當前 DSH 進程權限運行，安裝前建議檢查源碼與許可證。插件依賴 Node.js ^22.19.0 || >=24.0.0 和 DSH >=0.2.0，可選依賴 @deepseek-ai/cordis: ^4.0.5。
結尾¶
dsh-metrics 爲 DSH 提供了從單次調用到全局成本與緩存效率的完整透視能力，適合將 Token 用量與成本納入日常開發與運營的閉環。插件目錄頁與源碼倉庫鏈接如下：
- 插件目錄頁：https://www.skillhub.cn/plugins/zdt3476/dsh-metrics
- GitHub：https://github.com/zdt3476/dsh-metrics
