前言¶
DSH 的目录、Profile、Agent 预设基本都落在本地磁盘上。换一台机器或者重装系统之后，settings.yaml、AGENTS.md、profiles/*/cordis.patch.yml 这些东西都要手工重装重配一遍；Profile 里的 pnpm-lock.yaml 和依赖锁也没法直接复制过去。自己接 WebDAV 写脚本同步，又要处理忽略规则、冲突判定和删除保护，容易写出一堆只适配自己机器的代码。
下面介绍的 2315137135/dsh-webdav-sync 就是专门做这件事的插件：只同步配置与清单，不碰设备本地数据，并在「设置 → WebDAV 同步」里提供了一个检查面板，用来解释每个文件为什么被同步或被忽略。它由 2315137135 维护，分类为联网工具，纯 JavaScript 实现，无需构建。
插件定位¶
一句话说清：在多台设备之间，通过标准 WebDAV 服务同步 DSH 的配置与插件清单，同时提供忽略规则、路径检查器和冲突策略。
它不是通用的文件同步工具。默认同步范围限定在「配置与清单」这一类文件，sessions/、storages/、附件、凭证和依赖目录都不参与；这样做的目的是避免把某台设备上的本地状态广播到其他设备。
仓库地址：https://github.com/2315137135/dsh-webdav-sync
社区目录页：https://www.skillhub.cn/plugins/2315137135/dsh-webdav-sync
同步范围¶
先明确同步什么，比直接开跑更重要。插件默认范围如下：
| 范围 | 路径 |
|---|---|
| 主设置 | settings.yaml |
| 指令 | AGENTS.md |
| Profile | profiles/*/cordis.patch.yml、cordis.yml、package.json、pnpm-lock.yaml、pnpm-workspace.yaml |
| Agent 预设 | .agent-presets/** |
| 额外范围 | 面板「设置 → 额外同步范围」，每行一个 glob |
几个容易踩的点：
- Profile 的
package.json与锁文件会把 git 依赖带到其他设备，目标设备执行一次插件安装或pnpm install即可。 link:/file:安装的本地插件不会随同步迁移，面板会单独告警。- 依赖目录、会话、附件和凭证默认不同步，插件自身建议从 GitHub 安装。
默认忽略规则¶
忽略规则按顺序匹配，后出现的优先；! 前缀可以重新包含。默认规则包括：
sessions/、storages/、attachments/、dsh-runtimes/、webdav-sync/**/node_modules/、**/.git/、**/.cache/profiles/*/.dsh-market/、profiles/*/.plugin-manager/logs/.credentials.yaml（可在面板开启）、.env、.anonymous-user-id、settings.yaml.imported***/*.log、**/*.tmp、系统文件
面板的「忽略规则」页可以调整范围与规则，路径检查器能实时回答「这个路径为什么同步 / 为什么忽略」；「文件」页则按状态筛选，并对误同步的文件提供一键追加忽略规则。所有规则和每条命中原因都可见，不是黑盒。
安装与启用¶
从 GitHub 安装，纯 JavaScript，无需构建。在 DSH 里执行：
plugin_manager install_bundle
target: github:2315137135/dsh-webdav-sync
也可以使用 git+https://github.com/2315137135/dsh-webdav-sync.git，或克隆到本地后用绝对目录安装。安装后刷新 Harness 页面，菜单里就会出现「设置 → WebDAV 同步」。
需要说明的是，这个插件以当前 DSH 进程的权限运行。安装前应先打开源码检查一下（仓库为 MIT 许可），确认 client.js、index.js 等文件与你的部署环境没有冲突。
典型用法¶
先做 WebDAV 服务配置，再做首次同步，之后按需设置自动同步。
- 打开「设置 → WebDAV 同步 → 设置」，填写服务器地址、用户名、密码和远程目录，点「保存并测试」。标准 WebDAV 实现即可，README 中提到坚果云、Nextcloud、ownCloud、群晖等均可。
- 在「概览 → 检查差异」查看上传 / 下载 / 冲突数量，确认结果符合预期。
- 点「立即同步」按当前方向与策略执行。冲突策略可选较新优先、本地优先、远程优先或跳过。
- 「文件」页按状态筛选，逐文件查看原因。
同步方向有三档：
two-way：双向，默认push：只上传pull：只下载
删除行为默认是「保留另一侧文件」，也就是说某台设备删了文件，不会把其他设备上的删掉。需要在面板中显式切换为「同步删除」。即使切换为同步删除，一次计划中超过 3 个本地删除也会被拦截并保留，避免远程异常导致本地被批量清空。
凭证、自动同步与 Agent 工具¶
凭证和传输安全的处理方式：
- 密码保存在
$DSH_HOME/webdav-sync/config.json，文件权限0600；留空表示沿用已保存的密码。 - 也可以用环境变量
DSH_WEBDAV_PASSWORD提供密码，配置文件中不落盘。 - 传输使用系统 TLS 校验；自签证书需要在面板中显式开启「忽略 TLS 证书校验」。
- 只支持 Basic Auth 和标准 WebDAV 方法（PROPFIND / GET / PUT / DELETE / MKCOL）。
自动同步：把间隔设为大于 0 的分钟数即可，修改后立即生效；设为 0 关闭。
Agent 工具有三个：webdav_sync_status、webdav_sync_plan、webdav_sync_run。
已知边界¶
先看这些限制，决定它是否适合你的场景：
- 逐文件同步，没有跨文件事务；中断后再次同步会按基线补齐。
- 远程身份优先使用 ETag；服务器不返回 ETag 时退化为大小 + 修改时间。
- 单文件默认上限 2 MB，可在面板调整；超过上限的文件会被跳过并在「文件」页标出。
- 不处理文件名大小写冲突与符号链接。
冲突判定基于每个设备上次成功同步的基线（本地状态文件）。首次在新设备上同步时，如果远程存在基线清单，会用它初始化比较，避免把所有文件误判为冲突。这一点对首次接入很重要。
开发与测试¶
仓库自带测试，纯 Node 运行：
node --check index.js
node --check client.js
node test/ignore.test.js
node test/plan.test.js
node test/sync.test.js
node test/client-render.test.js
node test/client-i18n.test.js
node test/live-sync.mjs # 需要 DSH 正在运行，使用临时本地 WebDAV 服务
node --test test/ 在某些受限环境会因无法创建子进程而失败；直接运行单个测试文件即可。
小结¶
dsh-webdav-sync 解决的是配置漂移问题：把「哪些文件要同步、为什么忽略、冲突怎么判」这套逻辑固化进插件，并提供可检查的面板，而不是让每个使用者维护一套自己的同步脚本。它以当前 DSH 进程权限运行，同步范围默认保守，适合有多台设备、且希望配置可复现的 DSH 开发者。
目录页：https://www.skillhub.cn/plugins/2315137135/dsh-webdav-sync
GitHub：https://github.com/2315137135/dsh-webdav-sync
