简体中文 ·
English
dsh-quick-backup
面向 DeepSeek Harness（DSH） 用户环境的本地 Git 增量备份工具，提供 设置 → 备份 面板。
> 本 GitHub 仓库只包含插件和工作流脚本。
> 你的 DSH profile、会话、凭据、API Key 和备份数据永远不会进入这个仓库。
> 备份保存在 setup.ps1 创建的独立本地仓库中。
你将获得
- 在 DSH 设置 → 备份 中一键备份
- 本地 Git 历史，日期版本号：
vYYMMDD.E.SSS - DSH 启动时自动备份（可选 watcher）
- 查看版本、导出、复制安全的恢复命令
- 缓存感知：单纯重启 DSH 不会产生无意义的版本
- 不联网、没有远程仓库、不上云
⚠️ 数据与密钥风险（务必阅读）
> [!WARNING]
> 如果开启“备份凭据与 APIKey”，数据仓库会把 .credentials.yaml 和 APIKey 以明文保存在本地，而且 Git 历史永不遗忘。
>
> 默认不备份这两项。若你主动开启，并把备份文件夹进行云同步、网盘同步、网络驱动器同步，或者转发给他人，由此导致的凭据或隐私泄露由你自行承担，作者不承担任何责任。
>
> 注意！v0.1 默认为开启保存密钥设置。 使用 v0.1 时请特别小心；建议升级到 v0.2 或更高版本。
环境要求
- Windows 10/11
- PowerShell 5.1（系统自带）
- Git for Windows（脚本优先使用
C:\Program Files\Git\cmd\git.exe） - DSH desktop
>= 0.2.1-rc.2
快速开始
1. 获取文件
git clone https://github.com/SShiRkiT/dsh-quick-backup.git
cd dsh-quick-backup
2. 创建本地备份仓库
备份路径默认是空的。 必须显式传入 -RepoPath：
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -RepoPath "D:\DSH-Backups" -EnableAutostart
setup.ps1 会：
- 检测/使用你的
.dshprofile（默认%USERPROFILE%\.dsh） - 在你指定的路径创建备份仓库
- 复制工作流脚本并写入
backup.config.json - 初始化本地 Git，并创建第一个基线版本
- 注册插件发现配置
- 可选安装登录 watcher（
-EnableAutostart）
常用参数：
# 自定义 profile / 安装目录
.\setup.ps1 -RepoPath "D:\DSH-Backups" -DshProfile "$env:USERPROFILE\.dsh"
# DSH 安装在自定义目录
.\setup.ps1 -RepoPath "D:\DSH-Backups" -InstallRoot "D:\DSH\Desktop"
# 只复制脚本和配置，暂不复制 profile
.\setup.ps1 -RepoPath "D:\DSH-Backups" -SkipInitial
# 如需备份 .credentials.yaml 与 APIKey（默认不备份）
.\setup.ps1 -RepoPath "D:\DSH-Backups" -IncludeCredentials
3. 安装插件
打开 DSH 桌面端的 设置 → 插件，选择从仓库安装，填写：
https://github.com/SShiRkiT/dsh-quick-backup
然后重启 DSH，应该能看到 设置 → 备份。
> 私有仓库需要先完成 GitHub 登录；公开后不需要。
> 开发调试时也可以让 DSH 指向你本地的仓库目录。
4. 使用
打开 设置 → 备份。如果 setup 没有配置过备份路径，在 备份仓库路径 输入框中填写路径，然后点 保存路径。
| 控件 | 作用 |
|---|---|
| 备份仓库路径 | 设置或修改本地数据仓库路径 |
| 备份凭据与 APIKey | 默认关闭；开启后备份 .credentials.yaml 和 APIKey |
| 恢复旧 storages 缓存 | 从 .dsh.pre-restore-* 恢复 cost-meter / session 缓存；不进入 Git 历史 |
| 备份 | 增量备份（遵守 60 秒最小间隔） |
| 忽略间隔备份 | 立即强制备份 |
| 校验 / 深度校验 | 校验仓库与 Git 对象 |
| 历史版本 | 选择版本 |
| 复制恢复命令 | 复制安全的恢复命令 |
| 导出 | 将选定版本导出到新目录 |
| 启用 / 停用 | 安装/移除登录 watcher |
| 运行诊断 | 执行一次不备份的 watcher 检查 |
备份仓库路径
- 插件默认路径为空；不会擅自假设某个目录。
setup.ps1会把选定路径写入%LOCALAPPDATA%\dsh-quick-backup\config.json。- 插件也支持环境变量
DSH_BACKUP_REPO（优先级最高）和同一个配置文件。 - 路径必须是本地绝对路径，例如
D:\DSH-Backups。 - 该目录必须是由
setup.ps1创建的数据仓库（包含scripts\backup.ps1）。如果还没初始化，面板会显示“未就绪”并提示先运行 setup。 - 在插件中修改路径会立即生效，不需要重启 DSH。
凭据备份开关
- 默认关闭：不备份
.credentials.yaml与APIKey。 - 可在 设置 → 备份 → 备份凭据与 APIKey 开启，或在 setup 时使用
-IncludeCredentials。 - 开启后，后续版本会包含这两项；关闭只会排除后续版本，旧 Git 历史不会自动清理。如果之前备份过凭据，需要重建数据仓库或清理 Git 历史，才能真正移除旧副本。
恢复旧 storages 缓存
备份会把 storages\cost-meter、storages\session_projcache、session_projcache.json 排除在 Git 历史之外，所以它们不能通过回档 tag 恢复。
在 设置 → 备份 → 恢复旧 storages 缓存 中：
- 输入完整副本路径（通常是
.dsh.pre-restore-*）；留空会自动选择最新副本 - 只复制
cost-meter、session_projcache、session_projcache.json - 不修改
workspace.json、设置、插件、凭据 - 复制前先把当前 storages 安全备份到数据仓库
state\storage-restore-* - 不执行 git add/commit，不会产生新的 Git 版本
- 恢复后请重启 DSH 使缓存生效
版本规则
格式：vYYMMDD.E.SSS
| 段 | 含义 |
|---|---|
YYMMDD |
当前大环境基线建立日期 |
E |
该日期内第几次大环境变动（1、2……；跨天重置为 1） |
SSS |
该基线内第几次小变动（001……；大环境变动时重置） |
以下情况进位：
- 大版本 / 环境变动：DSH 升级、插件安装/更新/移除、
dsh-ops或运行时更新 - 小版本：会话、附件、设置、凭据、工作区状态、脚本/文档更新
示例：
v261025.1.001 基线
v261025.1.002 新对话
v261025.2.001 同一天更新插件
v261026.1.001 次日升级 DSH
详细规则见 docs/VERSIONING.md。
仓库结构
dsh-quick-backup/ # 本仓库（不含个人数据）
├─ package.json # DSH 插件包根配置
├─ lib/ # 插件 host + client
├─ cordis.patch.yml
├─ scripts/ # 会复制到数据仓库的工作流脚本
├─ setup.ps1 # 创建本地数据仓库
├─ docs/
└─ test/ # 插件自测
<你选择的路径>/ # 数据仓库（仅本地，绝不提交到这里）
├─ .git/ # 备份历史
├─ mirror/ # 当前 DSH 状态镜像
├─ state/ # 日志、每版本元数据（gitignored）
├─ backup.config.json # 本地配置（gitignored）
├─ version.txt
├─ VERSIONS.md
└─ scripts/
数据仓库是一个独立的 Git 仓库。本项目的 .gitignore 不会跟踪任何备份数据。
命令行
以下命令都在数据仓库中运行：
$B = "D:\DSH-Backups"
# 立即备份
powershell -ExecutionPolicy Bypass -File "$B\scripts\backup.ps1" -Trigger manual
# 查看版本
powershell -ExecutionPolicy Bypass -File "$B\scripts\restore-version.ps1" -List
# 回档（会关闭 DSH！）
powershell -ExecutionPolicy Bypass -File "$B\scripts\restore-version.ps1" v261025.1.002 -Force
# 只导出
powershell -ExecutionPolicy Bypass -File "$B\scripts\restore-version.ps1" v261025.1.002 -ExtractTo "D:\DSH-restore-261025-1-002"
# 校验
powershell -ExecutionPolicy Bypass -File "$B\scripts\verify.ps1" -Deep
缓存文件不备份
以下内容会被有意排除，避免单纯重启就产生新版本：
.dsh\cache、.dsh\logsstorages\session_projcache*storages\cost-meter\（包括ledger.json；成本历史不备份）studymate\reach\- Electron 的
Cache、Code Cache、GPU*、logs、Local Storage、Session Storage、Network、Shared Dictionary、blob_storage、WebStorage、Preferences、LOG*、lockfile、Cookies*、DIPS* profiles\node_modules（失效 junction）- DSH 程序本体
会话正文（sessions、attachments）和设置会被备份。
回档安全
- 回档脚本会关闭 DSH（当前会话会结束）。
- 当前 profile 会被改名为
.dsh.pre-restore-<时间戳>，而不是直接删除。 - 设置页不会直接执行回档；插件只复制一条命令，由你在独立 PowerShell 窗口中运行。
- 回档前请先确认选定版本的 DSH 程序版本与当前一致（仓库中保存了
install-info.txt）。 - 回档完成后，下一次备份会把回档后的状态记录为新版本。
隐私与安全
- 备份数据仓库仅在本地；
push.default=nothing和pre-push钩子会阻止误推送。 - 数据仓库包含你的会话、附件、设置等隐私内容；若开启凭据备份，还会包含明文凭据（
.credentials.yaml、APIKey），请按敏感数据保管。 - 本 GitHub 仓库不包含任何凭据、会话、profile 副本或备份数据。
- 不要把数据仓库上传到 GitHub 或云盘。
详见 docs/SECURITY.md。
卸载
# 移除 setup 安装的登录 watcher
powershell -ExecutionPolicy Bypass -File "D:\DSH-Backups\scripts\uninstall-autostart.ps1"
# 移除插件
dsh plugin --profile desktop remove dsh-quick-backup
只有当你不再需要历史时才删除数据仓库。
故障排查
- 设置里没有插件：检查
dsh plugin --profile list，然后重启 DSH。 - 面板显示“未就绪”：路径为空，或该目录不是数据仓库；运行
setup.ps1 -RepoPath，或保存正确的路径。 - 备份失败：查看
state\logs\backup.log、state\last-run.json。 - 正常使用不需要 Git 认证；本工具从不推送。
- 需要对象完整性检查时运行
verify.ps1 -Deep。
开发
# PowerShell 语法检查（Windows PowerShell 5.1）
powershell -File .\scripts\verify.ps1 # 需要已有数据仓库
# 插件自测
node .\plugin\verify.mjs
test/verify.mjs 使用临时 fixture，不会接触你的 DSH 数据。
许可证
MIT，见 LICENSE。
