前言¶
在 DeepSeek Harness（DSH）裏跑多步任務時，模型回覆和工具調用往往串成一條長鏈。出問題時，僅靠終端滾動或零散日誌很難回答「第幾步開始偏了」「兩次重試差在哪裏」。手工複製上下文做對比也費時，且缺少每步耗時。
下面介紹社區插件 dsh-step-trace：把每個會話的步驟追加寫入本地 replay 文件，並提供 CLI 與設置頁裏的面板，按步查看輸入輸出、分叉重跑，以及對比兩條會話的分歧點。
這是什麼¶
dsh-step-trace 由維護者 hj01857655 發佈，npm 包名同爲 dsh-step-trace。包描述爲：記錄智能體走過的每一步，並支持正向、反向逐步查看，定位出錯環節。
獨立倉庫 hj01857655/dsh-step-trace 已在社區目錄標註爲已歸檔，源碼曾併入 monorepo hj01857655/dsh-plugins；2026-10-20 起該 monorepo 工作區僅保留其餘兩個包，dsh-step-trace 等七個包已從倉庫移除，但 npm 上仍可安裝，安裝方式不變（見 monorepo README 說明）。
SkillHub 目錄頁將本插件歸類爲可安裝聯網工具，當前展示版本爲 v0.5.1；npm 最新版爲 0.6.1（2026-10-16 發佈）。許可證：MIT。
核心功能¶
以下能力均來自 npm 包 README，安裝啓用後由插件在 DSH 宿主側接入。
記錄與存儲¶
- 每次模型回覆與工具調用記爲一條 trace step。
- 數據寫入工作區下的
.replay/.jsonl：按會話分文件、僅追加（append-only）。
逐步查看與分支¶
- 可按步驟向前或向後瀏覽，查看該步完整輸入與輸出；每步帶時間戳與耗時。
- 可從任意一步分叉（branch）出新會話，用於「若當時選了另一條路徑會怎樣」的試探。
- 分歧檢測（divergence）：對同一任務的兩條會話，找出第一個不一致的步驟，便於理解重試結果爲何不同。
統計與界面¶
- 會話級統計：總步數、總時長、平均步延遲、最慢一步。
- Panel：Settings 內「Step trace」頁；宿主註冊
GET /api/step-trace.panel，每次請求從 replay 文件重建數據。無 Web 界面的 headless 宿主可跳過該路由。 - 面板包含：按時間排序的會話列表（步數、總時長）、逐步查看器、步驟耗時時間線、雙會話分歧對比視圖。
安裝與啓用¶
官方推薦從 npm 安裝（需 DSH 的 web profile）：
dsh plugin --profile web add dsh-step-trace
README 亦給出從 GitHub 源安裝的方式（獨立倉庫已歸檔，若命令失敗可改用 npm）：
dsh plugin --profile web add github:hj01857655/dsh-step-trace
安裝前建議在 npm 或歷史提交中閱讀源碼與 MIT 許可證。插件以當前 dsh 進程權限運行，會讀寫工作區 .replay/ 下的會話數據。
典型用法¶
CLI¶
插件提供可在 DSH 外單獨使用的命令行入口，常用子命令如下：
dsh-step-trace list # 列出已記錄的會話
dsh-step-trace trace <id> # 顯示某會話的全部步驟
dsh-step-trace step <id> <n> # 查看第 N 步詳情
dsh-step-trace diverge <a> <b> # 找出兩個會話首次分歧的步驟
將 <id> 換爲 list 輸出中的會話標識；<n> 爲從 1 起的步序號。
設置面板¶
在 DSH Settings 中打開 Step trace 頁：瀏覽會話、逐步查看 I/O、看時間線，或在分歧視圖中並排對比兩個會話。適合不習慣純 CLI、但需要看清某步完整 payload 的場景。
適用場景與注意¶
適合誰
- 調試多步 Agent：定位第一次錯誤工具調用或異常模型輸出。
- 對比兩次運行（例如改 prompt 或換模型後重試），用
diverge或面板找分叉點。 - 需要會話級耗時分佈，而不是隻看總 wall time。
注意
- Replay 文件落在項目目錄
.replay/，含模型與工具輸入輸出，請注意敏感信息與版本管理（勿誤提交密鑰）。 - 面板依賴 web profile 與宿主路由；純 headless 環境以 CLI 與
.jsonl爲主。 - 社區目錄 SkillHub 與 GitHub 倉庫並非 DeepSeek / 幻方官方應用商店；DSH 生態主張「一切皆插件」，安裝第三方包前請自行審計代碼。
結尾¶
dsh-step-trace 把「每步發生了什麼、花多久、兩條路何時分開」落到可查詢的 replay 與 CLI/面板上，適合作爲 DSH 多步任務的事後排查工具。
- 目錄頁：https://www.skillhub.cn/plugins/hj01857655/dsh-step-trace
- 原 GitHub 標識：
https://github.com/hj01857655/dsh-step-trace（已歸檔；當前 npm 主頁指向 monorepo 歷史路徑） - npm：https://www.npmjs.com/package/dsh-step-trace
- 維護者 monorepo：https://github.com/hj01857655/dsh-plugins
