dsh-env-backup

Readme

# dsh-env-backup

DSH 环境自动备份插件：在每次插件安装/更新导致 web 插件表变化时，自动备份
`~/.dsh/profiles/web` 目录，采用轮转命名并支持保留策略自动清理，防止插件
安装/更新把现有环境搞坏后无法回退。

An automatic web-profile backup guard for DeepSeek Harness: whenever a plugin
install/update changes the web plugin table, it snapshots `~/.dsh/profiles/web`
with a rotating naming scheme and prunes old backups per your retention policy.

## 功能 / Features

- **自动触发**（多路径覆盖，任何安装/更新方式都不会漏）：
  - **启动时指纹比对**：比对源目录（package.json、pnpm-lock.yaml、
    cordis*.yml、.dsh-market/state.json、node_modules 顶层）与上次备份时记录的
    指纹，有变化立即备份（`boot`）；
  - **周期检查**：运行中每 60 秒做一次同样的指纹比对（`change`），覆盖宿主
    热重载、CLI `dsh plugin` 等在进程内不触发插件表事件的操作；
  - **插件表事件**：订阅 `clientModules.onGraphChanged` / `onRebuilt`
    （`auto`），进程内重组图时快速响应；
  - **手动**：设置页「立即备份」或 `POST /dsh-env-backup/backup`。
- **轮转命名**：最新备份为 `web.latest_bak`；下一次备份把旧的
  `web.latest_bak` 归档为 `web.YYYYMMDDHHMM`（按备份时间，同分钟冲突加
  `-2` 后缀）。
- **保留策略**（可在 设置 → 环境备份 中调整，持久化于 `~/.dsh/web-backup.json`）：
  - `retentionDays`：保留时长（天），超出即自动清理；`0` = 不限。
  - `maxBackups`：最多保留的备份数量（含 `web.latest_bak`）；`0` = 不限。
  - `backupDir`：备份目录，默认 `~/.dsh/profiles`。
- **设置页**：设置 → 环境备份（备份目录 / 保留时长 / 最多数量 / 立即备份 /
  清理过期 / 备份列表 / 恢复指引）。
- 只清理匹配 `web.latest_bak` / `web.<12位时间戳>` 的备份目录，绝不触碰其它目录。

## 安装 / Install

本地安装（本机开发）：

```sh
dsh plugin --profile web add file:/path/to/dsh-env-backup
```

GitHub 安装（上传后）：

```sh
dsh plugin --profile web add github:<你的用户名>/dsh-env-backup
```

安装后**重启 dsh** 生效（宿主侧在启动时加载）。插件会以 bundle 形式写入
profile 的 `dsh.profile.bundles`，之后不受其它插件更新和重启影响。

## 恢复 / Restore

若插件安装/更新导致环境崩溃：

1. 停止 dsh；
2. 把备份目录中的 `web.latest_bak`（或某个 `web.YYYYMMDDHHMM`）复制回
   `profiles/web`（先移除当前损坏的目录）；
3. 重新启动 dsh。

注意：`web.latest_bak` 是插件表变化后生成的备份；若它已是损坏状态，请回退
到时间更早的 `web.YYYYMMDDHHMM`。

## 配置 / Configuration

配置文件：`~/.dsh/web-backup.json`（首次运行自动生成，也可在设置页修改）：

```json
{
  "enabled": true,
  "backupDir": "/home/<user>/.dsh/profiles",
  "retentionDays": 30,
  "maxBackups": 5
}
```

## 开发 / Development

```
dsh-env-backup/
├── package.json        # dsh.bundle.patch + dsh.client 声明
├── cordis.patch.yml    # 把本插件插入 profile 层栈
├── lib/index.js        # 宿主：备份引擎 + HTTP API + 自动触发
├── client/client.js    # 客户端：设置页（module-loader 格式）
├── README.md
└── LICENSE
```

## License

MIT