前言¶
在 DeepSeek Harness（DSH）裏跑智能體，最常見的操作之一就是用 write/edit 改文件。這類操作一旦執行，文件原內容就被覆蓋了——模型改錯一處，或者一輪批量重構改壞了關鍵文件，改動前的內容就找不回來，只能靠手工備份或版本控制補救。
dsh-snapshot 把這件事做成了插件：每次 write/edit 調用後自動備份文件歷史，需要時恢復到任意歷史版本。下面介紹它的功能、安裝方式和使用注意。
這是什麼¶
dsh-snapshot 是由 Hyna-hla 維護的 DeepSeek Harness 宿主插件，定位是「文件快照與撤銷」，許可證爲 MIT。它做兩件事：
- 攔截
write/edit工具調用，自動把文件內容備份到快照倉庫； - 提供一組工具，用於查詢、恢復、清空歷史版本，並把當前會話導出爲 Markdown / JSON。
DSH 的理念是「一切皆插件」，dsh-snapshot 就是按這個方式接入宿主的組合（composition）。
核心功能¶
自動備份¶
每次 write/edit 工具調用後，插件會把文件當前內容寫入快照倉庫，路徑形如：
<工作區>\.dsh-snapshots\snap-<b64>.json
其中 <b64> 是文件路徑經 btoa 編碼後的結果，每個被追蹤的文件對應一個 JSON 文件。有兩個上限：每文件最多保留 20 版，單版內容不超過 2MB。達到上限後靠覆寫舊版本騰出空間，而不是刪除——原因是 DSH 的 fs 服務沒有 mkdir/unlink 能力，插件只能在既有文件上覆寫。
四個工具¶
snapshot_list：列出快照倉庫，顯示每個被追蹤文件的版本數與最新版本時間；snapshot_restore：把文件恢復到指定歷史版本。恢復前會自動再備份一次當前內容，所以恢復操作本身也可以撤銷；snapshot_purge：清空所有歷史版本；export_session：把當前會話導出爲 Markdown / JSON。
典型的使用流程是：先做 snapshot_list 確認某個文件有哪些版本，再用 snapshot_restore 恢復到指定版本；不需要歷史時用 snapshot_purge 清空。
安裝與啓用¶
資料未提供一鍵安裝命令，需要手動完成三步。
第 1 步：把構建產物拷入 profile 的 node_modules\dsh-snapshot，或者經 file: 依賴引入。
第 2 步：在 cordis.patch.yml 裏註冊，id 與 name 均爲 dsh-snapshot，config 中配置兩個上限：
- insert:
- id: dsh-snapshot
name: dsh-snapshot
config:
maxVersions: 20
maxContentBytes: 2097152
maxContentBytes 是單版內容的字節上限，2097152 即 2MB。
第 3 步：重啓 DeepSeek Harness，組合在進程啓動時加載。
經過上面的步驟，插件即隨宿主進程生效。
實現上的兩個細節¶
一是沙盒策略。宿主根上下文拿不到會話工作區，插件要往工作區寫快照時，需要透傳 sandboxPolicy，即調用 sandboxPolicy.resolve({session}) 解析出會話對應的策略。自己寫類似插件的話，這一點需要留意。
二是倉庫組織方式。快照倉庫按「每文件一個 JSON」組織，文件名是 btoa 編碼後的路徑；版本增刪靠覆寫而非刪除，原因如前所述——fs 服務沒有 mkdir/unlink。
適用場景與注意¶
適合讓模型高頻改文件的場景：批量重構、多輪修改代碼或配置，誤改後直接 snapshot_restore 回去，不必手工比對。也適合想在會話結束後留檔的情況，export_session 可以把會話導出爲 Markdown / JSON。
使用前注意幾點：
- 插件以當前 dsh 進程的權限運行，安裝前建議先讀一遍源碼，確認行爲符合預期；許可證爲 MIT，倉庫地址見文末。
- 版本數與單版大小上限通過
config的maxVersions與maxContentBytes設置，可按自己工作區文件的大小調整。 snapshot_purge會清空所有歷史版本，執行前確認不再需要這些記錄。
結尾¶
dsh-snapshot 解決的問題很具體：智能體改文件沒有後悔藥。它用每次 write/edit 後的自動備份，把撤銷變成一次工具調用，實現不復雜，但省掉的是實打實的排查時間。
- 插件目錄頁：https://www.skillhub.cn/plugins/Hyna-hla/dsh-snapshot
- GitHub 倉庫：https://github.com/Hyna-hla/dsh-snapshot
目錄頁來自社區維護的獨立站點，與 DeepSeek、幻方沒有官方從屬關係；安裝前請以上方倉庫中的源碼與說明爲準。
