检查点回滚 PerryLink/dsh-checkpoint-rewind

⏪ dsh-checkpoint-rewind

- 1024 store channel：先执行一次 npm i -g dsh1024，再执行 dsh1024 plugin --profile web add dsh-checkpoint-rewind（计入 deepseek1024.com 的安装排名）。

dshfind

统一的 DeepSeek Harness 检查点 —— 会话 + 工作区 + 配置三态快照，一次回滚到位。

对标 Claude Code Checkpoints，以能力接缝插件的形式实现：每次变更前先捕获，一条获批命令即可恢复三种状态中的任意一种。

官方仓库。 这是 dsh-checkpoint-rewind 唯一的官方仓库，由 PerryLink 维护。其他账号下的同名仓库与本项目无关。

dsh-doctor
DSH Market

English · 简体中文 · Español · Português · हिन्दी

dsh plugin --profile <name> add dsh-checkpoint-rewind

📖 生态知识库 —— 实测数据，不是营销话术：插件开发指南 · 插件选型数据 · 维护标准。

安装与卸载

- git 渠道（最新 main）：dsh plugin --profile web add github:PerryLink/dsh-checkpoint-rewind —— 纯 ESM，无需 prepare 或 allowBuilds 步骤。
- npm 渠道（已发布版本）：dsh plugin --profile web add dsh-checkpoint-rewind。
- tarball 渠道：在本仓库执行 npm pack，然后运行 dsh plugin --profile web add ./dsh-checkpoint-rewind-<version>.tgz。
- 存储栈（检查点必需，挂载可选）：@deepseek-ai/dsh-storage + @deepseek-ai/dsh-storage-json（配置 root）+ @deepseek-ai/dsh-storage-domain（配置 backend: json）—— 见快速开始；没有它们插件仍能挂载，每条命令都会说明怎么修。
- 卸载：dsh plugin --profile web remove dsh-checkpoint-rewind —— 快照文件会保留，直到你删除 $DSH_HOME/dsh-checkpoint-rewind；git 对象会被垃圾回收。

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

什么是 dsh-checkpoint-rewind？

统一的 DeepSeek Harness 检查点 —— 会话 + 工作区 + 配置三态快照，一键回滚。

相当于 Claude Code Checkpoints，以能力接缝插件的形式实现：每次变更前先捕获，用一条获批命令恢复三种状态中的任意一种。

dsh-checkpoint-rewind 的工作流示意图：安装 → 打开面板 → 操作。

工作流概览：安装 → 打开面板 → 操作。下面的示例使用真实的命令接口。

对比

dsh-checkpoint-rewind 的实测对比图

满分 2 项能力（能恢复文件吗？/ 能回退会话吗？）· 依据 README 对比表统计

兼容性

| 层面 | 状态 |
| Harness | DeepSeek Harness dsh-v0.2.1-alpha.1（GitHub tag，2026-09-25 验证；npm 锁定 0.1.7-rc.2，peer 依赖 >=0.1.6-0 <0.2.0 \|\| >=0.1.7-0 <0.2.0）（2026-10-04 适配）：宿主移除了 @deepseek-ai/dsh-settings-file，并把 ctx.settings 命名空间注册接口换成 SettingsForms —— 它把每个 Loader 条目的 Config 投射到设置表单，编辑结果写入 profile 补丁持久化 —— 插件配置字段现在声明为 volatile() 并实时读取，严格的 typert 编解码器只保留各自的 create() 工厂，回退通知声明自己的消息源 kind。旧版 settings.register 路径保留给 0.1.5-rc.2/0.1.6-alpha.2 宿主。2026-09-22 针对 dsh-v0.1.7-alpha.1 检出验证（按 alpha.1 类型面做类型检查 + 完整单元测试套件 + 组装后的无头集成测试）。 |
| Node | ^22.19.0 \|\| >=24.0.0 |
| 平台 | 全部（宿主命令 + 监听器；可选的设置页时间线走设置能力） |
| 模型 | 任意（不调用模型 —— 快照与恢复都是确定性的） |

你会得到什么

dsh-checkpoint-rewind 捕获三态统一检查点——工作区、会话游标、插件配置——并用一条经批准的命令恢复其中一个或全部三个：

