dsh-backup-rescue
Verifieddsh-backup-rescue · v0.4.6 · MIT · Web UI
Whole-$DSH_HOME backup and restore for DeepSeek Harness: one-click archives from the settings page, agent-facing tools, and a standalone restorer that runs without DSH.
Install
dsh plugin add dsh-backup-rescue Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
DSH 全量备份插件 v0.4.5
English | 简体中文
给 DeepSeek Harness 做整机备份/恢复:设置页一键备份,agent 侧有工具,另附一个不依赖 DSH 的独立恢复器。
功能
- 全量备份:备份整个
$DSH_HOME(settings、providers、plugins、skills、mcp、prompts、sessions、credentials 等) - 一般 / 完整两种备份:一般备份默认跳过
node_modules(插件代码本身)、cache、logs等可重建目录,只带配置与插件清单;勾选「包含插件文件」后一般备份也会打包profiles/*/node_modules;完整备份则把所有可重建目录(含dsh-runtimes、web-login、speech-to-text)一起带走,离线可恢复 - 工作区文件可一起备份:勾选「连同工作区文件」后,会从
storages/workspace.json读出登记的工作区目录(默认在$DSH_HOME之外,比如Documents\deepseek-harness\default-workspace),按__workspaces__/<id>/…收进同一个包;恢复时再按(已改写的)真实路径搬回去 - 恢复时自动改写路径:换机器(用户名/盘符不同)时,把备份里记录的旧
$DSH_HOME、旧用户目录前缀自动替换成恢复目标的路径(覆盖storages/workspace.json等文本配置,跳过node_modules与.backup-snapshot),restore.bat与界面恢复都支持 - 备份位置可选:设置页可以填任意绝对路径当备份根目录;换位置时可勾选“同时把已有备份迁移过去”,旧备份(含同名
.bat)连同修改时间一起搬走,搬完自动清空旧目录 - 定时自动备份:填
i分钟跑一次、j份封顶;每次自动做一份一般备份,超过j份时自动删掉最早的(完整备份永不自动删除) - 每份备份一个同名文件夹:压缩包与它的同名
.bat/.sh恢复脚本放在同一个以压缩包命名的文件夹里,多份备份互不覆盖 - 一键备份并更新:先从 npm 查最新版 → 自动做一份一般备份 → 再升级插件;升级把插件换坏时,用刚做好的这份备份恢复即可
- 加密备份:使用 DSHBK002(PBKDF2-SHA256 20 万次 + AES-256-CBC + HMAC-SHA256)加密整个 ZIP 包(
.zip.enc),需密码恢复;恢复脚本用 Windows 自带 PowerShell 就能解开 - SHA-256 校验:清单文件记录每个文件的 SHA-256,恢复前全量校验
- 自动快照:恢复前将被覆盖的文件备份到
.backup-snapshot/<时间戳>/ - 独立恢复器:每份备份自带同名
.bat/.sh,不依赖 DSH 运行 - 插件清单:一般备份在清单里记下每个 profile 装了什么插件(name@version),恢复后如果插件代码缺失会直接提示怎么重装
- Agent 工具:注册
backup_plugin_create/create_full/restore/list/status/check_update/update/settings/prune九个工具
安装
插件已自动安装到 ~/.dsh/profiles/desktop/node_modules/dsh-backup-rescue/。
重启 DSH 以加载插件。
使用
Agent 工具
在 DSH 对话中可以直接使用以下工具:
backup_plugin_create— 创建备份- 参数:
dshHome(可选)、backupDir(可选)、password(可选,加密密码)、includeSecrets(可选) - 无需传参即可备份当前 DSH 安装
- 参数:
backup_plugin_list— 列出备份文件backup_plugin_restore— 恢复备份- 参数:
backupPath(必填)、targetDir(可选)、password(加密备份密码)、dryRun(预览)、force(跳过 DSH 运行检查)
- 参数:
backup_plugin_status— 查看备份状态(含自动备份调度状态)backup_plugin_settings— 读写插件设置- 参数:
backupDir(绝对路径,传空串表示恢复默认位置)、migrate(是否顺带迁移旧备份)、autoEnabled、autoIntervalMinutes(每隔 i 分钟)、autoMaxBackups(最多保留 j 份)
- 参数:
backup_plugin_prune— 只按保留份数清理普通备份- 参数:
maxBackups(默认取设置里的 j)、backupDir(可选)
- 参数:
备份位置
设置页「📂 备份位置」卡片(或工具 backup_plugin_settings、HTTP GET/POST /api/dsh-backup-rescue/settings):
- 填任意绝对路径(支持
~、%USERPROFILE%),保存后新的备份都落在那里;留空保存即恢复默认位置<DSH_HOME>/dsh-backup-rescue/exports - 勾选「同时把已有备份迁移过去」后,旧目录里的
normal/、full/、历史平铺备份(含同名.bat)会整体搬到新位置,并保留修改时间;目标已存在同名备份时不会覆盖,会改名合并 - 迁移只在保存成功前发生:目标目录建不出来就报错并保留原设置
- 设置存放在
<DSH_HOME>/dsh-backup-rescue/settings.json
自动备份
设置页「⏱ 自动备份」卡片:
- 勾选启用后,按填的数字 每隔 i 分钟自动做一份一般备份(
i取 1–43200) - 最多保留 j 份(
j取 1–5000):每次自动备份后按时间倒序只留最新的 j 份普通备份,更早的连同它们的文件夹、同名.bat一起删掉 - 完整备份不参与淘汰,永远不会被自动删除
- 卡片里能看到调度状态、下次执行时间、上次执行结果与上次清理了几份
- 卡片提示「恢复时请运行对应版本的 .bat」:备份文件夹里的
<备份名>.bat与你当前插件版本配套,别混用别的版本留下的脚本
备份目录布局
<backupDir>/ 默认 ~/.dsh/dsh-backup-rescue/exports
├── normal/
│ └── dsh-backup-2026-10-22T10-15-00-000Z/ ← 与压缩包同名的文件夹
│ ├── dsh-backup-2026-10-22T10-15-00-000Z.zip
│ ├── dsh-backup-2026-10-22T10-15-00-000Z.bat ← 双击恢复这份备份
│ ├── dsh-backup-2026-10-22T10-15-00-000Z.sh ← macOS/Linux 同一份
│ ├── restore.bat
│ └── restore.sh
└── full/
└── dsh-backup-full-2026-10-22T10-20-00-000Z/
├── dsh-backup-full-2026-10-22T10-20-00-000Z.zip
└── …(同上)
一般备份与完整备份分开存放;每份备份的压缩包和它的恢复脚本在同一个文件夹里,不会互相覆盖,删掉一个文件夹就等于删掉这一份备份。
一键备份并更新
设置页「版本」卡片上的 🔄 一键备份并更新(Agent 工具 backup_plugin_update,HTTP POST /api/dsh-backup-rescue/update)固定按这个顺序执行:
- 先做一份一般备份(失败就立即终止,不会在没有备份的情况下动插件)
- 查 npm 上的最新版本;本地不比它旧就直接结束,只留备份
- 把
dsh-backup-rescue@<新版本>加进 profilepnpm-workspace.yaml的minimumReleaseAgeExclude(否则 24 小时内发布的新版会被 pnpm 拒绝) - 优先用 DSH 自带的 pnpm 安装(
dsh-runtimes/*/dependencies/pnpm),失败退回npm install --save-exact - 校验安装后的版本号,重启 DSH 生效
独立恢复器
恢复必须用对应版本的脚本:每份备份的文件夹里都有一份与压缩包同名的 .bat(加密备份对应 .bat 里带 --password 提示),双击它就会恢复这一份备份:
<备份名>.bat/<备份名>.sh— 双击即恢复该备份;加密备份会先提示输入密码restore.bat/restore.sh— 交互式:手动挑任意备份、查看清单、选择目标目录
注意(0.4.1 起):restore.bat 是纯 ASCII + CRLF,既不带 BOM 也不含中文。原先是 UTF-8 BOM + 中文注释,cmd.exe 会按当前代码页重新读文件,多字节字符把解析器带到行中间,双击就变成“窗口一闪而过”(还会报 'OT' is not recognized)。所以脚本内所有提示改成了英文,中文说明放在设置页与本文档里。
加密备份(.zip.enc)的解密环境:
DSHBK002(0.4.1 起):Windows 用自带 PowerShell 5.1;macOS/Linux 用node,没有 node 时用python3 + opensslDSHBK001(0.3.x–0.4.0):需要 DSH 自带node.exe(Windows)或pycryptodome(macOS/Linux),否则脚本会提示改用 DSH 界面恢复
把某个备份文件夹整体挪到别的机器上,双击里面的同名 .bat 也能恢复(脚本用 %~dp0 定位同目录的压缩包)。自动化可用环境变量:DSH_RESTORE_PASSWORD(密码含引号/空格/& 时只有这种方式可靠)、DSH_RESTORE_TARGET、DSH_RESTORE_YES=1、DSH_RESTORE_NO_PAUSE=1、DSH_RESTORE_SKIP_PROCESS_CHECK=1。
注意(0.4.2 起):覆盖文件前会先清掉只读属性、写完再还原。DSH 把 attachments/v1/objects/** 存成只读的校验和对象,以前恢复会在这类文件上抛 ExtractToFile 的“访问被拒绝”,整次恢复中断。另外在设置页点「恢复」加密备份时会先弹窗要密码,没给就返回 400 password-required,不会再静默失败。
文件结构
dsh-backup-rescue/
├── src/
│ ├── index.ts # 插件入口(同时启动自动备份调度器)
│ ├── types.ts # 共享类型定义
│ ├── backup.ts # 备份核心
│ ├── restore.ts # 恢复核心
│ ├── update.ts # 一键备份并更新(npm 查询 + pnpm/npm 安装)
│ ├── settings.ts # 设置持久化(备份位置 / 自动备份)
│ ├── migrate.ts # 换备份位置时的迁移
│ ├── prune.ts # 保留份数 + 删除最早的普通备份
│ ├── scheduler.ts # 自动备份调度器(setTimeout 链)
│ ├── tools.ts # Agent 工具注册
│ └── routes.ts # REST API 路由
├── templates/
│ ├── restore.bat # Windows 独立恢复器(纯 ASCII + CRLF,不带 BOM)
│ └── restore.sh # macOS/Linux 独立恢复器
├── tests/
│ ├── backup.test.ts # 备份/恢复/加密/插件清单单测(34 条)
│ ├── update.test.mjs # 一键备份并更新单测(15 条)
│ ├── settings.test.mjs # 设置/迁移/清理/调度单测(38 条)
│ └── client-render.test.mjs # 设置页组件渲染冒烟
├── cordis.patch.yml # Cordis 插件加载配置
└── package.json
跳过规则
默认跳过:
node_modules、.git、.cache、cache、logs、log、tmp、tempdsh-runtimes、web-login、speech-to-text、dsh-market(顶层)- 目录名含
snapshot、.bak、.old、.trash的目录 - 后缀为
.log、.tmp的文件
加密
加密备份格式(0.4.1 起):
[DSHBK002][16-byte salt][16-byte IV][32-byte HMAC][AES-256-CBC 密文]
- 密钥:PBKDF2-HMAC-SHA256(20 万次)从密码派生 64 字节,前 32 字节做 AES-256-CBC 密钥,后 32 字节做 HMAC-SHA256 密钥
- 认证:HMAC 覆盖
magic | salt | IV | 密文(encrypt-then-MAC),密码错误报wrong password (HMAC mismatch) - 为什么不用 GCM:独立恢复脚本只能用 Windows 自带的 PowerShell 5.1,它既没有
AesGcm也没有 scrypt,而 PBKDF2 / AES-CBC / HMAC 全都有 - 旧格式
DSHBK001([DSHBK001][salt][IV][tag][AES-256-GCM 密文],scrypt 派生密钥)仍可解密 - 密码至少 4 个字符
测试
npm run build
node --test tests/backup.test.ts # 47 条:备份/恢复/加密/排除规则/只读覆盖/插件清单/可选带插件/路径改写
node tests/update.test.mjs # 15 条:版本比较、registry 查询、白名单、一键备份并更新
node tests/settings.test.mjs # 38 条:设置读写、位置迁移、保留策略、定时调度
node tests/restore-bat.test.mjs # 32 条:真实调用 cmd.exe 跑 .bat(双击路径、特殊密码、错误密码、只读目标、路径改写、工作区恢复、旧格式)
node tests/client-render.test.mjs ./client.js # 设置页组件渲染冒烟
版本历史
0.4.5 — 备份可包含工作区文件:新增
includeWorkspaces(设置页「连同工作区文件」复选框、工具参数同名),从storages/workspace.json读取工作区路径并逐文件打包到__workspaces__/<id>/…(清单记录workspaceRoots、includedWorkspaces;工作区里同样跳过node_modules/cache/*.log等);恢复时先按路径改写算出新位置,再把暂存文件搬到真实目录并清空暂存(.bat与界面恢复都支持,结果里多出workspaceRestores)。踩坑:.bat里用FullName.Substring(stage.Length)求相对路径时,%TEMP%的 8.3 短路径(XIAOXI~1)与 .NET 返回的长路径长度不一致,导致文件被塞进-6\这类错目录;改成按名字递归搬运后修复0.4.4 — 一般备份新增「包含插件文件」选项(勾上后
includeNodeModules: true,把profiles/*/node_modules打进包,体积约 +455 MB,换机器/离线可直接用);恢复默认自动改写绝对路径:把备份清单里的旧$DSH_HOME、旧用户目录前缀替换为恢复目标(同时匹配\、JSON 转义的\\与/三种写法,跳过node_modules与.backup-snapshot,单文件 ≤8 MB),restore.bat(脚本内报告[OK] path rewrite: N file(s))与界面/工具恢复(rewritePaths,结果里带pathRewrites统计)都支持,可用rewritePaths: false关闭0.4.3 — 修复“完整备份其实没带插件”:
node_modules一直被无条件跳过,导致全量备份也缺插件代码,恢复后 DSH 有插件记录却加载不到;现在全量备份会打包profiles/*/node_modules等目录(只永久跳过exports/.git/临时目录);一般备份在清单里新增plugins(各 profile 的 name@version)与includedNodeModules标记,恢复后若 profile 有依赖清单却没有node_modules会明确提示pnpm install --frozen-lockfile;设置页对两种备份的差异加了醒目提示0.4.2 — 修复恢复被只读文件打断:DSH 的
attachments/v1/objects/**是只读对象,.bat的ExtractToFile与界面恢复的writeFileSync都会抛“访问被拒绝/EACCES”,现在覆盖前清只读、写完还原(restore.bat与src/restore.ts同一策略,新增 4 条只读覆盖断言);设置页恢复加密备份时会弹窗要密码,缺失时后端返回400 password-required,界面不再把ok:false当成功显示0.4.1 — 修复「加密备份双击同名
.bat只闪一下就关」:根因是restore.bat以 LF 保存、且用 UTF-8 BOM + 中文(cmd 按当前代码页重读文件会把解析器带到行中间);改为纯 ASCII + CRLF、无 BOM;加密封装升级为DSHBK002(PBKDF2-SHA256 20 万次 + AES-256-CBC + HMAC-SHA256),让恢复脚本只靠 Windows 自带 PowerShell 就能解密,旧DSHBK001仍可读;restore.sh支持两种封装并优先用 node、没有 node 时用python3 + openssl(解压也支持退回 python3 的zipfile);新增tests/restore-bat.test.mjs(真实调用cmd.exe走双击路径、特殊密码、错误密码、旧格式)0.4.0 — 备份位置可选(任意绝对路径,可连同已有备份一起迁移,保留修改时间、冲突不覆盖);新增定时自动备份(每隔 i 分钟做一份一般备份,最多保留 j 份,超过自动删最早的,完整备份不参与);新增
settings.json持久化、backup_plugin_settings/backup_plugin_prune工具与GET/POST /settings、POST /prune路由;设置页新增「备份位置」「自动备份」两张卡片0.3.3 — 「一键更新」改为「一键备份并更新」(先做一般备份再从 npm 升级,备份失败即中止);每份备份改为独立同名文件夹,压缩包与同名
.bat/.sh放在一起;一般备份与完整备份分别落在exports/normal/、exports/full/;设置页显示三个备份目录、备份列表带类型列并提供「对应恢复脚本」提示;listBackups兼容 0.3.2 的平铺目录0.3.2 — 新增全量备份(包含 node_modules 等所有目录)、一键更新检查/安装;包名从
dsh-backup-plugin改为dsh-backup-rescue0.3.1 — 新增 types.ts 共享类型;修复 restore.bat UTF-8 BOM;测试全面更新;独立恢复器支持加密备份
0.3.0 — 完整备份/恢复,SHA-256 校验,AES-256-GCM 加密,Agent 工具注册
许可证
MIT