dsh-shadow-rewind

Shadow Rewind

基于隐藏影子 jj 仓库的会话级文件快照与回退，并内置 AI 改动文件审查：侧边栏 diff、聊天轮尾卡片、hunk 级撤销/重做、终端写盘审计（检查点窗口归属 + 轮末检查点精确归属 + 写盘归因 + 可撤销）、Code Mode 录制（融合 dsh-file-review-tab）。

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add dsh-shadow-rewind@0.9.2

兼容性与来源证明

Shadow Rewind 以 dsh-shadow-rewind 发布，当前版本为 0.9.2。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: web
发布来源: npm
Registry 更新时间: 2026/9/20

版本

0.9.2stable

2026/9/1

0.9.1stable

2026/9/1

README

dsh-shadow-rewind

DeepSeek Harness 的会话级文件快照与回退插件。
每一轮自动影子快照 —— diff 审查、块级撤销、终端写盘审计、整树恢复。

功能全景 • 安装 • 配置 • 测试 • 已知边界

⭐ GitHub 仓库：DreamsTOF/dsh-shadow-rewind —— 觉得有用就点个 Star；问题与需求请提 Issue

every turn → shadow snapshot → diff · review · restore

针对 DeepSeek Harness 的会话级文件快照与回退 + AI 改动文件审查 + 终端写盘审计插件。

功能全景

不管文件是被 AI 的 write/edit 工具、终端命令（PowerShell / bash / git）、还是外部进程修改的——每轮的全部文件变更都可见、可显示 diff、可撤销：

面	机制	粒度	入口
会话回退	影子 jj 仓库整树快照	整个工作区（内容 + 权限位 + 空目录）	每条直发用户消息旁的「恢复到发送之前」
文件审查	工具 hunk 文本重放	改动块（hunk）/ 文件 / 轮	聊天轮尾卡片 + 侧边栏「文件审查」tab
终端写盘审计	检查点窗口归属对比	文件 / 空目录 / 权限位	轮尾卡片 + 轮中 live 条 + 侧边栏
写入闸	所有权登记 + 工具裁决	会话 × 工具	自动；侧边栏运行时开关

核心设计：影子仓库平行线。 工作区自身的任何 VCS（git / jj / 无）与本插件的影子 jj 仓库完全隔离——插件枚举文件只走目录扫描，快照字节只写入存储根下的隐藏 jj 仓库；恢复时只改写工作区文件，绝不触碰工作区的 .git、.jj、HEAD、分支或提交。

你的项目目录（随便怎么折腾）          插件存储根（$DSH_HOME/shadow-rewind/v1）
├── src/...                          └── workspaces/<key>/
├── .git/   ← 插件从不读写               ├── manifests/           恢复点清单
└── ...                                  ├── blobs/               内容寻址存储（legacy 后端）
                                         ├── operations/          恢复操作日志（崩溃恢复依据）
                                         ├── turn-outcomes/       检查点跳过记录
                                         ├── file-review/recorded/ Code Mode 录制（持久）
                                         ├── file-review/rescue/   fs 删除前的找回副本
                                         └── shadow-repos/<key>/  影子 jj 仓库（快照字节）

一、会话回退（影子快照）

自动检查点：每轮对话在 Agent 第一步之前自动快照轮起树状态，轮结束（turn/end 事件）时再快照轮末树状态——每个检查点是一条显式记录（轮起/轮末相位各自计配额）。默认走隐藏 jj 仓库；宿主机没有 jj CLI 时自动降级为内置内容寻址 blob 存储（启动日志提示），功能不中断；off 可整体关闭。
回退入口：每条直发用户消息下出现「恢复到发送之前」；对话框预览将恢复的文件清单与快照时显式跳过的路径，并提供两种落点：
- 恢复文件并从这里继续 —— 恢复文件后分叉新会话（原会话保留）；
- 只恢复文件 —— 当前对话不动。
恢复安全闸（全部强制，任何一步失败立即 fail-closed）：限时计划 + 确认串逐字回显 → 恢复前自动 rescue 备份（rescue 点有独立配额，不挤占手动恢复点上限）→ 持久操作日志 → 事后逐路径哈希/类型/权限验证；主恢复失败自动从备份回滚，崩溃后由操作日志驱动恢复，绝不留半恢复状态。
增量捕获：stat 指纹缓存 + 内容寻址去重——未变文件零重读；捕获到的超大/类型不支持/读取失败路径显式记录并在预览展示「恢复不会碰它们」，而不是静默失败；缓存被 GC/影子仓库丢失等意外波及后自动失效重读，不产生死引用。

