前言¶
DeepSeek Harness (DSH) 智能體在執行過程中會頻繁修改文件或調用 Shell 命令（如 sed -i、rm 等）。現有的回滾插件往往只能捕獲回合邊界的快照，或者只能識別文件編輯工具的參數，無法記錄 Shell 命令產生的副作用。這導致一旦操作出錯，難以精確還原到某個步驟之前的狀態。dsh-zcode-rewind 旨在解決這一痛點，提供細粒度的、基於工具調用的檢查點系統。
插件簡介¶
dsh-zcode-rewind 是 DeepSeek Harness 的一個工作流插件，由 BOWLUNA 維護。它爲 DSH 提供了 per-tool-call 工作區檢查點功能，能夠捕獲每一次文件變更和 Shell 命令，以內容尋址的方式存儲 Blob，並提供行級差異預覽和可逆的還原操作。
核心功能¶
該插件的核心能力集中在以下幾個方面：
- 全量捕獲：捕獲所有 mutating tool call，包括 bash、pwsh、write、edit、MCP 工具以及 subagent 工具。
- 記錄變更：記錄文件的刪除、創建和修改，併爲每個路徑附帶可恢復的先前內容哈希。
- 內容尋址：存儲內容尋址的文件內容（SHA-256），實現跨會話和跨工作區的去重。
- 持久化日誌：提供按條目順序排列的持久化變更日誌，重啓 DSH 後依然存在。
- 操作支持：支持手動創建檢查點，以及 undo/redo 操作。
安裝與前置條件¶
安裝前，請確保環境滿足以下要求：
- Node.js >= 20.0.0
- DSH >= 0.1.5-alpha.1
安裝命令如下：
dsh plugin --profile web add dsh-zcode-rewind
安裝完成後，需要重啓 DSH 才能使插件生效。可以通過 dsh --profile web --dump-config | grep workspace-rewind 驗證插件是否已正確綁定。
使用方式¶
插件提供了一系列工具命令來管理檢查點。以下是主要工具及其用途：
rewind_now：創建一個手動檢查點，例如在執行高風險操作前。rewind_list：列出最近的記錄，按時間倒序排列，顯示 ID、時間、工具類型以及變更統計（+added ~modified -deleted）和路徑樣本。rewind_diff：預覽還原計劃及行級統一差異，此操作不會實際修改文件。rewind_restore：執行還原操作。mode=revert用於撤銷單條記錄；mode=asof用於將工作區恢復到某個檢查點的時間狀態。rewind_undo：撤銷上一次還原操作，重複執行可切換 undo/redo 狀態。rewind_status：顯示存儲統計信息，包括記錄數、Blob 數、字節數、配額和當前配置。
配置項¶
插件支持通過配置文件調整行爲。以下是一個典型的配置示例：
- insert:
- id: workspace-rewind
name: 'dsh-zcode-rewind'
config:
capture: all # 捕獲模式：all | fileTools | off
maxFileBytes: 8388608 # 單文件最大字節數，超過僅記錄事件
maxFiles: 20000 # 單次遍歷文件數量上限
maxTotalBytes: 536870912 # 存儲總字節數上限，舊 Blob 會自動清理
keepRecords: 500 # 日誌保留條目數閾值
excludes: ['.git', 'node_modules', 'dist']
secretNames: ['.env', '*.pem', '*.key']
注意事項¶
- Shell 副作用捕獲：與市場上其他 rewind 插件不同，本插件能捕獲 Shell 命令的副作用（如
sed -i），因爲其採用指紋差異對比而非解析參數。 - 檢查點粒度：捕獲是基於“每次工具調用”，而非“回合邊界”，因此能更精確地定位問題。
- 存儲位置：存儲目錄位於
$DSH_HOME/workspace-rewind/，位於工作區之外，不會污染 Git 倉庫。 - 去重機制：由於使用 SHA-256 內容尋址，相同的文件內容在多次修改中只佔用一份存儲空間。
總結¶
dsh-zcode-rewind 爲 DeepSeek Harness 提供了細粒度的、可逆的工作區狀態管理能力。對於需要高可靠性和精確控制回滾範圍的智能體開發場景，該插件是一個實用的工具。其詳細文檔與源碼位於 GitHub。
