前言¶
DSH 理念是「一切皆插件」。在开发智能体时，开发者常依赖本地插件来扩展功能，这些插件往往包含自定义的依赖和链接配置。在更换电脑或重装系统时，仅仅复制设置文件往往无法恢复完整的开发环境，因为本地插件及其依赖关系容易丢失。
这个插件解决了上述痛点。它提供了一套完整的备份与恢复机制，能够将设置、凭据、技能、预设以及本地插件打包成 ZIP 文件。在需要时，可以将环境还原回原来的目录结构。
功能与特性¶
插件的主要功能围绕「发现」、「打包」和「还原」展开：
- 发现本地插件：插件不仅读取 profile 的
package.json依赖，还会扫描node_modules软链接/junction，以及dsh.profile.bundles指向本地的 bundle，生成完整清单。 - 勾选打包：发现插件后会列出清单，支持复选框勾选和「全选」操作，界面会实时显示发现数量、可打包数量和已勾选数量。
- 插件是一等公民：每个本地插件连同其生产运行依赖都会被打包进归档中，manifest 会记录完整的链接拓扑。
- 还原回原位置：还原时优先恢复到备份记录中的原始绝对目录；若原目录不存在，则自动落点到
$DSH_HOME/plugins/<插件名>，并同步改写 profile 的声明与链接。 - 补齐声明：对只存在于
node_modules但未声明的插件，还原时会自动补写link:依赖，防止下次安装时被删除。 - 逐项校验：还原完成后，会对目录、入口文件和 profile 链接进行校验，结果直接反馈在设置页面。
- 恢复可逆：任何一次恢复操作前，都会自动打一份快照，因此恢复过程本身是可撤销的。
- 不覆盖更新的内容：系统基于文件系统时间判断，如果目标文件比归档新且内容不同，则跳过并保留原文件。
- 大备份可靠下载：采用 4MB 分块下载机制，避免因单次响应体过大导致的下载失败。
- 备份记录列表：所有备份文件会列在设置页，支持直接恢复或删除。
安装与启用¶
通过命令行安装：
dsh plugin --profile desktop add github:hello-heyongping/dsh-helloai-bak
安装完成后，进入 设置 页面即可看到「备份与恢复」选项。
使用方法¶
备份
- 打开 设置 → 备份与恢复；
- 在「本地插件」清单中勾选需要打包的插件（默认会勾选可打包项）；
- 点击 「备份全部配置」，生成 ZIP 文件并下载；
- 备份文件默认保存在
$DSH_HOME/backups目录，同时出现在下方的「备份记录」中。
恢复
- 在「备份记录」中找到对应的备份点，点击 「恢复」；或者在换电脑时点击 「从 ZIP 恢复」 手动选择文件；
- 恢复前系统会自动打快照，确保可逆；
- 恢复完成后，界面会逐项列出每个插件的结果（如已恢复、已保留、未备份、失败等）。
注意事项¶
- 敏感信息：备份文件包含
.credentials.yaml等敏感凭据，请仅在可信渠道保存和传输。 - 覆盖规则：恢复是整体覆盖，但会优先保留比备份更新的文件。若需强制覆盖，界面会提供相应按钮。
- 无作用域选择：恢复操作没有作用域选择，设置、凭据、技能、预设和插件会一起恢复。若只想恢复部分内容，需在恢复后手工回退。
- 目录位置：备份目录固定在
$DSH_HOME/backups，暂不可配置。 - ZIP 限制：采用经典 ZIP 格式，条目上限为 65535。
- 悬空链接：如果
node_modules中的链接指向的目录已被删除，无法打包，只能在清单中报告。
总结¶
该插件通过将本地插件视为一等公民，解决了 DSH 环境迁移时的配置丢失问题。配合快照机制和不覆盖更新策略，提供了可靠且安全的备份体验。
