dsh-config-sync
把本机 DSH（DeepSeek Harness）的全部插件与设置备份成一个可移植的 .zip，再批量同步到下一台电脑。
📖 日常操作请看 使用说明.md——按"照着做"的口径编写，含换电脑完整流程、回退步骤和常见问题。本文档偏设计与实现。
它解决什么问题
换电脑时，DSH 的环境散落在很多地方：profile 里装了哪些插件、每个插件的版本、cordis.patch.yml 里的配置覆盖、插件自己写的数据、全局工作区设置……手工搬极易漏项，而漏掉一处就可能让新电脑上的 DSH 起不来。
这个插件把这些收拢成一个文件，并保证还原过程可预览、可回退。
核心设计取舍
| 决策 | 原因 |
|---|
不备份 node_modules | 插件本体有几百 MB，且完全可由 package.json + pnpm-lock.yaml 复现。归档只记录版本，还原时重装，新电脑得到的是干净正确的依赖树。 |
| 不备份运行时/Electron/日志/缓存 | 这些属于机器而非用户，是可重建的。把 Windows 运行时拷到新装环境正是"还原把好环境弄坏"的典型原因。 |
| 凭据默认不含，且永不明文 | .credentials.yaml 和 workbuddy-vault/ 里是 API key 和登录 token。归档是会被拷到 U 盘和网盘的文件，默认排除；显式要求时用 AES-256-GCM 加密成独立成员。 |
| 还原默认只预览 | 写入前必须先看到"会改哪些文件、会增删哪些插件"。加 apply: true 才真正执行。 |
| 应用前自动做还原点 | 每次写入前把当前 profile 配置快照到带时间戳的目录，误操作可退回。 |
| 目标有额外插件时拒绝执行 | 避免"同步一次，把本机独有的插件配置弄丢"。需显式 overwritePlugins: true。 |
安装
插件目录：D:\Dsh\Sync\dsh-config-sync
D:\Dsh\resources\runtime\cli\bin\dsh.cmd plugin --profile desktop add D:\Dsh\Sync\dsh-config-sync
装完需要重启 DSH 才会注册工具。
该命令要写 C:\Users\ThinkPad\.dsh\profiles\desktop（在工作区之外），在受限沙箱下会报 EPERM，需要一次完全权限。
用法
在 DSH 会话里（推荐）
装好后直接对 agent 说，例如：
- 「看看我这台电脑现在有哪些插件和设置」→
dsh_config_status
- 「把插件和设置备份出来」→
backup_dsh_config
- 「把这个备份还原到新电脑」→
restore_dsh_config
五个工具：
| 工具 | 作用 |
|---|
dsh_config_status | 看现状：装了哪些插件、各类设置文件数量、备份会包含什么 |
backup_dsh_config | 生成备份归档（支持 dryRun 预览） |
restore_dsh_config | 预览/应用还原 |
verify_dsh_config | 校验归档完整性（逐个成员核对 sha256） |
list_dsh_backups | 列出已有归档 |
命令行（DSH 起不来时用这个）
$cli = "D:\Dsh\resources\runtime\cli\bin\dsh.cmd" # 仅用于装插件
node D:\Dsh\Sync\dsh-config-sync\bin\dsh-config-sync.mjs <命令>
# 看现状
node bin\dsh-config-sync.mjs status
# 备份（默认不含凭据和会话）
node bin\dsh-config-sync.mjs backup --output D:\backup\dsh.zip
# 备份并加密包含登录凭据
node bin\dsh-config-sync.mjs backup --output D:\backup\dsh.zip `
--categories profile-config,home-config,plugin-state,credentials --password 你的口令
# 校验
node bin\dsh-config-sync.mjs verify --input D:\backup\dsh.zip
# 还原：默认只预览
node bin\dsh-config-sync.mjs restore --input D:\backup\dsh.zip --profile desktop
# 确认后真正写入
node bin\dsh-config-sync.mjs restore --input D:\backup\dsh.zip --profile desktop --apply
换电脑的完整流程
旧电脑
node bin\dsh-config-sync.mjs backup --output D:\dsh-backup.zip
新电脑（先装好 DSH 本体）
# 1. 校验归档，确认传输没损坏
node bin\dsh-config-sync.mjs verify --input D:\dsh-backup.zip
# 2. 预览：看清楚会写入什么、插件增删情况
node bin\dsh-config-sync.mjs restore --input D:\dsh-backup.zip --profile desktop
# 3. 应用
node bin\dsh-config-sync.mjs restore --input D:\dsh-backup.zip --profile desktop --apply
4. 安装插件（归档不含 node_modules，第 3 步会打印完整命令）
D:\Dsh\resources\runtime\cli\bin\dsh.cmd plugin --profile desktop add dsh-pet@0.3.7
D:\Dsh\resources\runtime\cli\bin\dsh.cmd plugin --profile desktop add dsh-mnemon@0.5.29
# …按第 3 步输出的清单逐个装
5. 重启 DSH。
备份类别
| 类别 | 默认 | 内容 |
|---|
profile-config | ✅ | package.json、pnpm-lock.yaml、cordis.yml、cordis.patch.yml 等 |
home-config | ✅ | storages/workspace.json、telemetry/ 等全局设置 |
plugin-state | ✅ | 各插件在 DSH_HOME 下的状态目录 |
credentials | ❌ | 登录凭据，需 password，AES-256-GCM 加密 |
sessions | ❌ | 会话记录，体积大 |
安全说明
- 明文凭据从不进入归档。代码里有一条独立防线：任何成员名命中凭据模式都会直接报错中止，而不是默默写进去。
workbuddy-vault/ 存的是明文 token，它在 plugin-state 里会被自动排除并给出提示——这是实测发现的真实风险点。- 加密用 scrypt（N=2¹⁵）派生密钥 + AES-256-GCM，口令错误或归档被篡改都会解密失败，不会还原出似是而非的内容。
- 忘记口令 = 凭据无法恢复，需要在新电脑重新登录。
测试
node --test test/ # 或直接：node test/sync.test.mjs
覆盖 ZIP 往返与损坏检测、加密往返与错误口令、清单排除规则、凭据隔离、预览不落盘、还原点、篡改检测和 CLI。
在受限沙箱里，涉及子进程的 4 个 CLI 用例会因 spawn EPERM 跳过——那是沙箱禁止管道 stdio，不是插件缺陷。
目录结构
dsh-config-sync/
├── bin/dsh-config-sync.mjs # 独立 CLI（DSH 起不来时的救援通道）
├── lib/
│ ├── index.js # 插件入口，注册 5 个工具
│ ├── inventory.js # 决定备份什么（核心策略所在）
│ ├── archive.js # 备份 / 预览 / 还原 / 校验
│ ├── crypto.js # 口令加密
│ └── zip.js # 零依赖 ZIP 读写
├── test/sync.test.mjs
└── cordis.patch.yml
零运行时依赖：ZIP 和加密都用 Node 内置模块实现，避免在"正在修环境"的机器上还要先装依赖。
