dsh-undo-savepoint — DSH Undo/Rollback System

中文 | English | Changelog

An undo/rollback system built for DeepSeek Harness (DSH): install plugins, change skins, tweak settings — auto-save means auto-snapshot; manually save anytime; one-click undo / redo / roll back to any version. Even when DSH won't start, there's a stand-alone WebUI / GUI / CLI as a fallback.

Fed up with DSH crashes? Worried that small changes cause big trouble? One-click rollback of config & plugin code, secret redaction, one-click safe mode — self-rescue even when DSH is down.

Preview

Session header: undo / redo / snapshot / message rollback all as icons + auto-snapshot status badge (saved 24 · 3 hours ago)

WebUI snapshot panel: manual save / undo / redo / cleanup / export-import / safe mode, with per-entry "diff / roll back to this version / delete"	DSH settings "Snapshots" section (auto-save / retention count / sensitive mode / plugin whitelist / scheduled snapshots)

Stand-alone WebUI: crash banner + undo / redo / safe mode / diagnostics / message rollback / settings, works without DSH running (snapshot comparison & settings: see stand-alone tools section)

Core Capabilities

Basic capabilities (keyboard shortcuts, chat commands, auto-cleanup, dual-mode save, configurable parameters, etc.) are in the sections below and the Changelog.

Platform Support

Since v0.4.0 the core is extracted into pure Node zero-dependency modules (lib/core.mjs / lib/zip.mjs), with per-platform distribution around it; available on Windows / macOS / Linux:

CI is a three-platform matrix (windows/ubuntu/macos × node[20,22]). ZIP export / import is implemented by the pure Node zero-dependency lib/zip.mjs (deflate / store, CRC32, UTF-8); no runtime dependencies are introduced, and interoperability with PowerShell has been verified in both directions.

Logo / icon: generation prompt in docs/logo-prompt.md; the WebUI favicon uses the built-in tools/webui/logo.svg. Custom icon: save a transparent PNG as tools/webui/logo.png, run node tools/make-ico.mjs tools/webui/logo.png tools/webui/logo.ico to generate the .ico, and it will be picked up automatically the next time a shortcut is created (fallback order logo.ico → logo.png → system default).

Crash Rescue Quick Reference

Safe-mode confirmation: one-click disable of all user plugins except this one, ensuring DSH can boot, then troubleshoot one by one

Installation

Prerequisites: DSH (@deepseek-ai/dsh) and Node.js (≥20) installed. Host mode runs on a profile that provides tools / systemPrompt / webServer services (all Web-type profiles qualify); when DSH cannot start at all, use the out-of-host CLI / GUI instead.

Method A: GitHub Direct Install (Recommended)

Install the latest commit on master:

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

After installing, restart DSH to activate (snapshot dir, params, etc. are all editable in settings).

Method C: npm Registry Install

dsh plugin --profile web add dsh-undo-savepoint

dsh plugin add delegates to pnpm to complete the install in the profile directory; this package's package.json declares dsh.bundle.patch, so it is automatically registered into the profile's bundle manifest after installation. Restart DSH for it to take effect.

Method B: Local Source / No-Publish

1. Place the repository in a local plugin directory (avoid Chinese in the path for safety), e.g. D:\dsh\plugins\dsh-undo-savepoint:

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

2. Create a junction (Windows) so DSH's module resolver can find the local source by the package name dsh-undo-savepoint (both the host plugin and the WebUI client plugin rely on it):

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

DSH resolves package names upward from its own node_modules. The default install location is C:\Users\<用户名>\node_modules (when npm installs into the user directory); when run via the npx cache, a junction is created to the node_modules under the npx cache directory. Run npm root -g or check the path in DSH startup errors to confirm.

3. Mount into the profile patch layer: edit <DSH_HOME>\profiles\web\cordis.patch.yml and append:

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

4. Active: saving triggers a hot reload (host part); refresh the page to see the header button and settings; restart DSH for steady state (old flat snapshots auto-migrate).

Dependency note: the host plugin loads @deepseek-ai/dsh-tools via createRequire('<DSH安装根>/package.json'). If DSH lives elsewhere, set the env var DSH_ROOT=<DSH安装根> — no extra installs needed.

Usage (Inside DSH)

• Undo: the header "Undo" button / Ctrl+Alt+Z / tell the AI "undo the last step".
• Redo: the "Redo" button / Ctrl+Alt+Y (only valid when no new operation occurred after the undo).
• Manual save: "Manual Save" in the panel / tell the AI "save a snapshot" / CLI snapshot.
• Roll back to a specific version: click "Roll back to this version" on the snapshot row in the panel; or tell the AI "roll back to \<id\>"; or CLI restore -Id <id>.
• Delete a snapshot: click "Delete" in the panel; or CLI remove -Id <id>.
• Message-level undo: "Conversation Withdraw" in the conversation header; select a message batch to withdraw its file changes.
• Custom shortcuts: Settings → General → Undo / Redo shortcuts (click the input box and press the key combo; Backspace clears it).
• Save parameters: Settings → General → Snapshot Settings (auto-save toggle, debounce, retention count, the two directories, tracked workspace directories; the 📁 button next to a directory opens the system directory picker). "Tracked workspace directories" supports comma/semicolon-separated multiples; when non-empty, it overrides the default working directory.