二、文件审查（工具改动半边）

聊天轮尾卡片：每轮结束后展示「Edited N files · +M −K」、整轮撤销/重做开关、文件行（点击深链进侧边栏对应轮的差异）；每个文件可单独撤销/重做该文件在本轮的全部改动；文件行悬停即显完整 diff 浮层（宽度与卡片框对齐、视口内自动翻转）；
侧边栏「文件审查」tab（需要 dsh-better-sidebar，可选依赖）：逐轮分组清单 + 行级红绿 diff、tab 徽章计数、在编辑器中打开、复制差异、面板拖动调宽；
块级撤销/保留：diff 视图里每个改动块（hunk）可勾选——只撤销/重做选中的块，未勾选的原样保留；
每轮「快照恢复」：侧边栏每轮组头部可直接走影子快照把整个工作区恢复到该轮开始之前（复用会话回退的全部安全闸）；被运行中会话阻塞时自动静默重试；
文件级时间线：每个文件行可打开时间线，纵览本会话改动过它的每一轮；点击时间线或恢复对话框里的 +/− 统计直接跳到对应轮差异；
Code Mode（run_code）录制：嵌套派发的文件修改在宿主侧记录 before/after 并回放为 diff；录制持久化到磁盘，宿主重启后依然可审查、可撤销（损坏记录自愈）；
最终回复文件提及：注入系统提示引导模型用行内代码引用被修改文件，点击即可打开。

hunk 撤销的安全语义：逐 hunk 逆序文本回放 + 行锚点匹配 + 提交前字节级 CAS 复核 + 原子写 + 保留 CRLF 行尾风格；外部编辑造成的失配如实报告为「冲突」，绝不猜着改。

三、终端写盘审计（检查点对比）

终端命令的写盘没有工具结果可解析，插件用轮末归属补齐：第 N 轮的文件系统变更 = diff(第 N 轮轮起检查点, 第 N 轮轮末检查点)——协调器订阅宿主的 turn/end 会话事件，在轮结束那一刻冻结树状态，轮结束后的任何写盘都不会混入本轮。旧数据或轮末捕获失败时回退旧语义：diff(轮 N 轮起, 轮 N+1 轮起)。

三类变更全部可见可撤销：修改=红绿行级、新增=全绿、删除=全红；新增的撤销=删除文件，删除的撤销=写回旧内容（父目录按需重建）；
权限位透传：检查点记录的两侧权限位随变更下发，撤销/重做写回时原样恢复（不再一律 0644）；
纯 chmod 可见：内容未变、仅权限位变化的文件作为独立变更出现，撤销/重做即权限位翻转（内容漂移时按冲突拒动）；
空目录追踪：快照记录子树无内容的空目录；建/删空目录同样进轮变更并可撤销（mkdir/rmdir 互逆；目录非空时拒绝删除，绝不递归）；
轮中 live 条：当前轮进行中，输入卡上方实时列出本轮已落盘的变更（工具 + 终端），悬停同样弹 diff 浮层，轮结束自动切换为轮末卡片；
计数先行、全文按需：服务端随清单下发每个变更的 +/− 行数与工作区数据版本（rev），渲染零全文请求；完整内容只在悬停/展开/撤销时按需拉取并按轮记忆化；
删除安全网：任何走删除分支的 fs 撤销（新增撤销 / 删除重做）先把即将删除的内容落一份可找回副本，落盘失败则拒绝删除；
多会话归属过滤：轮配对与 live 清单都按检查点窗口归属过滤——只呈现本会话窗口的写入，其它会话的变更不会出现在本会话的卡片上，单文件撤销动不到别人的工作。轮末检查点把窗口终点从「下一轮轮起」收紧到「本轮轮末」，轮后写盘不再误挂；live 条只覆盖尚无轮末快照的最新轮（进行中的回合）。两条保守边界：同一路径被多会话触碰（多主）时从单会话视图剔除（引擎级整树恢复仍可还原）；会话在自己开轮捕获之前的写盘归属前一个窗口。

