# dsh-config-sync 使用说明

> 日常操作手册。技术设计与代码结构见 [README.md](README.md)。
> 本文档按"照着做"的口径编写，命令可直接复制。

---

## 〇、两种使用方式，选一种即可

| 方式 | 适合场景 | 怎么用 |
|---|---|---|
| **在 DSH 会话里说一句话** | 日常使用，DSH 正常运行时 | 直接对 agent 说："备份一下插件和设置" / "看看现在装了哪些插件" / "还原这个备份 D:\xxx.zip" |
| **命令行 CLI** | 新电脑还没装本插件、或 DSH 起不来 | `node <插件目录>\bin\dsh-config-sync.mjs <命令>` |

两条路径功能完全一致，都是先预览、后执行，不会无声写入。

---

## 一、日常备份（旧电脑上做）

### 1.1 先看看会备份什么（可选，建议第一次做）

```
看看我这台 DSH 现在的插件和设置情况
```

或命令行：

```powershell
node D:\Dsh\Sync\dsh-config-sync\bin\dsh-config-sync.mjs status
```

输出会告诉你：装了哪些插件、备份将包含多少个文件、有哪些提醒（比如凭据未包含）。

### 1.2 想先预览、不落盘

```powershell
node D:\Dsh\Sync\dsh-config-sync\bin\dsh-config-sync.mjs backup --dry-run
```

（在会话里说："预览一下备份内容，先不要真的写文件"。）

### 1.3 正式备份

```powershell
# 归档默认写到 C:\Users\<你>\.dsh\backups\，也可以自己指定路径：
node D:\Dsh\Sync\dsh-config-sync\bin\dsh-config-sync.mjs backup --output D:\DshBackup\dsh-2026-10-16.zip
```

**默认包含**：profile 配置（插件清单+版本+cordis 设置）、全局设置、插件数据。
**默认不含**：登录凭据、聊天会话记录、node_modules、运行时。

### 1.4 备份含登录凭据的版本（可选）

默认备份**不含** DeepSeek API key 和 WorkBuddy 登录 token。如果想让新电脑连登录状态一起搬过去：

```powershell
node D:\Dsh\Sync\dsh-config-sync\bin\dsh-config-sync.mjs backup `
  --output D:\DshBackup\dsh-with-secrets.zip `
  --categories profile-config,home-config,plugin-state,credentials `
  --password 你的口令
```

要点：

- **必须给口令**，凭据以 AES-256-GCM 加密写入，归档内不存在明文（已实测验证）。
- **口令忘了就没人能救**，只能在新电脑重新登录。
- 建议归档名带上 with-secrets，和普通备份区分开，且不要把它传到不放心的地方。

### 1.5 备份 web profile（可选）

一个归档只装一个 profile。除了 desktop 之外还有 web profile 的话，再跑一次：

```powershell
node ...\bin\dsh-config-sync.mjs backup --profile web --output D:\DshBackup\dsh-web.zip
```

### 1.6 连聊天记录一起备份（可选）

```powershell
node ...\bin\dsh-config-sync.mjs backup --with-sessions --output D:\DshBackup\dsh-full.zip
```

体积会明显变大，一般只有想完整留档时才用。

---

## 二、验证备份（建议每次换机前做）

```powershell
node D:\Dsh\Sync\dsh-config-sync\bin\dsh-config-sync.mjs verify --input D:\DshBackup\dsh-2026-10-16.zip
```

会逐个成员核对 sha256。**归档经过 U 盘/网盘/微信传输后，务必先 verify 再 restore**——校验不过就别用，宁可重新备份一次。

---

## 三、换电脑完整流程（重点）

前提：新电脑已安装 DSH 本体。

### 第 1 步：把归档拷过去

U 盘 / 网盘 / 局域网都行。例如拷到新电脑的 `D:\DshBackup\dsh-2026-10-16.zip`。

### 第 2 步：校验

```powershell
node <插件CLI路径>\bin\dsh-config-sync.mjs verify --input D:\DshBackup\dsh-2026-10-16.zip
```

> 新电脑此时还没有这个插件：最省事的做法是先把整个 `dsh-config-sync` 文件夹随归档一起拷到新电脑（任意位置均可，比如 `D:\Dsh\Sync\dsh-config-sync`），CLI 是零依赖的，拷过去就能跑，不需要安装。

### 第 3 步：预览（默认就是预览，不加参数不会写任何东西）

```powershell
node ...\bin\dsh-config-sync.mjs restore --input D:\DshBackup\dsh-2026-10-16.zip --profile desktop
```

看清楚三件事：

- **待写入文件数**：会覆盖哪些设置；
- **新增插件 / 移除插件**：新电脑上插件会怎么变；
- **注意列表**：比如"目标 profile 已有归档中没有的插件"。

### 第 4 步：确认后应用

```powershell
node ...\bin\dsh-config-sync.mjs restore --input D:\DshBackup\dsh-2026-10-16.zip --profile desktop --apply
```

- 如果预览提示"目标有归档中没有的插件"，而你确认要覆盖，加 `--overwrite-plugins`。
- 应用前会自动把**当前 profile 配置**快照到还原点目录（见第五节）。

如果备份时带了加密凭据，这一步同时给口令并显式要求写入凭据：

```powershell
node ...\bin\dsh-config-sync.mjs restore --input D:\DshBackup\dsh-with-secrets.zip `
  --profile desktop --apply --password 你的口令 --with-credentials
```

