前言¶

用 DeepSeek Harness（DSH）跑長任務時，原生軌跡會記錄消息、工具調用和事件，但一輪任務往往包含成百上千個步驟。想回答幾個基本問題並不容易：Agent 實際採用了什麼策略？哪些步驟在推進任務，哪些是重複試探？失敗來自模型判斷、工具使用還是環境條件？一段「已經完成」的回答有沒有足夠證據？

逐條翻軌跡效率很低。下面介紹的 dsh-trace-insight 做的就是這件事：把密集的軌跡事件整理成持續更新的分析時間線，並讓每條結論都能回到對應的原始事件。

這是什麼¶

dsh-trace-insight（DSH Trace Insight｜DSH 軌跡解讀器）是 Liu-Bot24 維護的 DSH 只讀執行復盤插件，許可證爲 MIT。DSH 的理念是「一切皆插件」，Trace Insight 就以插件形式接入 DSH web 界面的右側欄，左側保留對話或軌跡，右側顯示解讀結果，寬度可調。

它直接讀取 DSH 的結構化 Session Event Log，先用本機規則分析建立事實底座，再按需使用獨立配置的模型解釋決策、風險和改進方向。

邊界需要先說清楚：插件只讀取數據，不修改被檢查的 Session、工作區、Skill 或全局記憶，也不干預、不暫停、不阻斷開發 Agent 的執行。

核心功能¶

分析側的能力：

• 持續覆盤：按 Turn 和 Seq 整理規則分析與模型分析，長任務不必等到整輪結束就能看到階段進展。
• 規則分析：在本機識別工具失敗、重複失敗、無進展循環、路徑猜測、工具誤用、完成信號和證據缺口，不調用模型。
• 模型解讀：使用獨立配置的 DSH 模型分析策略、根因、風險、下一步和可複用經驗，不影響開發 Agent 的主模型。
• 受控重分析：爲指定區間臨時切換模型重新分析，不改變以後自動分析使用的默認模型。

消費分析結果的能力：

• 證據定位：從結論回到對應的 Seq、Turn、Step、Tool、摘錄和原始前後文。
• 任務概覽：按開發階段、工具使用和問題線索彙總整個任務，只整理已有分析，不產生新的模型調用。
• 結果對比：比較同一段軌跡的兩次成功模型分析，分別展示結論、配置、資源用量和原始證據，可觀察不同模型或配置給出的差異。
• 歷史與導出：分析記錄保存在本機，可分別導出分析歷史、原始 Session 歷史或完整分析包。

右側欄包含覆盤、概覽、對比、設置四個頁面。

安裝與啓用¶

先確認環境：需要 Node.js 22.19.0 或更高版本（package.json 中 engines 要求 node >=22.19.0）。插件通過 dshCompatibility 聲明兼容 DSH 0.1.0-rc.7、0.1.0-rc.8、0.1.1-rc.1、0.1.1-rc.2，surface 爲 web。

安裝前必須關閉正在運行的 DSH，然後下載或克隆倉庫，在倉庫根目錄運行安裝程序。

macOS 或 Linux：

bash ./install.sh

Windows 下雙擊 安裝到DSH.cmd，或在 PowerShell 中運行：

powershell -ExecutionPolicy Bypass -File .\install.ps1

安裝程序會爲發現的每個受支持 DSH 安裝接入右側欄，插件包保存在 <DSH_HOME>/trace-insight/packages；安裝完成後，DSH 不依賴源碼目錄或下載目錄繼續存在。

啓動 DSH：

dsh web

如果沒有全局 dsh 命令，使用：

npx --yes --package=@deepseek-ai/dsh dsh web

打開任意會話後，點擊「解讀」即可打開右側欄。

一個需要留意的版本說明：README 提示當前版本請使用 packages/standard 下的「標準無補丁側欄 1.5.0」，倉庫根目錄的安裝、卸載腳本屬於舊補丁版；標準版的具體安裝方式見倉庫 packages/standard/README.md，兩版的具體關係資料中未展開，安裝前建議先確認要用哪一版。

卸載同樣先關閉 DSH，在倉庫根目錄運行對應的卸載腳本（uninstall.sh / uninstall.ps1 / 雙擊 卸載插件.cmd）。卸載會移除 Trace Insight、右側欄和安裝程序管理的插件包，已保存的分析歷史保留在數據目錄中。

