插件备份迁移 DaJiang07/dsh-plugin-backup

插件与设置备份

一个 DSH 插件：把「你装了哪些插件」和「你把设置调成了什么样」打包成一个 JSON 文件。换电脑后装上本插件、选中那个文件，就能一键恢复。打开打包全部，连本地插件源码和插件数据一起走。

它保存什么

| 内容 | 来源 |
| 全部设置 + 插件开关 | <profile>/cordis.patch.yml（配置层，原样保存） |
| 插件包选择与版本 | <profile>/package.json 的 dsh.profile.bundles 与 dependencies |
| 用户设置文档（可选） | $DSH_HOME/settings.yaml |
| 插件清单（诊断用） | ctx.pluginManager.listPlugins() / listBundles() |

打开「打包全部」后额外带上：

| 组 | 内容 |
| plugin-source | package.json 里 link: / file: / 绝对路径依赖的整个目录（本地插件的源码，跳过 node_modules、.git 等） |
| home-data | $DSH_HOME 下插件自己的状态：settings.yaml、dream-skin.json、dsh-market、dshm、engram、synapse、storages、data、skills |
| profile-data | profile 目录里的插件状态：.dsh-market |

永不打包：.credentials.yaml、sessions、attachments、profiles、plugin-backups、node_modules、.git。

单文件上限 8 MiB，整包上限 96 MiB；超出的文件会写进报告的 skipped，不会静默丢掉。

恢复做什么

1. 先把当前配置存成 $DSH_HOME/plugin-backups/pre-restore-<时间>.json（可以再恢复回来）。
2. 写回 cordis.patch.yml；备份里带 settings.yaml 时一并写回。
3. 有 package 时：先恢复本地插件源码——原目录还在就写回原处，不在就解到 $DSH_HOME/plugin-sources/<包名> 并 link 进 profile；再恢复插件数据，每个数据根目录先整块移到 plugin-backups/pre-restore-data-<时间>/ 再写入新内容。
4. 启用备份里记录、但本机还没启用的插件包。
5. 备份里有、本机没装的网络插件包不在这里装（安装很慢），而是返回给页面，由页面逐个调用 pluginManager.installBundle() 并显示进度。
6. 不删除本机多出来的插件包，只在报告里列出来。

界面

设置（Settings）→「备份与恢复」：

- 备份（勾选「打包全部」）并下载，同时存一份到 $DSH_HOME/plugin-backups/。
- 从文件恢复（≤ 40 MiB 走浏览器上传）。
- 按路径恢复：Host 直接读硬盘上的文件，多大的全量备份都能恢复。
- 本机备份列表（标出「恢复前存档」和「全量」），点一下即可恢复。

接口

Host 端只注册一条需要登录的 Web 路由 /dsh-plugin-backup（复用 ctx.connection 的 Host/Origin 与浏览器登录校验）：

| 方法 | 路径 | 作用 |
| GET | /status | 当前 profile、文件大小、插件统计、可打包根目录、本机备份列表 |
| GET | /export?full=1 | 生成快照（full=1 带 package），同时存一份到 $DSH_HOME/plugin-backups/ |
| POST | /restore | 应用快照（{ snapshot }，body ≤ 64 MiB） |
| POST | /restore-path | 按路径应用备份（{ path }，≤ 256 MiB） |
| POST | /restore-local | 应用本机备份（{ file }） |
| POST | /install | 装一个缺失的网络插件包（{ spec }） |

快照带 format: "dsh-plugin-backup"、version: 2；version: 1（只有配置、没有 package）的旧备份照样能恢复。

已知限制

- 备份里不含凭据（API Key、登录状态）和对话记录，换机器后需要重新登录/填 Key。
- 插件代码本身不随备份走，除非打开「打包全部」——而且只覆盖 link:/file: 的本地插件；registry 包恢复时按版本重装。
- 页面按根路径请求 /dsh-plugin-backup；如果把 DSH 挂在反向代理的子路径下，需要相应调整 client.js 里的 BASE。
- 恢复只做「加」不做「减」：本机多出来、备份里没有的插件包会保留并列在报告里。
- 需要安装脚本的包不会自动批准，要在「插件」页面手动同意。
- 数据根目录是被整块替换的：恢复完成后它们的内容就等于备份里的那一刻，恢复后新产生的状态不会合并进来（旧内容在 pre-restore-data-* 里）。

安装

在 DSH 里，把本目录作为本地 bundle 安装： plugin_manager install_bundle，target 为本目录绝对路径