配置迁移助手 ygcdsj/dsh-home-migrate

dsh-migrate

实验性 — DSH 配置迁移工具：导出/打包 → 换机还原 → 校验 + 回滚。

npm version
npm downloads
license

从任意 DSH 安装打包配置，在目标机还原为新建 profile，全程校验、失败自动回滚。不做云、不做历史、不做跨品牌。

工作流程

dsh-migrate 迁移流程总览

与现有项目的区别

| 项目 | 定位 | dsh-migrate 的边界 |
| dshmarket（dsh-market）Backup & Restore | 市场内 profile 插件层备份/恢复 | 我们不碰插件市场；dsh-migrate 覆盖 vendor/ link 目录、.agent-presets、settings.yaml、凭据脱敏——归档格式互通是 v2 目标 |
| dsh-backup-sync | 本地快照 + WebDAV 跨机同步 | 备份/同步 ≠ 迁移；我们做“打包 → 换机还原”完整闭环 |
| dsh-backup | 一键备份 + 定时 + sha256 + 轮转 | 同上 |
| dsh-session-sync | 会话库 git 镜像 | 我们 MVP 明确不做 sessions |
| dsh-movein / DSH-Portable | 导入（Claude Code → DSH）/ 便携构建 | 反向或不同形态，不冲突 |

功能（MVP）

- 导出：扫描 ~/.dsh（profiles 配置、settings.yaml、.agent-presets、vendor/ link 目录）；硬排除 .credentials.yaml/.env/.pnpm-store/sessions/storages/node_modules 等；settings/presets 做字段级凭据扫描 + 脱敏，处理明细进 manifest（secretReport）
- 打包：单一 .dshmig（zip），内置 manifest（版本、平台、文件清单、sha256 校验和、link 映射）
- 导入：预检（同 OS、dsh 版本、磁盘）→ 备份目标机 → 默认新建 profile（-migrated，重名自动递增）→ link: 路径重算 → vendor/presets/settings 还原 → pnpm install → 验证链（链接解析 → dsh --dump-config）→ 失败自动回滚
- 验证链：L1 pnpm install / L2 link 解析（junction realpath）/ L3 dsh --dump-config
- 界面：设置页「迁移」入口（导出向导 + 导入向导）；host 工具 dsh_migrate_export / dsh_migrate_import 可被 agent 直接调用

MVP 明确不做（v2 或生态）

sessions/storages 迁移、WebDAV/Gist 云同步、跨品牌导入、便携化、跨 OS 迁移、覆盖现有 profile、无人值守自动迁移、凭据管理（只排除 + 脱敏 + 引导重配）。

安装

发布到 npm 后：

在 profile 目录内
dsh plugin --profile web add dsh-migrate

本地开发/注入（需要 dsh-super-injector）：

npm install --legacy-peer-deps --no-audit --no-fund
npm run build # 构建（无 bash/无源码 checkout 时自动降级 _npx 缓存官方包树）
注入器环境内： dev_inject_plugin

完整迁移流程（第一次使用）

1. 源机导出：设置 → 迁移 → 导出 → ① 预览导出内容 → ② 执行导出
2. 拿到产物：.dshmig 文件生成在 ~/dsh-migrate-exports/dsh-migrate--.dshmig——一个 zip，内含 manifest（校验清单）、profile 配置、settings.yaml（已脱敏）、.agent-presets、vendor/ link 包；凭据尽力排除/脱敏（secretReport 含 unscannedFiles 未扫描清单，传输前请核对）
3. 传输：U 盘 / 网盘 / scp 均可（脱敏尽力而为，请以 secretReport 为准）
4. 目标机导入：目标机 DSH → 设置 → 迁移 → 导入 → 粘贴 .dshmig 路径 → ① 预检（逐项 ✓/✗）→ 确认步骤清单 → ② 执行导入
5. 等待验证：自动执行 pnpm install + 验证链（L1 安装 / L2 链接解析 / L3 dsh --dump-config），全部通过才收尾
6. 切换使用：导入为新建 profile（-migrated），验证通过后手动切换默认 profile；确认无误后清理 ~/.dsh/.dshmig-backup/

