dsh-config-sync

DSH 的「多端配置同步」插件：把本机 DSH_HOME 下的配置面文件纳管到一个私有 Git 仓库，在设置页里一键捕获、推送、拉取、应用、回滚。插件本体按 pnpm-lock.yaml 确定性重建，不传 node_modules。

已在本机验证：DSH Desktop 0.2.1-rc.2 / Windows x64 / DSH_HOME=D:\dsh\data。 客户端只依赖宿主注入的 react，宿主只依赖 Node 内置模块 —— 无需构建、无第三方运行时依赖。

• npm：https://www.npmjs.com/package/@liangfengqi/dsh-config-sync
• 源码：https://github.com/bxzfxl/dsh-config-sync

---

它同步什么

类别	路径（相对 DSH_HOME）	说明
设置	profiles/<profile>/cordis.patch.yml	0.2.x 的设置真正所在（模型默认、UI 偏好、插件配置）
插件清单	profiles/<profile>/package.json	依赖 + dsh.profile.bundles
依赖锁	profiles/<profile>/pnpm-lock.yaml、pnpm-workspace.yaml	让另一台机器可重建插件
技能	skills/**	存在时才纳管
角色/外观	agents/**、pet.json、skin-center-active.json	存在时才纳管

永远不同步：.credentials.yaml、sessions/、node_modules/、dsh-runtimes/、cordis.yml（生成物）、.dsh-market/、插件自持目录（如 task-board/、dsh-usage/）。

---

安装

方式一：插件市场 / npm（推荐）

市场收录后：DSH → Plugins → 市场 → 搜索 dsh-config-sync → 一键安装。

也可以直接用 npm：

dsh plugin --profile web add @liangfengqi/dsh-config-sync

方式二：本地安装脚本（没有 dsh CLI 时）

⚠️ 先完全退出 DSH Desktop（profile 的 package.json 有文件锁），再在 PowerShell 里执行。

cd D:\文档\deepseek-harness\default-workspace\dsh-config-sync
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-plugin.ps1 -DshHome D:\dsh\data

脚本会：备份 profile → 写入 dependencies 与 dsh.profile.bundles → 用 DSH 自带 node + pnpm 安装依赖。 装完重启 DSH，设置里会多出「配置同步」页。

卸载：

powershell -NoProfile -ExecutionPolicy Bypass -File .\install-plugin.ps1 -DshHome D:\dsh\data -Uninstall

---

首次配置

1. 在 GitHub / Gitee / GitCode / 自建上建一个 私有空仓库（不要用公共仓库：cordis.patch.yml 可能含内网地址/账号标识）。

2. 设置 → 配置同步：

   • 仓库地址：git@github.com:you/dsh-config.git 或 https://github.com/you/dsh-config.git
   • 分支：main
   • 访问令牌：HTTPS 仓库填 PAT（只写本机，接口永不回显；SSH 仓库留空）
   • 保存

   如果仓库地址里直接夹了令牌（https://<token>@github.com/you/repo.git），保存时会自动把令牌拆出来存到本机，地址里不会保留凭据。

3. 点 初始化仓库 → 捕获并推送。

4. 到另一台机器：装好同版本 DSH → 安装本插件 → 保存同一仓库 → 拉取远端 → 应用（写入本机） → 重启 DSH。

日常：改设置/装插件后 → 捕获并推送；到另一台 → 拉取远端 → 应用 → 重启。应用前会自动备份，点「恢复最近备份」可回滚。

---

安全

• 令牌存在 DSH_HOME/dsh-config-sync/settings.json（0600，仅本机），不进仓库、不回显。
• 仓库请保持私有，并给 token 最小权限（只读写这一个仓库）。
• 「扫描密钥」会检查仓库里的 sk-…、ghp_…、xox…、私钥块、Bearer、apiKey/token/password = <长串>；命中就改成本机文件或占位符。
• 如果某个插件把密钥写进了 cordis.patch.yml，请先把它改成占位符，或把该插件设置挪到不同步的本机文件。
• apply 会覆盖本机 cordis.patch.yml：建议只在一台主用机上改设置，其他机器只拉取/应用。

---

数据位置

DSH_HOME/dsh-config-sync/
├─ settings.json        # 本机插件设置（含 token，0600）
├─ repo/                # 配置仓库克隆（默认位置，可在设置里改 repoDir）
│  ├─ home/             # 与 DSH_HOME 同构，只放纳管文件
│  ├─ meta/capture.json # 上次捕获：主机/时间/版本/哈希
│  └─ dshcfg.json       # 纳管清单（与 CLI 工具共用）
├─ backups/<时间戳>/    # apply / restore 前的自动备份
└─ .askpass.sh          # HTTPS 令牌注入用的临时助手（git 子进程专用）

仓库布局与 dshcfg.ps1 CLI 完全一致，可以在有终端时用 CLI 做脚本化操作，插件里照常识别。

---

HTTP API（同源、仅本机回环）

方法	路径	作用
GET	/api/dsh-config-sync/status	状态：路径、纳管数、差异、git 状态、上次捕获
GET	/api/dsh-config-sync/settings	读设置（不含 token）
PUT/POST	/api/dsh-config-sync/settings	写设置（token 非空才覆盖；clearToken:true 清除）
POST	/api/dsh-config-sync/init	初始化本地仓库
POST	/api/dsh-config-sync/capture	捕获；body {push?:boolean, message?:string}
POST	/api/dsh-config-sync/pull	git pull --rebase --autostash（首次接入自动对齐远端分支）
POST	/api/dsh-config-sync/apply	备份 + 写入本机；body {install?:boolean} 额外跑 pnpm install
POST	/api/dsh-config-sync/restore	用备份恢复；body {name?:string}
POST	/api/dsh-config-sync/scan	密钥扫描
GET	/api/dsh-config-sync/backups	备份列表

非回环来源一律 403；所有操作串行执行（并发返回 409）。

---

已知限制

• 应用后必须重启 DSH 才生效（cordis.patch.yml / package.json 是启动时读取的）。
• 「应用并安装依赖」在运行中的进程里跑 pnpm：新插件文件可写入，但被占用的原生模块可能安装失败；失败时重启后再到终端执行 pnpm install。稳妥做法：应用 → 重启 → 如提示缺插件再装一次。
• 多机建议同版本 DSH；仓库里记录了捕获时的版本，跨版本应用前请先升级。
• 自动捕获默认关闭；开启后只在有变更时提交，自动推送建议只在主用机开启。
• macOS / Linux 未实测（宿主代码只用 Node 内置模块，路径按 POSIX 处理；客户端逻辑与环境无关）。

---

开发与测试

node --check lib/index.js
node --check client/bundle.js
node --test test/host.test.mjs      # 20 项：capture/push/pull/apply/restore/scan + HTTP + 客户端注册契约
npm pack                            # 生成 liangfengqi-dsh-config-sync-0.1.0.tgz
npm publish --access public         # 发布到 npm（当前维护者账号 liangfengqi）

测试用临时 DSH_HOME + 本地 bare 仓库，不需要真的连远端。

---

License

MIT