# dsh-backup 📦

[English](README.md) | [简体中文](README.zh-CN.md)

![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)

*非官方项目：社区成员独立开发维护，非 DeepSeek 官方产品。*

DSH 数据自动备份——会话记录、配置文件与自定义目录打包成 `.zip`，支持定时与手动备份、自动轮转。

## 截图

![dsh-backup 设置页](assets/dsh-backup-settings.png)

| 操作 | 效果 |
|---|---|
| 定时备份 | 按设定的间隔自动打包 DSH 数据（默认每 6 小时） |
| 手动备份 | 设置页一键「立即备份」 |
| 自定义目录 | 每行一个绝对路径（如记忆库） |
| 自动轮转 | 只保留最近 N 份（默认 10），旧的自动删除 |
| 恢复 | 仅手动——把压缩包解压回原位置（步骤见 `docs/install.md`） |

**默认备份内容（v0.4.0 起扩充）：** `~/.dsh/sessions`（会话记录）、`~/.dsh/profiles`（配置，**排除** `node_modules`）、`~/.dsh/AGENTS.md`（全局约定）、`~/.dsh/cordis.patch.yml`（全局补丁）、`~/.dsh/storages`（定时任务 / 工作区，**排除**投影缓存）、`~/.dsh/bin`（自建脚本）、根层小配置（`*.json/yml/yaml/txt`，< 1MB）、**`~/.dsh/attachments`（上传原件，默认开、可在设置页关掉）**、**凭据（`.credentials.yaml` / `llm-deepseek`，默认开；⚠️ zip 不加密——关掉它，恢复时需重新登录/填 key）**。其它内容（比如记忆库）加到自定义目录列表。

**自动跳过（噪音 / 可重建）：** `.DS_Store`、`*.lock`、`*.bak-fix`、`*-shm`/`*-wal`、`storages/session_projcache*`。**明确不备份**（重装/重建即可）：`session-index.sqlite`、`cache/`、`dsh-runtimes/`、`speech-to-text/`。

## 安装

```bash
# DSH 0.1.7 及以后：
dsh plugin --profile web add "github:a903067276-rgb/dsh-backup#main"
# DSH 0.1.5 及更早（本版需要 0.1.7+）：
# dsh plugin --profile web add "github:a903067276-rgb/dsh-backup#v0.1.4"
```

然后重启 `dsh web`。手动兜底：`docs/install.md`。

## 使用

打开 **设置 → 备份**：

- 状态行：上次备份 / 下次定时 / 备份目录
- 「立即备份」按钮
- 备份列表：文件名、大小、时间、删除
- 设置：备份目录、定时开关 + 间隔（小时）、保留份数、自定义目录（每行一个绝对路径）

## 平台支持

| 平台 | 状态 |
|---|---|
| macOS | ✅ 实测 |
| Linux | ✅ 预期可用（纯 Node 实现，不依赖系统 zip） |
| Windows | ✅ 预期可用（纯 Node 实现，不依赖系统 zip） |

## 环境要求

- DSH web（≥ 0.1.0-rc.6）
- **版本兼容**（尽力兼容——设置卡片用双字段 `key`+`id` 注册，同满足 rc.6（id 契约）与 rc.7+（key 契约）；已在本地实测 rc.6/rc.8/0.1.1-rc.2/0.1.5-rc.1，**不保证每个 DSH 版本**）：
  - DSH 0.1.0-rc.6 及以上（含 0.1.1-rc.1/rc.2）：装 `main`（默认）。
  - **DSH 0.1.7：配置即时生效**——配置字段改由插件导出 `Config` schema 声明（全部 `.volatile()`），设置页保存走官方设置服务，**改完立即生效、不需要重启**；插件写配置走自己的 profile 条目 config（`settings.update(entryId, patch)`）。需宿主 `@deepseek-ai/schemastery` ≥ 3.18.3（0.1.7 自带）。
  - **DSH 0.1.5-rc.1：加载实测通过**（host 半加载日志正常）；只用 `settings`/`shell` 等稳定服务，不碰 0.1.5 变更过的契约。备份/还原端到端流程未在 0.1.5 上复测。
  - 保守回退（升级前的最后版本）：DSH 0.1.0-rc.7/rc.8 → `v0.1.2`（`dsh plugin add github:a903067276-rgb/dsh-backup#v0.1.2`）；DSH 0.1.0-rc.6 → 冻结 `rc6-compat`（不再维护）。
- Node.js ≥ 16.7（DSH 自带）
  - ✅ **DSH 0.1.7 及以后——装本版（`v0.3.2`）**：它声明了 `peerDependencies: {"@deepseek-ai/dsh": "^0.1.7-rc.1 || ^0.2.0-rc.1"}`，宿主不匹配会明确拒绝加载并说明原因，不再静默出错。配置迁到 0.1.7 的插件 `Config`（`.volatile()` 字段可即时生效），改完不用重启。
  - ✅ **DSH 0.2.0-rc.1——已验证兼容**：peer 范围同时覆盖两条线（`^0.1.7-rc.1 || ^0.2.0-rc.1`），`dsh.compatibility.dshReleases` 矩阵新增 `"0.2.0-rc.1": "compatible"`——已在 0.2.0-rc.1 真机 + 影子实例验证。0.2 起宿主对 profile bundle 做 peer 门禁，范围不覆盖当前运行时会**整个跳过加载**，靠这个范围插件才会被加载。
  - ⚠️ **DSH 0.1.5 及更早——请装上一版 tag `v0.1.4`**：那条线保持原行为，不含任何 0.1.7 专用 API。
  - ⛔ **旧版本插件（≤ `v0.1.4`）在 0.1.7 上不受支持**——设置静默失效（`settings.register/get` 已删除）。插件要跟宿主一起升。
- **维护策略**：本插件将持续跟随 DSH 最新版本演进；对旧版 DSH 的兼容仅是尽力而为、不保证长期有效。

## 工作原理

- **Host 半**：零依赖 zip 打包器（`lib/zip.js`，纯 Node 流式——不依赖系统 zip、不走 shell、不受会话沙箱限制）；`timer` 定时调度；`/api/dsh-backup/*` 路由供设置页调用。
- **Client 半**：一个设置页区块（`settings.section`，「备份」）负责列备份、改配置；保存走官方设置服务写进插件自己的 profile 条目 config（volatile 字段，**改完即时生效、无需重启**；只有 0.1.7 之前的老宿主才回落写 patch 文件，那条路径仍需重启）。

## 注意事项

- 恢复故意只做手动：先停 DSH、把压缩包解压覆盖回原路径，且确认恢复无误前保留现有数据。插件自身绝不覆盖任何东西。
- 备份目录默认 `~/Documents/DSH/backup`，可在设置里修改。
- 只列出/删除本插件命名的备份（`dsh-backup-*.zip`），目录里其它文件不动。

## License

MIT