前言¶
在 DeepSeek Harness（DSH）裏跑智能體時，軌跡（trajectory）視圖是排查「哪一步慢、哪次工具失敗、模型在等什麼」的常用入口。內置 trajectory 以列表或時間線方式呈現，多輪、長 idle、模型首 token 與解碼分段等信息一屏裏往往不夠直觀。社區插件 dsh-trace-waterfall 用獨立的瀑布圖界面替換該視圖，交互參考 Kobra Trace Waterfall 的思路，實現與資源均不依賴 Kobra 代碼。下面介紹它是什麼、能做什麼，以及如何安裝與日常使用。
這是什麼¶
dsh-trace-waterfall 由 omdsh-dev 維護，分類爲客戶端插件；在 SkillHub 目錄中的簡介爲：A live, searchable trace waterfall for DeepSeek Harness.（實時、可搜索的 Harness trace 瀑布圖。）
插件只做展示層：不增加工具、不改變 agent 行爲、不上報遙測。安裝後通過 bundle 中的 cordis.patch.yml 關閉 ui-trajectory，並註冊 trace-waterfall；視圖 ID 仍爲 trajectory，因此原有視圖偏好與工具檢查鏈接可繼續使用。
核心功能¶
單輪分段條¶
每一輪（turn）用一條分段 bar 表示模型調用、工具、等待、handoff、失敗等活動，類型一目瞭然。
三車道概覽與縮放¶
概覽分爲 input / model / tools 三條車道，支持拖拽框選時間範圍進行縮放；雙擊可重置。超過 60 秒的 idle 在軸上會被壓縮顯示，記錄中的實際時長不變。任意一輪可通過聚焦圖標單獨放大查看。
模型耗時拆分¶
模型 bar 將「首 token 時間（TTFT）」與「解碼階段」分開顯示，便於區分排隊/推理與生成。
摘要與詳情¶
點擊某行或 bar 會先彈出錨定在對應片段上的摘要；可再打開完整詳情，查看完整 input、output、時序與 metadata。
實時跟隨與穩定時間軸¶
進行中的 session 默認從底部打開；停留在底部時新行會自動保持在視野內。向上滾動、搜索、僅看錯誤、聚焦某輪或打開摘要時會暫停跟隨，滾回底部可恢復。歷史 session 從頂部打開。
全局視圖會爲最新調用預留空間，並按整 block 擴展；已完成的 bar 在擴展之間位置固定，session 結束後時間軸貼合錄製結束時間。手動縮放與 turn 聚焦會保留所選範圍。
搜索與錯誤過濾¶
Ctrl/Cmd+F 搜索，匹配名稱、參數、prompt、輸出並高亮。Errors only 只列出失敗操作及其父級上下文；若失敗已恢復，該輪顯示 error 徽章而不是整輪標紅。
按 Escape 可關閉摘要或詳情，或清除過濾器。
與 DSH 狀態欄一致的 token 統計¶
總 token = 未緩存 input + cache-read input + cache-write input + output，與 DSH 狀態欄一致。緩存命中率 = cache-read input / 全部 input。
其他說明¶
- 獨立子 agent session 不會合並進父 trace。
- 不展示 cost（錄製 trace 無權威定價數據）。
安裝與啓用¶
環境要求：Node 24.9+，且 pnpm 11 在 PATH 中（dsh plugin 使用 pnpm；pnpm 10 會報 ERR_PNPM_ADDING_TO_ROOT）。README 註明在 DSH 0.2.1-rc.5 與 0.2.2-alpha 線（master 於 ce7073d）上測試；DSH 插件 API 仍屬 pre-stable 階段。
從 GitHub 安裝（web profile）：
dsh plugin --profile web add github:omdsh-dev/dsh-trace-waterfall
安裝後請重啓 DSH Web 或刷新瀏覽器。更新到最新 commit 時，重複執行同一條 add 命令即可。
恢復 DSH 內置 trajectory：
dsh plugin --profile web remove dsh-trace-waterfall
不要同時啓用兩個 trajectory 提供方，它們共用同一視圖。
當前 package 版本爲 0.1.0，許可證 MIT；適配模塊部分衍生自 DSH MIT 許可的 trajectory 實現，詳見倉庫 THIRD_PARTY_NOTICES.md。
典型用法¶
安裝並 reload 後，在 Web 端打開 session，進入仍爲 trajectory 的軌跡視圖即可看到瀑布圖。常用操作如下。
- 縮放時間範圍：在概覽上拖拽框選；雙擊重置；點擊某輪的 target 圖標聚焦該輪。
- 跟跑 live session：保持在列表底部以自動跟隨新行；需要細看時向上滾動或搜索，看完再滾回底部。
- 查失敗：開啓 Errors only，結合分段條上的 error 徽章定位已恢復的失敗。
- 查內容：
Ctrl/Cmd+F在 trace 文本中搜索並跳轉高亮。
README 提供約 100 秒演示視頻與多張 light/dark、多輪概覽、handoff、popover 截圖，路徑見 GitHub 倉庫。
本地開發者在已構建的 DSH checkout 上可用 patch 預覽，無需正式安裝：
pnpm dsh --patch <path-to-this-repository>/cordis.source.patch.yml --no-open
用確定性測試數據預覽 UI：
node scripts/build-preview.mjs
python3 -m http.server 3468 --bind 127.0.0.1 --directory dist/preview
適用場景與注意¶
適合：經常在 DSH Web 裏讀 trace、對比模型/工具耗時、在多輪與 handoff 場景下做 live 跟跑與搜索的開發者。
注意：
- 插件隨當前 DSH 進程在本地運行，安裝前宜瀏覽倉庫源碼與許可證，確認符合你的環境與合規要求。
- SkillHub 插件目錄（如 dsh-trace-waterfall 目錄頁）是社區站點，與 DeepSeek / 幻方無官方從屬關係；DSH 生態強調「一切皆插件」，本文介紹的是社區維護的客戶端擴展。
- 僅 web profile 安裝流程在 README 中明確寫出；開發與 link 步驟需自備 DSH 源碼 checkout。
結尾¶
dsh-trace-waterfall 把 DSH 的 trajectory 視圖換成可縮放、可搜索、可 live 跟隨的 trace 瀑布圖，並在不改變 agent 行爲的前提下保留原有視圖 ID 與鏈接習慣。需要安裝命令、演示與截圖時，以倉庫 README 爲準。
- 目錄頁：https://www.skillhub.cn/plugins/omdsh-dev/dsh-trace-waterfall
- GitHub：https://github.com/omdsh-dev/dsh-trace-waterfall
