前言¶
在 DeepSeek Harness (DSH) 的開發環境中，智能體經常需要執行復雜的多文件重構、運行破壞性 Shell 命令或安裝依賴。當意外發生迴歸或工作區狀態損壞時，手動使用 Git 回滾不僅過程繁瑣，還存在丟失未跟蹤文件或破壞用戶歷史記錄的風險。
dsh-time-machine 是爲此類場景設計的 DSH 插件。它提供了一套智能檢查點、工作區安全衛士和即時回滾機制，能夠在後臺創建輕量級的影子 Git 快照，確保工作區狀態的完整性和可恢復性。
核心功能¶
該插件提供以下核心能力：
- 輕量級影子 Git 快照：在後臺捕獲全量工作區、暫存區及未跟蹤文件，使用隔離的 Git 影子樹引用，不干擾用戶的提交歷史、當前分支或暫存區。
- 即時安全回滾：支持將整個工作區或特定文件恢復到任意歷史檢查點，使用非破壞性
checkout-index操作，不移動HEAD或重寫分支歷史。 - 可視化快照差異檢查器：提供文件級的視覺差異對比，高亮新增、刪除和修改的行，並顯示統計信息。
- 交互式側邊欄與設置時間軸：集成於 DSH Web UI 的側邊欄和設置標籤頁，以時間軸形式展示會話檢查點，支持一鍵回滾、差異查看和刪除操作。
- 命令失敗自動修復：當工具或命令執行失敗時，自動記錄檢查點以保留恢復選項。
- 選擇性文件回滾與暫存安全衛士：支持單文件恢復，並在高風險操作前自動創建檢查點，保護用戶暫存的 Git 索引。
安裝¶
使用官方命令安裝該插件：
dsh plugin --profile web add @goodandready/dsh-time-machine
配置¶
在 DSH 的配置文件中添加以下內容以啓用自動快照和回滾提示：
dsh-time-machine:
autoSnapshotEnabled: true # 在文件修改前自動創建檢查點
maxSnapshots: 20 # 內存中保留的最大滾動檢查點數量
autoHealPrompt: true # 命令失敗時提示回滾
工具參考¶
插件爲 Agent 提供了以下工具，可用於程序化控制：
time_machine_checkpoint_create- 描述：在執行高風險編輯或操作前創建影子 Git 工作區檢查點。
- 參數：
label?: string, sessionId?: string
time_machine_checkpoint_list- 描述：列出最近的會話檢查點（按時間倒序）。
- 參數：
sessionId?: string
time_machine_checkpoint_rollback- 描述：將工作區文件恢復到指定檢查點。
- 參數：
id: string, confirm: boolean
time_machine_diff- 描述：計算當前工作區與目標檢查點之間的統一文件差異。
- 參數：
from: string, to?: string
time_machine_checkpoint_delete- 描述：永久刪除單個檢查點並清除其 Git 引用。
- 參數：
id: string, confirm: boolean
time_machine_checkpoint_prune- 描述：清理會話檢查點，僅保留最新的 N 個。
- 參數：
sessionId?: string, keep?: number
注意事項¶
- 運行環境：插件以當前 DSH 進程權限運行，安裝前請檢查源碼與許可證。
- 依賴要求：需要 Node.js 20 或更高版本。
- 版本更新：
- v0.1.16：安全加固與側邊欄標籤去重。修復了在特定環境下側邊欄重複註冊的問題，並嚴格限制了 REST 路由的 HTTP 方法（僅 POST 用於修改，GET 用於讀取）。
- v0.1.15：選擇性文件回滾與暫存安全衛士。新增單文件恢復工具
time_machine_file_rollback及/rollback-file路由。