1. 三态记录——每个检查点都保存工作区状态（git tree SHA，或一份副本清单）、会话事件游标（seq + 轮次边界）和配置快照，并按来源打标签（manual / auto / guard / mutation）。
2. 四种捕获触发——每次变更类工具执行前（fs/write-intent、fs/edit-intent、tools/pre-execute）、按自动间隔（autoCheckpoint，默认每步）、手动触发（/checkpoint 和 checkpoint 工具），以及每次回退前的守卫。
3. git 优先服务商——git stash create / commit-tree 生成未被引用的快照对象，绝不触碰你的工作树、索引或历史；恢复只作用于工作树，且路径显式指定。非 git 目录（以及 unborn-HEAD 仓库）降级为增量 copy 服务商，复用硬链接。
4. 一键回滚——/rewind workspace|session|config|all <target> 恢复选中的状态；preview 是只读的影响报告，diff 比较两个检查点，clear 删除检查点（当前会话；clear --all 覆盖所有会话与工作区）。
5. 基于 fork 的会话回滚——会话回滚通过官方 SessionStore.fork 原语，把事件重放到检查点边界，写入新的子会话（宿主没有 fork，或检查点没有边界时，回退到带种子的 sessions.create 路径）；原会话保留完整历史。
6. 设置页时间线——Plugins → Checkpoints 标签页渲染当前会话的检查点，并给出两两之间的行级差异。

为什么还要另一个 rewind 插件？

| 插件 | 卖点 | 恢复文件？ | 回退会话？ |
| dsh-checkpoint-rewind（本插件） | git 对象快照 + 三态回滚 + 一键恢复 | ✅ 完整工作区状态 | ✅ 种子重放的子会话 |
| Anionex/dsh-turn-rewind | 持久化 Change Ledger，记录每次变更的增量 | ✅ 通过重放反向增量 | ✅ 自己的 ledger 模型 |
| LingLambda/dsh-undo | 纯上下文回滚到上一个完成的步骤 | ❌ | ✅ 仅上下文 |
| Mongfayi/dsh-recall | 消息召回（删除某一轮及其之后的一切） | ❌（明确不支持） | ✅ 删除轮次 |

一句话说清区别：dsh-checkpoint-rewind 在每次变更前用无副作用的 git 原语捕获工作区状态，把「回到第 N 步」变成一条经批准的命令——先守卫检查点，再恢复文件，再恢复配置，再重放会话，每个阶段都有日志。 没有会漂移的增量记账，没有消息级编辑（那属于另一个插件），也没有跨设备同步。

快速开始

dsh plugin --profile web add github:PerryLink/dsh-checkpoint-rewindsh

1. 把 bundle 装进你的配置档

dsh plugin --profile web add github:PerryLink/dsh-checkpoint-rewind

或从 npm 安装（已发布的版本）

dsh plugin --profile web add dsh-checkpoint-rewind

2. 重启并确认配置行

dsh --profile web --dump-config | grep -A4 'id: checkpoint-rewind'

检查点通过 storageDomain 服务持久化。缺少该服务时插件照样挂载，也绝不会阻塞配置档启动——此时 checkpoint/rewind 命令会返回结构化错误，指出需要添加的具体配置行。把存储栈组合一次，即可启用检查点： yaml
- insert:
- id: checkpoint-rewind-storage
name: '@deepseek-ai/dsh-storage'
- id: checkpoint-rewind-storage-json
name: '@deepseek-ai/dsh-storage-json'
config:
root: !!js dshHomePath('checkpoint-rewind/storage')
- id: checkpoint-rewind-storage-domain
name: '@deepseek-ai/dsh-storage-domain'
config:
backend: json

这个包是纯 ESM，没有构建步骤——index.mjs 和 lib/ 就是随包发布的产物。现在工作区发生变更会自动创建检查点；运行 /rewind 列出它们（或 /rewind list brief 查看单行条目，每条带上该检查点的会话编号）： text rewind: 3 checkpoints (newest last): #a1b2c3d4 · (git) · turn 2 step 1 · 2026-08-14 12:00:01 (3 min ago) · trigger: bash · 4 files · 1.2 MiB #b2c3d4e5 · (git) · turn 2 step 3 · 2026-08-14 12:00:41 · trigger: str_replace_editor · 2 files · 310 KiB #c3d4e5f6 · (copy) · turn 3 step 1 · 2026-08-14 12:01:10 · trigger: write · 1 file · 90 KiB run "/rewind <id>" to restore files and fork the session from that checkpoint

