跨机迁移说明
August 22, 2026 · View on GitHub
场景：在 A 电脑导出快照 ZIP → 拷到 B 电脑导入 → 在 B 上回滚到某个快照。 English: migration.en.md
一、会发生什么
1. 配置文件：正常恢复
快照里的 6 类配置文件（cordis.patch.yml / package.json / settings.yaml 等）会原样写回 B 的对应位置。
2. 插件代码文件：不会被塞进 B（v0.2.0 起）
快照包含插件代码树（blob 引用），但恢复时有一道硬校验（liveDirs 检查）：
- B 没装那个插件 → 整个插件条目跳过，零写入，恢复报告列出「directory no longer present」；
- B 装了同名插件 → 插件代码会被覆盖成 A 快照时的版本（恢复 = 把 B 变成 A 当时的状态，请知悉）。
3. blob 残留：只占空间，不写文件
导出/导入会把 A 的插件代码 blob 一起带过去（为保证恢复可用而设计）。导入后只占磁盘空间，不会被自动写回任何文件。
4. 真正的坑：patch 引用了 B 没有的插件 → 启动报错
快照里的 cordis.patch.yml 会原样恢复。如果它挂载了 A 的插件而 B 没装 → DSH 启动时 loader 加载失败（MODULE_NOT_FOUND）。
跨机恢复的本质 = 把 B 的配置变成 A 的样子，B 必须装齐 A 的插件才能正常启动。 这不是插件代码树功能引入的新问题，恢复配置本来就会这样。
二、跨机一致性预检（v0.3.1 起，自动提示）
恢复时自动扫描目标快照引用的插件（patch 挂载条目 + package.json bundles），探测本机能否解析。缺失时恢复报告明确提示：
⚠️ Cross-machine preflight: referenced but NOT resolvable on this machine: dsh-xxx
DSH may fail to start after restore — install them first, or use undo_safe_mode action "on" ...
- 本地文件条目（
name: './xxx'）不探测； - 多锚点探测（用户
node_modules/ profile 依赖树 / 插件位置链），任一可解析即视为已装，避免误报； - 预检只提示不阻断；跳过缺失挂载的自动恢复在后续版本提供。
三、最佳实践
| 步骤 | 操作 |
|---|---|
| 1 | A 上「导出」快照 ZIP |
| 2 | B 上先装齐 A 的插件（dsh plugin --profile web add <插件>），再导入 ZIP |
| 3 | B 上恢复，注意预检提示 |
| 4 | 启动失败？安全模式兜底：undo_safe_mode on → DSH 一定能启动 → 再决定装插件或回退 |