在智能體開發中，文件狀態的回滾往往比對話歷史的回溯更棘手。當代碼生成進入深水區，開發者需要一種機制，能夠在對話的每個回合邊界保存當前工作區的狀態，以便隨時回滾文件改動。dsh-tui-checkpoints 旨在解決這一痛點，通過影子倉庫機制，爲 dsh-TUI 補全文件級別的“真回溯”能力。
下面介紹 dsh-tui-checkpoints 插件。
定位與功能¶
dsh-tui-checkpoints 是一個用於 dsh-TUI 的社區插件。它不會觸碰項目原本的 .git 倉庫，而是爲每個工作區創建一個獨立的影子倉庫。
核心功能包括：
* 回合快照：在每個 turn 邊界自動保存工作區狀態。
* 影子倉庫：在 ~/.dsh/checkpoints/repos/ 下維護獨立的 git 倉庫。
* 文件回溯：通過 /checkpoints 面板瀏覽和恢復文件狀態。
* 安全機制：恢復操作前自動創建 safety-* 分支，確保可回滾。
* 撤銷能力：支持對文件級別的修改進行回滾。
安裝與啓用¶
該插件目前處於 Spike（技術驗證）階段，未發佈到 npm。需要從源碼打包安裝。
git clone https://github.com/FUSU123fusu/dsh-tui-checkpoints.git
cd dsh-tui-checkpoints
npm pack
dsh plugin --profile dsh-tui add file:dsh-tui-checkpoints-0.1.0.tgz
安裝後，重啓 dsh-TUI 即可生效。
功能與用法¶
1. 打開檢查點面板¶
在終端中輸入命令：
/checkpoints
2. 瀏覽快照¶
面板列表顯示快照的元數據：
* 符號：● 表示輪後快照，◦ 表示輪前快照。
* 信息：Turn 編號、Commit 短 Hash、時間戳。
3. 查看差異¶
選中列表中的某一行，下方會實時顯示該快照與當前工作區的差異統計。
4. 恢復文件狀態¶
按下 r 鍵進行恢復。系統會要求在 3 秒內按兩次確認。
* 恢復邏輯爲 reset --hard + clean，即還原文件內容並刪除新增文件。
* 恢復前，當前狀態會先提交到 safety-* 分支，因此恢復本身也是可逆的。
5. 對話回溯¶
文件狀態恢復後，需配合 dsh-TUI 內置的雙擊 Esc /rewind 功能，將對話回溯到同一輪，以保持文件與對話的一致性。
原理與細節¶
影子倉庫機制¶
插件在 ~/.dsh/checkpoints/repos/<工作區hash>.git 創建影子倉庫。項目目錄本身被當作該影子倉庫的 work tree。這意味着：
* 項目的 .git 目錄完全不受影響。
* 即使項目目錄不是 git 倉庫，插件也能正常工作。
快照時機¶
插件監聽 session/event，在頂層會話的 turn/start（輪前）和 turn/end（輪後）各執行一次快照。快照操作是串行排隊執行的，如果文件無變化，會複用 HEAD 提交，避免生成大量空提交。
忽略規則¶
默認排除 .git、node_modules 等目錄，並讀取項目的 .gitignore，將規則寫入影子倉庫的 info/exclude。
性能表現¶
- 首次全量快照：約 5.8s。
- 無變化快照：約 0.7s（使用
add -A+diff --cached）。
嵌套倉庫處理¶
如果工作區包含嵌套的 git 倉庫（子模塊或 worktree），插件會將其記錄爲 Gitlink，不展開其內部漂移。
注意事項¶
- Spike 階段：這是技術驗證版本，尚未發佈到 npm，代碼可能存在不穩定性。
- 文件覆蓋風險：恢復操作是工作區級的。如果當前有未保存的編輯內容，恢復時會直接覆蓋，儘管這些內容已被安全提交到
safety-*分支。 - 對話與文件分離：對話回溯由 dsh-TUI 內置功能處理，本插件僅負責文件層面的狀態管理。
結語¶
dsh-tui-checkpoints 爲 dsh-TUI 提供了文件級別的回溯能力，解決了智能體開發中“改代碼難回滾”的痛點。雖然目前是 Spike 版本，但其影子倉庫的設計思路和雙段式恢復機制（文件 + 對話）爲未來的核心 PR 提供了驗證基礎。