定位检查点有四种方式：会话编号（/rewind list brief 显示的那个有界短编号）、唯一 id 前缀、步骤编号，或 latest： text /rewind list brief # one line per checkpoint, numbered, newest first /rewind 3 # the checkpoint numbered 3 in THIS session (exact hit, never a fuzzy match) /rewind preview 3 # read-only: show which files would change, touch nothing /rewind b2c3d4e5 # unique id prefix (the 8-char id in the list) works exactly as before /rewind step 2 /rewind latest /rewind workspace 3 --files src/a.ts,src/b.ts # selective restore: only these files (approval-gated) /rewind clear # confirmed deletion of this session's checkpoints (files untouched) /rewind clear --all # confirmed deletion across ALL sessions and workspaces (files untouched)

会话编号（有界短 id）

- 每个检查点在创建时都会拿到一个编号，从 1 开始。/rewind 3 会精确解析这个编号——数字永远不会被当作 id 前缀，所以 /rewind 3 绝不会落到 UUID 恰好以 3 开头的那个检查点上。
- 作用域：按会话（sessionId）。每个会话各自给检查点编号；编号在所属会话内唯一，/rewind <number> 只针对当前会话（以及当前工作区）的检查点解析。
- 单调递增，永不复用。 配额清理（maxSnapshots）和 /rewind clear / /rewind clear --all 会删除记录，但绝不释放编号：清理之后，下一个检查点从之前的高水位继续（所以 #1 #2 #3 之后执行 clear，下一个是 #4，不是 #1）。编号存在记录本身上，计数器存在该域的全局槽位里，因此删除记录无法重置它。
- 旧检查点在首次出现时编号。 此功能上线前写入的记录（没有编号字段）会在会话首次列出或回退时按创建顺序编号，并持久化该编号；全新的检查点接着往后排。不会跳过或重新分配，id 前缀寻址对它们依然有效。
- /rewind list（详细列表）保持不变：仍然每行打印 8 字符 id，最后一行指向 /rewind list brief 查看编号。

preview 走同一套寻址，打印影响但不要求确认，也不写入任何内容。--files 只恢复指定的文件，同样走需审批的事务（未知路径按失败处理；它与 workspaceRestore: reset-hard 不兼容，在 selectiveRestore: false 时禁用）。

示例

以下是插件的真实入口；安装一次，然后调用其中一个。

详细示例

命令

~~~sh
/rewind preview cp-9

输出

~~~text
rewind preview: checkpoint #cp-9 (provider git, turn 2 step 3)
restoring it would overwrite 2 file(s):
a.txt
b.txt
5 file(s) already match the checkpoint (not touched).
no files are deleted: 1 file(s) created after the checkpoint would be left in place:
new.txt
run "/rewind <id>" to confirm and apply (a guard checkpoint is captured first)

摘自 test/checkpoints.test.mjs:289-301; lib/checkpoints.mjs:484-500

失败分支

输入

~~~text
/rewind nope

输出

~~~text
rewind: unknown checkpoint id "nope" (run /rewind to list)

摘自 plugins/dsh-checkpoint-rewind/lib/errors.mjs:72; plugins/dsh-checkpoint-rewind/index.mjs:1223; plugins/dsh-checkpoint-rewind/test/index.test.mjs:346-350

简要示例

- /checkpoint
- /rewind preview

配置

所有可调项都是 Schemastery 的 Config 字段（可在 cordis.yml 中修改）。没有硬编码。服务商选项（gitBin、snapshotDir、excludeGlobs、verifyByHash）在使用时从实时配置读取，所以改 cordis.yml 无需重启即可生效。

