前言¶
DSH 环境里，一个 profile 通常不只包含 profile 配置，还可能包含 settings.yaml、.agent-presets、vendor/ link 目录等内容。换机时如果只手工复制目录，容易遗漏 link 映射、vendor 包和 settings 配置；如果直接导入，又缺少版本校验、备份和失败回滚。
下面介绍 dsh-migrate。它把 DSH 配置迁移整理成固定流程：源机导出打包，目标机导入还原，中间做预检、备份、校验，失败时回滚。
这是什么¶
dsh-migrate 是一个 DSH 配置迁移工具，定位是：
DSH 配置迁移工具：导出/打包 → 换机还原 → 校验 + 回滚。
它由 ygcdsj 维护，GitHub 仓库为 ygcdsj/dsh-home-migrate，包名为 dsh-migrate，许可证为 MIT。package.json 显示版本为 0.0.11，README 标注为 experimental。
它主要解决同 OS 环境下的 DSH 配置迁移问题，覆盖 profile 配置、settings.yaml、.agent-presets 和 vendor/ link 目录。MVP 限定同 OS；跨 OS 会在预检阶段明确拒绝。
核心功能¶
导出¶
导出阶段会扫描 ~/.dsh，范围包括：
- profiles 配置
settings.yaml.agent-presetsvendor/link 目录
对 settings 和 presets 会做字段级凭据扫描和脱敏，处理明细会进入 manifest 的 secretReport。
vendor 包配置文件内的疑似凭据会原地脱敏。迁移后的 vendor 包如果依赖被脱敏的值，例如 API token，需要在目标机重新配置。
打包¶
导出产物是一个单一 .dshmig 文件，本质是 zip 包。
它内置 manifest，包含：
- 版本
- 平台
- 文件清单
sha256校验和link映射
导入¶
导入阶段会先做预检，再执行还原。预检检查：
- 同 OS
- dsh 版本
- 磁盘空间
导入不会直接覆盖现有 profile，而是默认新建 profile，名称形如：
<name>-migrated
如果目标机已存在同名 profile，会自动递增。
还原顺序为：
link:路径重算vendor/presets/settings还原pnpm install- 验证链
- 失败自动回滚
验证链包括链接解析和 dsh --dump-config。
入口¶
dsh-migrate 提供两类入口：
- 设置页「迁移」入口，包含导出向导和导入向导
- host 工具
dsh_migrate_export和dsh_migrate_import，可被 agent 直接调用
安装与启用¶
已核实的安装示例如下，针对 web profile：
# 在 profile 目录内执行
dsh plugin --profile web add dsh-migrate
包信息显示如下：
version: 0.0.11
license: MIT
peerDependencies:
@deepseek-ai/dsh-client-ui-slots: ^0.1.1-rc.2
cordis: >=4.0.0-rc <5
从 0.0.9 起，迁移包会带 dsh-migrate 自己。历史版本 ≤0.0.8 不带，目标机需要手动安装。
典型用法¶
设置页导出¶
在源机执行：
- 进入设置 → 迁移
- 预览导出内容，包括文件清单、大小、排除项、疑似凭据
- 执行导出
导出产物位于：
~/dsh-migrate-exports/*.dshmig
目标机导入¶
在目标机执行：
- 进入设置 → 迁移
- 输入
.dshmig路径 - 查看预检结果，逐项确认
- 确认步骤清单
- 执行导入
- 查看验证链结果与备份目录
导入完成后，迁移结果在新建的 <name>-migrated profile 中。
启动迁移后的 profile¶
如果迁移的是 web profile，已核实的启动示例为：
dsh --profile web-migrated
host 工具¶
导出预览：
dsh_migrate_export { dryRun: true }
执行打包：
dsh_migrate_export { dryRun: false, outDir }
导入预检：
dsh_migrate_import { archive, dryRun: true }
执行导入：
dsh_migrate_import { archive }
导入失败时会自动回滚。
开发与测试¶
已核实的本地测试命令：
npm test
npm run test:install
适用场景与注意¶
dsh-migrate 适合在同 OS 的 DSH 环境之间迁移 profile 配置，尤其是希望有预检、备份、校验和回滚的场景。
使用时需要注意：
- README 标注 experimental。
- MVP 限定同 OS；跨 OS 会在预检阶段明确拒绝。
- 导入会执行归档中的代码，包括
pnpm install安装脚本、bundle 插件解析，之后启动 profile 还会执行其中插件。仅导入信任来源。 - 凭据排除和脱敏是尽力而为，不是绝对保证。导出报告会列出
unscannedFiles，传输前请核对。 vendor包配置文件内的凭据会原地脱敏。迁移后的vendor包若依赖被脱敏的值，需要在目标机重新配置。settings.yaml为符号链接时拒绝覆盖。- HTTP API 仅本机回环，并有
Host白名单、CSRF token、Origin同源、Sec-Fetch-Site校验。将 DSH web 暴露到局域网会扩大导入风险，因为任何可访问者可能导入归档。 git:依赖不打包，目标机pnpm install时重新拉取，需要网络和凭据。- dsh-migrate 会运行在当前 dsh 进程权限下，安装前应检查源码与 MIT 许可证。
结尾¶
dsh-migrate 的价值不在于简单复制目录，而在于把 DSH 配置迁移整理成可预览、可校验、可回滚的流程。对于需要同 OS 换机、还原 DSH profile 配置的场景，它提供了一条相对保守的路线。
目录页：在 DSH 社区目录中检索 dsh-migrate；社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。
GitHub：https://github.com/ygcdsj/dsh-home-migrate
