前言¶
在 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 工作流补一层文件级安全网。