四、多会话并行：两种恢复语义

同一个项目目录跑多个会话时，侧边栏「文件审查」头部的开关随时切换语义（走 /shadow-rewind/gate，重启后回到 writeGate 配置初值）：

以当前为准（写入闸开启，默认）

同一时刻只允许一个会话写入，旁观者无关紧要、可被恢复波及：

所有权：最近一次回合开始的会话拥有工作区，即「当前」；切换到另一个会话发消息的瞬间所有权翻转——纯权限变更，无任何磁盘操作；
旁观者降级只读：非当前会话的文件写入、终端、run_code、子代理派生一律被拒绝并收到明确理由；读取、搜索、待办、提问照常放行；writeGateAllow 可扩充白名单；
子代理继承：当前会话的子代理经会话谱系继承写权利，自身回合开始不抢所有权；谱系环/断链安全回落为拒绝，所有者消失（会话关闭）则视为无主放行；
恢复放宽：只有「你正在恢复的会话」和「当前所有者」还在运行时才阻塞恢复。

对称（写入闸关闭）

两边的工作都要保全时用这个模式：

并行写入不限制（裁决关闭；所有权登记照常，随时可切回）；
恢复按归属勾选：预览里每条变更按检查点窗口标注归属——本会话 / 其它会话 / 双方都改过 / 来源不明——默认只勾选本会话路径，也可手动勾选任意路径，「全部选中」即整树恢复；
运行中的会话阻塞恢复：并行写入合法，恢复只在工作区空闲时执行；
归因来自影子仓库里所有会话的检查点时间线（检查点在回合开始捕获 → 窗口 [S_j, S_{j+1}) 的写者就是 S_j 的会话）。标签是建议而非裁决——勾选权在用户，错了最多误导、不破坏数据。

边界：闸与归因只作用于本插件可见的 DSH 工具调用与影子快照——外部编辑器、IDE 与系统进程不受限。

安装

pnpm install
pnpm run check          # 构建 + 全量测试（含混沌套件；jj 可用时自动加测影子后端）
dsh plugin --profile web add dsh-shadow-rewind

依赖：Node ≥ 22.19；jj CLI 可选——缺失时自动降级 blob 存储。频繁迭代可跳过发布链路：pnpm apply（构建 + 把 lib 与补丁文件直灌 profile 安装目录，依赖仍从 profile 顶层解析，与正式安装同语义），重启 DSH 生效；目标目录可用 DSH_PROFILE_DIR 覆盖。

配置（cordis.patch.yml）

- id: ui-deliverables
  disabled: true                   # 内置产物卡片由本插件的轮尾卡片接管

- insert:
    - id: shadow-rewind
      name: 'dsh-shadow-rewind'
      config:
        turnCheckpointMode: jj          # jj（默认）/ legacy / off
        excludePatterns:                # 工作区相对 glob；字面路径=任意层级同名目录
          - .git
          - .jj
          - node_modules
          - dist
        maxFileBytes: 16777216          # 超限文件跳过并显式记录
        maxFiles: 20000
        maxSnapshotBytes: 536870912
        maxTurnCheckpointsPerSession: 30
        maxRestorePoints: 50
        planTtlMs: 900000
        turnCheckpointTimeoutMs: 5000
        turnCheckpointMaxNewBytes: 33554432
        turnCheckpointTrust: fast       # fast=stat 缓存增量；strict=全量重读
        writeGate: true                 # true=以当前为准（默认），false=对称；侧边栏可运行时切换
        writeGateAllow: []              # 写入闸在只读白名单外额外放行的工具名
        # 命令窗口（写盘归因：哪条命令、哪个会话在何时写盘；窗口持久化到存储目录）
        commandWindowFlushMs: 400           # 落盘防抖（毫秒）
        commandWindowRetentionMs: 21600000  # 窗口保留期（毫秒，默认 6h）；超长回溯可任意调大，磁盘占用极小
        commandWindowMaxPerWorkspace: 2000  # 每工作区窗口条数上限（修剪保留最新）
        commandWindowDetailBytes: 2048      # 每条窗口记录的工具参数（如命令文本）字节上限；0=不记录内容

