前言¶
在 DeepSeek Harness（DSH）里装插件，一旦装到不兼容或破损的包，常见结果是 DSH 起不来、会话全崩，或 profile 清单被改乱。官方已有 engines.dsh 闸门、安装失败诊断、热更新回退等能力，但侧重「事后诊断」，没有「装前拍快照、DSH 挂了还能从外部还原」这一层。社区项目 dsh-snap（维护者 sunrulin123，分类 admin-security）针对插件安装域补上 checkpoint：装/删插件前自动快照，并用不依赖 DSH 进程的零依赖 CLI 一键回到装前。本文为非官方社区工具介绍，与 DeepSeek 官方无隶属关系。
这是什么¶
dsh-snap 由 装前自动快照 与 外部还原器 CLI 组成：Cordis 插件负责在各类安装路径触发快照并提供 Web/命令面板；快照库存于 profile 同卷、DSH 目录之外，内附 cli/dsh-snap.mjs 副本，DSH 完全退出后仍可 restore。设计原则是危险项只报告、绝不动手；会话数据与工作区文件永不触碰。
核心功能¶
触发路径¶
装插件的方式不同，快照挂钩点也不同：
| 方式 | dsh-snap 行为 |
|---|---|
Agent 经 plugin_manager 安装 |
tools/pre-execute 执行前拦截快照，并记录 spec |
| Web 界面安装/更新 | pnpm 动 node_modules 之前，经 plugin-manager/install-state 快照 |
终端 dsh plugin add |
监视 .plugin-manager/run.json 尽力快照（desktop profile 下 CLI 常被官方拒绝并发操作，属 best-effort，以最近一次快照为还原点） |
| 手动 | 设置页「立即快照」、/snap now、snapshot CLI |
插件启用后，启动时会后台拍一次基线快照（不阻塞启动），之后装/删插件自动快照。
还原语义¶
快照库默认路径为 $DSH_HOME/../.dsh-snap/，可用环境变量 DSH_SNAP_HOME 覆盖。还原前会自动拍 guard 快照，还原本身可用 undo 撤销。
- 回写 profile 清单（如
package.json、pnpm-lock.yaml、cordis.patch.yml等） - 用硬链接回填
node_modules中缺失或被改坏的文件 - 多出来的包默认保留并报告；需
--prune-extraneous才移入 trash $DSH_HOME配置层（如settings.yaml）默认不动；--include-home才参与还原- 不触碰会话数据与工作区文件
命令与工具面¶
外部 CLI 支持 list、snapshot、restore、undo、verify、prune、doctor、crash、preflight、serve 等子命令。会话内可用 /snap list | now [备注] | doctor。全局安装后可直接调用 dsh-snap。Agent 侧仅暴露只读类工具（snap_list、snap_snapshot、snap_doctor）；还原 deliberately 不进 agent 工具面，避免 LLM 触发破坏性操作。
preflight <pkg> 装前体检查 registry 元数据（存在性、弃用、engines.dsh 等），只告警不阻断；唯一网络请求即此类查询，可用 config.preflight: false 关闭。serve 提供本机回环救援台（随机 token），DSH 起不来时仍可在浏览器中列快照、预览并两步确认还原。
安装与启用¶
资料推荐的安装方式如下（desktop profile）：
dsh plugin --profile desktop add dsh-snap
亦可在 Web 插件页搜索 dsh-snap。当前 package 版本为 0.7.4，许可证 MIT，要求 Node ≥20，engines.dsh 为 >=0.2.0-0 <0.3.0。装完即生效，无需额外开关即可在后续装/删插件时自动快照；定时轻量快照等策略可在 cordis.patch.yml 的 config 字段中调整。
安装第三方插件前，建议在 GitHub 仓库 自行核对源码与许可证；插件以当前 DSH 进程权限运行。
典型用法：DSH 崩溃后外部还原¶
下面在 DSH 已无法正常使用时的标准营救流程（摘自 README）：
# 1. 完全退出 DSH（含托盘）
# 2. 任选一种：
node "<快照库>/cli/dsh-snap.mjs" restore last # 回到最近一次装前
node "<快照库>/cli/dsh-snap.mjs" list # 查看所有快照
# Windows 可双击 <快照库>/cli/restore-last.bat
# 3. 若还原有误，可撤销（还原前已拍 guard 快照）：
node "<快照库>/cli/dsh-snap.mjs" undo
将 <快照库> 替换为实际路径，一般为 $DSH_HOME/../.dsh-snap/。若文件在快照后被原地改写（不换 inode），硬链接方案可能导致快照侧指纹污染；verify 与 doctor 可预检，CLI 会报告并给出如 pnpm install --frozen-lockfile 等修复路径。
装前可对可疑包做体检：
node "<快照库>/cli/dsh-snap.mjs" preflight <包名>
与其它插件的分工¶
dsh-snap 只管 插件安装域 + 外部 CLI 营救，不与对话回滚、整机 GB 级备份、崩溃后自动停用元凶等重叠承担：
dsh-checkpoint-rewind：对话/工作区步骤回滚@xiaoyuyu6420/dsh-backup：整机定时备份dsh-lifeguard：崩溃规则与自愈停用（动手）；dsh-snap 的crash仅归因报告dsh-fix：patch 层急救；dsh-snap 做数据层快照还原
选型时按「装插件搞崩」还是「对话/整机/运行时自愈」区分即可。
适用场景与注意¶
适合：频繁试装社区插件、用 Agent 自动装包、希望在坏包拖垮 DSH 前有可回滚点的 desktop 用户。
注意：CLI 安装路径为 best-effort；home 层含凭据类键名的文件在快照前会被扫描，命中则整文件不入库（快照库明文落盘）。自动清理默认保留约 15 个快照 / 3GB / 30 天，手动快照与 guard 快照豁免。插件为非官方社区项目，目录页见 SkillHub，源码与 issue 见 GitHub。
结尾¶
dsh-snap 把「装前快照 + 外部一键还原」补进 DSH 插件生态：自动挂钩常见安装路径，还原不依赖 DSH 进程，且还原可撤销。若你经常在插件市场上试错，装前先让它拍一张，比事后重装或手搓恢复省事得多。