启动迁移后的 profile（重要）：dsh web 是 dsh --profile web 的别名，永远启动原生的 web profile——迁移成果在新建的 -migrated profile 里，必须显式指定：

dsh --profile web-migrated # 启动迁移后的 profile（GUI）

用 dsh web 打开的是未迁移的原生环境，自然看不到迁移过来的插件/皮肤/设置，这不是故障。web 是 dsh CLI 的硬编码别名（dsh web ≡ dsh --profile web），DSH 没有默认 profile 也没有切换命令。要让 dsh web 直接启动迁移后的环境，唯一方式是重命名 profile 目录：确认迁移无误后，先停用/移走旧 web 目录，再把 -migrated 重命名为 web（两者都在 $DSH_HOME/profiles/ 下）；不确定时继续用 dsh --profile -migrated 显式启动。⚠ 目录改名后 pnpm 会报 ERR_PNPM_UNEXPECTED_VIRTUAL_STORE（虚拟商店路径失配，pnpm 已知行为），修复方法见 FAQ。

导入全程不覆盖你现有的 profile；任何一步失败自动回滚。

用法

设置页向导（推荐）

1. 导出：设置 → 迁移 → 预览导出内容（文件清单/大小/排除项/疑似凭据）→ 执行导出 → 产物在 ~/dsh-migrate-exports/.dshmig
2. 导入：目标机设置 → 迁移 → 输入 .dshmig 路径 → 预检（逐项 ✓/✗）→ 确认步骤清单 → 执行 → 查看验证链结果与备份目录
3. 验证通过后手动切换默认 profile 使用；.dshmig-backup/ 确认无误后可手动清理

Host 工具

dsh_migrate_export { dryRun: true }（预览）/ { dryRun: false, outDir }（打包）；dsh_migrate_import { archive, dryRun: true }（预检）/ { archive }（导入，失败自动回滚）。

安全边界

dsh-migrate 导入安全门禁

- 凭据尽力排除/脱敏，非绝对保证：.credentials.yaml、.env 硬排除；settings/presets/vendor 配置文件内疑似凭据字段自动脱敏（）并记录于 secretReport；未扫描文件清单（unscannedFiles）随报告导出，请核对后再传输
- vendor 包配置文件内的凭据会原地脱敏：迁移不搬运凭据的必然代价——迁移后的 vendor 包若依赖被脱敏的值（如 API token），需要在目标机重新配置；README/导出报告会提示
- 导入 = 执行归档中的代码：导入会 pnpm install（默认 --ignore-scripts）并解析 bundle 插件，之后启动该 profile 会执行其中插件——仅导入你信任的来源（UI 确认框有醒目警告）
- 导出产物只在本机生成；上传/传输由用户自行负责
- link: 目标断言在 /vendor 内（防路径逃逸）；manifest 路径字段（files/links/profiles）白名单校验 + 落地断言（防穿越写盘）
- HTTP API 仅本机回环（Host 白名单）+ CSRF token + Origin 同源 + Sec-Fetch-Site 校验；将 DSH web 暴露到局域网 = 任何人可导入任意归档（RCE 面）
- settings.yaml 为符号链接时拒绝覆盖（防穿透写目标）
- 并发导入各自独立 staging 子目录，互不清理

FAQ

导入会覆盖我现在的配置吗？ 不会。MVP 只新建 profile（-migrated）；settings.yaml 在备份后覆盖（可在导入前取消勾选）。

为什么 dsh web 看不到迁移的插件？ dsh web 只是 dsh --profile web 的硬编码别名，启动的是原生的 web profile；迁移工具不覆盖现有 profile，成果都在新建的 -migrated 里。请用 dsh --profile -migrated 启动。确认迁移无误后，可停用旧 profile 并把 -migrated 重命名为 web（$DSH_HOME/profiles/ 下改目录名即可，DSH 无默认 profile 机制），此后 dsh web 即启动迁移后的环境。

