在 DSH Web 環境中開發智能體時，調試複雜的工具調用鏈路和推理過程往往需要精確的執行快照。dsh-trace-repeat 插件通過原子、版本化的方式，記錄任意會話的執行 trace，將每次推理完成或工具執行封裝爲不可變版本，並支持基於 git worktree 的歷史版本恢復。
功能特性¶
原子化版本記錄¶
插件訂閱宿主的 session/event，按序記錄三種類型的版本：
1. 推理版本：對應 assistant/message，記錄收齊後的最終消息。
2. 工具版本：對應 tool/call 和 tool/result，包含工具名、參數、執行結果及錯誤狀態。
3. 用戶版本：對應普通用戶輸入。
每個版本都是一個不可變的 JSON 文件，使用原子寫操作（tmp 文件 + rename）落盤，索引文件同樣原子更新，避免數據損壞。
完整可復現元數據¶
每個版本均附帶完整的上下文信息，用於復現當時的執行環境：
* 推理元數據：provider、model、reasoningEffort、maxTokens、usage、完整 content。
* 工具元數據：工具名、callId、參數、結果、isError。
* 會話頭信息：workspace、cwd、preset、agentOptions。
Git 版本管理與恢復¶
默認開啓 git 版本化：trace 根目錄被初始化爲專用 git 倉庫，每個版本對應一次 commit。插件支持將歷史版本物化爲 git worktree，路徑位於 .dsh-trace-worktrees/<session>-v<seq>。
通過 /trace resume 命令，可以從任意歷史版本恢復執行。系統會自動重建平衡上下文（截斷到最近一個無懸掛 tool 調用的推理完成版本），並在對應的 worktree 中新開會話繼續執行，新會話的 trace 獨立產生。
安裝與啓用¶
插件通過 manifest 自動激活，無需額外配置。安裝後需重啓宿主進程。
# 從 GitHub 安裝
dsh plugin --profile web add github:p2coder/dsh-trace-repeat
安裝完成後，在瀏覽器中刷新 DSH Web 頁面即可生效。
使用方式¶
安裝並重啓後，無需手動開啓，任意會話的執行即自動記錄。通過以下命令進行操作：
# 列出當前所有會話
/trace
# 查看指定會話的版本時間線及詳情
/trace show <session> [vN]
# 從指定版本恢復執行
/trace resume <session> <vN>
注意事項¶
- 只記錄最終消息：插件僅記錄收齊後的最終消息，不記錄流式輸出的增量內容。
- 恢復版本限制：恢復執行只能在“推理完成”版本（即無懸掛 tool 調用）進行。若嘗試在回合中間版本恢復，系統會報錯並提示更早的平衡版本。
- 獨立新會話：回放或恢復操作不會修改原會話的 trace，而是產生一個新的獨立 trace。
- 工作區快照：git 物化操作僅覆蓋 trace 文件，不包含該時刻工作區內的文件快照。
- 暫停/恢復標記：暫停/恢復標記版本僅在“暫停/恢復後的下一個會話事件”時寫入。若僅執行暫停和恢復且中間無其他事件，則不會產生標記版本。
總結¶
dsh-trace-repeat 提供了從微觀工具調用到宏觀會話狀態的完整記錄鏈路。通過不可變版本和 git worktree，開發者可以方便地追溯任意時刻的執行上下文並進行狀態回溯。
