简体中文 | English
用一台 WebDAV 服务器,把 DeepSeek Harness(dsh)的插件、技能和模型配置同步到你的所有机器。
一台装好,其余机器自动跟上。分叉时自动合并、内容自动去重,不用再重复安装、手工拷贝 settings.yaml,也不用为了对齐环境折腾一晚上。
| 能力 | 说明 |
|---|---|
| 同步插件 | profile 里的 bundle 打包上传,其他机器下载后自动安装 |
| 同步技能 | 宿主实际扫描的技能根($DSH_HOME/skills、~/.agents/skills、~/.claude/skills)下的技能目录整包同步,装一次到处可用 |
| 同步模型配置 | settings.yaml 顶层 key 按 key 合并同步,默认关闭;仅对存在 settings.yaml 的布局生效(桌面版 0.2.x 无此文件,此时该能力自动停用并在诊断页如实显示) |
| 双向 / 单向 | 每台机器可独立选择双向、仅上传、仅下载 |
| 内容寻址存储 | 目录内容与 zip 本体各算一份 SHA-256:同一条目重传命中远端已有文件时复用;下载后先校验 zip 哈希、再复核内容 hash,任一不符拒绝安装 |
| 三路智能合并 | base 取上次同步快照,只有两端都改过才算分叉;分叉按修改时间、再按版本号裁决赢家,输家自动备份 |
| 默认全自动 | 分叉自动裁决、下载即安装、删除自动传播、定时开关保存即生效,不需要人工处理冲突 |
| 删除传播 | 一端删除,另一端跟随:远端进 trash/,本地先备份;单轮删除量异常时由批量护栏整批阻断待确认 |
| 实时进度 | 阶段 + 百分比 + 上传/下载/合并/跳过/删除计数 + 当前条目,运行中随时取消 |
| 结构化日志 | 按级别与分类(上传/下载/合并/跳过/删除/去重/冲突/连接/调度/环境)落盘 JSONL,界面可筛选、搜索、导出 |
| 干跑分析 | 同步前先看差异清单(每个条目要上传、下载、合并还是跳过),只读不写 |
| 自动清理 | 远端 tombstone 与超期 trash 自动清理,本地备份按份数轮转(默认保留 10 份) |
在 dsh 的 Add plugin 向导里搜索 dsh-webdav-enhanced 并安装,或用 CLI:
# 桌面版(Electron):profile 名为 desktop
dsh plugin --profile desktop add dsh-webdav-enhanced
# Web 版:profile 名为 web
dsh plugin --profile web add dsh-webdav-enhanced本地开发版(link 安装,重新构建后重启即可生效):
dsh plugin --profile desktop add link:/path/to/dsh-webdav-enhanced装好后重启 dsh。面板有两个入口,内容完全一致:
- 插件详情页:左侧边栏 插件 → 已安装插件 → 点开 WebDAV 同步(包名
dsh-webdav-enhanced),面板占详情页主体,共 7 个页签,第一个是「概览」。 - 设置弹窗:左侧导航里的 WebDAV 同步 独立设置页,和插件页是同一套面板。
说明:配置页注册在
plugins.bundle.config、plugins.row.config与设置弹窗的settings.section(idwebdav-sync)三个插槽上。包内locale/*.json提供列表里的标题、描述与详情文档路径,icon.svg提供图标;缺任意一项时 dsh 会退回包名与默认插画。
- 看一遍「说明」:面板里的「说明」页签是卡片化的上手文档,快速开始、能力地图、同步规则、兼容性、安全与 FAQ 都在里面。
- 连接:填 WebDAV 地址、账号、密码,点「测试连接」。测试会依次验证 PROPFIND、MKCOL、PUT 与回读,并探测服务端是否支持 LOCK / If-Match。
- 内容:勾选要同步的东西。默认插件 + 技能,模型配置默认关闭。
- 方式:选择方向与定时间隔(例如每 1 小时)。默认双向、不定时。
- 同步:回「概览」点「分析差异」先看清单,确认后点「立即同步」;进度卡会实时显示阶段、百分比与逐条结果。
每个页签点一次「保存」。测试连接通过后可直接点「立即同步」跑第一次。
插件详情页与设置弹窗共用这 7 个页签,顺序固定:
| 页签 | 内容 |
|---|---|
| 概览 | 状态头(连接 / 机器 / 上次同步 / 方向)、立即同步 + 进度卡、最近一次运行分类统计、一键「分析差异」结果表 |
| 说明 | 卡片化文档:快速开始、能力地图、同步规则、服务器兼容、安全、FAQ、关于(版本 / 机器 ID / 数据目录) |
| 连接 | 地址、账号、密码、测试连接、高级(超时 / 远端根目录 / 忽略自签 TLS)、服务端能力 |
| 内容 | 插件 / 技能 / 配置三组,模式选择 + 条目勾选 + 排除项 |
| 方式 | 方向、定时开关与间隔、冲突策略、智能选项开关组 |
| 日志 | 级别与分类筛选 + 搜索 + 列表 + 导出,运行中自动刷新 |
| 诊断 | 环境 KV、锁持有者、服务端能力、重新探测、危险区(重置本机 / 清空远端) |
常用项都能在设置页里改,其余通过 profile 的 cordis.patch.yml 配置:
| 字段 | 默认 | 说明 |
|---|---|---|
profile |
自动探测 | 要同步的 dsh profile 名。留空时按「哪个 profile 装了本插件」判定,桌面版得 desktop、Web 版得 web |
connection.url / connection.username |
空 | 也可在设置页填写 |
connection.password |
— | v0.5 起 cordis 配置不再接受密码字段;只在设置页填写,存本机凭据文件 |
options.timeoutMs |
30000 |
单次 WebDAV 请求超时(毫秒) |
options.remoteRoot |
/dsh-sync/ |
远端同步根目录 |
options.ignoreTlsErrors |
false |
仅内网自签证书场景开启 |
schedule.enabled / schedule.intervalHours |
false / 1 |
定时同步开关与周期,保存即生效,无需重启 |
conflictPolicy |
auto |
冲突策略,见下文「冲突策略」 |
syncOptions.propagateDeletions |
true |
删除传播:一端删除另一端跟随 |
syncOptions.autoResolve |
'auto' |
分叉裁决方式:auto / local / remote / manual |
syncOptions.dedupeRemote |
true |
跨条目远端去重:远端已有同 hash 文件时只登记不重传 |
syncOptions.autoInstall |
true |
下载后自动安装:bundle 走插件安装、技能解压、配置按键合并 |
syncOptions.contentMerge |
true |
配置按顶层 key 合并,不再整体覆盖文件 |
syncOptions.maxBackups |
10 |
每类条目保留的本地备份份数,超出删除最旧 |
syncOptions.pruneTombstones |
true |
同步结束后清理远端 tombstone 与超期 trash |
syncOptions.hardDelete |
false |
是否在结束后物理删除远端 tombstone(默认只清 trash) |
syncOptions.bulkDeleteGuard |
true |
批量删除护栏:单轮 delete-local 超过 3 条且超过远端存活数 30% 时整批阻断,需在界面确认后重跑 |
scope.* |
插件 + 技能 all,配置 none |
同步范围 |
- 插件:profile
package.json依赖里带dsh.bundle标记、或列在dsh.profile.bundles里的条目,按本地路径打包;link 安装的目录视为开发工作区,只上传、不会被删除传播搬走。 - 技能:按宿主实际扫描的多个根目录(
$DSH_HOME/skills、~/.agents/skills、~/.claude/skills,按存在性取用、realpath 去重)中每个含SKILL.md的目录,连内部文件一起同步;新下载的条目落到第一个现存根。 - 配置:
settings.yaml的顶层 key,可用includeKeys精确指定。.credentials.yaml永不参与;apiKey等敏感顶层 key 整段跳过,保留块内的敏感字段行(apiKey:、token:等)逐行剔除并计数告警。
配置模式选「全部」时同步所有非敏感顶层 key;选「指定」时只动 includeKeys 列出的 key。
范围是双向生效的:某类选「不同步」或把条目加进排除列表后,既不扫描上传,也不会从远端下载;删除传播同样不会碰它。
v0.4.0 起默认策略是 auto:两端都改过才算分叉,分叉时自动按「修改时间 → 版本号 → 远端优先」裁决赢家,输家自动备份,不产生需要人工决策的冲突。
| 策略 | 行为 |
|---|---|
auto(默认) |
修改时间差 > 2 秒时新的赢;差距 ≤ 2 秒按版本号裁决;仍相同则远端赢(避免两机互踢)。输家自动备份 |
merge-backup |
兼容旧版:分叉时下载远端版本,本机旧版本备份 |
ask |
兼容旧版:只在显式选择时生效,不裁决,冲突条目落进报告并在界面标红 |
local-wins |
固定本机赢,上传本机版本覆盖远端(远端旧版本进 trash) |
remote-wins |
固定远端赢,下载远端版本覆盖本机(本机旧版本先备份) |
想彻底退出自动模式、每次都人工过一遍冲突,把 conflictPolicy 设为 ask;其余情况保持默认即可。
| 服务 | 说明 |
|---|---|
| Nextcloud / ownCloud | 完整支持,请使用应用专用密码 |
| 坚果云 | 可用,需在账号设置里开启 WebDAV 并使用应用密码;有频率限制,建议间隔 ≥ 1 小时 |
| 群晖 Synology | 安装 WebDAV Server 套件后完整支持 |
| AList | 完整支持,任意存储驱动 |
| 自建服务 | 任意 RFC 4918 实现;不支持 LOCK 时自动降级为软锁,不支持 If-Match 时提交后回读校验,检测到覆盖冲突自动重试 |
v0.5 把安全边界作为首要修复目标,以下承诺与实现逐条对应:
- API Key 默认不同步:
.credentials.yaml永不参与;settings.yaml里apiKey等敏感顶层 key 整段跳过;保留块内的apiKey:/token:等字段行也会被逐行剔除,剔除数量在日志中如实告警。 - 密码不出本机:WebDAV 密码只写
$DSH_HOME/.webdav-enhanced/credentials.json(原子写;0600 权限仅在 POSIX 生效,Windows 依赖用户目录 ACL——建议配应用专用密码),不进 cordis 配置、不上传远端;接口返回的配置里永远不含密码。 - 远端数据全部视为不可信:清单条目逐条结构校验(name/hash/file 越界即丢弃并告警);包内
_meta与清单身份交叉核对;所有落盘路径 resolve 后断言在管理根内。 - 下载完整性:zip 本体按 SHA-256 校验,解包后目录再按内容 hash 复核,任一不符拒绝安装。
- 删除有兜底:远端删除进
trash/保留 7 天(按落站时间戳判定,判不了龄就保留);本地删除前先备份;单轮批量删除超阈值时整批阻断待确认。 - link 工作区保护:不在 profile/skills 管理范围内的目录(如
link:指向的源码工程)永不被删除传播搬走。 - 设置页 API 仅同源可达:
/api/webdav-enhanced/*校验Origin/Sec-Fetch-Site,浏览器里的第三方页面打不进来;请求体限 2 MiB。 - 传输超时兑现:
timeoutMs对每次 WebDAV 请求生效(AbortSignal),不会因单次挂起卡死整条同步链。
/dsh-sync/
├── manifest.json # 全局账本:条目、hash、版本、来源机器、删除墓碑
├── locks/sync.lock # 软锁(服务端支持时用原生 LOCK)
├── bundles/*.zip # 内容寻址的插件包
├── skills/*.zip # 内容寻址的技能包
├── configs/*.zip # settings.yaml 片段(可选)
└── trash/ # 删除与冲突的兜底副本,超期自动清理
每次同步结束会清理墓碑与超过 7 天的 trash,由 syncOptions.pruneTombstones 与 hardDelete 控制。
$DSH_HOME/.webdav-enhanced/
├── webdav-enhanced.json # 同步配置与状态(不含密码)
├── credentials.json # WebDAV 密码(0600,不进 git、不上远端)
├── hash-cache.json # 扫描哈希缓存,加速差异分析
├── backups/<kind>s/ # 合并 / 覆盖前的本地备份,按 maxBackups 轮转
└── logs/sync.jsonl # 结构化日志(>1MB 轮转为 sync.1.jsonl)
插件向 dsh 注册两个工具,可以直接在对话里调用:
| 工具 | 用途 |
|---|---|
webdav_sync_status |
查询上次同步时间、机器 ID、环境探测结果、定时配置 |
webdav_sync_now |
立即执行一次同步并返回报告 |
| 现象 | 原因 | 解决 |
|---|---|---|
| 插件页里找不到面板 | 面板有两个入口:插件详情页与设置弹窗 | 插件 → 已安装插件 → WebDAV 同步;或设置弹窗左侧的「WebDAV 同步」,两处是同一套面板 |
| 进度卡停在某个阶段不动 | 单条大文件传输慢、服务端限速,或在等软锁 | 看「日志」页签最新一条消息;仍不动就点「取消」,检查网络与远端锁;坚果云这类有限速的服务把定时间隔放到 ≥ 1 小时 |
| 日志在哪里看 | 界面和文件都有 | 面板「日志」页签可筛选、搜索、导出;落盘在 $DSH_HOME/.webdav-enhanced/logs/sync.jsonl |
| 备份在哪里找 | 合并或覆盖前的旧版本 | $DSH_HOME/.webdav-enhanced/backups/<kind>s/,按 syncOptions.maxBackups 轮转(默认 10 份) |
| 自动合并会不会丢数据 | 不会 | 输家版本自动备份,远端删除进 trash;想全部人工确认可把 conflictPolicy 设为 ask |
| 想先看差异再同步 | 干跑分析 | 概览 → 「分析差异」,只列清单,不写任何东西 |
| 定时同步改了不生效 | 旧版需要重启 | v0.4.0 起保存即生效;仍不跑就看「日志」里调度分类的记录 |
| 列表里只显示包名、没有图标 | dsh.client 或 icon / locale 导出缺失 |
0.3.0 起已内置,确认安装的是 >=0.3.0 |
| 测试连接 401 | 账号或密码错误 | Nextcloud、坚果云需使用应用专用密码;改了密码请重新在面板里输入并保存 |
| MKCOL / PUT 返回 423 | 远端目录被 LOCK 锁住 | 「测试连接」不再锁目录;若仍报 423,等 10–60 秒或重启 WebDAV 服务端清掉残留锁 |
| readback 返回 404 | 上一步 PUT 没写进去 | 先解决 423 / 403;文件根本没落盘时读回必然 404 |
| MKCOL 返回 405 | 目录已存在 | 无害,同步继续 |
| 同步返回 412 | 远端在合并期间被改动 | 自动重试 3 次;持续失败说明另一台机器正在同步 |
| 同步很慢 | 目录里混入大文件 | node_modules 已自动排除,其余请加入排除列表;也可先在概览点「分析差异」确认这次要动多少条目 |
| 技能同步后不可见 | dsh 缓存了技能索引 | 新开对话或重启 dsh web |
| 插件安装后未生效 | dsh 启动时加载插件 | 点提示条上的「重启」,或手动重启 |
npm install
npm run check # 类型检查 + 测试 + 构建npm run build 先跑 tsc 产出 lib/*.js,再把 src/client.js 复制成 lib/client.js。前端是纯 JS、无 import,不需要打包器;dsh 通过 exports["./client"] 加载它,格式为 window.__ModuleLoader__.load({ id, factory })。
测试使用内置的 mock WebDAV 服务(tests/mock-webdav-server.ts),无需真实服务器即可跑通完整同步流程。