Conversation-level withdraw: roll back the changes of a message batch (time can be traced back to any conversation)

Diff preview: file-level changes with red deletions and green additions; confirm before rolling back	Edit notes / tags: modify directly in the snapshot list

Out-of-Host Tools (Available Even When DSH Is Down)

Out-of-Host WebUI (Recommended, All Platforms)

node tools/undo-server.mjs     # 或双击 launch-undo.bat / .command / .sh / .desktop

Spins up a local 127.0.0.1 server + built-in web UI: timeline / rollback / diff / safe mode / diagnostics. Double-click to use, no DSH dependency. After loading, a "dsh-undo-savepoint" desktop shortcut is auto-created — double-click to open directly. The diagnostics panel can also fix issues: fixable items are marked "Fixable"; click "Fix" to repair in place (auto-saves a manual snapshot first, re-checks immediately after).

Desktop shortcut: auto-created after the plugin loads, double-click to open the out-of-process WebUI

Snapshot diff: file list + change stats (+8 / -2) + line-level diff highlighting	Out-of-process settings: debounce / retention count / masking mode / directory picker / desktop shortcut

Tool Locations

Out-of-process tools (GUI + CLI) live in the plugin's install dir, not on the desktop:

$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"

Command Line (Windows PowerShell)

进入仓库目录后：

# 程序窗口（推荐）：双击 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.ps1" list
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo.ps1" snapshot -Label "原因"
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo.ps1" undo
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo.ps1" undo -SyncDeps
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo.ps1" redo
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo.ps1" restore -Id <id> -Force
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo.ps1" restore -Id <id> -Force -SyncDeps
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo.ps1" remove -Id <id>
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo.ps1" prune -KeepAuto 20

# 启动预检（DSH 起不来时也能用）；-Fix 修复可修项
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo.ps1" doctor
powershell -NoProfile -ExecutionPolicy Bypass -File "tools\dsh-undo.ps1" doctor -Fix

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

UI Language

DSH_UNDO_LANG=zh|en forces the language; when unset, Chinese systems default to Chinese, otherwise English. Applies to server output, offline CLI / GUI, and the WebUI — all dictionary sources are unified under lib/i18n/{zh,en}.json.

Common incident: DSH fails to start with errors like duplicate loader entry id → open "DSH Undo Manager", select the snapshot from before the problem, roll back, then restart DSH. No reinstall, no lost sessions.

Snapshot Contents & Storage

Snapshot objects are DSH's key startup configurations: cordis.patch.yml, package.json, cordis.yml, pnpm-workspace.yaml, pnpm-lock.yaml (under the profile) + cordis.patch.yml, settings.yaml, .env, .credentials.yaml (under $DSH_HOME, default ~/.dsh).

When a restore involves package.json / pnpm-lock.yaml, by default it only reports that node_modules may be out of sync; to actually rebuild dependencies, add -SyncDeps (offline CLI), sync_deps: true (chat tool), or syncDeps: true (REST). The plugin runs pnpm install --frozen-lockfile (plain pnpm install if no lockfile is present). A failed install does not affect the config files that have already been restored.

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

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

多 Profile 与自定义家目录

多 Profile（v0.3.3 起）：插件从启动参数自动识别当前 profile（dsh --profile mine / --profile=mine；dsh web 回退为 web），并按当前 profile 工作：

• 配置目录：默认 $DSH_HOME/profiles/<当前 profile>（DSH_HOME 默认 ~/.dsh）；
• 快照仓库：默认 <快照根>/<当前 profile>/{auto,manual}（按 profile 隔离）；作用域目录不存在而旧版平铺目录存在时自动回退平铺，旧快照不会「隐身」；
• 归属标识：快照 manifest 记录 profile 字段，undo_list 显示当前 profile。

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

自定义家目录（v0.3.5 起，issue #6）：与官方启动器（@deepseek-ai/dsh-home-paths）解析完全一致——DSH_HOME 环境变量优先（空白视为未设置，支持 ~ / ~/ / ~\ 前缀），否则回退 <用户家目录>\.dsh。设置文件（$DSH_HOME\undo\settings.json）、默认快照根（$DSH_HOME\undo-snapshots）、profile 目录、home 根、插件发现路径全部基于它——第三方客户端不再出现「两套家分裂」，重启后自定义目录稳定保留。

显式覆盖始终优先：环境变量 DSH_UNDO_SETTINGS / DSH_UNDO_ROOT / DSH_UNDO_EXPORT，以及 config 里的 homeDir / profileDir / manualDir / autoDir / profileName。

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     :: 189 项逻辑测试（快照/撤销/重做/存储分流/无变化提示/消息级撤销/孤儿GC/zip互操）
node tools\e2e-watch.mjs      :: 10 项真实时序回归（自动存档/撤销不误伤/重做）
node tools\check-size.mjs     :: 体积门禁（<5MB）
node tools\check-version.mjs  :: 版本号 semver 校验

License

MIT