DSH 插件用量與能力看板

前言¶

在 DeepSeek Harness（DSH）裏做智能體開發，常常會遇到一個問題：不知道自己用了哪些能力、調用頻率有多高、哪些工具容易出錯。本地跑完一通，只能靠日誌回憶，沒有統一的看板。DSH 的理念是「一切皆插件」，社區裏有不少插件做特定功能，但缺乏一個統一的用量與能力看板。wjf1/dsh-plugin-usage-analytics 就是爲此出現的一款本地插件：訂閱會話事件，把工具調用、回合、錯誤、耗時與能力使用情況聚合成日表，在側欄面板裏展示，並對外提供一套本地 HTTP 查詢接口。默認 local 模式、零出站，不採集任何消息正文。

核心功能¶

1. 本地採集與聚合¶

插件訂閱 DSH 的會話事件，按工具名、能力類型（如 MCP / skill）進行聚合，生成以下維度：

工具調用次數、錯誤數、錯誤率、平均耗時
回合數、會話數
tokens 進出量

聚合結果按天落盤，存儲結構包括：

meta：安裝 ID、設置、游標、丟棄與採樣計數
daily：按天的總量（toolCalls/toolErrors/turns/sessions/tokens/ms）
toolDaily：按天 + 工具維度的明細
capDaily：按天 + 能力鍵維度的明細（MCP / skill 等）
sessions：會話首見與累計（turns/toolCalls/errors/model）

2. 側欄面板¶

插件加載後，在側欄顯示「用量分析」入口。主面板包含：

6 張 KPI 卡：窗口內工具調用、錯誤數、錯誤率、平均耗時、會話數、tokens 進出
14 日趨勢柱狀圖（SVG 自繪，不引第三方圖表庫）
Top 工具表：調用數、錯誤數、平均耗時、佔比
能力分佈：MCP / skill 等非原生能力的調用佔比條
設置區：collect 勾選、sampleRate 滑桿、retentionDays 數字框
操作區：刷新、立即落盤、清空本地數據（二次確認）、窗口天數切換（1/7/14/30/90）

配色使用宿主 --dsw-alias-* 主題 token，跟隨淺色/深色主題。

3. 本地 HTTP 查詢接口¶

前綴爲 API_PREFIX = /dsh-plugin-usage-analytics/api。提供兩類接口：

JSON-RPC 方法面：POST <prefix>/，請求體 { "method": "...", "params": { ... } }，響應 {ok:true,value} 或 {ok:false,error:{code,message,retryable?,detail?}}
REST 便捷端點：GET /、/overview?days=、/series?days=、/sessions?limit=、/tools?days=、/tool?name=&days=、/settings、/diagnostics、/export（NDJSON 下載）；POST /settings、/flush、/reset?confirm=RESET

支持的 JSON-RPC 方法包括：

overview：4 KPI + 窗口彙總 + Top 工具
plugins：工具/能力榜，每頁 50
plugin：單工具逐日明細
capabilities：能力排行（mcp/skill）
env：宿主與插件版本、存儲狀態
series：逐日序列（calls/errors/sessions/turns）
events：最近會話摘要
settings.get / settings.set：讀/改設置（白名單）
consent.get / consent.set：同意態（只支持 local/off）
report.preview / report.now / report.clear：上報預覽/立即/清空（當前未啓用上報）
data.delete：刪除本地全部數據
export：內聯導出（json/csv/ndjson）
diagnostics：運行態診斷
reset：清空並重掃

range 參數接受數字、"7d"、{days}、{from,to}，上限 366 天。

4. 隱私與安全¶

只記錄事件元數據：工具名、能力分類、成敗、耗時、會話短哈希、模型名、回合/步數、token 計數
不記錄：消息正文、工具參數原文、工具輸出、文件路徑、用戶名、環境變量
會話 ID 以 sha256(sessionId + ':' + installId) 截 16 位存儲，卸載重裝即換新 installId，歷史無法互相拼接
默認 local 模式，代碼裏沒有任何出站請求（可 grep -R "http" lib/ 自證：只有 http://localhost 的 URL 解析基線）

5. 隔離與限流¶

