前言¶
在多台机器上跑 DSH 时，profile、会话记录和工作区里的文档往往各存一份：拷 U 盘麻烦，整目录丢网盘又容易把旧文件盖掉新版本。手工合并既慢，也不容易看见「谁删了谁、两边都改过」这类冲突。
dsh-sync 是 DeepSeek Harness（DSH）上的多设备同步插件：把用户选定的本地目录做成内容快照，发布到本地目录、WebDAV 或另一台 DSH，并在设备之间做双向、增量、带冲突保护的同步；还支持 .dshsync 单文件导出与导入。维护者为 irerc，归类为联网工具；当前 package.json 版本为 1.2.0，许可证 MIT。
下面按定位、能力、安装、配置与使用顺序说明。
这是什么¶
dsh-sync 面向「需要在多设备间保持一致的那一类文件」：例如 DSH profile、会话记录、工作区文档等。同步粒度是目录内的文件内容，不是把整个 DSH 进程状态原样克隆。
远程侧有三种 target，可同时启用，一轮同步会扇出到所有已启用的 target；每个 target 维护独立同步基线，互不影响：
| 类型 | 典型用途 |
|---|---|
| local | 本机路径或 rclone、Termux 等挂载的云盘目录 |
| webdav | Nextcloud、坚果云、群晖、Alist 等 WebDAV |
| peer | 同一局域网/VPN 内另一台正在跑 DSH 的实例 |
此外可用 .dshsync 做本地发送式归档（浏览器下载/上传、Agent 工具或本地路径），适合不方便开长期同步通道时的一次性迁移。
插件以 Node 内置模块实现，README 写明不新增 npm 依赖、无构建步骤；行为以仓库内冻结版 SPEC（v1）为准。
核心功能¶
同步语义（简要）¶
- 内容寻址：每个文件按
sha256存为objects/<sha256>；各设备把自己的清单写成devices/<deviceId>.json（含 entries 与 tombstones）。 - 三方合并：对比「本地本次扫描 / 多设备清单合并 / 上次同步基线」，得到 pull、push、删除、复活、冲突等动作。
- 快照发布：一轮内先推本地变更再拉远端；冲突时本地内容保留，远端内容另存为冲突副本。
后端目录布局在 local 与 peer 存储上一致：
<store>/
├── devices/<deviceId>.json
└── objects/<sha256>
能力矩阵（README 摘要）¶
- 增量同步：三种 target 与
.dshsync导入均支持（按内容 hash 或 manifest 合并）。 - 删除传播：tombstone。
- 冲突保护：冲突副本。
- WebDAV：HTTP Basic Auth；peer：
x-dsh-sync-token。 - 设置页 UI 与 Agent 工具均覆盖配置、同步与导入导出。
安装与启用¶
前置条件：Node.js ≥ 20；可用的 DSH Web profile（dsh web）。
GUI 安装（GitHub）¶
- 打开 DSH Web GUI，侧边栏进入插件页。
- 选择安装组合包，目标填写：
https://github.com/irerc/dsh-sync.git
（也接受 https://github.com/irerc/dsh-sync。）
3. 确认 dsh-sync 出现在组合包列表且已启用；未启用 HMR 时重启 dsh web。
4. 打开 设置 → dsh-sync，应能看到状态卡、targets、roots、配对、导入导出与日志。
CLI 安装（能直连 GitHub 时）¶
dsh plugin --profile web add https://github.com/irerc/dsh-sync.git
随后在插件页勾选启用 dsh-sync，未启用 HMR 时执行 dsh web 重启。
README 还记录了在 github.com 被阻断时的替代 URL（2026-11-08 本机实测），例如：
dsh plugin --profile web add https://codeload.github.com/irerc/dsh-sync/tar.gz/refs/tags/v1.2.0
# 或
dsh plugin --profile web add https://raw.githubusercontent.com/irerc/dsh-sync/main/dist/dsh-sync-1.2.0.tgz
固定版本可将 tarball 地址换成对应 tag。配置与状态保存在 $DSH_HOME/dsh-sync/，升级插件一般不抹掉该目录。
本地目录安装（开发或离线）¶
把仓库放到目标设备绝对路径后，在插件页 安装组合包 中填写该路径，启用并视情况重启 dsh web。
说明：dsh plugin ... add 只负责依赖安装；组合包是否在 profile 中启用，需在插件页勾选，或通过 plugin_manager 工具设置。
设置页与典型配置¶
入口：设置 → dsh-sync（order 60）。主要区块包括状态卡（自动同步/保存间隔、立即同步 等）、Targets、Roots（要同步的绝对路径根目录，不可嵌套或重复，禁止 /）、一键配对码、导入/导出 .dshsync、活动日志与冲突列表。
路径字段支持 $DSH_HOME、$HOME、$DSH_PROFILE 与 ~，保存时展开为绝对路径；也可直接编辑 $DSH_HOME/dsh-sync/config.json。
WebDAV（跨网络常用）¶
{
"id": "dav",
"type": "webdav",
"label": "WebDAV",
"enabled": true,
"url": "https://cloud.example.com/remote.php/dav/files/alice",
"username": "alice",
"password": "应用密码",
"basePath": "/dsh-sync"
}
只支持 HTTP Basic Auth，建议使用应用密码并走 HTTPS。服务端需支持 WebDAV 的 PROPFIND 等操作，纯 HTTP 静态文件服务不能作为此 target。
本地或挂载目录¶
{
"id": "local",
"type": "local",
"label": "本地/挂载目录",
"enabled": true,
"path": "$DSH_HOME/dsh-sync/store"
}
路径所在文件系统需支持同目录临时文件 + rename 的原子写。
Peer（另一台 DSH）¶
{
"id": "peer",
"type": "peer",
"label": "另一台 DSH",
"enabled": true,
"url": "http://192.168.1.20:38445",
"token": "<配对区复制的 token>"
}
url 可填完整协议根（含 /dsh-sync/v1）或仅 origin，后端会自动补全且不重复拼接。两台设备须能直连；DSH Web 监听端口即为 peer 协议端口。README 指出 peer 为明文 HTTP + 静态 token，公网场景宜套 HTTPS 反向代理并妥善保管 token。
Peer 与 WebDAV 配对¶
一键配对码（推荐）：在一端配置好 WebDAV 或复制本机 peer 配对码，另一端在 设置 → dsh-sync → 一键配对码 粘贴并 连接并同步，会自动新增 target 并触发同步。若 peer 只监听回环地址，需用 --host 0.0.0.0 启动 dsh web 后再复制配对码。
也可让 Agent 调用 dsh_sync_configure 或 dsh_sync_pair；口述的密码会进入对话上下文，应使用应用密码而非主账号密码。
手动 peer：提供存储的一方在配对区复制 url 与 token；连接方新增 peer target，测试连接 会 GET /dsh-sync/v1/ping 并探测写权限，通过后启用并 立即同步。
适用场景与注意¶
适合需要在多台 DSH 环境之间同步选定目录、或希望用 WebDAV 做异地副本、偶尔用 .dshsync 做单次迁移的开发者。可同时启用 local 做本机备份、webdav 做异地备份，二者基线独立。
安装前宜自行查看 GitHub 仓库 源码与 MIT 许可证。插件随当前 dsh web 进程权限运行，roots 里填写的路径即会被读写；配对码内含 WebDAV 密码或 peer token，只发给可信设备。
社区目录 SkillHub 上的 dsh-sync 页 与 GitHub 为独立信息来源，与 DeepSeek / 幻方无官方从属关系；DSH 生态以「一切皆插件」为方向，具体行为以仓库 SPEC 与 README 为准。
结尾¶
dsh-sync 把多设备间的 DSH 相关文件目录，收敛为「内容 hash + 设备清单 + 三方合并」一套模型，并用 local、WebDAV、peer 与 .dshsync 四种出口落地。按需安装启用、在设置页配好 roots 与 target 后即可增量同步；冲突会保留副本而非静默覆盖。
- 目录页：https://www.skillhub.cn/plugins/irerc/dsh-sync
- GitHub：https://github.com/irerc/dsh-sync