典型用法¶

第一次使用的完整流程：

1、打開任意 DSH 會話，點擊「解讀」，進入「覆盤」。規則分析直接讀取現有軌跡，不需要配置模型。

2、如需模型解讀，進入「設置 → 模型與自動策略」，選擇 DSH 已註冊的 provider 和模型並保存。

3、保存後可以等待自動分析觸發，也可以在覆盤中選擇一段軌跡手動分析。

4、點擊分析結論中的證據入口，查看對應的原始事件和前後文。

經過上面的步驟，每條模型結論和規則發現都可以打開獨立證據抽屜，每條引用標出 Seq、Turn 和摘要，需要時再讀取原始前後文。

有幾件事不會觸發模型調用：打開或刷新 Trace Insight、篩選時間線、查看證據、進入概覽、對比已有分析。只有自動分析或用戶主動發起模型分析時才產生模型請求。

模型配置分三層：全局默認模型、當前 Session 專用模型、僅本次分析臨時使用的模型。只有前兩項會保存；臨時換模型不會修改以後自動分析使用的默認配置。自動分析只在 Session 已被即時執行納入觀察、已配置默認模型並滿足觸發條件時運行；模型失敗、取消或返回無效結果時，分析進度不會越過該區間。

如果看不到「解讀」入口，先完全關閉 DSH 再重新運行安裝程序；仍未出現時，可以檢查插件是否進入 web profile：

dsh --profile web --dump-config | grep "trace-insight"

Windows PowerShell 換用 Select-String：

dsh --profile web --dump-config | Select-String "trace-insight"

僅通過 npx 使用 DSH 時，把命令中的 dsh 替換爲 npx --yes --package=@deepseek-ai/dsh dsh。

數據目錄與導出¶

默認數據目錄如下，設置了 DSH_HOME 時爲 <DSH_HOME>/trace-insight：

目錄中主要包含 settings.json 和 sessions/<session-id-hash>.json。

導出分三類：分析歷史（規則分析、模型分析、運行狀態和分析進度）、原始 Session 歷史（DSH 原始事件、surface 與會話譜系）、完整分析包（前兩者都有）。導出原始歷史或完整分析包時需要再次確認；分析歷史可能包含證據摘錄和模型原文，共享前先檢查內容。

隱私與費用邊界¶

• 規則分析完全在本機運行，不調用模型。
• 模型輸入使用經過裁剪和常見憑證脫敏的軌跡證據，不會發送完整原始日誌；使用外部模型時，相應證據會發送給你選擇的模型供應商。
• 原始 Session 數據默認不會包含在普通分析導出中。
• Trace Insight Host RPC 僅允許 loopback 頁面訪問，需在運行 DSH 的同一臺機器上通過 127.0.0.1 或 localhost 使用；通過局域網地址打開 DSH 時讀不到數據。

適用場景與注意¶

適合的人羣和場景：經常用 DSH 跑長任務、需要覆盤 Agent 行爲的開發者；想在保留原始軌跡的同時獲得結構化分析的人；需要在同一段軌跡上對比不同模型或配置解讀結果的場景。

使用前注意幾點：

1、插件以當前 DSH 進程的權限運行，安裝前應自行檢查倉庫源碼與許可證（當前爲 MIT）。
2、安裝和卸載前必須關閉正在運行的 DSH。
3、顯示「等待默認模型」時，規則分析仍會繼續運行；配置默認模型後模型分析纔會開始。模型分析失敗時，失敗記錄保留，進度不跳過失敗區間，可檢查 provider 憑證、模型路由和限流狀態後從失敗區間重試。

結語¶

dsh-trace-insight 把軌跡覆盤拆成兩層：本機規則分析做事實底座，獨立配置的模型做解釋層，所有結論都能回溯到原始事件，且全程只讀、不干擾開發 Agent。如果你在用 DSH 跑長任務並苦於逐條翻軌跡，可以試試它。

• 社區插件目錄：https://www.skillhub.cn/plugins/Liu-Bot24/dsh-trace-insight
• GitHub 倉庫：https://github.com/Liu-Bot24/dsh-trace-insight