前言¶
在 DeepSeek Harness（DSH）裏跑智能體任務，對話窗口通常只呈現「最終選中的那條路」：哪次工具調用成功了、模型接着說了什麼。失敗重試、檢索撲空、繞遠折返，往往散落在多輪輸出裏，要靠肉眼翻日誌才能拼出全貌。
如果你要對比兩次運行（比如同一任務用 flash 與 pro）、或者想看清長會話裏時間花在哪，純文本 session log 並不直觀。下面介紹的 dsh-trace-compare 是社區維護的 DSH 客戶端插件，把執行軌跡可視化成「迷宮」：主幹、支路、折返點落在同一根時間軸上，支持離線對比與即時跟隨。
這是什麼¶
dsh-trace-compare（GitHub：lamost423/dsh-trace-compare）由維護者 lamost423 開發，歸類爲 客戶端 插件。npm 包名 dsh-trace-compare，當前倉庫版本 0.6.2。
插件做一件事：從 session log 或當前會話事件流中解析工具調用與回答節點，用統一的視覺語言畫出智能體的探索過程——成功推進的主幹、失敗/撲空/無效重試的支路，以及折返回分支點的回程線。
兩個入口共用同一套圖例與判定邏輯：
- Trace 對比（側邊欄）：上傳 1 個 log 看單次運行的迷宮，或上傳 2 個做同軸對比。
- 即時迷宮（會話內頁籤）：迷宮隨當前會話執行即時生長，工具結果落定後支路立刻顯現。
核心功能¶
迷宮圖例¶
圖上各元素含義如下（均來自插件 README 說明）：
- 實線主幹：工具調用成功推進的步驟與回答節點。
- 時長膠囊條：每步從開始到結束畫成圓角條，按判定上色；條夠寬時耗時寫在條內。一步內 ≥2 次並行工具調用時（v0.3.2 起），每次調用在膠囊條下方畫細小條，按各自起止擺位。
- 虛線弧（支路）：工具失敗（紅 ✗）、檢索撲空（灰 ·）、盲目重試（灰 ↻），以及折返回分支點的回程線。
- 子代理支路（v0.4.0 起，即時頁籤）：模型派生的 dsh 子代理會話（
origin: 'subagent'）畫成主幹分出的聚合節點，與父會話共享時間軸；運行中的子代理即時生長。手動分支與 side-chat 不入圖。
懸停節點或弧線可快速預覽；點擊在右側打開詳情面板，含完整命令與返回（各帶複製按鈕，返回保留前 5000 字）、耗時、判定與思考摘要。
Trace 對比（雙會話）¶
上傳兩個 session log 後，插件按輪次自動對齊兩邊的回答節點，並支持：
- 輪次對齊線（v0.3.0 起）：每輪迴答節點互連，標註兩邊本輪耗時、耗時差與支路數差；v0.5.1 起耗時口徑爲「該輪起點 → 回答完成」，輪間用戶空閒不計入。
- 手動錨點：在兩條泳道各點一個節點，釘帶時差標註的對比線，適合輪次錯位但語義等價的時刻。
- 支路盤點：按輪次列出兩邊支路步數、牆鍾耗時、類別構成與差額結論；點一行可縮放到該輪。
即時迷宮¶
會話頁籤內同一張圖隨執行生長。詳情面板可點「在對話中定位此步驟」，宿主切回對話頁並高亮對應工具行（行過舊、超出已加載窗口時退化爲只切頁籤）。
即時頁籤只畫對話已加載的事件窗口（v0.2.3 起標註）；窗口外更早步驟會丟棄並提示「另有 N 步更早歷史未加載」。要看全會話，用「Session log 下載 → 上傳對比」。
交互與導出¶
- 縮放導航：滾輪以光標爲中心橫向縮放，拖拽平移，雙擊空白或「整圖」復位；軸刻度隨縮放加密（最細到 1 秒）。
- 搜索與過濾：「只看失敗/重試」開關、按工具類型過濾、命令與返回全文搜索；不命中節點淡化至 15% 透明度。
- 播放：最高 300× 回放整次運行。
- 導出：當前視圖導出爲 SVG 或 2x PNG；導出固定淺色底。
- 界面雙語（v0.5.0 起）：嵌入宿主時跟隨 dsh 語言設置；獨立打開按瀏覽器語言兜底。
- 主題跟隨（v0.3.1 起）：隨宿主明暗主題切換。
時間軸與判定規則¶
時間軸上的誠實約定：
- 超過 60 秒無活動的區間壓縮爲帶
⏸的細縫，標明省略時長；活動段內刻度仍爲牆鍾真值。 - 步驟標識帶輪次（如
S15·47）；token 讀自 session log 裏assistant/message的usage（v0.2.2 起）；日誌無 usage 時標籤回退爲「推理 N 段（日誌未報 token 用量）」。
支路判定（v0.2.1 引入，頁面與即時共用 src/client/verdict.js 的 VERDICT_RULES）：
- 錯誤標誌（
isError）→ 失敗； - 強/弱失敗特徵，只掃輸出開頭與末尾窗口，避免長文本中部「引用」的報錯字樣誤判；
- 按工具分類：寫入類無錯誤即成功；檢索類空結果纔算撲空；bash 及未知工具空輸出纔算撲空；
- 行爲學檢測：連續「同工具 + 參數相似」且簇內至少一次失敗的調用，非失敗成員判爲無效重試。
一步進主幹還是支路，由該步最壞工具判定決定。
支持的 log 格式¶
按文件內容識別，文件名任意：
- 純文本
.jsonl（session 格式 v0 事件流） ~/.dsh/sessions/下原樣.jsonl.zstd（瀏覽器端解壓，優先原生DecompressionStream('zstd')，否則內置 fzstd）
安裝與啓用¶
插件已在官方 0.1.0-rc.6（構建 + 全量測試）與 rc.8（插槽/類型覈對 + 實機驗收）驗證；peer 範圍覆蓋 rc.6 到當前 rc 線。
下面是從 README 給出的安裝步驟。插件以當前 dsh 進程權限運行，安裝前建議查看 GitHub 倉庫 源碼與許可證。
npm install --global @deepseek-ai/dsh@0.1.0-rc.8
dsh plugin --profile web add dsh-trace-compare
dsh web
若要釘住特定發佈版本，可使用 Release 附帶的 tgz（README 示例爲 v0.5.2）：
dsh plugin --profile web add https://github.com/lamost423/dsh-trace-compare/releases/download/v0.5.2/dsh-trace-compare-0.5.2.tgz
從源碼安裝：
git clone https://github.com/lamost423/dsh-trace-compare.git
cd dsh-trace-compare
corepack enable
pnpm install
pnpm build
dsh plugin --profile web add .
dsh web
重啓 dsh web 後，側邊欄底部出現「Trace 對比」入口，每個會話視圖多一個「即時迷宮」頁籤。
社區目錄頁：SkillHub · lamost423/dsh-trace-compare。DSH 生態奉行「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
典型用法¶
對比兩次運行¶
- 在 DSH 中分別跑完同一任務（或導出兩次 session log）。
- 打開側邊欄「Trace 對比」，上傳兩個
.jsonl或.jsonl.zstd文件。 - 查看同軸雙泳道：輪次對齊線對比每輪耗時與支路差額；需要時用「加錨點」釘住語義等價時刻。
- 點「支路盤點」按輪次查看失敗/重試/撲空構成，點某行縮放到該輪細節。
即時觀察當前會話¶
- 安裝插件並啓動
dsh web。 - 進入任意會話，切換到「即時迷宮」頁籤。
- 隨工具調用觀察迷宮生長；點節點看詳情，必要時「在對話中定位此步驟」跳回原文。
- 用過濾與搜索定位失敗步驟；會話結束後可導出 SVG/PNG 分享。
分析長會話¶
README 提到插件可處理大規模日誌（示例：14 小時、8.6MB），按寬度鋪滿並支持縱向滾動，時間軸釘頂；⌘/Ctrl+滾輪可縮放到任意片段。若即時頁籤提示有未加載更早歷史，下載完整 session log 再走 Trace 對比上傳。
適用場景與注意¶
適合誰：
- 需要對比同一任務不同模型或不同 prompt 的智能體開發者；
- 調試工具調用失敗、無效重試、檢索撲空等行爲；
- 分析含子代理派生的複雜會話（即時頁籤，依賴宿主「後臺加載子會話歷史」能力）；
- 需要把軌跡導出爲圖分享給同事的場景。
使用注意：
- 即時迷宮只反映對話已加載窗口內的事件，不等於完整 session；全長分析請用 log 上傳。
- 支路判定基於確定性規則，閾值可在
VERDICT_RULES按項目語料調整，但不調用 LLM 二次判斷。 - 子代理支路在官方 rc 線暫缺「後臺加載子會話歷史」時會自動靜默隱藏。
- Node 引擎要求：
^22.19.0 || >=24.0.0（見 package.json）。
結尾¶
dsh-trace-compare 把智能體「實際走過哪條路」從日誌裏抽出來，畫成可縮放、可對比、可導出的迷宮圖。離線雙會話對比與即時頁籤共用一套判定與時間軸規則，適合在 DSH 開發流程裏做軌跡覆盤與運行差異分析。