圍欄：Host 必須是迴環名（127.0.0.1/localhost/[::1]），擋 DNS rebinding
一致性校驗：Sec-Fetch-Site + Origin/Host 一致性校驗
限流：寫方法面每秒 10 次上限，請求體 64KB 上限

安裝與啓用¶

在線安裝（推薦）¶

dsh plugin --profile <profile> add github:wjf1/dsh-plugin-usage-analytics

插件無需構建，package.json 聲明瞭 dsh.bundle（patch: ./cordis.patch.yml）與 dsh.client（web UI），lib/ 產物隨倉庫提交。

裝好後打開側欄「用量分析」即可看到面板；GET /dsh-plugin-usage-analytics/api/ 應返回 {"ok":true,"value":{"ready":true,...}}。

離線安裝 / 手工等價¶

把包目錄放進 profile 的 node_modules（Junction 或直接拷貝）：
C:\Users\admin\.dsh\profiles\desktop\node_modules\dsh-plugin-usage-analytics
在 profile 的 package.json 的 dsh.profile.bundles 數組裏追加 "dsh-plugin-usage-analytics"（不要加進 dependencies，bundle 不需要 npm 解析）
重啓 DSH（新增 bundle 可以靠 HMR 加載，替換已裝包必須重啓；本倉庫採用 Junction，改動即時可見但首次加載仍需宿主掃到 bundle 列表）

配置¶

配置寫在 cordis.patch.yml 的 config 段（也可在運行時通過設置接口熱改，僅白名單鍵）：

鍵	默認	說明
`mode`	`local`	`local` 只落本地；`remote`/`opt-in` 爲未來上報預留，當前不產生任何出站流量
`collect`	`true`	總開關，`false` 時不再消費會話事件
`sampleRate`	`1`	採樣率（0..1），按 `tool/call`+`tool/result` 成對抽稀，丟棄量記在 `meta.sampled`
`retentionDays`	`90`	保留天數（1..400），定時任務按此裁剪
`maxEventsPerDay`	`200000`	單日事件上限，超出記 `meta.dropped`
`flushIntervalMs`	`10000`	合併落盤間隔，最小 2000
`layout`	`single`	存儲佈局，`single` 整單元重寫 / `per-record` 逐條寫（小數據量更穩，大數據量注意小文件數量）
`selfExclude`	`false`	是否排除本插件自身產生的調用
`profileName`	`null`	存儲 domain 的 profile 後綴。默認自動探測（`config` → `profile` 服務 → `app.profile` → `DSH_PROFILE`/`DSH_PROFILE_NAME`/`DSH_PROFILE_DIR` → `--profile=` → `ctx.baseDir` 的 `profiles/<name>` → `default`），顯式指定可保證多 profile 隔離

使用示例¶

查詢概覽¶

curl http://localhost:<port>/dsh-plugin-usage-analytics/api/overview?days=7

查詢工具排行¶

curl http://localhost:<port>/dsh-plugin-usage-analytics/api/plugins?days=14&q=&sort=toolCalls&cursor=

查詢環境與存儲狀態¶

curl http://localhost:<port>/dsh-plugin-usage-analytics/api/env?days=1

導出數據¶

curl http://localhost:<port>/dsh-plugin-usage-analytics/api/export?range=30&format=json > analytics_30d.json

適用場景與注意¶

適合需要統一查看工具調用、錯誤率、平均耗時與能力分佈的 DSH 智能體開發者
插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證（MIT）
當前版本不支持插件清單與逐事件行，設計 v1.0 與評審報告不在本倉庫內

總結¶

wjf1/dsh-plugin-usage-analytics 是一款本地、零出站的 DSH 用量分析插件，通過側欄面板與本地 HTTP 接口，提供工具調用、錯誤、耗時、能力分佈等維度的聚合數據。默認 local 模式，只記錄事件元數據，隱私可控。對於需要在本地梳理智能體使用情況、優化工具選擇與性能的開發者，這是一個可以直接上手使用的工具。

參考鏈接¶

插件目錄頁：https://www.skillhub.cn/plugins/wjf1/dsh-plugin-usage-analytics
GitHub：https://github.com/wjf1/dsh-plugin-usage-analytics