dsh-sync

dsh-sync

中文 | English

把整台机器的 dsh 状态搬到另一台机器 —— 换机后新机不只是"能跑",而是跟旧机一样: 同样的设置、同样的插件、同样的历史会话、同样的工作区列表、同样的 skills 链接。

• 三层一起走:声明层(设置 / 凭据 / 插件源码)→ 状态层(会话 / 工作区记录 / skills / 附件)→ 可选的工作区代码。
• 会话改不坏:zstd 多帧日志只重写首帧里的 cwd,事件区逐字节原样保留。
• 落地就核对:15 项检查(I1–I14 另含 I6b)逐条给 PASS / FAIL / WARN,不是"应该没问题"。
• 能再迁一次:merge=true 先出分歧清单,未决议就停在写盘之前,不静默盖掉目标机这期间的新东西。

两条路:手动搬 bundle(导出 → 拷 → 落地 → 核对),或局域网直传(配对后一条命令拉过去、自动落地并核验,不用 U 盘也不用网盘)。

术语(全文与工具输出统一按此方向):源机 = 旧机 —— 有历史、要搬出去的那台,跑 dshsync_export / dshsync_lan_host,全程只读;目标机 = 新机 —— 刚装好、要变成跟旧机一样的 那台,跑 dshsync_apply / dshsync_lan_pull / dshsync_verify。「source」永远不指「正在配置的这台」。

方向不靠插件猜:在哪台跑导出,哪台就是源机。搞反的后果与拦截见 文末折叠块「先确认哪台是新机」。

安装

dsh plugin --profile web add github:huangfuren/dsh-sync

把 web 换成你实际使用的 profile(桌面端是 desktop)。新旧两台机器都要装 —— 发送端与落地端 都在这个包里。装完重启 dsh:8 个工具与 3 条同源路由都在启动时注册,不重启既看不见也调不到。

也可以在插件市场(dsh-market)里搜 dsh-sync,从详情页一键安装。

要求:node ≥ 22.19(要有内建 zstd);走局域网直传时两台机器需在同一网段。

快速开始

三步:旧机导出 → 搬过去 → 新机落地并核对。

1. 旧机:导出

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

先 preview=true 看一眼(只扫描、不写文件),确认清单后再去掉它真跑。预览会列出工作区候选 (路径 + 体积 + 是否含 git),按名字勾选:

dshsync_export(profile="*", includeWorkspaces=true, workspaces=["dsh-chat","dsh-plugin"])
dshsync_export(profile="*", includeWorkspaces=true, workspaces=["*"])   # 全选

不传 workspaces 就是全选所有源机上存在的候选;includeGit=false 可丢掉 .git 换体积。 产出 dsh-sync-bundle/,目录结构见文末折叠块「bundle 里有什么」。源机全程只读。

2. 搬过去

A. 局域网直传(推荐) —— 不占 U 盘、不过网盘,两台机器在同一网络下走完。

源机导出完成后起一个发送端:

dshsync_lan_host()                     # bundleDir 缺省取配置里的「输出目录」(= 导出时的落点)
dshsync_lan_host(bundleDir="D:/其它")  # 也可以显式指定