HTTP 端点均为同源、仅接受回环请求：

端点	用途
`GET/POST /shadow-rewind`	消息回退预览（`?sessionId&messageSeq`）、按轮快照预览（`?sessionId&turn`）、`paths=[...]` 铸造勾选子集计划、`POST` 计划 id + 确认串执行恢复
`GET /shadow-rewind/fs-changes?sessionId`	批量返回该会话所有轮次的终端写盘变更（行数、权限位、目录标记、`rev` 数据版本；归属过滤后）
`GET /shadow-rewind/file?checkpointId&path&cwd`	按检查点读取文件内容（`checkpointId=live` 读当前磁盘，工作区围栏）
`GET/POST /shadow-rewind/gate`	查询 / 翻转恢复语义模式

浏览器半边随包分发；宿主服务以 ctx.shadowRewind（cordis）与 Typert fileReview 命名空间暴露。

测试

pnpm test 使用真实临时目录跑完整链路（62 用例）：

引擎：修改/删除/新增恢复、空目录条目恢复、排除规则、超大文件跳过、计划过期拒绝、删除确认闸、无变更短路、stat 缓存增量、死缓存自愈、影子仓库丢失自愈；jj 可用时双后端全测；
文件审查：hunk 子集撤销、Code Mode 录制持久化往返与损坏自愈、终端写盘撤销语义（新增=删除 / 删除=写回 / 纯权限位翻转 / 空目录互逆 / 非空拒删）、删除前 rescue 副本、CRLF 不误报；
写入闸：所有权翻转、按工具拒绝/放行、子代理谱系继承、环与断链兜底、恢复占用分诊、运行时开关；
对称模式：窗口归因四类标签、勾选式子集恢复、未知路径拒绝；
终端写盘端点：轮次配对行数与 rev、权限位透传、轮配对与 live-tail 的跨会话归属剔除；
混沌套件（固定种子可复现）：双会话交错的归属分离与整树恢复收敛、检查点淘汰+GC 压力下存活检查点全部可恢复、双会话随机操作/恢复/淘汰全搅拌（每次恢复后与检查点零差异）、轮末检查点三例（轮末冻结树隔离轮后写盘 / 协调器经 turn/end 事件捕获 / 轮起轮末淘汰按相位互不挤占）；7 会话（A-G）不对称轮数（5/2/7/3/6/1/4）+ 两种相反完成顺序下「每会话每轮变更被精确识别」的逐条断言。

边界（当前版本）

恢复的是文件内容 + 权限位 + 空目录：不回滚任何 VCS 历史（工作区 git 的提交不受影响）；非空目录不单独立条目（由子条目在恢复时隐式重建）；符号链接仅在 POSIX 环境验证；
排除清单内的写入完全不可见（.git、node_modules、构建产物等 18 项默认排除）；超过大小/数量上限的路径显式跳过、不可恢复；
终端写盘归属是窗口语义：轮末检查点之后的轮间手动/外部修改不属于任何轮（不再误挂给前一轮）；同一路径被多会话触碰时从单会话视图保守剔除；轮内创建又删除的临时文件两端检查点都不含、不可见；
Windows 上权限位语义受限（只读位有效）；
跨机共享存储未设计（锁判活按单机 pid）；
Code Mode 录制按结果形状 {path, before, after} 识别嵌套修改，返回该形状的非文件工具会被误录。

致谢

本插件的功能设计借鉴了两个优秀的同类插件：

