dsh-backup
English | 简体中文
你所有的 DeepSeek Harness（DSH）工作数据都在一个目录里：~/.dsh。一次升级失败、一次误删、一次换电脑——没有备份，会话、设置、技能全没了。dsh-backup 用一条命令把它们找回来。
dsh plugin --profile web add @xiaoyuyu6420/dsh-backup # 安装
# 重启 dsh web，然后输入：
/backup # → 一份带校验的备份落在 ~/Desktop/DSH Backups/
v0.9.0 全新安装的真实输出：
备份完成: dsh-20260826-195150036.tar.gz
sha256: 8f9ae6322ef782d21554981cf4547220d5bb3e64d7964a883317415ad54e3cbb
轮换删除 0 份（保留 7 份）
不想敲命令也行：dsh web → 设置 → 插件 → 备份 里有可视化面板——列备份、校验、恢复、删除、改设置，全都立即生效不用重启。
备份面板
三条承诺（完整对齐与交付标准见 ALIGNMENT.md）：
- 🔐 凭据不离开本机 —— API Key / Token 默认脱敏，明文只留在本机 vault；要更强，可选口令加密备份（AES-256-GCM）。
- ↩️ 恢复绝不静默覆盖 —— 恢复前先自动快照当前数据、预览要写入的内容，失败自动回滚。
- 🧭 装上就知道怎么用 —— 首屏三步引导 + 每个高级功能一句人话说明；三个 Tab（备份 / 恢复 / 设置），主按钮只有一个「立即备份」。
它替你挡掉哪些事
| 你担心的 | dsh-backup 做的事 |
|---|
| 「升级把环境搞坏了」 | 宿主版本一变就自动拍 dsh-pre-upgrade- 快照——放心试新版，坏了随时回滚 |
| 「我误删 / 改坏了东西」 | /backup restore latest --dry-run 先预览要恢复什么再动手；恢复失败自动回滚并给出结果回执 |
| 「DSH 根本起不来了」 | 每次备份都会往备份目录放一个零依赖的救援控制台（dsh-rescue / rescue.mjs，或双击「点我恢复」）——不依赖 DSH 的网页版恢复界面 |
| 「API Key 会被传到云上吗」 | 凭据默认脱敏，不进备份包；明文只存本机 vault，永不离开这台机器 |
| 「会话日志损坏了」 | /backup doctor 体检并从备份定点修复；损坏文件先隔离再入档，防止轮换把好副本也带走 |
| 「升级后老会话打不开了」 | /backup migrate-check 迁移预检：升级前静态扫描全部会话，预测哪些会被新宿主拒绝、挂在哪条规则；旧版扁平凭据文件在宿主改写前自动存底 |
| 「换新电脑了」 | GitHub 同步：/backup github pull 拉回云端备份，restore --sync-deps 顺手重装插件 |
| 「备份悄悄坏了没人知道」 | 每份归档带 sha256，/backup verify all 随时体检；每日/每周分级保留，留得住有用的历史 |
| 「我会忘记备份」 | /backup auto 12——每 12 小时自动跑，重启不中断，旧副本自动轮换（默认保留 7 份） |
| 「换新电脑，插件和配置都要重装」 | 单文件 ZIP 导出/导入 + 本地 link:/file: 插件迁移；也能 WebDAV / S3 兼容 / Gist 多通道推送(跨机恢复走 GitHub 通道拉取或 ZIP 导入) |
| 「想从别的 AI 工具搬过来」 | 从 Claude Code / Cursor / Codex 读取技能与全局指令，预览后导入（MCP 只检测报告） |
| 「想回到对话里的某个时刻」 | 会话 Rewind 分叉：从指定轮次开新分支，原会话完整保留 |
| 「备份把磁盘占满了」 | 磁盘占用报告 + 分级清理：只清可再生缓存/过期备份，快照与同步数据不动 |
| 「想装社区现成配置」 | 配置市场：索引校验 + 预览安装 + 供应链提示，逐个确认才写入 |
遇到具体报错？ 按症状与报错原文查的排错手册：故障排查（会话打不开、29 字节空包、面板消失、Token 按钮报错、换机迁移……各条的版本与修法都写明）。
备份设置
安装
要求：macOS / Linux / Windows 10+（自带 tar），DSH 0.1.1-rc.2+（0.1.1 / 0.1.2 / 0.1.5 / 0.1.6 / 0.1.7 列车均已实测，0.2.0 / 0.2.1 列车分别自 0.13.2 / 0.14.0 起支持；当前兼容状态见 兼容性矩阵）。
dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
# 或者直接从 GitHub 安装：
dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
装完重启 dsh web 后插件才生效。
安装时可能刷出 ✕ missing peer @deepseek-ai/... 警告，属预期现象：这些
peer 包由 DSH 宿主在运行时提供，不装在 profile 目录里。只要命令以
Done 结尾就是装成功了。
快速上手
- 按上面装好插件，重启
dsh web
- 输入
/backup
- 搞定 —— 备份出现在
~/Desktop/DSH Backups/，文件名带时间戳，旁边一份 .sha256
想定时自动跑？/backup auto 12（每 12 小时一次；off 关闭，status 看状态）。
命令速查
| 场景 | 命令 |
|---|
| 立即备份 | /backup |
| 分类型备份（只备份选中类型） | /backup --types skills,sessions（可选：credentials·mcp·skills·sessions·settings·profiles；--only 同义） |
| 定时备份（重启不中断） | /backup auto 12 · off · status |
| 恢复（先预览） | /backup restore latest --dry-run |
| 正式恢复 | /backup restore latest |
| 分类型恢复（merge，不动其他类型） | /backup restore <归档> --types skills |
| 列出备份 | /backup list |
| 校验完整性 | /backup verify [前缀|all] |
| 会话日志体检/修复 | /backup doctor · --repair [前缀|latest] |
| 升级前迁移预检 | /backup migrate-check |
| DSH 起不来时自救 | 双击备份目录里的「点我恢复」，或 dsh-rescue / node rescue.mjs |
| 删除 / 保留策略 | /backup delete <前缀|latest> · /backup --keep N（默认 7） |
分类型备份
只想备份/恢复某几类数据？--types（或 --only）按内容类型子集操作，可选类型：credentials（凭据/api key）、mcp（MCP 配置）、skills（技能）、sessions（会话）、settings（设置）、profiles（插件 profiles）。
- 备份：
/backup --types skills,sessions 生成 dsh-t- 前缀的子集归档，与全量备份分开轮换、互不挤占保留份数
- 恢复：
/backup restore <归档名> --types skills 只把 skills 合并回现有 ~/.dsh（先 --dry-run 预览；覆盖的现有文件自动留档 .pre-merge-*），其他类型完全不碰
- 凭据类型特殊：
--types credentials 会把 api key 明文打进归档（默认全量备份是脱敏的）——这类归档绝不进 GitHub 同步，仅建议本机保存或手动拷到新机
- 安全护栏：分类型归档不带
--types 直接整包恢复会被拒绝（防止误覆盖丢数据）；rescue 救援通道同样不列、不整包恢复它们
- 面板（Settings → 插件 → 备份）同样支持：备份按钮下方勾选类型；分类型归档在独立分区展示与恢复
换新电脑
前提：旧电脑配过 GitHub 同步（配置方法）。
- 新电脑装好插件，配置里填同一个
githubRepo
/backup github pull —— 拉回云端备份/backup restore latest --sync-deps —— 恢复并重装插件依赖- 重启
dsh
常见问题
API Key / 密码会进备份包吗？
不会。已知的凭据文件打包前会脱敏，明文留在本机 vault 里不离开这台机器；恢复时自动还原。
到底备份了什么？
~/.dsh 下的全部——会话、设置、技能、插件配置——减去你配置的排除模式和 node_modules。
我把 ~/.dsh 搞坏了，dsh 都启动不了，还有救吗？
有——这正是救援通道的用途。每次备份都会往备份目录写 rescue.mjs 和双击启动器（macOS .command / Windows .bat / Linux .sh）。它只用普通 Node 就能跑，不需要 DSH，起一个本地网页让你浏览和恢复备份。
升级后老会话打不开了怎么办？
先别再点开它。运行 /backup migrate-check：静态扫描全部会话日志，告诉你哪些会话会被新宿主拒绝、挂在哪条规则（subagent descriptor 旧版本、插件注入的历史事件等），并检查文件系统硬链接支持。升级前先 /backup 拍一份，坏掉的会话可用 /backup doctor --repair 从更早的归档定点修复。
支持 Windows 吗？
支持——Windows 10+（用系统自带 tar），救援启动器是 .bat 文件。
备份默认放哪？
~/Desktop/DSH Backups/——在面板（设置 → 插件 → 备份）里随时可改，立即生效不用重启。0.14.0 起默认目录由旧的 ~/Desktop/dsh-backups 改名而来：从未配置过备份目录的用户，升级后首次启动会把旧目录自动改名（同盘、原子、不丢备份）；显式配置过目录的一律不动。
备份目录里那些文件都是什么？
每次备份会在目录根写一份「使用说明.txt」，逐个解释归档、.sha256 校验边车、救援工具、vault/ 凭据、auto.json 状态，以及恢复的三条路。第一次打开文件夹看完就知道哪个能删、恢复从哪下手。
反馈
用过吗？哪里坏了、缺什么、喜欢什么，都欢迎说——反馈直接决定路线图：
更新日志
最近的版本
-
0.14.2 —— 复核修复：加密/解密改分块流式并「写临时文件 → 原子替换」（大归档不再整包入内存，崩溃不留半截密文）；补 setGithubToken 缺失的客户端 descriptor + 「面板方法必有 descriptor」反向断言；redactSyncChannel 补花括号（修掉 s3/gist 通道假的 passwordSet:false）；文案补 Codex、导入预览不再承诺界面逐项覆盖、多通道同步写清为单向推送、About 加反馈入口、rescue --fix --map 需 --yes；验收 smoke 596 / settings 47 / client 62 / 真机 e2e 70。
-
0.14.1 —— 补发:npm 上的 0.14.0 先于 Codex 支持发布,本版把「Codex 聊天记录导入」补齐到 npm 版本(Claude Code / Codex 双来源:扫描 → 预览 → 导入为新会话,函数调用按 call_id 配对成工具调用/结果,原数据零改动),并同步验收数字(smoke 587 / settings 47 / client 60 / 真机 e2e 70)。
-
0.14.0 —— 一次大版本：备份目录 UX + 面板重构 + 与同类方案对齐的完整能力。① 目录改名：默认 ~/Desktop/dsh-backups → ~/Desktop/DSH Backups，从未配置过 destination 的用户升级后首次启动同盘自动改名（原子、不丢备份），显式配置不动，失败继续用旧目录；每次备份在根目录写「使用说明.txt」（每个文件是什么 + 三条恢复路径）。② 面板重构：三个 Tab（备份 / 恢复 / 设置）+ 首启三步引导 + 分类型 chips + 文案去术语 + 响应式。③ 备份增强：可选口令加密（scrypt+AES-256-GCM，口令不落盘）、单文件 ZIP 导出/导入（节段预览 → 冲突默认保留 → 自动快照 → 失败回滚）、本地 link:/file: 插件迁移。④ 同步与运维：WebDAV / S3 兼容 / Gist 多通道单向推送（跨机恢复用 GitHub 通道拉取或 ZIP 导入；Gist 单文件上限 10MB，只适合小体积）、GFS 月/年保留、操作锁 + 残留锁回收、磁盘占用报告 + 分级清理、每周调度。⑤ 生态：配置市场（索引校验 + 预览安装 + 供应链提示）、从 Claude Code / Cursor / Codex 导入技能与全局指令（MCP 只检测报告）、Profiles 管理（内置只读）、会话 Rewind 分叉（原会话零改动）、About 面板、agent 工具 1→6、跨工具聊天记录导入(Claude Code / Codex → 新 DSH 会话,原数据不动)、离线 CLI（reinstall / sessions repair / recover-stale-lock）。⑥ 兼容与验收：DSH 0.2.1-rc.2 真机 e2e 70/70，smoke 587 / settings 47 / client 60 全绿；另修复 Windows 上 doctor --repair 因 bsdtar 拒绝覆盖同名对象而失败（#131）：改为暂存区解包 + 按目标拷贝，非目标文件零改动。peers/engines 不变（^0.2.0-rc.1 覆盖 0.2.1 列车，下一 peer 边界 0.3.0）。
-
0.13.4 —— 元数据版（无代码与行为变更）：npm 描述与关键词对齐检索用词——补入「迁移 / 换机 / 插件 / MCP / 技能 / 会话 / 工作区」等，让"搬家换机、升级翻车"场景的人在 npm 搜索里能找到本插件。功能、归档格式、设置项、RPC 与 0.13.3 完全一致；升级到本版与停留在 0.13.3 在行为上没有任何区别。
-
0.13.3 —— 三条真实用户报障的修复 + 两个自建缺陷修复，全部在四条宿主列车（0.1.5-rc.3 / 0.1.7-rc.2 / 0.2.0-rc.2 / 0.2.1-alpha.1）真机 e2e 各 41/41 复验：① 含附件的归档恢复全链路不可用（#112，@zevs281）：DSH 附件库用硬链接（tar 记为 h 条目），而恢复校验器只放行 -/d——0.13.2 及更早对这类归档的完整恢复/dry-run/分类型合并/doctor 修复一律拒绝。修法：条目与目标都在备份根内的硬链接放行（符号链接、设备仍拒）。② 大归档恢复被误拒（#119，@Yoshino-JF）：归档清单超过宿主 subprocess 的 spill 上限时宿主会丢弃 spill 文件、只留 8 KB 尾窗，校验器把"断在文件名中间的碎片"当成不安全条目 → 整包拒绝（备份成功、verify 报完整、只在恢复时炸）。修法：清单改走原始流逐行校验（无上限，发现违规立即终止）。③ doctor/migrate 看不见 v4 会话日志（#117，@xiuwufangoc-design）：宿主 0.1.7 起会话格式为 v4（），而文件名与校准代写死到第 0 代/v3——体检与迁移预检一份都扫不到。修法：按宿主同源形态匹配文件名、校准代推进到 v4、更新代只提示。④ （#115）：pnpm 只在声明范围内升级，跨 minor 停在旧版且回执谎报成功。修法： + 跑完读回 profile 内真实版本核对。⑤ （#113，@zevs281）：未知 从"判打不开"降级为提示，名单对齐宿主权威集合（真机曾把 81/82 份健康日志误报）。
更多
定时备份策略、敏感文件脱敏、GitHub 同步、恢复保护机制、配置参考、故障排查、开发说明——都在进阶文档。便携安装与配置：INSTALL.md。跨运行时兼容性说明：compatibility.md。与同类方案的完整能力对齐与验收标准：ALIGNMENT.md。发布说明与宣发物料：docs/promo/。
致谢
支持这个项目
如果 dsh-backup 帮到了你：⭐ 给个 Star 是最直接的鼓励，也能让更多 DSH 用户找到它。遇到问题或有想法，欢迎到反馈帖留言。
许可证
MIT