### 第 5 步：安装插件本体

归档**有意不含** node_modules（几百 MB，且按清单重装才干净）。第 4 步的输出会打印完整安装清单，照着执行即可：

```powershell
# 新电脑上 dsh.cmd 的路径以实际安装位置为准
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
D:\Dsh\resources\runtime\cli\bin\dsh.cmd plugin --profile desktop add dshmarket@^1.66.27
# ……按输出清单逐条执行；github: 来源的照原样整串填进去
```

> 小技巧：把清单粘贴到会话里让 agent 逐条执行也行；装插件要写 profile 目录，若在 DSH 受限沙箱里跑，每条会弹一次权限确认，属正常现象。

### 第 6 步：在新电脑装上本插件本身

```powershell
D:\Dsh\resources\runtime\cli\bin\dsh.cmd plugin --profile desktop add D:\Sync\dsh-config-sync
```

（路径换成你实际拷贝到的位置。装完重启 DSH。）

### 第 7 步：重启 DSH，检查

重启后在新电脑的会话里说"看看现在的插件和设置情况"，和旧机器的输出对一下。

### 第 8 步（仅此台机器需要注意）：手工补两项环境级配置

以下两项是**环境变量/安装位置**，不在文件备份的覆盖范围内，换机后需手动做一次：

1. **WorkBuddy 自定义安装路径**：若 WorkBuddy 没装在默认位置，设置用户级环境变量
   `WORKBUDDY_APP_EXECUTABLE = <WorkBuddy.exe 实际路径>`，否则 workbuddy 插件读不出账号。
2. 重新登录 DeepSeek 账号（如果没迁移加密凭据）。

---

## 四、日常小操作速查