dsh-file-review-tab（Lzh3070）——「聊天轮尾审查卡片 + 侧边栏文件审查」的产品形态，以及 Code Mode（run_code）文件修改录制并回放为 diff 的思路；本插件在此基础上补齐了 hunk 级撤销 / 重做与终端写盘审计。
dsh-turn-rewind（Anionex）——「按消息锚定恢复工作区、恢复后可从该请求重新出发」的会话回退语义；本插件改用影子 jj 仓库实现整树快照，并以检查点窗口归属扩展出终端写盘审计。

感谢原作者们的开源分享。

License

MIT

Star History

Star History Chart

⭐ 如果影子快照帮你救回过一次改动，就给它一个 star 吧！

README

dsh-shadow-rewind

DeepSeek Harness 的会话级文件快照与回退插件。
每一轮自动影子快照 —— diff 审查、块级撤销、终端写盘审计、整树恢复。

功能全景 • 安装 • 配置 • 测试 • 已知边界

⭐ GitHub 仓库：DreamsTOF/dsh-shadow-rewind —— 觉得有用就点个 Star；问题与需求请提 Issue

every turn → shadow snapshot → diff · review · restore

针对 DeepSeek Harness 的会话级文件快照与回退 + AI 改动文件审查 + 终端写盘审计插件。

功能全景

不管文件是被 AI 的 write/edit 工具、终端命令（PowerShell / bash / git）、还是外部进程修改的——每轮的全部文件变更都可见、可显示 diff、可撤销：

面	机制	粒度	入口
会话回退	影子 jj 仓库整树快照	整个工作区（内容 + 权限位 + 空目录）	每条直发用户消息旁的「恢复到发送之前」
文件审查	工具 hunk 文本重放	改动块（hunk）/ 文件 / 轮	聊天轮尾卡片 + 侧边栏「文件审查」tab
终端写盘审计	检查点窗口归属对比	文件 / 空目录 / 权限位	轮尾卡片 + 轮中 live 条 + 侧边栏
写入闸	所有权登记 + 工具裁决	会话 × 工具	自动；侧边栏运行时开关

你的项目目录（随便怎么折腾）          插件存储根（$DSH_HOME/shadow-rewind/v1）
├── src/...                          └── workspaces/<key>/
├── .git/   ← 插件从不读写               ├── manifests/           恢复点清单
└── ...                                  ├── blobs/               内容寻址存储（legacy 后端）
                                         ├── operations/          恢复操作日志（崩溃恢复依据）
                                         ├── turn-outcomes/       检查点跳过记录
                                         ├── file-review/recorded/ Code Mode 录制（持久）
                                         ├── file-review/rescue/   fs 删除前的找回副本
                                         └── shadow-repos/<key>/  影子 jj 仓库（快照字节）

一、会话回退（影子快照）

自动检查点：每轮对话在 Agent 第一步之前自动快照轮起树状态，轮结束（turn/end 事件）时再快照轮末树状态——每个检查点是一条显式记录（轮起/轮末相位各自计配额）。默认走隐藏 jj 仓库；宿主机没有 jj CLI 时自动降级为内置内容寻址 blob 存储（启动日志提示），功能不中断；off 可整体关闭。
回退入口：每条直发用户消息下出现「恢复到发送之前」；对话框预览将恢复的文件清单与快照时显式跳过的路径，并提供两种落点：
- 恢复文件并从这里继续 —— 恢复文件后分叉新会话（原会话保留）；
- 只恢复文件 —— 当前对话不动。
恢复安全闸（全部强制，任何一步失败立即 fail-closed）：限时计划 + 确认串逐字回显 → 恢复前自动 rescue 备份（rescue 点有独立配额，不挤占手动恢复点上限）→ 持久操作日志 → 事后逐路径哈希/类型/权限验证；主恢复失败自动从备份回滚，崩溃后由操作日志驱动恢复，绝不留半恢复状态。
增量捕获：stat 指纹缓存 + 内容寻址去重——未变文件零重读；捕获到的超大/类型不支持/读取失败路径显式记录并在预览展示「恢复不会碰它们」，而不是静默失败；缓存被 GC/影子仓库丢失等意外波及后自动失效重读，不产生死引用。