它打印 6 位配对码和进度页地址(http://<源机IP>:38473/),然后立即返回 —— 服务在后台跑, 对话不会被卡十几分钟。

新机器上两种发起方式,任选:

• 卡片里点(推荐):设置 → 内置插件 → dsh-sync 迁移 → 局域网设备(展开卡片时已经广播过一次, 没找到再点「扫描」全量找)→ 点选一台 → 开始迁移(填配对码、收到哪、项目代码落到)→ 点「开始迁移」。 之后卡片里直接看进度与结果,完成后还会列出落地后的下一步(最重要的一条是重启 dsh)。
• 对话里说:先 dshsync_lan_discover() 列出开着发送端的机器,再 dshsync_lan_pull(deviceId="1", code="123456", destDir="...", workspaceRoot="E:/code")。

两条路走的是同一份执行逻辑,负责:配对 → 等你在源机页面上点「接受」→ 逐文件接收并核对 sha256 → 自动 apply → 自动 verify。dshsync_lan_status(jobId="...") 随时查。 中断了直接重跑同一条命令,已收到且哈希一致的文件自动跳过。

B. 手动拷 —— 整个文件夹拷到新电脑(U 盘 / 网盘 / 局域网共享都行)。 用 dsh-localsend 的通道时,目录树走 localsend_smb_push;它的打包器会跳过软链,本插件的 links.json 机制正是为此设计,不受影响。

bundle 自带 apply.ps1 / apply.sh,目标机不装 dsh-sync 也能落地声明层与状态层(含整包校验、 备份、回滚),但不解包工作区代码、也不改写会话 —— 改写会话需要 zstd 帧级读写,脚本里没有现成能力。 要全功能请用工具;两者共用同一套映射口径,不会"脚本改一种、工具改另一种"。

3. 新机:落地

bundle 里带了工作区代码时,一个 workspaceRoot 就够了 —— 这是换机推荐的用法:

dshsync_apply(bundleDir="D:/incoming/dsh-sync-bundle",
              workspaceRoot="E:/code",     # 你在新机器上选的项目根目录
              dryRun=true)                 # 先预演

会话 cwd、工作区路径、skills 软链会自动改到 workspaceRoot/<原名> 下,不用再写映射。 预演会逐个打印「哪个工作区 → 落到哪」「哪些会话的 cwd 会被改成什么」,确认后再 dryRun=false。

只搬 .dsh、没带工作区代码时,路径不一致就给映射,否则会话指向不存在的目录:

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

映射规则:按顺序应用、首条命中即返回、命中必须落在路径段边界 (D:/deep 不会碰到 D:/deepseek/...)。不要自创"最长前缀优先" —— 多条规则重叠时会算出 与你书写顺序不同的结果。

目标机的 $DSH_HOME 可以放在任意位置。 与源机不同时,内部软链(指向 $DSH_HOME 里的那些) 会从源前缀重定位到目标前缀、保留相对路径,并报告数量。用环境变量 DSH_HOME 指定,或在插件配置里填 dshHome。

落地之后:

1. 完全退出 dsh(桌面版从托盘退出)→ 重开,宿主按新的 package.json 重建依赖;
2. 重开后插件列表若是空的,去插件管理器点一次「重新安装 / 修复」再重启;
3. 先别在界面里改设置 —— 免得宿主把内存里的旧配置写回,盖掉刚落地的文件;
4. 想确认搬对了:dshsync_verify(bundleDir="D:/incoming/dsh-sync-bundle"), 14 项检查逐条给结论,详见文末折叠块「核对项」。

FAIL 的含义是:这部分状态 dsh 看不到。不是"可能有点问题",是确定对不上。

再迁一次(第二次及以后)

第一次迁移的目标机是空的,覆盖写怎么写都无所谓。第二次不是 —— 目标机已经用了一段时间, 它自己装过插件、注册过工作区、改过设置,而这些不在源机的快照里,一盖就没了(备份目录里有, 但没人会去翻)。

第二次开始请加 merge=true:它先把 bundle 与本机现状比一遍,只要还有一项没决定就停在写盘之前, 本机一个字节都不会动:

dshsync_apply(bundleDir="D:/incoming/dsh-sync-bundle", workspaceRoot="E:/code", merge=true)

它会列出四类分歧:

然后照着清单填 resolutions 再跑一次(其他参数不变):

dshsync_apply(..., merge=true, resolutions={
  plugins:    {"desktop/dsh-outline": "keep-target"},   # 留本机装的
  workspaces: {"w-new": "keep-target"},
  settings:   "target",                                 # 保留本机设置
  sessions:   "append-missing",                         # 只补本机缺的日志
})

• keep-target = 留本机的;take-source = 跟源机走(本机这项就没了)。
• settings 是 target / source 二选一。
• sessions 统一给一个策略:skip(不动)/ append-missing(只补本机缺的那几份日志, 已有的一个字节都不碰,包括本机自己追加的)/ prefer-source(以源机为准,会覆盖)/ prefer-target(同 skip)。
• 没填的项没有默认值 —— 这就是 merge 的意义,宁可让你多看一眼,也不能替你猜。

会话一律是文件级操作:绝不拆帧再重组,否则"历史不可能被破坏"这条保证就不成立了。 目标机还是空的(第一次迁移)不用开 merge,没有东西可冲突,直接覆盖更简单。

工具

后悔了?dshsync_undo

apply 把每一笔变动(新建 / 覆盖 / 软链 / 分组改名)记进备份目录里的落地账本(journal.json)。 dshsync_undo 倒序回放:新建的删掉、覆盖的从备份还原、软链还原旧指向、分组名改回去。 安全网是内容指纹:每笔操作记着「apply 写完那一刻」的 sha256,当前内容对不上的文件(典型是 你已经继续用 dsh、会话追加了新帧)绝不碰,逐条报告 —— 撤销永远不会拿旧快照盖掉你新产生的数据。 所以 apply 刚跑完就撤销是干净的全量回退;用过之后再撤销是"部分撤销 + 精确跳过清单"。 缺省撤最近一次(回执定位);更早的备份在存在更新 apply 时拒绝撤销 —— 一层一层退。 dryRun=true 先看。删除备份目录 = 宣布这次迁移定稿,账本随它一起消失。

deviceId 认 id / 1 基序号 / 别名 / IP 四种写法;host 与 deviceId 都不给时,用卡片里选中的那台。 一个都没选过就报错并说清三条路,不会替你挑 —— 把 bundle 传给错的一方不可挽回。唯一的例外是 「只发现一台、且你还没选过」,这时自动选中并在界面上标出来;已经选过就绝不自动改选。

配置(settings 命名空间 sync)

设置在 设置 → 内置插件 → dsh-sync 迁移 这张卡片里改。卡片上半是下面标了「可编辑」的四项, 下半两块:只读的本机状态(会话 / 工作区 / skills 数量、默认输出目录里的 bundle、局域网发送端与任务), 以及局域网设备 + 开始迁移(展开即广播一次 → 点选一台 → 填配对码与两个路径 → 点开始 → 看进度、 结果与「接下来」)。整趟迁移可以在设置页里完成,不用回对话。

后两项(includeCredentials / credentialPassphrase)不在卡片里是有意的:前者一键把明文凭据打进 bundle,后者若进表单就会明文落在 settings.yaml 里。它们仍然可以用工具参数按次传入。

密钥策略(重要)

三条路线,按推荐度排序:

1. 加密搬运(推荐):给 credentialPassphrase。settings 与凭据以 AES-256-GCM 密文进 bundle (scrypt 派生密钥,每包随机 salt / iv,带认证标签)。口令错或文件被改都会在解密时直接失败, 不会解出一份错误明文。明文密钥既不丢也不裸奔,换机后不用挨个重填插件 key。
2. 不带凭据(默认):.credentials.yaml 不导出;settings 里的明文密钥行会被剔除并告警。
3. 明文携带(不推荐):includeCredentials=true 且不给口令 —— bundle 含裸密钥, 只适用于可信信道,用完立刻删。

补充规则:明文密钥判据是 *Env 字段必须是合法引用名(^[A-Za-z_][A-Za-z0-9_]*$),否则视为填了明文; key/token/secret/password 类字段值较长也会告警。工具只输出脱敏预览(前缀 + 长度),从不回显完整密钥。

已知限制

• 目标机需自重建依赖:node_modules 不随行。落地后要在目标机装一次依赖 (桌面版:退出重开,宿主自动重建;web:pnpm install 或 dsh plugin add),否则 dsh 起不来 —— verify 的 I9 会把这件事报成 WARN,不会让你以为完事了。
• 目标机 node 需 ≥ 22.15 才有内建 zstd;否则会话不迁移(会明确告警,不静默跳过)。
• 工作区代码默认不进 bundle:不打开 includeWorkspaces 时会话能列出但打不开(I8 逐个报出)。 打开后按根打包(默认带 .git、排除 node_modules),体积会从百 MB 级涨到 GB 级,先 preview=true 看候选再决定。 落位目录已存在且非空时会拒绝覆盖,要显式 overwriteWorkspaces=true。
• 外部软链需要目标机有对应路径:skills/ 下指向 $DSH_HOME 外部的链接,目标机没有那个目录时 链接会重建失败并如实报告(I6b 单独报),不会偷改指向。
• 宿主版本跨 major.minor 时插件可能被启动时拒装,需在插件管理器逐个授予精确版本豁免。 版本一个都取不到时(既没有 dsh-runtimes 也没有 dsh 命令)如实报「需人工确认」,不猜。
• github: 依赖在目标机首次 add 可能因 pnpm ≥10 的构建门被拒;不搬 pnpm-lock.yaml(含源机绝对 link: 路径)。
• link: 依赖已自动改写为指向 $DSH_HOME/plugins/<name> 的相对路径,换位置也成立; 只有未 vendoring 的 link:(源码缺失或 includePlugins=false)才保留源机路径,并在报告里点出来。
• settings.yaml 不存在时会静默通过:本机就没有该文件(只有历史 .bak),导出不会凭空造一份; 要确认设置是否搬了,看导出报告的 homeFiles 列表。
• 局域网进度页是浏览器页面,不是 DSH 界面里的面板:宿主工具接口没有执行期流式通道 (execute() 只在结束时返回一次),所以进度走本机 HTTP + SSE。
• 传输任务的状态在内存里:插件重载(改配置、升级、重启 DSH)后 jobId 就查不到了。已收到的文件 留在盘上,重跑一次 dshsync_lan_pull 会按哈希续传。传输期间别退出 DSH。
• Windows 首次监听会弹防火墙提示,要选「专用网络」允许;选公用网络或取消,对方就连不上(报错会指到这一条)。 UDP 38472 被拦时 dshsync_lan_discover 会自动改成逐地址扫描,只是慢两三秒。

开发与测试

npm run check   # node --check 全部源文件
npm test        # 247 个测试
npm run verify

测试全部使用合成数据(自建 zstd 多帧文件 + 临时 dshHome),不读真实 $DSH_HOME、不访问外部网络; 局域网那组起真实 HTTP 服务,但只走 127.0.0.1 回环。负向用例证明校验真的会报错 (篡改 bundle → apply 拒绝执行且零写入;破坏 cwd → verify 报 FAIL;未获确认就开流 → 403; 帧里给 ../../.ssh/... → 拒绝)。

License

MIT。实现为原创 JavaScript,零第三方运行时依赖(仅 Node 内置模块)。设计过程中参考过几个公开的 MIT 项目, 参考的是设计结论而非源码,详见 THIRD_PARTY_NOTICES.md。

深入：设计与细节

以下是「为什么要这么设计」与逐条细节。只用不改的人不必读;出问题时对着这里查。

dsh-sync-bundle/
  manifest.json          # 格式版本、profile 列表、状态层统计、告警
  checksums.json         # 全部文件的 sha256
  settings.yaml          # 或 settings.enc
  .credentials.yaml      # 或 .credentials.enc;需 includeCredentials
  AGENTS.md              # $DSH_HOME 根下的全局指令
  profiles/<name>/       # package.json(link: 已改写) / cordis.patch.yml / cordis.yml /
                         #   .npmrc / pnpm-workspace.yaml / .dsh-market/state.json
  plugins/<name>/        # 每个 link: 插件的源码(已排除 node_modules/.git)
  state/
    sessions/            # 会话文件(真实文件;软链不在此)
    storages/            # workspace.json、session_projcache 等
    skills/              # 真实文件;软链不在此
    attachments/         # 附件库
    background/          # 自定义背景图
    dsh-market/          # 市场本地状态
    llm-deepseek/        # 模型文件索引
    links.json           # 软链清单:rel → target(迁移时按此重建)
    sessions.json        # 会话索引摘要
  workspaces/<name>/     # 会话真正打开的项目目录(需 includeWorkspaces;含 .git,不含 node_modules)
  tools/dsync-helper.mjs
  apply.ps1  apply.sh    # 零依赖兜底脚本
  APPLY.md

✓ 方向：源机 DESKTOP-OLD/jichen.huang → 本机 DESKTOP-NEW/jichen.huang

dsh plugin --profile desktop list     # 桌面版自带 CLI,列出该 profile 的实际依赖

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