dsh-undo-plugin

一句话定位

这是 DSH 的撤销/回退系统，会在配置或插件代码改动时自动存档，覆盖后能一键还原——包括「改错了某个配置」「插件代码改坏」「DSH 起不来」三种典型事故。

核心能力

• 自动存档配置与插件代码：受监控的配置文件或插件代码变更后经防抖自动生成快照，无需手动操作
• 三入口一键撤销/恢复/回退：WebUI 头部按钮、全局快捷键（Ctrl+Alt+Z / Ctrl+Alt+Y）、对 AI 说「撤销上一步」、CLI/离线工具全部可用
• 插件代码也能回滚：连改坏插件源码的事故（如某插件抛出 yield* is not async iterable）都能一键还原，无需重装
• 密钥脱敏与本机还原：.env / .credentials.yaml 进快照自动替换值为占位符，真实值存本机 vault；导出 ZIP 不会泄露密钥；本机回滚时仍能完整还原
• 一键安全模式：DSH 起不来时关闭所有用户插件只留撤销插件，重启保证能起来；面板和 CLI 都能切
• 崩溃归因：上次异常退出会在 WebUI / GUI 横幅里直接给出「最后正常快照」id 与一键回退按钮，不用自己猜回退到哪
• 跨机迁移：快照可导出/导入 ZIP；恢复前自动预检缺失插件并明确提示「可能起不来」
• 局外急救工具：插件目录里的 PowerShell CLI + GUI 窗口，DSH 完全挂了也能用

技术实现