二、文件审查（工具改动半边）

聊天轮尾卡片：每轮结束后展示「Edited N files · +M −K」、整轮撤销/重做开关、文件行（点击深链进侧边栏对应轮的差异）；每个文件可单独撤销/重做该文件在本轮的全部改动；文件行悬停即显完整 diff 浮层（宽度与卡片框对齐、视口内自动翻转）；
侧边栏「文件审查」tab（需要 dsh-better-sidebar，可选依赖）：逐轮分组清单 + 行级红绿 diff、tab 徽章计数、在编辑器中打开、复制差异、面板拖动调宽；
块级撤销/保留：diff 视图里每个改动块（hunk）可勾选——只撤销/重做选中的块，未勾选的原样保留；
每轮「快照恢复」：侧边栏每轮组头部可直接走影子快照把整个工作区恢复到该轮开始之前（复用会话回退的全部安全闸）；被运行中会话阻塞时自动静默重试；
文件级时间线：每个文件行可打开时间线，纵览本会话改动过它的每一轮；点击时间线或恢复对话框里的 +/− 统计直接跳到对应轮差异；
Code Mode（run_code）录制：嵌套派发的文件修改在宿主侧记录 before/after 并回放为 diff；录制持久化到磁盘，宿主重启后依然可审查、可撤销（损坏记录自愈）；
最终回复文件提及：注入系统提示引导模型用行内代码引用被修改文件，点击即可打开。

三、终端写盘审计（检查点对比）

三类变更全部可见可撤销：修改=红绿行级、新增=全绿、删除=全红；新增的撤销=删除文件，删除的撤销=写回旧内容（父目录按需重建）；
权限位透传：检查点记录的两侧权限位随变更下发，撤销/重做写回时原样恢复（不再一律 0644）；
纯 chmod 可见：内容未变、仅权限位变化的文件作为独立变更出现，撤销/重做即权限位翻转（内容漂移时按冲突拒动）；
空目录追踪：快照记录子树无内容的空目录；建/删空目录同样进轮变更并可撤销（mkdir/rmdir 互逆；目录非空时拒绝删除，绝不递归）；
轮中 live 条：当前轮进行中，输入卡上方实时列出本轮已落盘的变更（工具 + 终端），悬停同样弹 diff 浮层，轮结束自动切换为轮末卡片；
计数先行、全文按需：服务端随清单下发每个变更的 +/− 行数与工作区数据版本（rev），渲染零全文请求；完整内容只在悬停/展开/撤销时按需拉取并按轮记忆化；
删除安全网：任何走删除分支的 fs 撤销（新增撤销 / 删除重做）先把即将删除的内容落一份可找回副本，落盘失败则拒绝删除；
多会话归属过滤：轮配对与 live 清单都按检查点窗口归属过滤——只呈现本会话窗口的写入，其它会话的变更不会出现在本会话的卡片上，单文件撤销动不到别人的工作。轮末检查点把窗口终点从「下一轮轮起」收紧到「本轮轮末」，轮后写盘不再误挂；live 条只覆盖尚无轮末快照的最新轮（进行中的回合）。两条保守边界：同一路径被多会话触碰（多主）时从单会话视图剔除（引擎级整树恢复仍可还原）；会话在自己开轮捕获之前的写盘归属前一个窗口。

四、多会话并行：两种恢复语义

同一个项目目录跑多个会话时，侧边栏「文件审查」头部的开关随时切换语义（走 /shadow-rewind/gate，重启后回到 writeGate 配置初值）：

以当前为准（写入闸开启，默认）

同一时刻只允许一个会话写入，旁观者无关紧要、可被恢复波及：

