@weibaohui/dsh-sync

dsh plugin --profile web add @weibaohui/dsh-sync

@weibaohui/dsh-sync



多机同步插件：让多台机器上的 dsh 通过一个私有 Git 仓库（GitCode / GitHub / GitLab / Gitee / 自建，0.4.5 起）保持一致——技能、会话、设置、插件清单都能同步。除 Git 完整同步外，还支持 WebDAV 与 本地文件夹 两种纯备份协议，各协议一个页签一个开关。

核心功能

• 多协议备份，一个协议一个页签一个开关：
• Git 仓库（默认开）：完整的 分支 → PR → 合并 同步语义，冲突显化、AI 语义合并
• WebDAV（默认关）：填地址/账号/密码/子目录即可，兼容坚果云、Nextcloud、Alist 等一切标准 WebDAV 服务；每次同步按 sha1 清单增量上传（只传变化的文件、删除同步传播）
• 本地文件夹（默认关）：填一个目录（支持 ~）即可；每次同步整目录原子镜像（tmp-swap，中断不留半截备份）
• 未开启的协议只显示开关；开启后出现地址参数配置与「测试连接」
• 纯备份协议的内容与布局和 git 的备份策略完全一致：backup/<实例ID>/…，本地永不被读回覆盖；单协议失败不影响其他协议
• 四类内容可同步，每类独立开关 + 独立策略：
• 技能 skills（默认开，策略=并集）：覆盖 ~/.dsh/skills、~/.agents/skills、~/agents/skills 三个根；新增都收、双方改动交 AI 语义合并
• 会话 sessions（默认关，策略=备份）：写 backup/<实例ID>/，各机云上独立，本地永不被覆盖
• 设置 settings.yaml（默认开，策略=备份）：机器专属配置不打架，想共享键用「AI 智能对齐」逐键并
• 插件清单（默认开，策略=备份）：各机 bundle/依赖清单互不覆盖（跨机整文件覆盖曾致宿主 crash loop）
• 四种策略：备份（各机独立，永不被覆盖）/ 并集（新增都收、逐文件三方、冲突交 AI）/ 覆盖·远端为准（本地只读镜像，远端删本地也删）/ 覆盖·本地为准（只推不拉）
• 快照：本地优先，通用上云，勾选才传
• 「立即快照」默认只落本机（~/.dsh/dsh-sync/snapshots/，滚动保留 30 份，超窗真删除真释放）；勾选「上传到云端」才写入所有已启用的云端协议（git → backup/<实例ID>/snapshots/，WebDAV / 本地文件夹同布局），永久存档
• 每天首个同步自动打一份本地快照；范围=设置+插件清单（可选含技能），永远不含会话（体积大头）
• 一键恢复：本地快照直接恢复；本地没有的按 git → WebDAV → 本地文件夹 依次回退取回；恢复前自动把当前状态再拍一份（pre-restore-*）
• 分支 → PR → 合并：每台机器的变更以 PR 形式提交，冲突显化为一个待合并的 PR，绝不静默覆盖
• 同步前自动回填：每次推送前先把远端新增、本机没动过的内容拉回本机，本机快照不会误删别的机器推上来的新技能/新配置
• AI 智能对齐：点「AI 智能对齐」，先自动回填远端新增，再由 AI 对两边都改过的文件做语义合并（动手前自动备份本机文件），合并后由系统自动推送
• AI 一键解决冲突：出现冲突时设置页冒出「AI 解决冲突」按钮，点击后由系统取回冲突分支与 main 制造冲突工作树，AI 只做本地语义解冲突，推送与 PR 合并由系统自动完成
• 浏览远端备份：点「浏览远端」可查看云端仓库的完整目录树，自动识别 backup/<实例ID>/ 下每台机器的备份并标记本机；在树中勾选文件后「预览拉取」会给出安全判定（哪些可拉、哪些会被阻止及原因），确认后才写入本地——写入前自动拍一份 pre-remote-pull 安全快照
• 跨机安全提示（不阻止拉取）：另一台机器的 插件清单（本地已有时）和 settings.yaml 跨机拉取时会⚠警告（覆盖机器专属配置可能导致宿主崩溃），但允许用户自行决定是否拉取；技能文件可安全跨机拉取；本机自己的备份无警告（恢复语义）
• 浏览是只读的：远端 main 拉进独立 ref（refs/dshsync/browse，强制更新——该 ref 相对远端 main 常处于回退状态，见 0.4.7），不写工作树、不动分支，与同步循环无竞争（有目标 refspec 的 fetch 会写 FETCH_HEAD，写的是同步循环自己也会取的同一个分支 tip）
• 安全（0.4.5 起支持多托管方）：GitCode（默认）/ GitHub / GitLab / Gitee 四个托管方，保存时按 host 调 REST 判定仓库是否私有，公共仓库一律拒绝保存；自建/未知主机的私有性无法校验，保存前必须由用户在风险弹窗里显式确认（见「托管方支持与泄露风险」）；访问 token 只写不回读
• 凭据不出域：AI agent（冲突处理/智能对齐/远端对齐）的提示词不含任何访问令牌——需要凭据的 git 推送、PR 查询/合并全部由插件 host 侧完成，token 不会随提示词发送给模型服务（0.4.1 修复）。git 子进程同样不经 argv 携带 token（argv 可被 ps 全机看到），改为 GIT_ASKPASS 环境变量注入（0.4.1）；conflictMode=manual 时所有 AI 入口（自动触发 + 手动按钮）一律关闭，ai 才放行
• 残余风险提示：「智能对齐」的本质是把待合并文件的内容交给模型做语义判断——若 settings.yaml 等文件内含其他机密（如模型 apiKey），这些值仍会进入模型上下文（这是语义合并功能的固有性质，无法在保留功能的前提下消除）；介意者请把 conflictMode 设为 manual 或关闭对应同步开关
• 拉取安全：pull 只回写本地没动过的远端变更，本地改过的内容不会被覆盖

