存档点 ssipbss/dsh-savepoint

🗄️ dsh-savepoint · DSH 存档点

装插件前自动存档，出问题一键恢复，聊天记录永远不受影响。
插件2 装坏了？外科手术只回退插件2，先装的插件1、后装的插件3 原样保留。

这是什么？

你以前装 DSH 社区插件的循环：翻车 → 让 AI 修 → 越修越坏 → DSH 打不开 → 只能全卸重装。

dsh-savepoint 把「修复能力」放在 DSH 之外：

- 装插件前后各存一个档（配置文件快照，KB 级），命名「安装XX前」「安装XX后」；
- 出问题后一键恢复——DSH 打得开时用 AI 工具或设置页面板，打不开时双击一个脚本就能还原；
- 外科手术：按时间线装了插件1/2/3、插件2 搞坏 DSH 时，只回退插件2 的改动，插件1 和插件3 保持可用（三路合并，冲突区域保留现状并报告）；
- 聊天记录（sessions/）绝不恢复、绝不删除，恢复前后自动校验并写日志；
- 恢复前先把当前状态移入隔离区（不删除），误恢复可撤销。

特性

- 装插件前/后各存一个档，命名「安装XX前」「安装XX后」
- 自动存档三重保障：启动基线 + 变更检测（10 秒轮询，变化后延时 10 秒存档）+ 30 分钟兜底
- 三入口恢复：AI 工具（snapshot_restore/snapshot_surgery）/ 设置页「存档点」面板 / 双击脚本
- 外科手术式回退：只撤掉某一次插件安装，前后安装的其他插件不受影响
- DSH 打不开也能恢复（独立 PowerShell 脚本，零依赖、不联网）
- 聊天记录保护：绝不恢复、绝不删除，恢复前后签名校验留痕
- 恢复前隔离当前状态，误恢复可撤销
- snapshot_diff 定位肇事改动；面板支持列表/存档/恢复/对比/删除存档/外科手术
- 轮转清理：自动档保留 10 个、手动档保留 30 个（含带 tag 的存档）

快速开始

方式 A：完整体验（推荐）

1. 把 scripts/ 目录整个复制到 %USERPROFILE%\.dsh-snapshots\（即 $DSH_HOME-snapshots）；
2. 在 DSH 会话里让 AI 用 cordis_define 加载 plugin/savepoint.host.js（idPrefix: savep），并把 plugin/savepoint.client.js 作为 code.client 一起传入（获得设置页面板）。
插件启动时也会自动把内置脚本部署到 snapRoot（自部署版）。

方式 B：只要恢复能力

复制 scripts/ 到任意位置，手动运行：

手动存档 .\snapshot.cmd 或 powershell -NoProfile -ExecutionPolicy Bypass -File .\snapshot.ps1 -Reason "装 XX 前"

一键恢复（交互选择存档，绝不自动就近恢复；s=外科手术，d=删除存档可多选） .\restore.cmd 交互菜单里输入 s 进入外科手术模式（只回退某一次安装）

方式 C：持久化安装（随 DSH 启动自动生效，推荐）

把 plugin/persist-bundle/ 作为本地 npm 包挂进 profile：

1. 复制 plugin/persist-bundle/ 到稳定位置（例如 %USERPROFILE%\.dsh-local-plugins\savepoint\）；
2. 编辑 %USERPROFILE%\.dsh\profiles\web\package.json：
- dependencies 增加 "dsh-savepoint-plugin": "file:../../../.dsh-local-plugins/savepoint"
- dsh.profile.bundles 数组追加 "dsh-savepoint-plugin"
3. 在 %USERPROFILE%\.dsh\profiles\web\ 下运行 pnpm install；
4. 重启 dsh web —— 之后插件随启动自动加载：6 个工具全局可用、启动基线 + 变更检测自动存档常驻、无任何面板/UI。

卸载：移除上述两处引用后重新 pnpm install 即可。

注意：持久化版走组合级 tools.register()，工具参数必须用标准 JSON Schema（{ type:'object', properties, required[] }）；动态版（cordis_define）走 harness.defineTool 自动编译「属性表」格式。两种格式不要混用。

日常用法

装插件前 → snapshot_save(pluginName="xx", phase="before") → 「安装xx前」装插件后 → snapshot_save(pluginName="xx", phase="after") → 「安装xx后」出问题了 → snapshot_restore(snapshotId="...") → 全量恢复 → snapshot_surgery(beforeId="安装xx前", afterId="安装xx后") → 只回退这一次安装（或双击 restore.cmd 手动选档 / 选 s 外科手术）

目录结构

.dsh-snapshots/
├─ snapshot.cmd / snapshot.ps1 # 手动存档 ├─ restore.cmd / restore.ps1 # 一键恢复（交互选档；s = 外科手术） ├─ config.json # （可选）自定义 dshHome / snapRoot ├─ logs/ # 恢复/手术日志与结构化报告 ├─ broken/ # 隔离区（损坏现场，可撤销） └─ snap-<时间>-<manual|auto>/ # 每个存档 ├─ manifest.json # 清单（文件/哈希/原因/时间） ├─ files/ # 配置快照 └─ restore.ps1 / restore.cmd # 该存档自带的恢复脚本（自包含）

工作原理

存档的是 DSH 的关键小文件（KB 级）：cordis.patch.yml、package.json、settings.yaml、.credentials.yaml、workspace.json、.agent-presets/ 等。依赖树（node_modules）不复制——依赖损坏时恢复脚本可选执行 pnpm install --force 重建。

外科手术对「安装XX前/后」这对存档做三路合并：package.json 按 JSON 结构合并（插件2 新增的依赖条目被移除，插件3 后来加的条目保留）；其他文件按行合并（插件2 增加/修改的行被精确撤销）；若插件3 改过插件2 动过的区域，保留现状并报告冲突。改动前先把现状复制进隔离区，可撤销。

恢复脚本是纯 PowerShell，不依赖 DSH / node / pnpm / 网络，DSH 打不开时也能运行。

测试

tests/run-tests.ps1 在假 DSH 家目录上模拟「依次安装插件1/2/3，插件2 弄坏 DSH」的完整时间线，37 项断言覆盖：干净手术、冲突手术、全量恢复、聊天记录哈希保护、损坏 package.json 的退化合并、交互式选档、恶意 manifest 路径穿越拒绝、轮转清理。
powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tests\run-tests.ps1

边界与已知限制

| 限制 | 说明 |
| 自动存档需要插件在运行 | 插件是 DSH 动态插件（会话级）：重启后需在新会话重新加载。但已有存档和恢复脚本永远可用。 |
| 聊天记录 | 存在 $DSH_HOME\sessions\，手动全删 .dsh 仍会丢。本插件解决"不重装"，不解决"手滑全删"。 |
| 外科手术的粒度 | 按「前后」存档对界定一次安装；若前后没存档（如变更检测的自动档），恢复只能按档全量或手动选对。 |
| package.json 已损坏时 | 外科手术退化为行级合并（忽略尾逗号差异），尽力移除肇事插件的条目；文件本身若仍非法需手动修复。 |
| 首次使用 | 插件默认从 config.json 或环境变量探测路径；找不到时会在日志里明确报错，不会静默乱存。 |
| 沙箱策略 | 插件用当前会话解析的沙箱策略执行命令；若会话策略比危险全量更严，写存档目录会被拒绝并明确报错。 |

许可证

MIT © ssipbss

致谢

灵感来自 DSH 社区"装插件翻车→全卸重装"的真实痛点。