| 键 | 默认值 | 含义 |
| enabled | true | 总开关；设为 false 会完全移除命令、监听器和服务商 |
| provider | auto | 快照服务商：auto（有 git 就用 git，否则用 copy）· git · copy |
| gitBin | git | Git 可执行文件路径 |
| snapshotDir | $DSH_HOME/dsh-checkpoint-rewind（$DSH_HOME 未设置时回退到 ~/.dsh/dsh-checkpoint-rewind） | copy provider 快照的根目录 |
| maxSnapshots | 50 | 每个会话保留的检查点数量（超出时先裁剪最旧的） |
| maxSnapshotBytes | 536870912（512 MiB） | 全局增量字节软配额（每个活跃会话的最新快照始终保留） |
| pruneOnTurnEnd | true | 一轮结束时执行配额裁剪 |
| mutationTools | ['bash','write','edit','str_replace_editor','pwsh','terminal_send'] | 在 tools/pre-execute 阶段视为会改动文件的工具 |
| excludeGlobs | ['node_modules','.git','.dsh','dist','build'] | copy provider 跳过的 glob 模式 |
| confirmVia | auto | 确认渠道：auto（优先 userQuestions）· userQuestions · approval |
| listLimit | 10 | 只输入 /rewind 时显示的检查点数量 |
| preRewindCheckpoint | warn | 恢复前的保护性检查点：warn · require · off |
| verifyByHash | false | copy provider 的内容哈希比对与恢复校验 |
| autoCheckpoint.enabled | true | 在 step/start 时自动按间隔生成快照 |
| autoCheckpoint.intervalMinutes | 0 | 间隔；0 = 每步都生成 |
| workspaceRestore | restore | 工作区回滚：restore（安全覆盖）· reset-hard（CC 风格，需主动开启） |
| diffRenderer | pairwise | 设置页的 diff 渲染方式：pairwise（行级文本）· side-by-side（按文件双栏） |
| selectiveRestore | true | 按文件选择性恢复（/rewind … --files），以及面板里的按文件复选框 + 大小合计 |
| promptSection | true | 注入一段简短的角色说明提示词 |
| checkpointTool | true | 注册 checkpoint 模型工具 |
yaml
- insert:
- id: checkpoint-rewind
name: dsh-checkpoint-rewind
config:
provider: auto
maxSnapshots: 50
maxSnapshotBytes: 536870912
pruneOnTurnEnd: true
confirmVia: auto
preRewindCheckpoint: warn

工具与入口

| 入口 | 类型 | 说明 |
| /rewind | 命令 | [workspace\|session\|config\|all] <number\|id-prefix\|step <N>\|latest> · list [brief] · diff · preview <target> · clear [--all] |
| /checkpoint | 命令 | [note <text>\|list\|diff ] —— 手动生成检查点 |
| checkpoint | 工具 | 手动生成检查点，可附带备注 |
| fs/write-intent · fs/edit-intent · tools/pre-execute | 监听器 | 改动前抓取（前置透传；绝不抢占策略槽位） |
| session/event | 监听器 | 轮次/步跟踪、自动间隔、边界回填、轮末裁剪 |
| checkpoints 投影 | 会话投影 | 从会话日志折叠出的时间线 |
| 设置页时间线 | 客户端 | Plugins → Checkpoints 标签页，支持 pairwise（diffRenderer）diff 和按文件选择性恢复（selectiveRestore） |

安全模型
- Git 历史不可触碰。 git 服务商只运行白名单内的无副作用原语 —— stash create、commit-tree、restore --worktree、ls-tree、diff-tree、ls-files、status、rev-parse、cat-file -e —— 由运行时断言强制执行；对象引用在传给 git 之前会校验为十六进制 id（被篡改的记录无法注入 git 选项）。默认不执行 reset --hard，不执行 clean，永不改动索引或历史（见下文 workspaceRestore）。
- 回滚只覆盖，不删除。 恢复只覆盖已捕获的文件，git 服务商恢复的是显式路径（git restore … -- . 会删掉检查点之后 git add 过的文件）。检查点之后创建的文件（未跟踪或已暂存）只会被报告，原样留在原地。
- 不穿过链接写入，不做路径穿越。 copy 服务商在把检查点引用拼进快照目录路径之前先做校验，并拒绝穿过已变成符号链接的目标（或其祖先）恢复 —— 所以恢复永远不会顺着链接跑出工作区。
- 恢复需要审批。 覆盖用户文件一律走确认环节，语义为 ask；应答方缺失、抛异常或回答否，都按失败关闭处理。想先看影响范围，用只读的 /rewind preview。
- 回退可逆。 恢复之前，守卫检查点会先捕获当前状态；恢复守卫检查点即可撤销这次回退。preRewindCheckpoint: require 在守卫检查点无法捕获时中止回退。
- 固定顺序的事务。 先守卫，再工作区，再配置，最后会话重放；每个阶段都记日志；恢复失败时，文件、检查点、会话都保持原样。
- workspaceRestore: 'reset-hard' 等价于 CC，需显式开启。 它执行 git reset --hard <snapshot commit>（分支头移到快照提交；快照之前的历史仍可通过 reflog 找回；未跟踪文件不受影响）。默认关闭。
- 模型可见 ⟺ 有日志。 用户或模型看到的一切，都能从 command/run + command/done（以及宿主识别之后的 checkpoint/ 事件）加上持久化的 checkpoints 域重建出来。