安装

dsh plugin --profile web add @weibaohui/dsh-sync -w

装完重启 dsh web 即生效。

本地打包与测试

1. 打包

npm run check          # 语法检查（src + client）
npm test               # 离线测试 82 项
npm run build:client   # 改了 client/index.js 必须先重建，否则打进去的是旧界面
npm pack               # → weibaohui-dsh-sync-<version>.tgz
tar -tzf weibaohui-dsh-sync-0.4.8.tgz   # 应只含 src/、client/、cordis.patch.yml、package.json、README.md

发布时 npm publish 会自动跑 prepublishOnly（build:client + check + test），无需手工前置。

2. 装进本地 profile 验证

Desktop 的 profile 名是 desktop；先完全退出 Desktop（profile 的 package.json 有文件锁）：

dsh plugin --profile desktop add file:C:\path\to\weibaohui-dsh-sync-0.4.8.tgz
# 或从 npm 装发布版：dsh plugin --profile desktop add @weibaohui/dsh-sync -w
# 普通 web profile：dsh plugin --profile web add @weibaohui/dsh-sync -w

装完重启即生效。若只想跑一次端到端、不碰真实 profile，可用仓库内脚手架

（真实 dsh-app-boot + 真实 dsh-settings，用 file URL 直接加载工作区 src/index.js）：

node .repro/harness4.mjs real，结果写入 .repro/out4-real.json。

3. 开发期免「改一次装一次」

把 profile 里的安装副本换成指向源码目录的 junction（Windows 需开发者模式或管理员），

之后改 src/index.js → 重启 dsh；改 client/index.js → npm run build:client → 刷新页面：

$dst = "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\@weibaohui\dsh-sync"
Rename-Item $dst "$dst.bak"
New-Item -ItemType Junction -Path $dst -Target "D:\GfKaifaApplication\dsh-sync"

回滚：删除 junction，把 dsh-sync.bak 改回原名。

4. 验证与排障

• 设置页保存后，GET /dsh-sync/api/status 的 persist.fileOk 应为 true，并可看到 ~/.dsh/dsh-sync/settings.json 生成；重启 dsh 后值应保留。
• GET /dsh-sync/api/diag 显示 schemaKind / descriptorVisible / lastPersist：宿主写回失败时 persist.hostOk=false，此时 UI 提示「已保存到本地」。

使用

1. 到 GitCode（默认）或 GitHub / GitLab / Gitee 创建一个私有仓库（插件不会代建）

2. 打开 Web UI → 设置页 → dsh-sync → Git 页签，先在「仓库托管方」按钮组点选托管方（默认 GitCode，会自动补上地址前缀并保留已填的 owner/repo），再填仓库地址与 access token，保存

3. 按需开关四类同步内容

4. 之后每次修改，通过同步操作把本机变更推成 PR；多机之间即可保持一致

5. 日常可点「AI 智能对齐」让 AI 先回填远端新增、语义合并双方改动；出现冲突时设置页会出现「AI 解决冲突」按钮，点一下即可

6. 需要从其他机器恢复个别文件时，点「浏览远端」→ 在远端目录树中找到文件并勾选 → 「预览拉取」确认安全判定 → 「应用」写入本地（自动拍安全快照）

Windows 用户注意（路径转换）

在 Windows 的 Git Bash 里，MSYS2 runtime 会对传给原生 .exe 的参数做 POSIX→Windows 路径转换。

若路径中某个目录名带点（如 C:\Users\x\.dsh\dsh-sync\repo），这个点会被当成路径分隔符，

路径被改写成 C:\Users\x\dsh\dsh-sync\repo（点消失、多出一级），git 于是在不存在的目录里执行并报 fetch failed。

这是 Git for Windows 的既有行为，官方定性为 wontfix（git-for-windows#685）。

本插件自 0.4.2 起做了两层防护：

• host 侧：git 子进程在 Windows 下自动注入 MSYS_NO_PATHCONV=1 与 MSYS2_ARG_CONV_EXCL='*'（仅该子进程，不写全局环境）
• AI 侧：三个 AI 提示词都带 Windows 前置保险——先判定平台，再自检路径是否被改写，每条 git 命令前置开关，

并用 git -C <影子仓库> rev-parse --show-toplevel 确认目录真实可达后才动手；验证失败即停止汇报

⚠️ 请不要把 MSYS_NO_PATHCONV=1 写进 .bashrc 或全局环境——全局设置会影响其它程序，

Git for Windows 官方也专门警告过这一点（build-extra#376）。

只在你自己的终端里按"每条命令前置"的方式临时使用即可。

设置持久化与排障（0.4.3）

点「保存」后设置被写到两处，任何一处成功都能跨重启生效：

1. 宿主 settings 文档（profile

…(truncated)