| 想做什么 | 会话里说 | 或命令行 |
|---|---|---|
| 看现状 | "看看我的 DSH 插件和设置情况" | `status` |
| 备份 | "备份插件和设置到 D:\xxx.zip" | `backup --output ...`（不指定路径时默认存到 `C:\Users\<你>\.dsh\backups\`，首次使用会自动创建） |
| 预览备份 | "预览备份，先别写文件" | `backup --dry-run` |
| 验证归档 | "校验一下这个备份文件" | `verify --input ...` |
| 列出已有备份 | "列一下有哪些备份" | `list` |
| 还原预览 | "预览还原这个备份" | `restore --input ...` |
| 还原执行 | "确认还原，应用它" | `restore --input ... --apply` |

---

## 五、还原错了怎么回退

每次 `--apply` 都会先生成一个还原点：

```
C:\Users\<你>\.dsh\profiles\.dsh-config-sync-restore-point-desktop-<时间戳>\
```

里面是**被覆盖前的 profile 配置文件**（package.json、cordis.patch.yml 等）。

回退方法：把该目录里的文件复制回
`C:\Users\<你>\.dsh\profiles\desktop\`，然后重启 DSH。

注意两点（如实说明）：

- 还原点只覆盖 **profile 配置**；全局设置和插件数据（storages、dsh-pet 等）不在其中，所以重要数据建议在还原前先做一次新备份。
- 还原点不会自动清理，会按时间戳累积；确认没问题后可以手动删掉旧的。

---

## 六、常见问题

**Q1：`restore` 说"目标 profile 已有 N 个归档中没有的插件"，不敢继续？**
这是保护：新电脑上自己装过的插件会被清掉。确认没问题就加 `--overwrite-plugins`；想保留就先在新电脑备份一份，再决定。

**Q2：verify 报"校验和不符/大小不符"？**
归档在传输中损坏了。**不要用它还原**，回旧电脑重新 `backup` 一次再传。

**Q3：输入口令后报"解密失败：口令错误，或该文件已被损坏/篡改"？**
口令不对，或归档损坏。工具无法区分这两种情况，都会这样报。先 `verify` 排除损坏，再核对口令。

**Q4：`dsh plugin add` 卡住或报 allowBuilds？**
github: 来源、带构建脚本的插件（如 dsh-lsp-actions）会被 pnpm 的 allowBuilds 白名单拦截。`pnpm-workspace.yaml` 已随备份还原（里面带着旧电脑批准过的键），若插件版本换了导致键不匹配，按提示把新的「包名@codeload tarball URL」键加进去即可。构建卡得久可优先改装 npm 官方预构建版本。

**Q5：装插件时装的版本和旧电脑不一样？**
profile 的 `pnpm-workspace.yaml`（含供应链冷却策略 minimumReleaseAge 及其豁免名单）已随备份还原，正常会装到同版本；若 npm 上该版本已被下架或冷却期规则变化，可能出现差异，以 `status` 的实际清单为准。

**Q6：还原后 `tokenledger`（或其他插件）提示"未登记进 bundles，不会加载"？**
这是备份就如实记录的原有问题：装了包但没登记。想修：编辑
`C:\Users\<你>\.dsh\profiles\desktop\package.json`，把该包名加进 `dsh.profile.bundles` 数组，重启 DSH；不想要它就从 `dependencies` 里删掉。

**Q7：还原到新电脑后，package.json 里有一项 `link:D:/Dsh/Sync/dsh-config-sync`？**
那是本插件在旧电脑上的本地链接路径。两种处理：把插件源码文件夹拷到新电脑**相同路径**（推荐，保持一致）；或者从 `dependencies` 里删掉这一项，装插件时跳过它，之后用第 6 步的命令从新位置安装。

**Q8：在 DSH 会话里执行还原被拒绝（EPERM）？**
还原要写 `C:\Users\<你>\.dsh\`（工作区之外），受限模式下需要权限确认；给一次即可，或改用命令行方式在外部终端执行。

**Q9：想把某次备份里的一两个文件单独拿出来？**
归档是标准 .zip，用 Windows 资源管理器/7-Zip 直接打开即可；`manifest.json` 里有每个成员的路径、大小和 sha256 可对照。

---

## 附：类别与默认值

| 类别 | 默认 | 内容 | 备注 |
|---|---|---|---|
| `profile-config` | 含 | package.json、pnpm-lock.yaml、cordis.patch.yml 等 | 插件清单+版本+设置 |
| `home-config` | 含 | storages、telemetry 等全局设置 | |
| `plugin-state` | 含 | 各插件自己的数据目录 | 凭据类文件自动排除并提示 |
| `credentials` | **不含** | API key、登录 token | 需同时给 `--password` |
| `sessions` | **不含** | 聊天记录 | 体积大，按需 |

指定类别：`--categories profile-config,home-config,plugin-state,credentials`（逗号分隔）。