把 DSH 的可移植配置备份 / 同步到任意 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。
| 段落 | 来源 | 归档内前缀 |
|---|---|---|
skills |
$DSH_HOME/skills |
skills/ |
agentsSkills |
$DSH_AGENTS_HOME(默认 ~/.agents)/skills |
agents-skills/ |
mcp |
$DSH_HOME/profiles/<profile>/ 下的 cordis.patch.yml(含 DSH 全局设置:模型 provider、权限预设、主题偏好)、cordis.yml、package.json、pnpm-workspace.yaml、pnpm-lock.yaml |
mcp/ |
plugins |
profile 里所有 link: 依赖指向的插件源码(跳过 node_modules、dist) |
plugins/<包名>/ |
instructions |
$DSH_HOME/AGENTS.md、~/.agents/AGENTS.md |
instructions/ |
storages |
$DSH_HOME/storages(排除 session_projcache) |
storages/ |
memories |
$DSH_HOME/memories(跨会话记忆库) |
memories/ |
localPlugins |
$DSH_HOME/local-plugins(从本地路径安装的插件副本) |
local-plugins/ |
skillLock |
~/.agents/.skill-lock.json(技能来源清单) |
agents/ |
profiles |
其余 profile 的配置文件(cordis.patch.yml 等 5 个) |
profiles/<name>/ |
| 模型凭据 | $DSH_HOME/.credentials.yaml(需显式开启,加密后进包) |
secrets/.credentials.yaml.enc |
注意:这类凭据会加密进快照,但恢复时不会写回(见文末「已知限制」第 5 条)。不要把快照当密钥备份。
会话历史、附件、dsh-runtimes、node_modules、storages 缓存永不进包。
- 默认不含任何明文密钥,三类规则:
Authorization: Bearer xxx全文件替换;- 已知令牌前缀(
sk-、ghp_、AKIA、AIza、xox?-、hf_、npm_、afxp_、sk-ant-)不区分文件位置,命中即处理——覆盖storages/*.json这类插件状态文件里存的 key; mcp/、.env、*credential*里的key = value,只在值“像真密钥”时处理(长度 ≥ 16、无$ % < {)。
- 已经是
__SECRET__占位符或__ENC:…__令牌的值不会二次加密(否则会变成「密文的密文」,永远解不出真值)。 - 处理过的位置记在
manifest.json的placeholders里(含encrypted标记),/csync pull会说明「已还原 N 处」或「需重填 N 处」。 - 恢复保护:没有口令解不开的
__ENC__令牌、或只有__SECRET__占位符时,若本地已有真实密钥就判为"密钥保护跳过",不会覆盖本地真值(计划里以!标记)。
口令丢失 = 加密内容不可恢复。
__ENC令牌用 AES-256-GCM 加密,没有口令就无法解密; 恢复时若口令不匹配:本地已有真实值的文件判为「保护跳过」,既不覆盖也不改动;本地缺失的文件会写入__SECRET__占位符(提示你手填),不会把密文原样落盘。 由于口令即 WebDAV 应用密码,在坚果云改密码后,旧快照只能用旧密码恢复;改密码前先重新上传一份。
includeSecrets只决定要不要把.credentials.yaml本身也打进包;关闭它不影响__ENC令牌的生成与还原。
- 口令合一 = 同信任边界:口令即 WebDAV 应用密码,所以凡是能访问这份 WebDAV 的人(服务商运维、共享账号的协作者)都能解开快照里的密钥。这不是新增漏洞,而是「传输口令与加密口令复用」的必然结果;若以后支持把归档传到第三方对象存储,不要再复用传输口令。
- 加密口令默认就是 WebDAV 应用密码:文件内的密钥用该口令加密成
__ENC令牌,恢复时自动还原,无需单独设置。凭据槽CLOUD_SYNC_SECRET_PASSWORD仅作为可选覆盖(默认为空)。includeSecrets只控制要不要把.credentials.yaml本身也打进包(同样用 scrypt + AES-256-GCM)。 - 默认排除
**/node_modules/**、**/.git/**、*.exe/*.dll/...;不设单文件体积上限。
# 1. 托盘退出 DSH(确认任务管理器里没有 DeepSeek Harness 进程)
# 2. 在插件目录执行安装脚本(脚本按 UTF-8 BOM 保存,适配 Windows PowerShell 5.1)
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
# 3. 重新打开 DSH
# 4. 自检(可开着 DSH 跑)
powershell -NoProfile -ExecutionPolicy Bypass -File .\verify.ps1在任意会话里:
/csync secret <WebDAV 应用密码> # 写入 DSH 凭据槽,不落配置文件
/csync config username 你的邮箱@example.com
/csync status # 看连通性与远端快照
/csync push --dry-run # 先看会打包什么,不上传
/csync push # 真正上传
应用密码按服务生成:坚果云在「账户信息」的「安全选项」里新增「第三方应用管理」的应用密码;Nextcloud 在「设置」的「安全」里生成「设备专用密码」;群晖用账号密码或应用专用密码。
上传/恢复进行中会显示阶段与计时。关闭设置面板再打开、或在别的入口触发动作时,设置页会用服务端进度自动接管显示(常驻 1.5 秒轮询),不会回到「什么都没发生」的状态。
自动同步分两档,用来兼顾「配置频繁改动」和「技能库体积大、流量有限」:
| 档位 | 包含段落 | 默认周期 | 归档体积 |
|---|---|---|---|
| 日常档 | sections 去掉 fullOnlySections(默认去掉 skills、agentsSkills) |
跟随自动同步模式(改动后 / 定时间隔) | 约 2 MB |
| 全量档 | 全部启用段落,文件名带 -full |
fullSyncMinutes,默认 10080 分钟(每周) |
约 73 MB |
- 手动「上传」按钮始终走全量档。
- 保留策略:先按
keep保留最新若干份,另外keepFull份全量快照额外保底不删。 - 坚果云免费账号每月只有 1 GB 上传流量,全量档一周一次约 300 MB,日常档几乎不占流量。
设置页「自动同步」一行有三种模式,改完即生效(宿主每 30 秒读一次配置,不用重启):
| 模式 | 行为 |
|---|---|
| 关闭(默认) | 只能手动点上传 |
| 定时 | 每 N 分钟检查一次;距上次推送(含手动)超过 N 分钟才推送 |
| 改动后 | 监听技能目录、profile 配置、link 插件源码;最后一次改动后静默 N 秒才推送 |
两条防重复机制:
- 指纹比对:推送前对「同步清单」(路径 + 字节数 + 修改时间)算 SHA1,与上次推送记录相同就直接跳过,不会把同样的 60MB 反复上传。
- 首次基线:「改动后」模式首次启用只记录基线不推送,避免一开开关就上传全量;「定时」模式没有基线则按周期正常推送。
失败只写日志([cloud-sync] 前缀),不打断会话,也不影响手动操作。自动推送与手动上传共用同一条链路,快照内容、保留策略、状态栏完全一致。
装好后在「设置」里打开 云同步(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/压缩包等 |
keep |
5 | 远端保留份数(界面不暴露,prune 用) |
autoSyncMode |
off |
自动同步模式:off / interval / watch |
autoSyncMinutes |
60 | 定时模式间隔(分钟) |
autoSyncDebounceSeconds |
90 | 改动模式防抖窗口(秒) |
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 才完全生效。
- 整包加密的凭据负载(
secrets/.credentials.yaml.enc)不会随恢复写回(secrets/*被跳过),恢复时会明确提示——不要把快照当密钥备份。