工作原理 text capture ── fs/write-intent · fs/edit-intent · tools/pre-execute (prepend, pass-through) ── step/start auto interval ── /checkpoint · checkpoint tool ── pre-rewind guard │ ▼ ProviderRegistry.resolve(auto) → git: stash create / commit-tree │ copy: incremental dir + hardlinks ▼ checkpoints storage domain (SQLite rows / JSON file) + checkpoint/ event (adaptive gate)

/rewind <target> ── confirm (userQuestions / approval, fail-closed) ──▶ guard checkpoint
├─ workspace: provider.restore(ref) (restore | reset-hard)
├─ config: settings write-back (persisted on the profile patch)
└─ session: SessionStore.fork(source, boundary) → new child session (original untouched)

完整决策记录、事件词汇表、服务商接缝契约见 ARCHITECTURE.md。

会话事件（rc.2 说明）

插件把 checkpoint/snapshot、checkpoint/bound、checkpoint/prune、checkpoint/rewind 声明为仅写日志的 SessionEventMap 成员。Harness rc.2 没有插件事件注册接口，Session.append 也不会打上 ignorable 信封（它的第三个参数是 surface intent，不是 options），所以追加未知类型会让会话在重新加载时读不出来。因此插件通过自适应闸门追加：运行时探测（在一个分离、永不持久化的会话存储上）检测宿主的 append 是否打上 ignorable 信封——在 rc.2 上闸门保持关闭；在支持它的宿主上，checkpoint/ 事件会自动带上 ignorable: true 追加。在那之前，权威审计链是 command/run + command/done（harness 已知）加上持久化的 checkpoints 存储域。

Web UI 锚点

插件在命令结果里返回新会话 id（session: <id>），Web shell 可以导航过去。会话投影单元 checkpoints 已交付：只要 ctx.sessionProjections 存在，插件就通过 ctx.inject 注册该单元（把 checkpoint/snapshot|bound|prune|rewind 折叠成整值列表）——在 rc.2 宿主上它保持空列表，直到某个 harness 构建交付 checkpoint/ 词汇表或 ignorable 信封，之后无需改动插件就会自动填充。

FAQ

这会取代 git 吗？ 不会——它只是在可用时使用 git。在 git 仓库里，你能得到字节级精确、去重的快照对象，且不碰历史；在其他任何目录里，复制服务商用普通文件做同样的事。常规提交仍然是你的长期历史。

为什么默认不用 git reset --hard？ 因为销毁状态不是安全网该干的事。插件默认只创建无引用对象，并执行仅限工作区、路径明确的恢复，所以一次糟糕的回退永远不会丢失历史、索引或检查点之后创建的文件。reset-hard 放在 workspaceRestore: 'reset-hard' 后面，留给明确想要 CC 对等行为的用户。
检查点能恢复到多久以前？ git 服务商快照上不保留任何 ref。按设计，它们就是未被引用的 stash create/commit-tree 对象，discard 只删除记录，对象本身留给 git gc。检查点实际能保持可恢复的时长，受两件相互独立的事约束：插件自己的配额清理（maxSnapshots，每个会话默认保留 50 个；maxSnapshotBytes，默认 512 MiB 的全局软配额，捕获时通过 pruneAll() 强制执行，回合结束时再清扫一遍），以及宿主仓库的 git gc。按 git 的默认设置，未被引用的对象会一直存活到某次自动 gc 运行；即便那时，也只有早于 gc.pruneExpire（默认 2 周）的对象才会被清理。手动执行 git gc --prune=now、激进 repack、filter-repo，或者重新克隆，都可能让它们立刻消失。现在会提前检测被清理的对象：git 服务商在恢复前先探测快照对象（git cat-file -e），对象缺失时直接报错，而不是静默地什么都没恢复；doctor 检查会遍历每条检查点记录，探测对象是否存在，并给无法恢复的记录打上标记（列表中显示 [UNRESTORABLE: object missing]）。doctor 检查已实现并测试过，但还没接入恢复路径（恢复时还不会参考 unrestorable 标记；见 discussion #13）。