跨 OS 可以迁移吗？ MVP 限定同 OS；跨 OS 会在预检阶段明确拒绝。

目标机已经用过（装过插件/皮肤）还能导入吗？ 可以。导入只新建 profile（-migrated），不覆盖你现有的任何 profile；settings.yaml 会先备份再覆盖（导入前可取消勾选）；vendor 同名包跳过或校验一致、冲突只报告不覆盖。预检的 target-used 项会以警告（⚠）提示目标机状态（已有 vendor 包 / 非默认 profile / 迁移历史），不阻断导入；需要"目标机必须原生未动"的严格模式时，host 工具可传 requireFresh: true。
重命名 profile 目录后 dsh plugin 报 ERR_PNPM_UNEXPECTED_VIRTUAL_STORE 怎么办？ pnpm 会把虚拟商店的绝对路径写进 node_modules/.modules.yaml（virtualStoreDir 字段），profile 目录改名/复制后该路径失配，pnpm 就拒绝一切增删改——这是 pnpm 的已知行为，与迁移工具无关（dsh web 仍能正常启动，因为运行时加载走链接、不校验这个字段）。解决：停掉 dsh → 删除该 profile 目录下的 node_modules（pnpm-lock.yaml 在目录里不会丢）→ 重新执行 dsh plugin --profile add （或在该目录跑 pnpm install），pnpm 会按锁文件重建全部依赖。

迁移包会带 dsh-migrate 自己吗？ 从 0.0.9 起会：导出时工具自动把自身附加进归档内 profile（dependencies 加 dsh-migrate@^ + dsh.profile.bundles 追加），目标机导入后即自带迁移工具，无需手动安装（幂等：profile 已显式依赖时不重复附加；导入会从 npm 安装，需网络）。历史版本（≤0.0.8）不带：迁移只搬运 profile 的声明内容，而通过运行时注入（super-injector）挂载的工具不在 profile 依赖里——那时需目标机手动 dsh plugin --profile add dsh-migrate。

git: 依赖（skin 类）怎么办？ 不打包，目标机 pnpm install 时重新拉取（需网络/凭据），预检会提示。

导入安全吗？ 导入会执行归档内的代码（pnpm install 安装脚本 + bundle 插件解析，之后启动 profile 还会执行插件），所以只导入你信任的来源。默认 --ignore-scripts 禁止依赖安装脚本；路径字段白名单 + 落地断言防穿越；HTTP API 仅回环 + token 可调。

导入失败了会怎样？ 配置级完全回滚（删除新建内容 + 恢复快照），依赖级尽力恢复；.dshmig-backup/ 保留现场，绝不静默。

开发与测试

npm test # 冒烟（导出→导入→重写/还原/递增/故障注入），沙箱内可跑
npm run test:install # 完整链路（pnpm install + dump-config，需完整权限）

规格与设计决策见 docs/DEVELOPMENT.md（本机实测基线、生态惯例、勘察结论、风险登记）。

安全审查与修复记录：原始审查报告见 docs/SECURITY_REVIEW.md，核查与修复验证见 docs/VERIFICATION.md。

路线图（v2）

- sessions/storages 迁移（借鉴 dsh-session-sync git 镜像思路）
- 与 dshmarket 备份格式互通
- WebDAV/Gist 同步
- 跨 OS（实现已按跨 OS 设计，仅承诺保守）

许可证

MIT © 2026 dsh-migrate contributors

致谢

- dshmarket — 路由/HTTP 模式、pnpm 兼容层、备份模块参照
- dsh-super-injector — 插件形态与构建管线参照
- dsh-skin-market — pnpm 失败处理参照
- dsh-backup-sync、dsh-backup、dsh-session-sync — 生态定位对照
- DeepSeek Harness — 官方平台与 @deepseek-ai/dsh-home-paths 等标准包