前言¶
在使用 DeepSeek Harness (DSH) 構建工作流時，除了關注對話本身的內容（transcript），開發者通常還需要監控工具調用的實際表現，例如耗時是否異常、參數與結果消耗了多少 Token。傳統的日誌方式往往將大量數據注入上下文，不僅難以檢索，也缺乏聚合統計能力。本插件提供了一種“零模型可見面”的透視鏡，僅記錄關鍵指標，不干擾上下文。
插件介紹¶
dsh-plugin-tool-trace 是一個 DeepSeek Harness (dsh) 插件。它的核心職責是追蹤每次工具調用的耗時、參數量與結果量（僅記錄大小，不記錄內容）。數據按月生成 JSONL 文件落盤，並提供 /tools-stats 命令生成慢工具排行榜。
- 維護者：121212165
- 許可證：MIT
核心功能¶
- 慢工具排行榜：訪問
/tools-stats，系統會按累計耗時排序，展示每個工具的調用次數、累計耗時、平均耗時、最慢耗時、平均結果量以及錯誤計數。 - 零模型可見面：所有追蹤數據僅寫入本地文件，不進入對話上下文。這既保護了隱私，也使得數據純粹用於人眼分析。
- 容錯處理：如果進程崩潰導致寫入中斷，半行數據會被自動跳過並計數。對於中途死掉的調用（只有開始沒有結束），在聚合統計時會自然被忽略。
安裝與啓用¶
安裝過程需要通過 DSH 的插件命令將包添加到指定 Profile，並修改配置文件。
1、執行安裝命令（需確保 pnpm 在 PATH 上）：
dsh plugin --profile web add github:121212165/dsh-plugin-tool-trace
此命令會通過 pnpm 自動運行 prepare 腳本構建插件。
2、配置補丁文件。
找到本插件倉庫根目錄的 cordis.patch.yml，將其內容合併到 $DSH_HOME/profiles/web/cordis.patch.yml 中。
注意：該文件默認爲空數組 []。請將補丁內容並進數組，不要直接追加。追加會導致 YAML 解析錯誤（報錯 failed to parse overlay ... end of the stream or a document separator is expected）。
3、重啓 dsh。
配置層與客戶端都需要重啓才能生效（客戶端基於啓動時的內容 rev 下發，硬刷新瀏覽器無效）。
配置¶
插件支持以下配置項：
| 字段 | 默認值 | 說明 |
|---|---|---|
dataDir |
~/.dsh/tool-trace |
JSONL 日誌落盤目錄 |
captureArgsSize |
true |
是否記錄參數 JSON 的長度 |
典型用法¶
1、查看統計：在 DSH 界面或終端使用 /tools-stats 命令，查看慢工具排行榜。
2、查看日誌：進入 dataDir（默認 ~/.dsh/tool-trace），查看按月分割的 JSONL 文件，瞭解具體的調用指標。
注意事項¶
1、結果量精度：結果體大小的提取依賴下游結果的數據形狀。如果 content 爲字符串，大小計算是精確的；如果是其他形狀（如數組、對象），則通過序列化估算大小。
2、Live Mount 未驗證：插件未在正在運行中的 dsh 實例上進行 live mount 驗證。
3、生效條件：必須重啓 dsh 進程，插件才能生效。
結尾¶
本插件通過文件落盤和聚合統計，幫助開發者從“說了什麼”轉向“做了什麼、慢在哪”。更多細節與源碼，請訪問 GitHub 或 社區目錄。
