dsh-shadow-rewind

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

[图片: dsh-shadow-rewind]

dsh-shadow-rewind

  DeepSeek Harness 的会话级文件快照与回退插件。

  每一轮自动影子快照 —— diff 审查、块级撤销、终端写盘审计、整树恢复。

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

  [图片: Version]

  [图片: MIT License]

  [图片: DeepSeek Harness Plugin]

  [图片: npm version]

  [图片: npm downloads]

  [图片: GitHub Stars]

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

  [图片: every turn → shadow snapshot → diff · review · restore]

---

针对 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的**会话级文件快照与回退 + AI 改动文件审查 + 终端写盘审计**插件。

## 功能全景

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

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

**时间线审计（浮层面板 + 轨迹重放）**：会话头部的「时间线」面板把 turn 快照检查点（轮起/轮末、意图标签、degraded 降级标注）与会话轨迹节点（`tool/call` 边界）放在同一条时间轴上，点选两个节点即得区间 diff——快照走逐文件对比，轨迹从会话事件重放 `write`/`edit`/`str_replace_editor` 内容（**历史会话可用**，不依赖快照存活；被配额淘汰的检查点也能由轨迹兜底回答「那几轮改了什么」）。重放只覆盖内容型工具，终端/外部写盘由检查点对比补位——快照优先、轨迹兜底，盲区以 notes 诚实标注。恢复预览逐文件展开「当前 → 快照」方向行级 diff；恢复完成后可一键**撤销最近一次恢复**（进程内单次 undo，逐路径 CAS：被后续修改的路径跳过并如实报告，恢复新建文件的撤销即删除）。

**显示增强**：diff 渲染双层精度——红绿整行之上的**行内字符级下划线高亮**（替换对的字符级 diff，自 dsh-edit-diff 移植内核）+ **修改点跳转**（↑/↓ 导航、打开自动定位首个变更块）+ 大 diff 自动折叠防线；轮尾卡片带增/删**比例色条**与**目录折叠树**（单链目录合并、聚合计数）；时间线面板提供**横向拖选条带**（快照轨 + 调用三泳道、turn 刻度、拖选 ≥3px 提交选区对）、起/终下拉与点选双向同步、`(head)` 标记与**上次查看位置记忆**（localStorage，节点失配自动丢弃）。

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

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

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

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

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

- **聊天轮尾卡片**：每轮结束后展示「Edited N files · +M −K」、整轮撤销/重做开关、文件行（点击深链进侧边栏对应轮的差异）；**每个文件可单独撤销/重做该文件在本轮的全部改动**；文件行**悬停即显完整 diff 浮层**（宽度与卡片框对齐、视口内自动翻转）；
- **侧边栏「文件审查」tab**（需要 [dsh-better-sidebar](https://github.com/nicepkg/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 与系统进程不受限。

## 安装

```sh
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）

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

- insert:
    - id: shadow-rewind
      name: "dsh-shadow-rewind"
      config:
        turnCheckpointMode: jj # jj（默认）/ sqlite / 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`       | 批量返回该会话所有轮次的终端写盘变更（行数、权限位、目录标记、意图摘要、degraded 标注、`rev` 数据版本；归属过滤后）                         |
| `GET /shadow-rewind/trace?sessionId[&from&to]`  | 时间线（轨迹节点 + 检查点摘要）与区间 diff：`from/to` 为 `trace:序号`（内容重放）或 `rp_…`（快照对比），二者不可混用                        |
| `GET /shadow-rewind/file?checkpointId&path&cwd` | 按检查点读取文件内容（`checkpointId=live` 读当前磁盘，工作区围栏）                                                                          |
| `POST /shadow-rewind/restore-undo`              | 撤销该工作区最近一次恢复（进程内单次 undo；body `{sessionId}` 或 `{cwd}`）                                                                  |
| `GET/POST /shadow-rewind/gate`                  | 查询 / 翻转恢复语义模式                                                                                                                     |

### 命令面（headless）

宿主命令系统可用时自动注册两条命令（脚本 / CLI 可直接消费，输出为纯文本）：

- `/shadow-diff [起] [终]` — 两个时间节点的文件变更摘要。参数：轮号（如 `3`，单轮=轮起→轮末配对）、检查点 id（`rp_…`）、轨迹节点（`trace:序号`，内容重放区间）；快照与轨迹不可混用。
- `/shadow-undo` — 撤销该工作区最近一次文件恢复（同 restore-undo 端点）。

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

## 测试

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

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

## 边界（当前版本）

- 恢复的是**文件内容 + 权限位 + 空目录**：不回滚任何 VCS 历史（工作区 git 的提交不受影响）；非空目录不单独立条目（由子条目在恢复时隐式重建）；符号链接仅在 POSIX 环境验证；
- **恢复撤销是进程内单次 undo**：重启即失效（持久兜底是恢复时自动创建的 rescue 备份点）；只保留最近一次，再次恢复会替换；
- **轨迹重放只覆盖会话内的内容型工具**（`write`/`edit`/`str_replace_editor`）：终端命令与外部进程的写盘不可见（由检查点对比补位）；早于会话首次写入的文件基线不可知（区间 diff 中表现为新增，notes 注明）；
- **排除清单内的写入完全不可见**（`.git`、`node_modules`、构建产物等 18 项默认排除）；超过大小/数量上限的路径显式跳过、不可恢复；
- 终端写盘归属是窗口语义：轮末检查点之后的轮间手动/外部修改不属于任何轮（不再误挂给前一轮）；同一路径被多会话触碰时从单会话视图保守剔除；轮内创建又删除的临时文件两端检查点都不含、不可见；
- Windows 上权限位语义受限（只读位有效）；
- 跨机共享存储未设计（锁判活按单机 pid）；
- Code Mode 录制按结果形状 `{path, before, after}` 识别嵌套修改，返回该形状的非文件工具会被误录。

## 致谢

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

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

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

## License

MIT

---

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=DreamsTOF/dsh-shadow-rewind&type=Date)](https://star-history.com/#DreamsTOF/dsh-shadow-rewind&Date)

---

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