🗄️ dsh-savepoint · DSH 存档点

中文 | English

装插件前自动存档，出问题一键恢复，聊天记录永远不受影响。 插件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 -NoProfile -ExecutionPolicy Bypass -File tests\run-tests.ps1

边界与已知限制

许可证

MIT © ssipbss

致谢

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