能回退到回合中间的某一步吗？ 文件恢复精确到步（/rewind step <N> = 最近的快照 ≤ N）。但会话重放遵循 harness 的重放粒度：子会话只播种到检查点所在的回合边界。

如果没人能回应确认怎么办？ 什么都不动——插件按失败关闭处理（unavailable/rejected），保留检查点，并返回一条说明原因的报错。rc.2 上用 confirmVia: approval 时，消息会提示挂载 userQuestions，因为 approval 需要打开的回合，而命令在回合之间运行。

能撤销一次回退吗？ 能——每次批准的回退都会先捕获一个回退前状态的 guard 检查点；结果里会打印 rewind guard: <id>，用 /rewind <guard-id> 即可恢复那个状态。

怎么定位检查点？ 用会话编号（/rewind 3——见 /rewind list brief；按会话单调递增，永不复用）、唯一 id 前缀（列表里的 8 字符短 id 仍然可用）、/rewind step <N>，以及 /rewind latest。/rewind clear 删除本会话的检查点，/rewind clear --all 删除所有会话和工作区的检查点（不动文件）——两者都不会重置编号。/rewind preview <target> 用同样的定位方式展示影响，但不做任何改动。
为什么清空之后编号还在往上加？ 因为编号是地址，不是位置：清空之后如果让 #1 指向另一个检查点，所有提到 #1 的地方都会被悄悄改指。计数器持久化在 checkpoints 域（全局槽位），每条记录各自保存自己的编号，所以 prune 和 clear 只删除快照，不回收 id。

preview 做什么、不做什么？ 它先解析检查点，再跑一次只读比较：哪些文件会被覆盖（或重建），哪些已经一致，哪些在检查点之后新建的文件会原样保留。它不提示、不写入、不 fork，也不记录 checkpoint/rewind 事件——审批关卡只在真正的 /rewind <id> 上触发。

演示

一次真实组装的无头集成运行（npm run test:integration）会走完整流程：智能体跨两轮修改文件，然后 /rewind preview 以只读方式检查影响（没有确认关卡，没有写入），/rewind <id> 恢复文件并把会话重放进新的子会话。这次运行会断言文件内容、重放后的子上下文、守卫检查点，以及检查点之后新建的文件仍然存在——copy 和 git 两种服务商流程都覆盖（git 流程还会断言 HEAD 和 reflog 未被改动）。驱动脚本位于 test/integration/rewind-headless.mjs。

权限与数据

- 权限：workshop manifest 声明 workspace:read、workspace:write、git:read、git:write、snapshot-storage:write、session-log:read、settings:write 和 network:none。
- 数据：检查点记录存放在 checkpoints 存储域（SQLite 行或 JSON 文件）；copy 快照存放在 snapshotDir 下。该域的全局槽位保存每个会话的短编号计数器，所以删除记录（prune、clear、clear --all）永远不会回收编号。完全本地——不联网，不需要凭据。该域以双版本方式打开：0.4.x 时代的介质（域 v1）以兼容模式打开，旧记录仍可读，新捕获按 v2 结构存储，因此升级插件不会让已有介质变成孤儿。
- 会话日志：checkpoint/ 事件通过自适应关卡追加；权威审计链是 command/run + command/done 加上持久域。

安全边界

- Git 历史不可触碰。 只使用白名单内的无副作用原语；reset --hard 仅在显式开启 workspaceRestore: 'reset-hard' 模式时使用。永远不执行 git clean。
- 回滚靠覆盖，绝不删除。 恢复只覆盖捕获过的文件；检查点之后新建的文件会被报告并原样保留。
- 不通过链接写入，不做路径穿越。 copy 的 ref 会按快照 id 校验；恢复拒绝跟随符号链接逃出工作区。
- 恢复需要审批。 应答方缺失或拒绝时按失败关闭处理。
- Rewind 可回退。 先捕获回退前状态的守卫检查点。

已知限制

- 在 rc.2 上，checkpoint/ 会话事件会被自适应门控抑制；审计链依赖 command/run + command/done 以及存储域，直到宿主提供相应词汇或 ignorable 信封。
- confirmVia: approval 需要有一个打开的轮次，而命令在轮次之间运行——在 rc.2 上挂载 userQuestions（或设置 confirmVia: userQuestions）。
- 会话回滚会在检查点边界分叉出一个新的子会话；它从不重写或截断原始会话。
- workspaceRestore: 'reset-hard' 会把分支头移动到快照提交；默认关闭。
- 在任何已关闭轮次之前捕获的检查点没有重放边界——此时会话回滚会创建一个上下文为空的新子会话。

