Guojin0826/dsh-snapshot

DSH 快照工具

给 DeepSeek Harness(DSH) 做“存档 / 读档”。

装插件、改配置、升级核心之前先拍一张快照;出了任何问题,一键回滚到能用的状态。

License
English · Java 图形版说明

为什么需要它

DSH 的核心、插件、配置、密钥散落在 DSH_HOME 的多个目录里,手工备份既麻烦又容易漏。这个工具把“能完整还原一台 DSH 的关键状态”打包成一份快照,并刻意排除掉能用包管理器重建的大体积目录,让备份又快又小。

特性

- 一键备份 / 一键回滚:双击 .cmd 或用图形界面,无需记命令。
- 锁定精确依赖版本:备份 pnpm-lock.yaml,回滚后能装回一模一样的插件版本。
- 智能跳过未变化的文件:按「大小 + 修改时间」判断,只还原真正变了的文件,重复回滚几乎零开销。
- 回滚前自动再备份:每次回滚会先存一份 pre-restore,反悔了还能再滚回去。
- 覆盖还原、不误删:只还原已备份内容,不会删除快照之后你新建的文件。
- 回滚提示被移除的依赖:回滚完在日志里列出「当前有、但快照里没有」的插件,方便你确认。
- 双形态、快照互通:PowerShell 版与 Java 图形版读写同一份快照,可混用。
- 零依赖、不侵入:独立脚本 / 独立 JAR,不往 DSH 里注入任何插件,与 DSH 自身版本演进解耦。

两种形态

| | PowerShell 版 | Java 图形版 |
|---|---|---|
| 载体 | dsh-snapshot.ps1 + .cmd 双击包装 | java/dsh-snapshot.jar(Swing GUI + CLI) |
| 依赖 | Windows + PowerShell 5.1+ | JRE 8+(零第三方依赖) |
| 交互 | 命令行 / 双击脚本 | 图形界面 / 命令行 |
| 命令集 | backup list show restore help | backup list show restore delete help |
| 快照 | 同一套格式,可互相回滚 | 同一套格式,可互相回滚 |

目录结构

| 路径 | 说明 |
|---|---|
| dsh-snapshot.ps1 | PowerShell 版核心脚本 |
| backup-dsh.cmd | 双击一键备份 |
| restore-dsh.cmd | 双击一键回滚到最近快照(有确认提示) |
| java/dsh-snapshot.jar | Java 版(JAR,双击启动图形界面) |
| java/dsh-snapshot-gui.cmd | Java 图形界面的双击启动器 |
| java/src/ | Java 源码(JSON 解析、核心服务、Swing 界面) |
| snapshots/ | 快照存放目录(自动创建) |

快速开始

备份:双击 backup-dsh.cmd(或双击 java/dsh-snapshot.jar 后点「备份」)。

回滚:先停掉 dsh web,双击 restore-dsh.cmd 输入 y 确认(图形版选中快照后点「回滚选中」)。

命令行用法

PowerShell 版(参数用大写开头)

cd

备份
.\dsh-snapshot.ps1 backup -Label "装插件之前"
.\dsh-snapshot.ps1 backup -Label "升级核心前" -Zip          # 额外压成单个 .zip
.\dsh-snapshot.ps1 backup -NoSecrets                        # 排除 API 密钥
.\dsh-snapshot.ps1 backup -IncludeExternal                  # 连外部本地插件源一起备份

查看 / 回滚
.\dsh-snapshot.ps1 list
.\dsh-snapshot.ps1 show latest                              # 或 show
.\dsh-snapshot.ps1 restore latest -Force                    # dsh web 未停时强制回滚

通用选项:-DshHome  · -SnapshotRoot  · -Profile 。

Java 版(命令与参数全小写)

cd \java

java -jar dsh-snapshot.jar list
java -jar dsh-snapshot.jar backup -label "装插件前" -include-external
java -jar dsh-snapshot.jar show latest
java -jar dsh-snapshot.jar restore latest -force -auto-install   # 回滚后自动 pnpm install
java -jar dsh-snapshot.jar delete latest                          # 删除最近快照
java -jar dsh-snapshot.jar help

可选参数:-label · -no-secrets · -include-external · -zip · -force · -auto-install · -dsh-home  · -snapshot-root  · -profile 。

备份了什么

