前言¶
DSH 的插件生态采用「索引源」模式，没有全网搜索。别人要用这个插件，需要先把索引地址加进市场，然后在市场里搜「云同步」。dsh-cloud-sync 把 DSH 的可移植配置备份 / 同步到任意 WebDAV（默认坚果云，也兼容 Nextcloud、群晖、ownCloud、AList），零第三方依赖。
这是什么¶
dsh-cloud-sync 是 doraasn 维护的 DSH 插件，属于「联网工具」分类。它解决的问题是：如何把 DSH 的技能、插件源码、全局指令、模型凭据等可移植配置，安全地备份到自己的云存储，并在需要时恢复到另一台设备。
核心功能¶
- 支持同步多个段落：本机技能、共享技能、DSH 配置与插件清单、本地插件源码、全局指令、模型凭据（可选加密）
- 默认不打码明文密钥，只在值「像真密钥」时打码（长度 ≥ 16、无
$ % < {） - 加密凭据支持 scrypt + AES-256-GCM，口令来自凭据槽
- 提供命令行与图形界面，行为一致
- 提供 WebDAV 集成：默认坚果云，也兼容 Nextcloud、群晖、ownCloud、AList
安装与启用¶
DSH 的插件市场是「索引源」模式，没有全网搜索：别人要用，需要把这个索引地址加进去，然后在市场里搜「云同步」。
方式一：加索引源（推荐）
- DSH 打开 插件 → 发现 → 索引源 → 添加
- 粘贴：
https://raw.githubusercontent.com/doraasn/dsh-plugins-index/main/market-index.json
- 选中该市场，搜「云同步」或
cloud-sync，点安装。
该索引同时收录 doraasn 名下的其他 DSH 插件（额度看板、Web Chat、移动访问设置）。
方式二：命令行直接装（git）
dsh plugin --profile desktop add "git+https://github.com/doraasn/dsh-cloud-sync.git#7c98449c892c857d190422b8b6e594241ea83a99"
装完把 dsh-cloud-sync 加进该 profile package.json 的 dsh.profile.bundles，再重启 DSH（install.ps1 会自动做这两步）。
尚未发布到 npm（
dsh-cloud-sync这个名字在 npm 上已被占用），所以走 git 源。索引统一维护在 dsh-plugins-index，本仓库不再放market-index.json。
典型用法¶
在任意会话里：
/csync secret <WebDAV 应用密码> # 写入 DSH 凭据槽，不落配置文件
/csync config username 你的邮箱@example.com
/csync status # 看连通性与远端快照
/csync push --dry-run # 先看会打包什么，不上传
/csync push # 真正上传
应用密码按服务生成：坚果云在「账户信息」的「安全选项」里新增「第三方应用管理」的应用密码；Nextcloud 在「设置」的「安全」里生成「设备专用密码」；群晖用账号密码或应用专用密码。
装好后在「设置」里打开 云同步（settings.section 插槽）。卡片分四组：
- 连接：WebDAV 地址、账号、应用密码（+「保存」写入凭据槽）、远端目录
- 备份内容：六个开关，见下表；勾选即保存
- 动作：立即上传、预览备份内容、预览恢复
- 远端快照：每份快照的名称 / 大小 / 时间，逐条「预览恢复」
「备份内容」各开关对应的实际路径：
| 开关 | 内容 | 路径 |
|---|---|---|
| 本机技能（~/.dsh） | DSH 自有技能 | $DSH_HOME/skills |
| 共享技能（~/.agents） | 多个工具共用的技能目录 | $DSH_AGENTS_HOME/skills（默认 ~/.agents/skills） |
| DSH 配置与插件清单 | DSH 全局设置（模型 provider、权限预设、主题偏好）、插件与 MCP 条目、锁文件 | profiles/<name>/ 下的 cordis.patch.yml、cordis.yml、package.json、pnpm-workspace.yaml、pnpm-lock.yaml |
| 本地插件源码（link） | link: 依赖指向的插件源码（market 插件可从 registry 重装，不必打包） |
各 link: 目标目录 |
| 全局指令（AGENTS.md） | 每次会话都会读取的全局指令 | $DSH_HOME/AGENTS.md、$DSH_AGENTS_HOME/AGENTS.md |
| 模型凭据（加密） | 各模型 provider 的 API key | $DSH_HOME/.credentials.yaml（加密后进包） |
动作区：立即上传（主按钮）、预演打包、刷新快照、预演最新快照恢复；恢复必须先预演，预演结果里再点「确认恢复到本地」。
上传/恢复进行中会显示阶段与计时（依次为：正在收集文件、正在打包与校验、正在上传到云端、正在清理旧快照），期间按钮全部禁用；结束后用结构化卡片给出快照名、大小、文件数、耗时、各段落统计、跳过的大文件与占位符提示。
卡片与命令走同一份实现（lib/actions.js），因此两端行为一致。宿主暴露的接口：
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /cloud-sync/api/state |
配置（脱敏）、凭据槽状态、远端快照、上次推送、当前进度 |
| POST | /cloud-sync/api/action |
{ args: ["push"] } 形式的子命令调用 |
命令¶
| 命令 | 作用 |
|---|---|
/csync / /csync status |
配置、凭据槽、远端快照、上次推送总览 |
/csync config |
打印全部配置 |
/csync config <键> <值> |
改一项（值支持 JSON，例如 sections '["skills","mcp"]'） |
/csync secret <口令> |
写入凭据槽 |
/csync push [--dry-run] |
打包并上传，附带保留策略清理 |
/csync list |
列远端快照 |
/csync diff [快照名] |
下载并预演恢复计划（零写入） |
/csync pull [快照名] --yes |
真正落盘恢复（先自动备份，失败回滚） |
/csync prune |
按保留份数清理远端 |
配置键¶
| 键 | 默认 | 说明 |
|---|---|---|
baseUrl |
https://dav.jianguoyun.com/dav/ |
WebDAV 根地址 |
username |
空 | WebDAV 登录邮箱或用户名 |
passwordRef |
CLOUD_SYNC_PASSWORD |
口令所在的凭据槽名 |
remoteDir |
dsh-sync |
远端目录（相对 baseUrl） |
sections |
skills,agentsSkills,mcp,instructions |
同步段落 |
exclude |
[] |
额外 glob 排除，如 ["artifact-template-*/**/assets/**"] |
excludeBinaries |
true |
排除 exe/dll/压缩包等 |
maxFileBytes |
0 | 单文件上限，0 = 不限 |
keep |
5 | 远端保留份数（界面不暴露，prune 用） |
includeSecrets |
false |
是否打包 .credentials.yaml（加密） |
secretPasswordRef |
CLOUD_SYNC_SECRET_PASSWORD |
加密口令槽 |
redact |
true |
是否打码明文密钥（关掉则按原样进包） |
autoSyncHours |
0 | 定时自动推送间隔（小时），0 = 关闭；失败只记日志不打断会话 |
故障与回滚¶
- DSH 起不来：启动失败弹窗第 3 个按钮「禁用第三方插件、备份 profile patch 并重启」。
- 卸载：退出 DSH 后执行
uninstall.ps1，或手工从~/.dsh/profiles/desktop/package.json删掉依赖与dsh.profile.bundles里的dsh-cloud-sync。 - 恢复失败：
applyRestore会自动回滚；恢复前的原件复制在$DSH_HOME/cloud-sync/backup-<时间戳>/。
已知限制¶
- 密钥是否需要手填取决于口令：有口令则
__ENC__令牌在恢复时自动还原；无口令则为__SECRET__，需按提示重填。 - 单文件默认不设上限；WebDAV 服务端通常限制单文件 500 MB，超过仍需用
exclude排除。 - 图形卡片挂在设置分区
settings.section；若该插槽在你的 profile 里不可用，会退化为侧栏底部入口。 - 恢复技能与 MCP 后需要重启 DSH 才完全生效。
适用场景与注意¶
适合需要在不同设备间迁移 DSH 配置、技能和全局指令的开发者。使用前应检查源码与许可证，确认符合项目要求。
结尾¶
dsh-cloud-sync 把 DSH 的可移植配置备份 / 同步到任意 WebDAV，零第三方依赖，默认坚果云，兼容 Nextcloud、群晖、ownCloud、AList。查看目录页与源码：
- https://www.skillhub.cn/plugins/doraasn/dsh-cloud-sync
- https://github.com/doraasn/dsh-cloud-sync
