前言¶
DeepSeek Harness（DSH）用於調試和評估 Agent 行爲，但面對長鏈路執行，開發者很難直觀看到 Agent 在時間軸上的真實流動、失敗節點以及 Token 消耗情況。dsh-maze 將 Agent 的執行過程繪製成一張“迷宮圖”，把主幹路徑、失敗支路和折返點落在同一根時間軸上，並提供數據軌道和分析面板。
這是什麼¶
dsh-maze 是 DeepSeek Harness 的執行迷宮插件，由用戶 lamost423 維護。
該插件原名 dsh-trace-compare，在 v1.0.0 版本起更名爲 dsh-maze。舊包保留可安裝但不再更新，如需遷移只需執行兩條命令（具體命令見遷移說明）。
它主要解決 Agent 調試中的可視化問題：通過時間軸、數據軌道和確定性分析，讓開發者看清 Agent 是如何一步步走到結果的，而不是依賴 LLM 的自我陳述。
核心功能¶
迷宮時間軸
將執行過程的主幹路徑、失敗支路和折返點繪製在同一時間軸上。系統會自動摺疊超過 60 秒的空閒區間（顯示爲 ⏸ 標註），並將密集的操作段聚合成“×N”的徽標（點擊可放大查看標籤詳情）。進度條帶有失敗熱力色，即使是一場 8 小時的長會話，也能保持字字可辨。
數據軌道
在時間軸下方提供與迷宮聯動的數據軌道：
* 工具調用密度：按工具類型着色，顯示每次調用的刻線。
* Token 脈衝：堆疊柱狀圖展示緩存輸入、未緩存輸入、推理和可見輸出的 Token 數量。
* 上下文壓力：折線+面積圖，顯示模型窗口占用百分比及 70%/90% 閾值線。上下文壓縮事件會標註爲“⌄−N%”，懸停可查看壓縮前後的真值。
確定性執行分析
所有統計數據均爲對判定數據的確定性聚合，不調用 LLM。
* 失敗恢復鏈：記錄每個失敗調用後的處理方式（原樣重試 / 換參數 / 換工具 / 未恢復）及耗時。
* 執行分析區：提供耗時分佈散點圖、工具結果矩陣（含成功率、P50/P95/最長耗時），以及任務完成度判定（任務完成 / 測試 / 構建 / Lint / 產物 / 人工確認）。
多會話對比
支持同一任務在不同模型上的 2~5 次跑同軸對比。功能包括輪次對齊線（自動連接各輪的回答節點）、手動錨點（釘住語義等價的時刻）以及支路盤點（按輪次列出各泳道的支路步數和耗時差）。
回放與導出
支持最高 300× 的速度回放整場執行過程。支持一鍵導出當前視圖（含縮放窗口與過濾狀態）爲 SVG 或 2x PNG，導出固定爲淺色底，適合分享。
其他特性
* 界面雙語：支持中英文切換。
* 主題跟隨：自動跟隨宿主 DSH 的明暗主題。
* Agent 關係圖譜：可視化主 Agent 與子代理的星形總覽。
典型用法¶
實時迷宮
在 DSH 的對話頁籤中，迷宮會隨當前會話實時生長。側邊欄的「執行迷宮」入口也可以直接打開實時迷宮頁籤。
單看或對比
點擊側邊欄的「執行迷宮」，上傳 session log 文件即可查看或對比歷史會話。
定位與回溯
在迷宮圖上點擊任意節點或弧線，右側會打開詳情面板，顯示完整命令、返回內容（前 5000 字）、耗時和判定依據。詳情面板提供「在對話中定位此步驟」功能，可直接跳回對話頁並高亮對應行。
導出視圖
迷宮圖支持導出爲 SVG 或 2x PNG 圖片。
注意事項¶
- 數據真實性：插件對判定數據的聚合是確定性的，不調用 LLM。數據缺失時如實標註（不畫沒有數據的軌道、不猜未知模型的窗口），絕不編造。
- 舊版本提示：
dsh-trace-compare舊包保留可裝但不再更新。 - 依賴宿主能力：實時頁籤中的子代理支路功能依賴宿主對子會話歷史的後臺加載能力。
結尾¶
dsh-maze 通過可視化的方式，將 Agent 的執行迷宮、數據軌道和確定性分析整合在同一個界面中。對於需要深入理解 Agent 行爲邏輯、排查長鏈路問題或對比不同模型性能的開發者來說，這是一個實用的調試工具。