• 语言: JavaScript (ESM, Node 20+) + 客户端 React (打包进 client.js) + 离线 PowerShell
• 关键依赖: @deepseek-ai/dsh-tools（提供 defineTool，通过 createRequire 多锚点解析）、node:fs（快照与监听）、node:child_process（pnpm 依赖同步、PowerShell 文件选择器、ZIP 导出）、react/react/jsx-runtime（WebUI 头部按钮 + 面板）
• 架构模式: Cordis 双面插件 — host 端注册 8 个 defineTool 与 /api/undo/* REST 路由并启动 fs.watch 防抖存档；client 端注入会话头部按钮槽、设置项槽与全局键盘事件；离线 PowerShell 工具与 Node 共享 lib/spec.json 与同一快照仓库
• 入口文件: lib/index.js（host apply / 工具注册 / REST）、lib/client.js（React 组件与槽注入）、cordis.patch.yml（插件挂载声明）

适用场景

• 用户改了插件代码或配置后担心改坏想有后悔药 — 默认开自动存档，撤销就是一句话的事
• 安装/更新/卸载插件后 DSH 启动报错或行为异常 — 用快照回退到改动前即可，不必手工找配置文件回滚
• 装了某个插件导致 DSH 完全起不来 — 用 GUI/CLI 工具进安全模式保证能启动，再决定恢复或排查

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:lire1131/dsh-undo-plugin

配置项

配置在 WebUI 设置页「快照」分区修改，或直接编辑 $DSH_HOME/undo/settings.json；也支持在 cordis.patch.yml 的 config 块里以编程方式注入。

常见问题

Q: 装完插件没看到头部按钮？

A: 装完需要重启 DSH 才进入稳态。默认装到 web profile，请确认命令行带的是 dsh plugin --profile web add ...。多 profile 机器上若用其他 profile，需要把 --profile 改成对应名字，否则插件会写到 web profile 的快照库。

Q: 撤销会把当前改动丢了吗？

A: 不会。每次撤销/回退前都会先把当前状态保存成「后悔档」（pre-restore），所以即便撤销错了还可以用 redo 恢复回去；只有 redo 被新的真实改动消化后才会被自动清理。

Q: 快照会包含密钥吗？导出 ZIP 安全吗？

A: 默认敏感模式是「脱敏」：.env / .credentials.yaml 进快照时值被替换成占位符，真实值存本机 vault（仅本机回滚时还原）。导出 ZIP 在脱敏模式下不含真实密钥；如果切到「明文」模式或导的是旧快照，导出文件会带真值并打显眼的告警。

Q: DSH 完全起不来了还能用吗？

A: 能。安装目录的 tools\ 下有离线 CLI（dsh-undo-savepoint.ps1）和 GUI 窗口（dsh-undo-savepoint-gui.ps1），即便 DSH 进程不在也能用。最极端情况下可先开「安全模式」只保留撤销插件，再重启 DSH 一定起得来。

Q: 跨机迁移快照要做什么？

A: 在 A 机的快照面板点「导出」拿到 ZIP；先在 B 机装齐 A 用过的插件，再导入 ZIP。恢复时插件会做跨机预检，缺插件会明告，未安装的插件目录不会被写入。

Q: 撤销涉及插件代码改动要不要重启？

A: 需要。撤销/回退触及 cordis.patch.yml、profile/package.json 或插件代码时，报告里会出现「重启 DSH 后生效」的提示；纯 .env 或配置值变更一般不需要重启。

Q: 自动快照会不会无限堆积？

A: 不会。设置里可配自动档保留数量（默认 20 份）和后悔档保留数量（默认 10 份），超过上限会自动清理；手动保存的快照永不自动清除。

Q: 安装命令的 #master 要不要带？

A: 仓库当前安装命令是 dsh plugin --profile web add github:lire1131/dsh-undo-plugin，DSH 会拉默认分支。若你想锁版本，可显式加 #master 或 tag。

上手难度

入门 — 装上即用，默认配置已覆盖常见场景；遇到 DSH 起不来或想精调保留数量时再进设置页或离线工具即可。

已知问题与限制

• 单个快照引用体积上限 5MB；超出时插件代码树只记录清单 + 打 truncated 标记，不丢任何数据（手动快照/导出仍可兜底）— lib/index.js:170 / lib/index.js:392-394
• 撤销/回退涉及 package.json / pnpm-lock.yaml 时默认只报告 node_modules 不同步，不会自动跑 pnpm install；需显式传 sync_deps: true（CLI 用 -SyncDeps），且依赖同步失败不会回滚已还原的配置文件 — lib/index.js:932-959 / CHANGELOG.md:33
• 离线 CLI/GUI 工具主要面向 Windows PowerShell 5.1/7；macOS/Linux 上 host 部分可用，但一键桌面快捷方式与 GUI 窗口需手动改用本地终端 — .github/workflows/ci.yml:7-9 / CHANGELOG.md:45
• 跨机恢复时若目标快照引用了本机未装的插件，会出现 MODULE_NOT_FOUND 启动报错；插件会做预检提示但不会自动跳过缺失挂载 — docs/migration.md:23-49 / lib/index.js:560-589
• Windows 上 fs.watch 在被监听目录被删除/重命名时会异步抛 EPERM；插件已挂 error 处理器避免炸进程，但该 watcher 会被静默移除 — lib/index.js:2093-2101
• DSH 服务 API 调用逐项包 try/catch 降级（rc8 兼容盖子）：单个服务失败不会中断 apply，但对应能力会缺失 — lib/index.js:1700-1714

中文 | English | 更新日志

DSH 崩溃急救插件：配置与插件代码一键回滚、快照密钥脱敏、一键安全模式，DSH 起不来时也能用（离线 CLI/GUI）。

还在为 DSH 崩溃而苦恼?还在担心小改动会带来大灾难?这款工具能帮到你!

为 DeepSeek Harness (DSH) 打造的撤销/回退系统:装插件、换皮肤、改设置,自动保存即存档;手动保存随时存档;一键撤销/恢复/回退到任意版本,DSH 启动不了时还有局外工具(GUI 窗口 + 命令行)兜底。

预览

功能一览

基础能力（键盘快捷键、对话指令、自动清理、双模式保存、可配置参数等）详见下文与 更新日志。

崩溃急救速查（按场景选工具）

快照内容与存储

快照对象是 DSH 的启动关键配置:cordis.patch.yml、package.json、cordis.yml、pnpm-workspace.yaml、pnpm-lock.yaml(profile 下)+ cordis.patch.yml、settings.yaml、.env、.credentials.yaml($DSH_HOME 下,默认 ~/.dsh)。 恢复涉及 package.json / pnpm-lock.yaml 时,默认只报告 node_modules 可能不同步;需要真正重建依赖时加 -SyncDeps(离线 CLI)、sync_deps: true(对话工具)或 syncDeps: true(REST),插件会执行 pnpm install --frozen-lockfile(无 lockfile 时普通 pnpm install)。安装失败不影响已经还原的配置文件。

⚠️ 快照含 .env 等配置副本,可能含密钥——不要外传。

v0.3.7 体积约束：单个快照引用体积 ≤5MB（manifest 记录 totalBytes，undo_list 展示）。插件代码树超限时只记清单 + 标记 [truncated] 告警，不丢任何数据，可手动快照/导出兜底；无外部插件时快照仅配置文件（KB 级）。

多 profile 支持(v0.3.3)

插件从启动参数自动识别当前 profile(dsh --profile mine / --profile=mine;dsh web 回退为 web),并按当前 profile 工作:

• 配置目录:默认 $DSH_HOME/profiles/<当前 profile>(DSH_HOME 默认 ~/.dsh;此前硬编码 web——非 web profile 下快照读错、监听错、恢复写错位置);
• 快照仓库:默认 <快照根>/<当前 profile>/{auto,manual}(按 profile 隔离);作用域目录不存在而旧版平铺目录存在时自动回退平铺,旧快照不会"隐身";
• 归属标识:快照 manifest 记录 profile 字段,undo_list 显示当前 profile。

离线 CLI/GUI 看不到启动参数,通过环境变量 DSH_UNDO_PROFILE 或 settings 里的 profileName 指定(默认 web)。

显式配置优先级不变:profileDir / manualDir / autoDir / profileName(config 或 settings)始终生效。

自定义家目录支持(v0.3.5,issue #6)

DSH 数据家目录的解析与官方启动器(@deepseek-ai/dsh-home-paths)完全一致:DSH_HOME 环境变量优先(空白视为未设置,支持 ~ / ~/ / ~\ 前缀),否则回退 <用户家目录>\.dsh。设置文件($DSH_HOME\undo\settings.json)、默认快照根($DSH_HOME\undo-snapshots)、profile 目录($DSH_HOME\profiles\<profile>)、home 根、插件发现路径全部基于它——第三方客户端(自定义 DSH_HOME)不再出现"设置写到 ~/.dsh、DSH 实际用 $DSH_HOME"的两套家分裂,重启后自定义目录稳定保留。

显式覆盖仍然保留:DSH_UNDO_SETTINGS / DSH_UNDO_ROOT / DSH_UNDO_EXPORT(环境变量)与 config 里的 homeDir / profileDir / manualDir / autoDir 优先级最高。

仓库标签 (Topics)

方便在 GitHub 搜索与 Explore 中被发现,仓库已设置以下 topics:

deepseek-harness · dsh · dsh-plugin · undo · rollback · snapshot · crash-recovery · backup · windows · powershell

安装

前置:已安装 DSH(@deepseek-ai/dsh)与 Node.js(≥20)。

方式 A(GitHub 直装) — 安装 master 最新提交:

dsh plugin --profile web add github:lire1131/dsh-undo-savepoint#master

安装完成后重启 DSH 即生效(快照目录、参数等均可在设置中修改)。

方式 B(本地源码/免发布) — clone 到本地目录并手工挂载:

1. 把仓库放到本地插件目录(无中文路径更稳妥),例如 D:\dsh\plugins\dsh-undo-savepoint:

git clone https://github.com/lire1131/dsh-undo-savepoint.git D:\dsh\plugins\dsh-undo-savepoint

2. 建立 junction,让 DSH 的模块解析器通过包名 dsh-undo-savepoint 找到本地源码(host 插件与 WebUI client 插件都靠它):

mklink /J "<你的DSH安装>\node_modules\dsh-undo-savepoint" "D:\dsh\plugins\dsh-undo-savepoint"

说明:DSH 从它自己的 node_modules 向上解析包名。默认安装位置是 C:\Users\<用户名>\node_modules(npm 安装在用户目录时);若用 npx 缓存运行,则对 npx 缓存目录下的 node_modules 建 junction。执行 npm root -g / 检查 DSH 启动报错路径即可确认。

3. 挂载到 profile 补丁层:编辑 <DSH_HOME>\profiles\web\cordis.patch.yml,追加:

- insert:
    - id: dsh-undo-savepoint
      name: dsh-undo-savepoint

4. 生效:保存即热加载(host 部分);刷新页面出现头部按钮与设置项;重启 DSH 后一切进入稳态(旧版扁平快照会自动迁移)。

依赖说明:host 插件通过 createRequire('<DSH安装根>/package.json') 加载 @deepseek-ai/dsh-tools。若 DSH 安装在其他位置,设置环境变量 DSH_ROOT=<DSH安装根> 即可,无需额外安装依赖。

局外工具在哪(装完找不到?)

局外撤销工具(GUI 窗口 + 命令行)不装到桌面,而是随插件装在安装目录里:

一键创建桌面快捷方式(推荐,以后从桌面直接打开):

双击 tools\make-desktop-shortcut.bat(它会自动定位插件目录),桌面出现「DSH撤销管理器」图标; 或者把下面整段复制到 PowerShell 窗口回车(无需先找文件,自动定位):

$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { "$env:USERPROFILE\.dsh" }
$d = @("$dshHome\profiles\web\node_modules\dsh-undo-savepoint", "$dshHome\profiles\node_modules\dsh-undo-savepoint", "$env:USERPROFILE\node_modules\dsh-undo-savepoint") | Where-Object { Test-Path (Join-Path $_ 'tools\dsh-undo-savepoint-gui.bat') } | Select-Object -First 1
if ($d) {
  $w = New-Object -ComObject WScript.Shell
  $s = $w.CreateShortcut((Join-Path ([Environment]::GetFolderPath('Desktop')) 'DSH撤销管理器.lnk'))
  $s.TargetPath = Join-Path $d 'tools\dsh-undo-savepoint-gui.bat'
  $s.WorkingDirectory = Join-Path $d 'tools'
  $s.Save()
  Write-Host "已创建桌面快捷方式:$($s.FullName)"
} else { Write-Host '未找到插件目录,请先安装:dsh plugin --profile web add github:lire1131/dsh-undo-savepoint#master' }

只想打开工具目录看一眼:

$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { "$env:USERPROFILE\.dsh" }
explorer "$dshHome\profiles\web\node_modules\dsh-undo-savepoint\tools"

之后双击桌面「DSH撤销管理器」即可打开局外工具(DSH 崩溃、启动不了时也能用)。

使用

• 撤销:头部「撤销」按钮 / Ctrl+Alt+Z / 对 AI 说"撤销上一步"。
• 恢复:「恢复」按钮 / Ctrl+Alt+Y(仅当撤销后没有新操作)。
• 手动保存:面板里「手动保存」/ 对 AI 说"保存快照" / CLI snapshot。
• 回退到指定版本:面板里点快照行「回退到此版本」;或对 AI 说"回退到 ";或 CLI restore -Id <id>。
• 删除快照:面板里点「删除」;或 CLI remove -Id <id>。
• 自定义快捷键:设置 → 通用 → 撤销/恢复快捷键(点击输入框后按组合键,Backspace 清除)。
• 保存参数:设置 → 通用 → 快照设置(自动保存开关、防抖、保留数、两个目录,目录旁 📁 按钮可打开系统目录选择器)。

局外工具(DSH 挂了也能用)

界面语言:程序窗口按系统 UI 语言自动显示中文/英文;可用环境变量 DSH_UNDO_LANG=zh|en 强制指定。

进入仓库目录后:

# 程序窗口(推荐):双击 tools\dsh-undo-savepoint-gui.bat,或:
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo-savepoint-gui.ps1"

# 命令行
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo-savepoint.ps1" list
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo-savepoint.ps1" snapshot -Label "原因"
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo-savepoint.ps1" undo
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo-savepoint.ps1" undo -SyncDeps
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo-savepoint.ps1" redo
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo-savepoint.ps1" restore -Id <id> -Force
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo-savepoint.ps1" restore -Id <id> -Force -SyncDeps
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo-savepoint.ps1" remove -Id <id>
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo-savepoint.ps1" prune -KeepAuto 20

# 安全装插件(自动前后存档,失败自动回退)
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-plugin.ps1" add <包名>

常见事故场景:DSH 启动报 duplicate loader entry id 之类错误 → 打开「DSH 撤销管理器」选中出问题前的快照 → 回退 → 重启 DSH。不用重装、不丢会话。

REST API(WebUI 的后端)

设计要点

• 撤销语义:自动快照在变更之后生成,所以"恢复最新存档"是空操作;真实撤销 = 回退到与当前状态内容不同的最新快照;全部相同则明确提示"没有可撤销的变化"。
• 撤销不会撤销掉自己:恢复 cordis.patch.yml 后自动检查并重新写入 dsh-undo-savepoint 挂载条。
• 自动存档不误伤撤销:watcher 记录恢复操作写入的内容哈希,恢复动作自己的文件变化不会被自动存档(否则会挡住 redo);真实变更照常存档。
• 格式互通:Node 插件与 PowerShell 工具共用快照仓库与 manifest 格式;Windows PowerShell 5.1 与 PowerShell 7 均兼容。

开发

• 依赖解析:host 插件通过 createRequire(<DSH安装根>/package.json) 加载 @deepseek-ai/dsh-tools(环境变量 DSH_ROOT 可覆盖),无需在仓库内安装依赖。
• 测试(不需要 DSH 运行,在仓库目录执行):

node tools\smoke-test.mjs     :: 114 项逻辑测试(快照/撤销/重做/存储分流/无变化提示)
node tools\e2e-watch.mjs      :: 10 项真实时序回归(自动存档/撤销不误伤/重做)