故障排查

| 现象 | 原因 / 修复 |
| /rewind <id> 提示 rewind cancelled: no confirmation answerer | 没有挂载 userQuestions/approval 通道——插件会失败关闭。在 Web UI 中运行（或挂载问题服务商）；confirmVia 选择通道。 |
| /rewind <id> 提示 approval requires an open turn … | 命令在轮次之间运行，而审批需要一个轮次——挂载 userQuestions 或设置 confirmVia: userQuestions。 |

| rewind: checkpoint registry unavailable | The checkpoints storage domain could not open. Either the storageDomain service is not composed (add the storage stack rows from Quick start: @deepseek-ai/dsh-storage + @deepseek-ai/dsh-storage-json with config root + @deepseek-ai/dsh-storage-domain with config backend: json) or the backend is erroring; check the harness logs. |
| A checkpoint lists as fork: pending (turn not closed) | Its turn has no turn/end yet; files can still be restored, but the session replay waits for the turn to close. |
| files restored … but the session was NOT replayed | The transaction's session phase failed (no closed boundary, or replay rejected). Files stay restored; use the printed rewind guard: <id> to undo. |
| rewind: aborted — the pre-rewind guard checkpoint could not be captured | preRewindCheckpoint: require refused the rewind because the guard capture failed; fix the storage (or set warn/off). |
| A checkpoint lists as (copy) even though the directory is a repo | Unborn HEAD (no initial commit): git snapshot primitives require HEAD, so the plugin degrades to copy until the first commit. |
| MISSING_CREDENTIAL in headless runs | Unrelated to this plugin: no DEEPSEEK_API_KEY is configured for the model provider. |
| Snapshot storage grows | Pruning runs after every snapshot and at turn/end (pruneOnTurnEnd); lower maxSnapshots / maxSnapshotBytes, run /rewind clear, or delete $DSH_HOME/dsh-checkpoint-rewind after uninstalling. |

Development
sh
npm install # peer deps: @deepseek-ai/dsh-session@0.1.2-rc.1, schemastery, zod
npm test # node --test test/*/.test.mjs (provider suites incl.)
npm run test:integration # assembled-headless verification (test/integration/)

No build step: pure ESM — index.mjs/lib/ are the published artifacts.

Interoperability with other DSH plugins

Verified against DSH 0.2.0-rc.2 (the runtime this README ships for) and the high-star plugin set surveyed on 2026-10-05.

This plugin does not interfere with other plugins, including the widely installed high-star ones:

- No tool-name collision. Every tool is namespaced; no bare name owned by a shipped tool or another plugin is registered.
- No service-key collision. It provides no service key at all, so it cannot collide on one.
- No slot collision. It registers no client slot key, so it cannot contend for a shadows-shipped-ui seat.
- No HTTP route collision. It registers no webServer prefix.
- No patch-layer collision. The bundle patch only inserts its own row; it never overrides a built-in row's config.
- No global mutation. It does not patch prototypes, rewrite process.env, or replace the global fetch dispatcher.

Shared event listeners are non-interfering by construction. It observes the ordering-sensitive events fs/edit-intent, fs/write-intent, tools/pre-execute with ctx.on() — Cordis's broadcast registration, where every listener runs and none can starve another. Every listener here delegates through next(), so the chain is never short-circuited, and a mutation is applied to the value next() produced rather than returned in its place:
- tools/pre-execute — also used by cc-safety-net (1576★).

Static evidence: dsh-plugin-doctor K10–K13 report pass for every check on this repository.

Topics

deepseek-harness, dsh, dsh-plugin, rewind, checkpoint, snapshot, session-replay, session-fork, config-restore, workspace-safety, undo, cordis-plugin

Contributors