所有权：最近一次回合开始的会话拥有工作区，即「当前」；切换到另一个会话发消息的瞬间所有权翻转——纯权限变更，无任何磁盘操作；
旁观者降级只读：非当前会话的文件写入、终端、run_code、子代理派生一律被拒绝并收到明确理由；读取、搜索、待办、提问照常放行；writeGateAllow 可扩充白名单；
子代理继承：当前会话的子代理经会话谱系继承写权利，自身回合开始不抢所有权；谱系环/断链安全回落为拒绝，所有者消失（会话关闭）则视为无主放行；
恢复放宽：只有「你正在恢复的会话」和「当前所有者」还在运行时才阻塞恢复。

对称（写入闸关闭）

两边的工作都要保全时用这个模式：

并行写入不限制（裁决关闭；所有权登记照常，随时可切回）；
恢复按归属勾选：预览里每条变更按检查点窗口标注归属——本会话 / 其它会话 / 双方都改过 / 来源不明——默认只勾选本会话路径，也可手动勾选任意路径，「全部选中」即整树恢复；
运行中的会话阻塞恢复：并行写入合法，恢复只在工作区空闲时执行；
归因来自影子仓库里所有会话的检查点时间线（检查点在回合开始捕获 → 窗口 [S_j, S_{j+1}) 的写者就是 S_j 的会话）。标签是建议而非裁决——勾选权在用户，错了最多误导、不破坏数据。

边界：闸与归因只作用于本插件可见的 DSH 工具调用与影子快照——外部编辑器、IDE 与系统进程不受限。

安装

pnpm install
pnpm run check          # 构建 + 全量测试（含混沌套件；jj 可用时自动加测影子后端）
dsh plugin --profile web add dsh-shadow-rewind

配置（cordis.patch.yml）

- id: ui-deliverables
  disabled: true                   # 内置产物卡片由本插件的轮尾卡片接管

- insert:
    - id: shadow-rewind
      name: 'dsh-shadow-rewind'
      config:
        turnCheckpointMode: jj          # jj（默认）/ legacy / off
        excludePatterns:                # 工作区相对 glob；字面路径=任意层级同名目录
          - .git
          - .jj
          - node_modules
          - dist
        maxFileBytes: 16777216          # 超限文件跳过并显式记录
        maxFiles: 20000
        maxSnapshotBytes: 536870912
        maxTurnCheckpointsPerSession: 30
        maxRestorePoints: 50
        planTtlMs: 900000
        turnCheckpointTimeoutMs: 5000
        turnCheckpointMaxNewBytes: 33554432
        turnCheckpointTrust: fast       # fast=stat 缓存增量；strict=全量重读
        writeGate: true                 # true=以当前为准（默认），false=对称；侧边栏可运行时切换
        writeGateAllow: []              # 写入闸在只读白名单外额外放行的工具名
        # 命令窗口（写盘归因：哪条命令、哪个会话在何时写盘；窗口持久化到存储目录）
        commandWindowFlushMs: 400           # 落盘防抖（毫秒）
        commandWindowRetentionMs: 21600000  # 窗口保留期（毫秒，默认 6h）；超长回溯可任意调大，磁盘占用极小
        commandWindowMaxPerWorkspace: 2000  # 每工作区窗口条数上限（修剪保留最新）
        commandWindowDetailBytes: 2048      # 每条窗口记录的工具参数（如命令文本）字节上限；0=不记录内容

HTTP 端点均为同源、仅接受回环请求：

端点	用途
`GET/POST /shadow-rewind`	消息回退预览（`?sessionId&messageSeq`）、按轮快照预览（`?sessionId&turn`）、`paths=[...]` 铸造勾选子集计划、`POST` 计划 id + 确认串执行恢复
`GET /shadow-rewind/fs-changes?sessionId`	批量返回该会话所有轮次的终端写盘变更（行数、权限位、目录标记、`rev` 数据版本；归属过滤后）
`GET /shadow-rewind/file?checkpointId&path&cwd`	按检查点读取文件内容（`checkpointId=live` 读当前磁盘，工作区围栏）
`GET/POST /shadow-rewind/gate`	查询 / 翻转恢复语义模式

浏览器半边随包分发；宿主服务以 ctx.shadowRewind（cordis）与 Typert fileReview 命名空间暴露。

测试

pnpm test 使用真实临时目录跑完整链路（62 用例）：

