前言¶
在 DeepSeek Harness（DSH）裏讓智能體改代碼時，常見做法是依賴 Git 提交、stash 或整倉 reset。這些路徑要麼打斷工作流，要麼動到 HEAD、分支或暫存區，和「只把某幾個文件拉回上一版」的需求並不一致。
下面介紹社區插件 dsh-rewind（@lightjunction/dsh-rewind）：爲明確列出的本地文件保存檢查點，預覽後再恢復，並在覆蓋前持久保存 redo 檢查點。它不執行 reset/checkout/clean，也不改 HEAD、分支或用戶 index。維護者爲 LIghtJUNction，在插件目錄站點歸類爲工作流；行爲目標參考上游 arpagon/pi-rewind（MIT），爲獨立實現，首版未包含自動每輪快照、全倉恢復等上游能力。
這是什麼¶
dsh-rewind 向 DSH 註冊 rewind 工具，在宿主機本地 Git 倉庫根內，把選定文件的快照寫入 Git 對象（經獨立 refs，不生成普通提交），供後續 list、preview、restore。默認工作區取當前 agent 的 workingDirectory；無 agent 調用時可配置 root。
插件以當前 DSH 進程權限讀寫文件與 .git，不是安全沙箱，也不聲稱支持 DSH remote world/sandbox。安裝前宜自行查看 GitHub 源碼 與 MIT 許可證。
核心功能¶
檢查點與列表¶
- checkpoint：對
paths中已存在的文件各建一個檢查點，返回id。不會自動擴大到整個倉庫；每次 1–100 個文件，單文件最多 1 MiB，manifest 最多 8 MiB。 - list：列出本倉庫
refs/dsh-rewind/下的檢查點，重啓後仍可用。
檢查點將 JSON manifest 與 base64 文件內容寫入 Git blob；不調用 git add / read-tree / write-tree / reset / clean，不讀或重建用戶暫存區。
預覽與恢復¶
- preview：按
id返回 token，以及各文件 before/after 的 base64 原始字節（changed含權限差異），不是統一 diff，需自行解碼比較。 - restore：憑最新 preview 的 token 僅恢復檢查點裏選定的文件。返回的
backupId是覆蓋前的 redo 檢查點；要撤銷本次恢復，對backupId再 preview/restore。
token 綁定當前文件字節、權限、HEAD 和分支；預覽後若改動文件，恢復會失敗。恢復會覆蓋選定文件的當前內容（含未提交改動），其他 dirty/untracked 文件保持不變。跨 HEAD 或分支恢復會被拒絕。
約束與保護¶
工作區須爲已有提交、具名分支的 Git 倉庫根；未提交的新倉庫、detached HEAD、子目錄當根均不支持。拒絕工作區外路徑、.git 元數據、符號鏈接、多重硬鏈接和非普通文件；不刪除或創建恢復目標路徑（被刪文件需調用者先恢復路徑再使用本工具）。
檢查點佔用 .git/objects，不會自動 pruning，可能含敏感內容，paths 應由調用者明確選擇。多文件恢復非全批事務；併發改目錄時不宜 restore。
安裝與啓用¶
需要 Git、Node.js 24+ 和 DeepSeek Harness 0.2.1-rc.2。當前爲源碼交付（README 未表示 npm 已發佈）。在已安裝 monorepo 依賴的目錄執行：
npm run check --workspace @lightjunction/dsh-rewind
cd plugins/dsh-rewind
npm pack
dsh plugin --profile web add "$PWD/lightjunction-dsh-rewind-0.1.0.tgz" --ignore-scripts
重啓對應 profile，確認出現 rewind 工具。其他 profile 將命令中的 web 換成實際 profile 名。
本地驗證可運行：
npm run check --workspace @lightjunction/dsh-rewind
典型用法¶
以下參數均傳給 rewind 工具（JSON）。
建立檢查點：
{"action":"checkpoint","paths":["src/example.ts","README.md"]}
列出檢查點：
{"action":"list"}
預覽後再恢復（先 preview 拿 token，再 restore）：
{"action":"preview","id":"<檢查點 id>"}
{"action":"restore","id":"<檢查點 id>","token":"<最新 preview token>"}
經過上面的步驟，智能體或宿主可在不碰分支歷史的前提下，對少數文件做可審計的回退；需要撤銷 restore 時，用返回的 backupId 走同一 preview/restore 流程。
適用場景與注意¶
適合：在 DSH agent 改代碼前對關鍵文件打點；改錯後只回滾明確列表中的文件；需要 redo 檢查點而不是硬 reset 的工作流。
注意：
- 僅支持宿主機本地文件系統與本地 Git。
- 插件與 DSH 同權限運行；檢查點可能長期留在
.git/objects。 - 與上游 pi-rewind 相比，v0.1 取消了自動每輪快照、全倉庫恢復、會話回退等；不用上游的
reset --hard、read-tree 和 clean。
社區目錄 SkillHub 插件頁 與 GitHub 倉庫相互獨立索引，並非 DeepSeek / 幻方官方應用商店；DSH 生態以「一切皆插件」爲方向，選型以倉庫 README 與許可證爲準。
結尾¶
dsh-rewind 把「選定文件的檢查點、預覽、恢復與 redo」收進一個 rewind 工具，在不動 HEAD 與分支的前提下，爲 DSH 工作流補一層文件級安全網。
