前言¶

DeepSeek Harness（DSH）的日常状态分散在 $DSH_HOME：各 profile 的插件清单、本地 link: 插件源码、历史会话、工作区列表、skills 软链、市场分组与停用记录等。换电脑或重装系统时，若只拷贝部分目录或整包复制 ~/.dsh，常见结果是「能启动但和旧机不一样」：插件加载不对、会话列表空、工作区路径对不上。

社区插件 dsh-sync（维护者 huangfuren，分类：工作流）针对的是「声明层 + 状态层」一起迁走，并在目标机按路径映射改写会话与工作区记录。导出物是一个可移植 bundle，并附带 apply.ps1 / apply.sh；接收方不必安装 dsh-sync，跑一次脚本即可恢复声明层；若需要路径重映射、会话 cwd 改写与一致性核对，则在目标机使用插件提供的 dshsync_apply / dshsync_verify 工具。

这是什么¶

dsh-sync 把本机 dsh 配置与状态打包成 dsh-sync-bundle：包含 settings（凭据可选）、各 profile 的清单与 patch、link: 插件 vendored 源码，以及 sessions、storages、skills 等状态层内容。bundle 内带整包 sha256 校验与自安装脚本。

插件当前版本为 0.4.2（见仓库 package.json），许可证 MIT。实现为原创 JavaScript，运行时仅依赖 Node 内置模块；在 SkillHub 插件目录 可查看条目，源码在 GitHub：huangfuren/dsh-sync。

两层状态：缺一层就不算「一致」¶

README 把迁移对象分成两层，下面介绍各自包含什么、缺了会怎样。

声明层：settings.yaml、可选凭据、home 级 cordis.patch.yml、AGENTS.md、每个 profile 的 package.json / cordis 相关文件 / pnpm-workspace.yaml / .dsh-market/state.json，以及每个 link: 插件的源码。缺了会导致 dsh 起不来、插件未加载、停用与分组回到默认，或 agent 行为与旧机不同。

状态层：sessions/、storages/、skills/、attachments/、background/、dsh-market/、llm-deepseek/。缺了则 dsh 能跑，但历史会话、工作区列表、skills、附件与背景等为空。

profiles/<n>/package.json 同时决定「装什么」（dependencies）和「加载什么」（dsh.profile.bundles）。导出时会把其中的 link: 绝对路径改写成 link:../../plugins/<name>，指向 bundle 内 vendored 的源码，目标机 $DSH_HOME 位置可变。

下列内容 intentionally 不搬：node_modules（含平台相关原生模块）、dsh-runtimes、cache、logs、.anonymous-user-id（机器身份）。

核心功能¶

导出（源机只读）¶

在已安装并启用插件的源机上调用 dshsync_export。导出过程只复制，不修改源机配置。

两种落地路径¶

会话改写依赖 zstd 多帧读写（只替换首帧 header 中的 cwd，事件区逐字节保留）；PowerShell 脚本路径做不了帧级改写，因此完整迁移需 Node ≥22.15 的内建 zstd（README 已知限制中写明低于此版本时会话不迁移并告警）。dshsync_apply 与脚本共用 lib/path-map.js 的映射规则。

软链与传输¶

软链实体不直接打进 bundle，而是写入 state/links.json，落地时再重建，避免 zip、网盘或部分传输通道把符号链接摊平。README 提到与 dsh-localsend 的 localsend_smb_push 联用时，打包器会跳过软链，links 清单机制仍适用。

密钥与 bundle 安全¶

默认不导出 .credentials.yaml；settings 中疑似明文密钥会剔除并告警。推荐设置 credentialPassphrase（≥6 位），对 settings 与凭据做 AES-256-GCM 加密搬运。apply 前校验 checksums；覆盖前备份到 $DSH_HOME/.dsh-sync-backup-<时间戳>/。

安装与启用¶

README 未给出固定的 dsh plugin add … 一行命令。请在 SkillHub 目录页 按社区说明，在源机（以及需要在目标机使用 dshsync_apply / dshsync_verify 时）安装插件。

安装前建议自行查看 GitHub 仓库源码与 MIT 许可证。插件在 当前 dsh 进程权限下运行，导出会读取 $DSH_HOME 下的配置与会话；凭据相关选项会触及密钥文件，请按 README 的密钥策略选择加密或省略。

环境要求（来自 package.json）：Node ≥22.19；dsh 版本需满足其 engines.dsh 范围。peer 依赖包括 @deepseek-ai/dsh-tools 与 @deepseek-ai/cordis。

典型用法¶

1. 旧电脑：导出 bundle¶

先用预览确认扫描结果，再去掉 preview 正式导出：

dshsync_export(profile="*", includeCredentials=true, credentialPassphrase="<你记得住的口令>", preview=true)

正式导出后得到 dsh-sync-bundle/（默认输出目录名，可通过 settings 命名空间 sync 的 outDir 调整），其中包括 manifest.json、checksums.json、改写后的 profile 与 plugins/、state/、以及 apply.ps1、apply.sh 和 APPLY.md。

2. 拷贝 bundle¶

将整个文件夹拷到新机器（U 盘、网盘、局域网等均可）。

3. 新电脑：落地¶

若盘符、用户名或项目根路径不同，必须提供映射；建议先 dryRun=true：

dshsync_apply(bundleDir="D:/incoming/dsh-sync-bundle",
              mappings=[{"from":"D:/deepseek","to":"E:/code"}],
              dryRun=true)

确认预演无误后设 dryRun=false 执行。两台机器目录结构完全一致时可省略 mappings。映射按书写顺序应用，首条命中即返回，且命中须在路径段边界（README 有具体说明，勿自行改为「最长前缀优先」）。

若只需恢复声明层、且路径无需改写，可仅运行 bundle 内的 apply.sh 或 apply.ps1，无需在目标机安装 dsh-sync。

4. 新电脑：核对¶

dshsync_verify(bundleDir="D:/incoming/dsh-sync-bundle")

工具按 I1–I10 共 10 项不变量给出 PASS / FAIL / WARN；README 对每一项有表格说明。FAIL 表示该部分状态 dsh 无法正确看到，不是轻微差异。

settings 命名空间 sync（节选）¶

适用场景与注意¶

适合：换机、重装后希望新机 dsh「与旧机同一套插件、会话、工作区列表与 skills」；开发机与笔记本之间迁移本地 link: 插件与 profile 状态；需要在目标机验证迁移是否完整。

务必注意：

• 落地后目标机需自行 pnpm install 或 dsh plugin add 重建 node_modules，verify 的 I9 会以 WARN 提醒，不会静默略过。
• 会话 cwd 指向的工作区代码在 $DSH_HOME 之外；仅迁 dsh 状态时，目标机缺少对应目录则会话可列出但打不开，I8 会列出缺失路径。需同步拷贝仓库，或用 mappings 指到已有目录。
• includeState=false 时得到的是「能用的空环境」，不带历史会话与工作区记录。
• 社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系；插件星标以目录页展示为准（当前线索为 0）。

结尾¶

dsh-sync 解决的不是「拷贝一个文件夹」，而是按 DSH 真实数据结构导出、改写路径依赖、并在目标机可脚本化落地与核对。导出端只读；接收端可以只靠 bundle 脚本恢复声明层，完整会话与工作区迁移则依赖 Node 侧的 apply / verify 工具。

• 插件目录：https://www.skillhub.cn/plugins/huangfuren/dsh-sync
• 源码与详细说明：https://github.com/huangfuren/dsh-sync