引擎：修改/删除/新增恢复、空目录条目恢复、排除规则、超大文件跳过、计划过期拒绝、删除确认闸、无变更短路、stat 缓存增量、死缓存自愈、影子仓库丢失自愈；jj 可用时双后端全测；
文件审查：hunk 子集撤销、Code Mode 录制持久化往返与损坏自愈、终端写盘撤销语义（新增=删除 / 删除=写回 / 纯权限位翻转 / 空目录互逆 / 非空拒删）、删除前 rescue 副本、CRLF 不误报；
写入闸：所有权翻转、按工具拒绝/放行、子代理谱系继承、环与断链兜底、恢复占用分诊、运行时开关；
对称模式：窗口归因四类标签、勾选式子集恢复、未知路径拒绝；
终端写盘端点：轮次配对行数与 rev、权限位透传、轮配对与 live-tail 的跨会话归属剔除；
混沌套件（固定种子可复现）：双会话交错的归属分离与整树恢复收敛、检查点淘汰+GC 压力下存活检查点全部可恢复、双会话随机操作/恢复/淘汰全搅拌（每次恢复后与检查点零差异）、轮末检查点三例（轮末冻结树隔离轮后写盘 / 协调器经 turn/end 事件捕获 / 轮起轮末淘汰按相位互不挤占）；7 会话（A-G）不对称轮数（5/2/7/3/6/1/4）+ 两种相反完成顺序下「每会话每轮变更被精确识别」的逐条断言。

边界（当前版本）

恢复的是文件内容 + 权限位 + 空目录：不回滚任何 VCS 历史（工作区 git 的提交不受影响）；非空目录不单独立条目（由子条目在恢复时隐式重建）；符号链接仅在 POSIX 环境验证；
排除清单内的写入完全不可见（.git、node_modules、构建产物等 18 项默认排除）；超过大小/数量上限的路径显式跳过、不可恢复；
终端写盘归属是窗口语义：轮末检查点之后的轮间手动/外部修改不属于任何轮（不再误挂给前一轮）；同一路径被多会话触碰时从单会话视图保守剔除；轮内创建又删除的临时文件两端检查点都不含、不可见；
Windows 上权限位语义受限（只读位有效）；
跨机共享存储未设计（锁判活按单机 pid）；
Code Mode 录制按结果形状 {path, before, after} 识别嵌套修改，返回该形状的非文件工具会被误录。

致谢

本插件的功能设计借鉴了两个优秀的同类插件：

dsh-file-review-tab（Lzh3070）——「聊天轮尾审查卡片 + 侧边栏文件审查」的产品形态，以及 Code Mode（run_code）文件修改录制并回放为 diff 的思路；本插件在此基础上补齐了 hunk 级撤销 / 重做与终端写盘审计。
dsh-turn-rewind（Anionex）——「按消息锚定恢复工作区、恢复后可从该请求重新出发」的会话回退语义；本插件改用影子 jj 仓库实现整树快照，并以检查点窗口归属扩展出终端写盘审计。

感谢原作者们的开源分享。

License

MIT

Star History

Star History Chart

⭐ 如果影子快照帮你救回过一次改动，就给它一个 star 吧！

Shadow Rewind

兼容性与来源证明

版本

Shadow Rewind

README

dsh-shadow-rewind

功能全景

一、会话回退（影子快照）

二、文件审查（工具改动半边）

三、终端写盘审计（检查点对比）

四、多会话并行：两种恢复语义

以当前为准（写入闸开启，默认）

对称（写入闸关闭）

安装

配置（cordis.patch.yml）

测试

边界（当前版本）

致谢

License

Star History

兼容性与来源证明

版本

相关插件

相关插件

相关插件

README

dsh-shadow-rewind

功能全景

一、会话回退（影子快照）

二、文件审查（工具改动半边）

三、终端写盘审计（检查点对比）

四、多会话并行：两种恢复语义

以当前为准（写入闸开启，默认）

对称（写入闸关闭）

安装

配置（cordis.patch.yml）

测试

边界（当前版本）

致谢

License

Star History