Introduction¶

DSH’s directories, Profiles, and Agent presets are generally stored on the local disk. After switching machines or reinstalling the system, files like settings.yaml, AGENTS.md, and profiles/*/cordis.patch.yml must be reinstalled and reconfigured manually; furthermore, the pnpm-lock.yaml and dependency locks in the Profile cannot be copied over directly. Connecting WebDAV yourself to write sync scripts requires handling ignore rules, conflict resolution, and deletion protection, which often leads to writing a lot of code tailored only to your specific machine.

The plugin introduced below, 2315137135/dsh-webdav-sync, is designed specifically for this purpose: it only synchronizes configuration and manifests, leaving device local data untouched, and provides a check panel in “Settings → WebDAV Sync” to explain why each file is being synced or ignored. It is maintained by 2315137135, categorized as an online tool, implemented in pure JavaScript, and requires no build step.

Plugin Positioning¶

In a nutshell: synchronizes DSH configuration and plugin manifests between multiple devices via standard WebDAV services, while providing ignore rules, path checkers, and conflict strategies.

It is not a general-purpose file synchronization tool. The default synchronization scope is limited to files of the “configuration and manifests” type; sessions/, storages/, attachments, credentials, and dependency directories are excluded; the purpose of this is to prevent local state from one device from being broadcast to other devices.

Repository: https://github.com/2315137135/dsh-webdav-sync
Community Directory: https://www.skillhub.cn/plugins/2315137135/dsh-webdav-sync

Sync Scope¶

It is more important to clarify what is being synced before running. The default scope is as follows:

Points where you might easily step on:

• The package.json and lock files in the Profile will bring git dependencies to other devices, and the target device only needs to run a plugin installation or pnpm install.
• Local plugins installed via link: or file: will not be migrated with the sync; the panel will warn separately.
• Dependency directories, sessions, attachments, and credentials are not synced by default; the plugin itself suggests installing from GitHub.

Default Ignore Rules¶

Ignore rules are matched in order, with later rules taking precedence; the ! prefix can be used to re-include. Default rules include:

• sessions/, storages/, attachments/, dsh-runtimes/, webdav-sync/
• **/node_modules/, **/.git/, **/.cache/
• profiles/*/.dsh-market/, profiles/*/.plugin-manager/logs/
• .credentials.yaml (can be enabled in the panel), .env, .anonymous-user-id, settings.yaml.imported*
• **/*.log, **/*.tmp, system files

The “Ignore Rules” page in the panel allows you to adjust the scope and rules, and the path checker can answer in real time “why this path is synced / why it is ignored”. The “Files” page filters by status and provides one-click to append ignore rules for mistakenly synced files. All rules and the reason for each match are visible; it is not a black box.

Installation and Enablement¶

Install from GitHub; it is pure JavaScript and requires no build step. Execute in DSH:

plugin_manager install_bundle
target: github:2315137135/dsh-webdav-sync

You can also use git+https://github.com/2315137135/dsh-webdav-sync.git, or clone it locally and install using an absolute path. After installation, refresh the Harness page; “Settings → WebDAV Sync” will appear in the menu.

It is worth noting that this plugin runs with the permissions of the current DSH process. You should check the source code before installing (the repository is under the MIT license) to ensure files like client.js and index.js do not conflict with your deployment environment.

Typical Usage¶

First configure the WebDAV service, then perform the initial sync, and finally set up automatic sync as needed.

1. Open “Settings → WebDAV Sync → Settings”, fill in the server address, username, password, and remote directory, and click “Save and Test”. Standard WebDAV implementations work; Nutstore (Jianguoyun), Nextcloud, ownCloud, Synology, etc., are mentioned in the README.
2. In “Overview → Check Differences”, view the counts of uploads/downloads/conflicts to confirm the results meet expectations.
3. Click “Sync Now” to execute based on the current direction and strategy. Conflict strategies available are: newer priority, local priority, remote priority, or skip.
4. The “Files” page filters by status, allowing you to view the reason for each file individually.

Sync directions have three levels:

• two-way: Bidirectional, default
• push: Upload only
• pull: Download only

The default deletion behavior is “keep the file on the other side”; this means if a file is deleted on one device, it will not be deleted on the other. You need to explicitly switch to “Sync Delete” in the panel. Even if switched to sync delete, more than 3 local deletions in a single plan will be intercepted and kept to prevent local bulk clearing caused by remote anomalies.

Credentials, Auto Sync, and Agent Tools¶

Handling of credentials and transmission security:

• Passwords are saved in $DSH_HOME/webdav-sync/config.json with file permissions 0600; leaving it blank means using the saved password.
• You can also provide the password via the environment variable DSH_WEBDAV_PASSWORD, which is not saved to disk in the configuration file.
• Transmission uses system TLS verification; self-signed certificates require explicitly enabling “Ignore TLS Certificate Verification” in the panel.
• Only Basic Auth and standard WebDAV methods (PROPFIND / GET / PUT / DELETE / MKCOL) are supported.

Auto Sync: simply set the interval to a number of minutes greater than 0; changes take effect immediately; set to 0 to disable.

Agent tools available are: webdav_sync_status, webdav_sync_plan, webdav_sync_run.

Known Limitations¶

Check these limitations first to decide if they fit your scenario:

• Synchronization is per-file without cross-file transactions; after an interruption, re-syncing will fill in the gaps based on the baseline.
• Remote identity primarily uses ETag; if the server does not return an ETag, it degrades to size + modification time.
• The default single-file limit is 2 MB, which can be adjusted in the panel; files exceeding the limit will be skipped and flagged in the “Files” page.
• Filename case conflicts and symbolic links are not handled.

Conflict determination is based on the baseline (local state file) of the last successful sync on each device. On the first sync to a new device, if a baseline manifest exists remotely, it will be used to initialize the comparison, preventing all files from being misjudged as conflicts. This is important for first-time onboarding.

Development and Testing¶

The repository comes with tests that run on pure 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   # Requires DSH to be running, uses a temporary local WebDAV service

node --test test/ may fail in some restricted environments due to the inability to create subprocesses; simply running individual test files directly is sufficient.

Summary¶

dsh-webdav-sync solves the problem of configuration drift: it hardcodes the logic of “which files to sync, why they are ignored, and how conflicts are determined” into the plugin, and provides a verifiable panel, rather than requiring each user to maintain their own synchronization scripts. It runs with the permissions of the current DSH process, has a conservative default sync scope, and is suitable for DSH developers with multiple devices who wish for reproducible configurations.

Directory: https://www.skillhub.cn/plugins/2315137135/dsh-webdav-sync
GitHub: https://github.com/2315137135/dsh-webdav-sync