| ✅ 备份(可完整还原) | ⛔ 不备份(用锁文件/版本号重建) |
|---|---|
| DSH_HOME 顶层配置:settings.yaml、pet.json、cordis.patch.yml、skin-center-active.json、.credentials.yaml 等 | profile 的 node_modules(数百 MB,pnpm install 重建) |
| DSH_HOME 状态目录：skins、sessions、attachments、storages、skin-center、.agent-presets、task-board 等 | npx 核心缓存（按 manifest 记录的 dshCoreVersion 重新拉取） |
| profile 清单：package.json、pnpm-lock.yaml、pnpm-workspace.yaml、cordis.yml、cordis.patch.yml | |
| manifest.json：核心 / node / pnpm 版本、完整依赖清单、体积 | |

单份快照通常在几十 MB 量级。pnpm-lock.yaml 是核心——它锁定了所有依赖的精确版本，是“回滚后能装回一模一样依赖”的保证。

外部本地源（-IncludeExternal）

有些插件不是从 npm 装的，而是 package.json 里指向 DSH_HOME 之外的本地路径：

- link: 指向本地源码目录；
- file: 指向本地 *.tgz 包。

这些源默认不在 DSH_HOME 内，普通快照拍不到；一旦源被删/清理，回滚时 pnpm install 会失败。

加 -IncludeExternal 后，工具会自动扫描这些 link: / file: 依赖，把外部源一并拍进快照的 external/ 目录，回滚时自动还原到原路径。代价是快照体积明显增大（取决于外部源大小）。

建议：装卸插件、或清理 DSH_HOME 之外这些本地源之前，用 -IncludeExternal 备份一次。

回滚后必做

回滚只还原“已备份的配置文件”，依赖与核心需要重建：

1) 按快照锁定的版本重建 node_modules
cd "$env:DSH_HOME\profiles\web"   # 或你的实际 DSH 主目录
pnpm install

2) 若核心版本不符，按 manifest 里的 dshCoreVersion 重新拉取核心

3) 重启 dsh web 验证

图形版勾选「回滚后自动重装插件」可自动完成第 1 步（需 pnpm 在 PATH，或可用 npx；registry 依赖需联网）。

快照互通

PowerShell 版与 Java 版写入完全相同的布局（home/、profiles/web/、external/、manifest.json），因此：

- 用哪个版本备份的快照，都能用另一个版本回滚；
- 两种版本默认都落在同一 snapshots/ 目录，无需迁移。

配置

| 环境变量 | 作用 | 默认 |
|---|---|---|
| DSH_HOME | DSH 主目录 | ~\.dsh |
| DSH_SNAPSHOT_ROOT | 快照存放根目录 | 工具旁的 snapshots\ |

也可在命令行用 -DshHome / -SnapshotRoot（PowerShell）或 -dsh-home / -snapshot-root（Java）覆盖。

安全

- 快照内含 .credentials.yaml（API 密钥）——请妥善保管 snapshots/ 目录，不要提交到 git、不要随意同步/上传（已用 .gitignore 排除）。
- 不想备份密钥，备份时加 -NoSecrets / -no-secrets。
- 建议把 snapshots/ 拷贝到独立磁盘或网盘做异地容灾。

工作原理与常见问题

回滚会删掉我之后新建的文件吗？ 不会。回滚是「覆盖还原已备份文件」，不删除快照之后新增的文件。

重复回滚会很慢吗？ 不会。回滚按「大小 + 修改时间」跳过未变化的文件，只还原真正变了的。

回滚后插件没了的残留怎么办？ 回滚把清单覆盖回快照版本后，会在日志列出「当前有、但快照里没有」的依赖；若未自动重装，对应文件可能残留在 node_modules 里，但不会再被加载。

回滚错了吗？ 每次回滚前会先自动备份当前状态（pre-restore），反悔可再回滚。

为什么做成独立工具而不是插件？ 独立脚本 / 独立 JAR 零依赖、不注入 DSH 插件系统，不受 DSH 自身版本升级或插件兼容问题影响，备份 / 回滚本身更可靠。

从源码构建（可选）

dsh-snapshot.jar 已提交在仓库里，通常无需构建；只有改动 Java 源码时才需要：

cd java
javac -encoding UTF-8 --release 8 -d classes src\Json.java src\SnapshotService.java src\DshSnapshotApp.java
jar cfe dsh-snapshot.jar DshSnapshotApp -C classes .

（--release 需要 JDK 9+；JDK 8 改用 -source 8 -target 8。）

前置要求

- PowerShell 版：Windows + PowerShell 5.1+。
- Java 版：JRE 8 或更高。
- 回滚后重建依赖（可选）：pnpm 在 PATH，或可用 npx（会自动拉取 pnpm）；registry 依赖需联网。

License

MIT