- @mahirhir — object-existence doctor probe (#16), liveConfig for snapshotDir/excludeGlobs/verifyByHash (#17), live-session prune scoping (#18), missing-snapshot quota cleanup (#19), dynamic copy-provider config (#20).

- @PerryLink — creator and maintainer: the three-state checkpoint model, the git/copy provider seam, the three-phase rewind transaction, the Settings page timeline, docs, CI/CD and releases.
- @tmpdot (rmUnlucky) — v1-medium dual-version compatibility (#8), lazy storageDomain resolution (#9), checkpoint dedup reply hints (#10), and the $DSH_HOME-unset snapshot-dir bug report (#4).
- @shipinliang — checkpoint panel wire-contract reports: the missing acceptsUndefined on the limit parameter (#5) and the #deps private-field proxy failure (#6).
- @hwz1456 — web-profile checkpoint-capture report (#3).
- @Andiii208 — plugin_check publishing-spec report (#2).
- @alexchenzl (Ashu) — DSH Directory listing invitation (#7).

PerryLink DSH Plugin Family

This project is part of the DeepSeek Harness plugin family from PerryLink. The roster stays collapsed below so every README keeps a short first screen; expand it to see every row and its status.

Expand all plugins

| Plugin | Status |
| dsh-aqua-input-check | |
| dsh-archive-check | |
| dsh-auto-review | |
| dsh-autotier | |
| dsh-bid-ca-precheck | |
| dsh-bid-qual-check | |
| dsh-cert-mcp | |
| dsh-checkpoint-rewind | |
| dsh-click | |
| dsh-composer-history | |
| dsh-contract-stance | |
| dsh-customs-doc-check | |
| dsh-data-quality | |
| dsh-demurrage-ledger | |
| dsh-doublecheck | |
| dsh-drill-script-check | |
| dsh-eia-guide-check | |
| dsh-emergency-plan | |
| dsh-essay-rubric-check | |
| dsh-evidence-check | |
| dsh-export-ctl-check | |
| dsh-fast | |
| dsh-fmea-table-check | |
| dsh-forecast-penalty | |
| dsh-fund-research | |
| dsh-github | |
| dsh-gongwen-flow-check | |
| dsh-gongwen-word-check | |
| dsh-guard-plan-qc | |
| dsh-hazchem-check | |
| dsh-hazplan-check | |
| dsh-hidden-risk-map | |
| dsh-hs-classify | |
| dsh-icd-rule-check | |
| dsh-industry-research | |
| dsh-lawcite-adapter | |
| dsh-laya | |
| dsh-lc-doc-check | |
| dsh-learning-gap-check | |
| dsh-library | |
| dsh-local-ai | |
| dsh-lsp-actions | |
| dsh-mask | |
| dsh-mcp-panel | |
| dsh-medrec-qc | |
| dsh-memento | |
| dsh-nsfc-form-check | |
| dsh-nurse-record-check | |
| dsh-observe | |
| dsh-origin-rvc-check | |
| dsh-ota-review-check | |
| dsh-output-styles | |
| dsh-paper-doc-adapter | |
| dsh-permission-rules | |
| dsh-permit-report-check | |
| dsh-pipeline-check | |
| dsh-pleading-draft | |
| dsh-plugin-doctor | |
| dsh-plugin-guide | |
| dsh-plugin-kit | |
| dsh-plugin-upgrade | |
| dsh-policy-brief-draft | |
| dsh-power-loss-split | |
| dsh-power-ticket-check | |
| dsh-ppap-check | |
| dsh-protest-deadline | |
| dsh-railway-window | |
| dsh-repair-order-qc | |
| dsh-research-report | |
| dsh-review-reply-check | |
| dsh-rulefile-check | |
| dsh-safety-brief-check | |
| dsh-score | |
| dsh-session-sync | |
| dsh-site-log-check | |
| dsh-skill-pack-security | |
| dsh-soe-decision-check | |
| dsh-soilwater-check | |
| dsh-sop-sync-check | |
| dsh-spc-gbt-adapter | |
| dsh-talk | |
| dsh-tender-extract | |
| dsh-tender-matrix | |
| dsh-test-drive | |
| dsh-ticktick | |
| dsh-translate | |
| dsh-warranty-calc | |
| dsh-budget | 🧊 FROZEN — see the repo README |
| dsh-claude-move | 🧊 FROZEN — see the repo README |
| dsh-defend | 🧊 FROZEN — see the repo README |
| dsh-draw | 🧊 FROZEN — see the repo README |
| dsh-reach | 🧊 FROZEN — see the repo README |
| dsh-background-agents | 🚫 RETIRED — see the repo README |
| dsh-session-pin | 🚫 RETIRED — see the repo README |
| dsh-team-rooms | 🚫 RETIRED — see the repo README |

License

Apache License 2.0 © 2026 dsh-checkpoint-rewind contributors