前言¶

在 DeepSeek Harness（DSH）里跑一段时间后，$DSH_HOME 会积累设置补丁、技能树、插件 profile、会话和本地存储。手动拷贝整个目录既难区分「该备份什么」，也难在出问题后确认归档是否完整、能否安全写回。社区插件 dsh-plugin-backup（维护者 shiinakaze）把备份做成按类别打包、可校验、可恢复、可下载的流程，并可选同步到 GitHub；Web 设置页、模型工具面和 CLI 共用同一套引擎与单次运行锁。

这是什么¶

dsh-plugin-backup 是面向 DSH 的备份插件（npm 包名 dsh-plugin-backup，当前版本 1.0.0，MIT 许可证）。它把 $DSH_HOME 按类别打成可验证、可恢复、可下载的归档，命名规则为 dsh-backup-<YYYYMMDD>-<HHmmss>。未设置 $DSH_HOME 时回退到 ~/.dsh。插件无构建步骤、无第三方运行时依赖：宿主侧为纯 ESM，浏览器侧为可直接加载的 CommonJS 工厂。

核心功能¶

备份类别¶

任意深度始终排除：node_modules、.git*、符号链接，以及备份根目录本身（避免把备份目录嵌在 $DSH_HOME 内时递归）。

单次备份能做什么¶

每个备份目录包含各类别的 *.tar.gz 与最后原子写入的 manifest.json（含 schema、宿主信息、每类文件数/字节/sha256/归档信息、最近校验结论）。进行中文件带 .part 后缀；崩溃残留会在下次运行开始时清理或忽略。

对已有备份支持：下载（按类别或 manifest）、verify、preview restore、restore、delete（restore/delete 需二次确认）。

设置项（Web：Settings → Data backup）¶

• Backup settings：备份路径（空则 Windows 为 C:\Users\<user>\dsh_backups，其它为 ~/dsh_backups；支持 ~ 与 ${DSH_HOME} 展开）、定时间隔（关 / 15 分钟 / 小时 / 6 小时 / 日 / 周）、保留份数、创建后立即 verify。
• Backup categories：勾选本次或默认定时任务要包含的类别；「Back up now」只备份已勾选项，保存设置后该选择也作为定时默认。
• GitHub sync：开关、owner/repo（完整 URL 也可）、分支、子目录、token 环境变量名、是否检测到 token，以及 push / pull。

用户层设置写在 $DSH_HOME/dsh-plugin-backup/settings.json（权限 0600），与 profile 里 cordis.patch.yml 的部署基线浅合并（用户层优先）。

模型工具¶

典型流程：在 risky 变更前 backup_run，之后 backup_verify，必要时 backup_restore。backup_restore 会先 verify，损坏备份默认拒绝，除非 force。

GitHub 同步¶

1. 在设置页启用 sync，填写 owner/repo、分支、子目录。
2. Token 解析顺序：环境变量（默认 DSH_BACKUP_GITHUB_TOKEN，可在设置中改名）；或 $DSH_HOME/dsh-plugin-backup/github-token.json（{"token":"…"}，模式 0600）。Token 不会写入配置、日志或工具输出。
3. Push 经 Contents API 逐文件上传，先归档、最后 manifest.json；远端已有相同内容则跳过。Pull 只拉本地缺失的备份，并按 manifest 中 sha256 校验每个归档，不匹配则丢弃并说明原因。

远端布局：<subdir>/<backupId>/{manifest.json,<category>.tar.gz}。

安装与启用¶

插件面向 @deepseek-ai/dsh 的 0.1.7 与 0.2.0 线（engines.dsh 与 peerDependencies 为 ^0.1.7-rc.2 || ^0.2.0-rc.1）。Desktop 使用 desktop profile，需通过应用内插件管理器安装（或 dsh plugin --profile desktop add …）并重启应用。

Web profile 安装示例（来自仓库 README）：

# 本地开发目录
dsh plugin --profile web add file:C:/path/to/dsh-plugin-backup

# 或从 GitHub
dsh plugin --profile web add github:shiinakaze/dsh-plugin-backup

dsh plugin add 会记录依赖并把包名写入 dsh.profile.bundles。安装后重载或重启 Web 界面，打开 Settings → Data backup。

说明：file: 安装是快照；改插件源码后需 dsh plugin --profile web remove <name> 再重新 add。非 Web profile（无 webServer 服务）时 download 不可用，其余功能与工具仍可用。

典型用法¶

在 Web 里手动备份¶

1. 进入 Settings → Data backup。
2. 在 Backup categories 勾选需要的类别（例如默认的 settings、skills、plugins）。
3. 点击 Back up now (N categories)，在 Existing backups 查看 id、时间、大小与校验结果。
4. 需要时用行内 verify 或 download 菜单。

用模型工具做变更前后保护¶

在支持 DSH tools 的会话中，可先创建备份再改配置或插件：

• backup_run：立即打包（可选 categories、label）。
• 变更后 backup_verify（传入备份 id）。
• 若需回滚：backup_restore，先用 dryRun: true 看计划，再正式恢复。

大 skills 树与保留策略¶

README 在真实 harness home 上测过：skills 类别压缩后仍可能超过百 MiB；默认单类归档上限 512 MiB。若超出，可在设置中提高 maxArchiveBytes，或关闭 skills 类别改用手动备份。启用 skills 且保留 20 份时，本地存储规模可能达到约 3 GB 量级，需自行规划磁盘与保留份数。

适用场景与注意¶

适合：需要定期或变更前备份 DSH 设置、技能与插件组合；要在多台机器间通过 GitHub 同步备份目录；希望 restore 前有 verify 与 dry-run。

注意：

• 插件以当前 DSH 进程权限读写 $DSH_HOME 与备份路径；安装前应阅读源码与 MIT 许可证，并理解会备份 .credentials.yaml* 等敏感文件所在类别。
• sessions、storages 默认关闭，开启前确认体积与隐私。
• 备份 id 须匹配 ^dsh-backup-\d{8}-\d{6}$；归档条目拒绝绝对路径等不安全项（详见 README 安全边界表）。
• 社区目录 skillhub.cn 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；星标与简介以目录页为准。

结尾¶

dsh-plugin-backup 把 DSH 本地状态拆成可管理的五类归档，并在 Web、模型工具与 CLI 上提供一致的创建、校验、恢复与可选 GitHub 镜像。若你已在用 DSH 做长期开发或部署，可按上文命令安装，在 Settings → Data backup 完成路径与类别配置后再做第一次 Back up now。

• 社区目录：https://www.skillhub.cn/plugins/shiinakaze/dsh-plugin-backup
• 源码与文档：https://github.com/shiinakaze/dsh-plugin-backup