npm - @xiaoyuyu6420/dsh-backup - Versions diffs - 0.7.1 → 0.8.0 - Mend

@xiaoyuyu6420/dsh-backup 0.7.1 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -9,17 +9,7 @@ English | [简体中文](README.zh.md)
 **dsh-backup is a DeepSeek Harness (DSH) plugin that backs up and restores `~/.dsh` with a single command.**
-Everything you have in DSH — sessions, settings, skills, and plugin config — lives in one folder: `~/.dsh`. Delete it by accident, break a config, or move to a new machine: with a backup, you get it all back.
-What you get:
-- **One command to back up, one to restore** — every archive ships with a checksum so you can tell if it's corrupted, and old backups rotate out automatically.
-- **Scheduled backups** — set an interval and forget it. It keeps the schedule across restarts.
-- **Credentials never enter an archive** — plaintext stays in a local `vault/` folder and is restored automatically (details below).
-- **New machine, no panic** — backups sync to your private GitHub repo; pull them down on the new machine and restore.
-- **A web panel** — prefer clicking? There's a visual UI for everything.
-Works on macOS, Linux, and Windows.
+Sessions, settings, skills, and plugin config all live in `~/.dsh`. Delete it by accident, break a config, or move to a new machine — with a backup, you get it all back. Credentials never enter an archive; scheduled backups and GitHub sync are supported (details in the [advanced guide](docs/advanced.zh.md), Chinese).
 ## Install
@@ -29,160 +19,42 @@ dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
 dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
 ```
-Then restart `dsh web`.
-> ⚠️ **Don't install the wrong package**: the correct name is `@xiaoyuyu6420/dsh-backup`, with the scope. The unscoped `dsh-backup` on npm is an unrelated third-party package.
+Then restart `dsh web`. Requires macOS / Linux / Windows 10+ (ships `tar`) and DSH `0.1.1-rc.2` or compatible.
 ## Quickstart
-About 30 seconds:
 1. Install (above) and restart `dsh web`
 2. Run `/backup`
 3. Done — the archive lands in `~/Desktop/dsh-backups/`, named with a timestamp
-That one command covers day-to-day use. Want it to run on a schedule? See below.
-## Scenario cheat sheet
-| Situation | What to do |
-|---|---|
-| Routine backup | `/backup` (or "Back up now" in the panel) |
-| Afraid you'll forget | `/backup auto 12` — every 12 hours, keeps going across restarts |
-| Broke a config or a plugin install | `/backup restore latest --dry-run` to preview, then drop the flag to do it |
-| `~/.dsh` is gone entirely | `/backup restore latest` |
-| New machine | See "New machine" below |
-| Suspect a corrupt archive | `/backup verify all` |
-| Keep a copy in the cloud | `/backup github repo name/dsh-backups` — every backup pushes from then on (use a private repo) |
+Want it on a schedule? `/backup auto 12` — every 12 hours, keeps going across restarts.
 ## Commands
-| Command | What it does |
+| Task | Command |
 |---|---|
-| `/backup` | Back up now |
-| `/backup list` | List backups (name, size) and the auto-backup status |
-| `/backup verify [prefix\|all]` | Check that archives are intact (default: newest only) |
-| `/backup restore <prefix\|latest>` | Restore; `--dry-run` previews, `--sync-deps` reinstalls plugin dependencies afterwards |
-| `/backup auto <hours>\|off\|status` | Start / stop / check scheduled backups |
-| `/backup --keep N` | Override how many copies to keep (default 7) |
-| `/backup github …` | Cloud sync — see "GitHub sync" |
-| `/backup delete <prefix\|latest>` | Delete a backup and its sidecar files |
-The model can call the same operations directly via the `backup_dsh` tool (`mode=backup|list|verify|restore|auto`; restore accepts `syncDeps`).
+| Back up now | `/backup` |
+| Schedule | `/backup auto 12` (`off` to stop, `status` to check) |
+| Restore | `/backup restore latest` (`--dry-run` to preview) |
+| List backups | `/backup list` |
+| Verify integrity | `/backup verify [prefix\|all]` |
+| Delete | `/backup delete <prefix\|latest>` |
+| Keep N copies (default 7) | `/backup --keep N` |
-## Scheduled backups
-```
-/backup auto 12
-```
-From then on, a backup runs every 12 hours (any interval from 1 to 720).
-- `/backup auto off` — stop
-- `/backup auto status` — check
-State lives in `auto.json` inside the backup folder. After a restart, the schedule resumes from the last run instead of restarting the clock. Retention: intervals under 24 hours keep 3 copies by default, longer ones keep 7 (override with `config.keep`).
+Prefer clicking? There's a visual panel in `dsh web` settings.
 ## New machine
-Prerequisite: the old machine had GitHub sync configured (next section).
+Prerequisite: GitHub sync was configured on the old one ([setup](docs/advanced.zh.md#github-同步可选)).
-1. Install the plugin on the new machine and set the same `githubRepo`
-2. `/backup github pull` — fetches every remote backup (each one checksum-verified; corrupt copies are skipped and reported)
-3. `/backup restore latest --sync-deps` — restore, then reinstall plugin dependencies per profile
+1. Install the plugin, set the same `githubRepo`
+2. `/backup github pull` — fetch the remote backups
+3. `/backup restore latest --sync-deps` — restore and reinstall plugin dependencies
 4. Restart `dsh`
-The restore report tells you two things: the backup came from another machine (watch for absolute paths in configs), and which credential files you need to re-enter (they're not in the archive — see next section). To save a step, `/backup github pull --restore latest` restores right after pulling.
-## Credentials (passwords, tokens)
-Files like `.credentials.yaml`, `.env`, and `qq-bridge/config.json` never enter an archive, by default:
-- On backup: plaintext copies go into a `vault/` folder under the backup directory, locked to your user (mode 700/600). The archive and the GitHub sync carry only redacted copies.
-- Restoring on the same machine: credentials are copied back from the vault automatically.
-- Restoring on a new machine: there's no vault, so the report lists the missing files — re-enter them once.
-- To change the list, edit `config.redact`; `redact: false` turns the whole mechanism off (not recommended — that's the pre-v0.7 plaintext behavior).
+## More
-Each archive also carries two small metadata files: `.meta.json` (which machine, which home directory, when) and `.redacted.json` (what was redacted). Restore preflight reads them and warns about cross-machine restores.
-Archives and checksum files are chmod 600 on macOS/Linux; Windows relies on per-user profile ACLs.
-## GitHub sync (optional)
-Set `githubRepo` in the plugin config, and every backup (manual, scheduled, or from the panel) is pushed to that Git repository. Deletions sync too:
-```yaml
-- id: dsh-backup
-  name: 'dsh-backup'
-  config:
-    githubRepo: 'your-name/dsh-backups'   # owner/repo, a full URL, or a local path
-```
-Things to know:
-- **Use a private repository.** Archives carry no plaintext credentials, but they do contain your session content.
-- For https remotes, provide a token via `DSH_BACKUP_GITHUB_TOKEN` or `GITHUB_TOKEN`. It's written only to the sync worktree's credential file, never into process args.
-- The push is `HEAD:main --force-with-lease` — the remote's main is aligned with your local backup folder, so don't put anything else in that repo.
-- Archives over 90 MB are skipped from sync, with a notice.
-- Sync state (last push, last error) shows in `/backup github status` and the panel; `/backup github sync` pushes immediately instead of waiting for the next backup.
-## Web panel
-Open **Settings → Plugins → Backup** in `dsh web`: see every archive with its size, the auto-backup and sync status, and run back-up-now, per-archive verify, **download**, restore (dry-run preview plus confirmation), and **pull from GitHub** (the first step of a new-machine restore). Downloads go through a loopback-only route, never exposed externally.
-## How restore works
-Restore touches your live data, so every step is guarded:
-1. **Verify first**: a corrupt archive aborts the restore before anything is touched.
-2. **Path check**: any entry escaping the backup root (tar path traversal) rejects the restore.
-3. **Preflight**: a backup from another machine/home triggers an absolute-path warning; redacted archives explain that credentials come back from the local vault (or must be re-entered, cross-machine).
-4. **Keep an escape hatch**: the current `~/.dsh` is snapshotted, then moved aside to `~/.dsh.pre-restore-<timestamp>`. Restore replaces rather than merges, so stale files can't linger. If `~/.dsh` no longer exists (data lost, or first restore on a new machine), extraction proceeds directly.
-5. **Extract**: the archive is unpacked; credentials return from the vault; `--sync-deps` runs `pnpm install` per profile (node_modules never travel inside archives).
-6. **Restart `dsh`** and the restored sessions and settings take effect.
-`--dry-run` shows the summary and preflight hints without writing anything. When in doubt, dry-run first.
-## Configuration (optional)
-Defaults work out of the box. To adjust, add `config` to the plugin in your active cordis profile:
-```yaml
-- id: dsh-backup
-  name: 'dsh-backup'
-  config:
-    destination: '~/Backups/dsh'   # where backups go (default ~/Desktop/dsh-backups)
-    keep: 10                       # copies to keep for manual backups (default 7); also applies to scheduled ones when set
-    exclude:                       # extra tar --exclude patterns
-      - '*cache*'
-    redact:                        # extra credential files (relative to ~/.dsh); false/'off' disables redaction
-      - 'some-plugin/token.json'
-    githubRepo: 'name/dsh-backups' # GitHub sync (optional)
-```
-## Requirements
-- macOS, Linux, or Windows 10+, with `tar` in PATH (Windows ships it)
-- Checksums prefer `sha256sum`/`shasum` and fall back to a built-in hash when absent (that's the norm on Windows)
-- DSH `0.1.0-rc.6` or compatible
-## Troubleshooting
-- **Installed the wrong package** — the correct one is `@xiaoyuyu6420/dsh-backup` (scoped). The unscoped `dsh-backup` on npm is an unrelated third-party package. Check your profile's plugin list and reinstall with the scoped name.
-- **Plugin fails to load with `client api: method "backupPanel/remove" conflicts with its namespace service`** — you're on v0.5.0 (see [#2](https://github.com/xiaoyuyu6420/dsh-backup/issues/2), [#5](https://github.com/xiaoyuyu6420/dsh-backup/issues/5)). Fixed in v0.5.1: run `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup@latest` to upgrade, then restart `dsh web`.
-- **Which `tar` on Windows?** Either. System32 ships bsdtar and Git Bash provides GNU tar; verification works in both shells.
-## Development
-Zero runtime dependencies — the host plugin is `lib/index.js`. The browser half lives in `src/` and its bundle (`lib/client.js`, zod inlined, React/Cordis external) is committed, so git installs never build. The panel talks to the host through the `backupPanel` namespace (`/api` RPC); downloads use the loopback-only route `GET /backup-download/<name>`.
-Storage note: the plugin writes its own data (archives, checksum sidecars, `auto.json`, `vault/`) directly through `node:fs`, the same pattern as DSH's own session persistence — `ctx.fs` is the model-facing sandboxed surface and doesn't apply to host-owned storage.
-```sh
-node scripts/build-client.mjs   # rebuild the client bundle after editing src/
-node scripts/smoke.mjs          # host smoke suite (real temp dir, mocked DSH services)
-node scripts/smoke-client.mjs   # client bundle smoke: handshake, schemas, tab registration, SSR
-```
+Retention policy, credential redaction, GitHub sync, restore safeguards, config reference, troubleshooting, and development notes — in the [advanced guide](docs/advanced.zh.md) (Chinese).
 ## Acknowledgements

package/README.zh.md CHANGED Viewed

@@ -9,17 +9,7 @@
 **dsh-backup 是 DeepSeek Harness（DSH）的备份插件：一条命令备份 `~/.dsh`，一条命令恢复。**
-你在 DSH 里的会话记录、设置、技能、插件配置，全都在 `~/.dsh` 这一个目录里。误删了、改坏了、换电脑了——只要有过备份，就能找回来。
-它能做到：
-- **一键备份、一键恢复** —— 每份备份自动附带校验文件，随时能检查备份有没有损坏；旧备份自动清理，不会越积越多。
-- **定时自动备份** —— 设好间隔就不用管了，重启 DSH 后照常继续。
-- **密码等敏感文件不进备份包** —— 明文只留在本机的 `vault/` 目录里，恢复时自动放回原处（详见下文）。
-- **换电脑不慌** —— 备份可以自动同步到你的 GitHub 私有仓库，新电脑拉回来就能恢复。
-- **有图形界面** —— 不想敲命令，网页设置里有可视化面板。
-支持 macOS、Linux、Windows。
+会话记录、设置、技能、插件配置全在 `~/.dsh` 一个目录里。误删了、改坏了、换电脑了——有备份就能找回来。密码等敏感文件不进备份包，还支持定时自动备份和 GitHub 云同步（细节见[进阶文档](docs/advanced.zh.md)）。
 ## 安装
@@ -29,160 +19,42 @@ dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
 dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
 ```
-装完重启 `dsh web`。
-> ⚠️ **别装错包**：正确的包名是 `@xiaoyuyu6420/dsh-backup`，带前缀。npm 上另有一个不带前缀的 `dsh-backup`，那是无关的第三方项目，请勿安装。
+装完重启 `dsh web`。要求：macOS / Linux / Windows 10+（自带 `tar`），DSH `0.1.1-rc.2` 或兼容版本。
 ## 快速上手
-大约 30 秒：
 1. 按上面装好插件，重启 `dsh web`
 2. 输入 `/backup`
-3. 搞定 —— 备份文件出现在 `~/Desktop/dsh-backups/`，文件名带时间戳
-之后日常最常用的就是这一条命令。想定时自动备份？看下文。
+3. 搞定 —— 备份出现在 `~/Desktop/dsh-backups/`，文件名带时间戳
-## 场景速查
+想定时自动跑？`/backup auto 12`（每 12 小时一次，重启不中断）。
-| 遇到什么情况 | 怎么办 |
-|---|---|
-| 日常备份一次 | `/backup`（或在面板里点「立即备份」） |
-| 怕自己忘备份 | `/backup auto 12`（每 12 小时一次，重启不中断） |
-| 配置改坏了、插件装坏了 | `/backup restore latest --dry-run` 先预览，确认后去掉 `--dry-run` 真正恢复 |
-| `~/.dsh` 整个没了 | `/backup restore latest` |
-| 换新电脑 | 见「换新电脑」一节 |
-| 怀疑备份文件坏了 | `/backup verify all` |
-| 想把备份放云端 | `/backup github repo 账号/dsh-backups`，之后每次备份自动推送（务必用私有仓库） |
-## 命令一览
+## 命令速查
-| 命令 | 作用 |
+| 场景 | 命令 |
 |---|---|
-| `/backup` | 立即备份 |
-| `/backup list` | 列出所有备份（名称、大小）和自动备份状态 |
-| `/backup verify [前缀\|all]` | 校验备份是否完好，默认只查最新一份 |
-| `/backup restore <前缀\|latest>` | 恢复，支持 `--dry-run`（只预览不动手）和 `--sync-deps`（恢复后重装插件依赖） |
-| `/backup auto <小时数>\|off\|status` | 定时备份的开启、关闭、状态 |
-| `/backup --keep N` | 覆盖保留份数（默认 7） |
-| `/backup github …` | 云同步相关，见「GitHub 同步」 |
-| `/backup delete <前缀\|latest>` | 删除某份备份及其附属文件 |
-以上能力模型也能直接调用（工具 `backup_dsh`，`mode=backup|list|verify|restore|auto`，restore 支持 `syncDeps`）。
+| 立即备份 | `/backup` |
+| 定时备份 | `/backup auto 12`（`off` 关闭，`status` 看状态） |
+| 恢复 | `/backup restore latest`（`--dry-run` 先预览） |
+| 列出备份 | `/backup list` |
+| 校验是否完好 | `/backup verify [前缀\|all]` |
+| 删除某份备份 | `/backup delete <前缀\|latest>` |
+| 保留份数（默认 7） | `/backup --keep N` |
-## 定时自动备份
-```
-/backup auto 12
-```
-从现在起每 12 小时自动备份一次（间隔可设 1~720 小时）。
-- `/backup auto off` —— 关闭
-- `/backup auto status` —— 查看状态
-状态记录在备份目录的 `auto.json` 里。重启 DSH 后会接着上次的节奏排期，不会重新计时。保留份数：间隔不足 24 小时的默认留 3 份，更长的留 7 份（可用配置 `keep` 覆盖）。
+不想敲命令？`dsh web` 设置里有可视化面板。
 ## 换新电脑
-前提：旧电脑已经配置了 GitHub 同步（见下一节）。
+前提：旧电脑配过 GitHub 同步（[配置方法](docs/advanced.zh.md#github-同步可选)）。
 1. 新电脑装好插件，配置里填同一个 `githubRepo`
-2. `/backup github pull` —— 把云端备份全部拉回本地（每份都做校验，损坏的自动跳过并报告）
-3. `/backup restore latest --sync-deps` —— 恢复数据，并重装各 profile 的插件依赖
+2. `/backup github pull` —— 拉回云端备份
+3. `/backup restore latest --sync-deps` —— 恢复并重装插件依赖
 4. 重启 `dsh`
-恢复报告会提示两件事：这份备份来自另一台电脑（留意配置里的绝对路径），以及哪些敏感文件需要重新填（它们不在备份包里，见下节）。想省一步，可以用 `/backup github pull --restore latest` 拉取后直接恢复。
-## 敏感文件的处理（密码、token）
-`.credentials.yaml`、`.env`、`qq-bridge/config.json` 这类存凭据的文件，默认**不打进备份包**：
-- 备份时：明文复制到备份目录下的 `vault/` 文件夹，权限收紧到只有你能读（目录 700、文件 600）。备份包和云端同步的都是脱敏后的版本。
-- 同一台电脑恢复：凭据自动从 `vault/` 放回原位，不用你动手。
-- 新电脑恢复：本机没有 `vault/`，恢复报告会列出缺了哪些文件，重新填一遍即可。
-- 想增减敏感文件：改配置里的 `redact` 列表；`redact: false` 可整个关闭这个机制（不推荐，等于回到 v0.7 之前的明文行为）。
+## 更多
-每个备份还附带两个信息文件：`.meta.json`（备份来自哪台机器、哪个用户目录、什么时间）和 `.redacted.json`（哪些文件被脱敏了）。恢复前的预检会读取它们，跨机器恢复时提前给出提醒。
-备份文件和校验文件在 macOS / Linux 上权限都是 600（只有你能读）；Windows 靠用户目录的访问控制。
-## GitHub 同步（可选）
-在插件配置里填上 `githubRepo`，之后每次备份（手动、定时、面板点的）都会自动推送到这个 Git 仓库，删除旧备份也会一并同步：
-```yaml
-- id: dsh-backup
-  name: 'dsh-backup'
-  config:
-    githubRepo: '你的账号/dsh-backups'   # 支持 owner/repo、完整 URL 或本地路径
-```
-几个要点：
-- **务必用私有仓库** —— 备份虽然不含密码明文，但有你的会话内容。
-- 走 https 需要 token：环境变量 `DSH_BACKUP_GITHUB_TOKEN` 或 `GITHUB_TOKEN`。token 只写进同步工作树的凭据文件，不会出现在进程参数里。
-- 推送方式是 `HEAD:main --force-with-lease`，也就是远端 main 会被对齐成本地备份目录的状态——别往这个仓库里手动放别的东西。
-- 单个备份超过 90MB 会跳过推送并提示。
-- 同步状态（上次推送、最近错误）在 `/backup github status` 和面板里都能看到；`/backup github sync` 可以不等下一次备份，立即推送一次。
-## 可视化面板
-打开 `dsh web` 的 **Settings → Plugins → 备份** 标签页：查看备份列表与大小、自动备份状态、GitHub 同步状态，支持一键备份、逐份校验、**下载**备份、恢复（先预览再二次确认），以及**从 GitHub 拉取**备份（新电脑恢复的第一步）。下载只走本机回环地址的接口，不对外暴露。
-## 恢复是怎么工作的
-恢复动的是你现有的数据，所以每一步都有保护：
-1. **先校验**：备份文件损坏就直接中止，绝不碰现有数据。
-2. **路径检查**：备份包里出现越界路径（tar 路径穿越）就拒绝恢复。
-3. **预检提醒**：备份来自别的机器或用户目录时，提示绝对路径风险；脱敏备份则说明凭据会从本机 vault 还原（跨机恢复会列出要重填的）。
-4. **先留后路**：现有的 `~/.dsh` 先自动快照，再移到 `~/.dsh.pre-restore-<时间戳>`。恢复是整体替换，不是合并，不会被旧文件搅浑；如果 `~/.dsh` 已经不存在（数据已经丢了，或新机首次恢复），跳过快照直接解压。
-5. **解压还原**：解压备份；凭据从 vault 放回；`--sync-deps` 给各 profile 跑 `pnpm install`（node_modules 不进备份包，靠这步重装）。
-6. **重启生效**：重启 `dsh`，会话和配置就回来了。
-`--dry-run` 只显示概览和预检提示，不写入任何东西。拿不准就先 dry-run 一次。
-## 配置（可选）
-默认开箱即用，以下都可不配。想调整时，在生效的 cordis profile 里给插件加 `config`：
-```yaml
-- id: dsh-backup
-  name: 'dsh-backup'
-  config:
-    destination: '~/Backups/dsh'   # 备份存放位置（默认 ~/Desktop/dsh-backups）
-    keep: 10                       # 手动备份保留几份（默认 7）；设了以后定时备份也按这个数
-    exclude:                       # 额外排除的内容（tar --exclude 语法）
-      - '*cache*'
-    redact:                        # 追加敏感文件（相对 ~/.dsh 的路径）；false 或 'off' 关闭脱敏
-      - 'some-plugin/token.json'
-    githubRepo: '账号/dsh-backups' # GitHub 同步，见上文
-```
-## 系统要求
-- macOS、Linux 或 Windows 10+，PATH 里有 `tar`（Windows 自带）
-- 校验优先用 `sha256sum` / `shasum`，没有就自动改用内置哈希（Windows 上就是这样）
-- DSH `0.1.0-rc.6` 或兼容版本
-## 故障排查
-- **装错了包** —— 正确的包名是 `@xiaoyuyu6420/dsh-backup`（带前缀）。不带前缀的 `dsh-backup` 是无关的第三方包。检查 profile 的插件列表，用正确名字重装。
-- **插件加载失败，报 `client api: method "backupPanel/remove" conflicts with its namespace service`** —— 你装的是 v0.5.0 旧版（详见 [#2](https://github.com/xiaoyuyu6420/dsh-backup/issues/2)、[#5](https://github.com/xiaoyuyu6420/dsh-backup/issues/5)）。v0.5.1 已修复：执行 `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup@latest` 升级，重启 `dsh web` 即可。
-- **Windows 上用哪个 `tar`？** 都行。系统自带 System32 里的 bsdtar，Git Bash 里是 GNU tar，校验功能在两种 shell 下都能正常工作。
-## 开发
-运行时零依赖，宿主插件就是 `lib/index.js`。浏览器端源码在 `src/`，打包产物 `lib/client.js` 直接提交进仓库（zod 内联，React / Cordis 保持 external），从 git 安装不需要构建。面板通过 `backupPanel` 命名空间（`/api` RPC）与宿主通信；下载走仅限本机的 `GET /backup-download/<归档名>` 路由。
-存储说明：插件自有数据（归档、校验文件、`auto.json`、`vault/`）直接用 `node:fs` 写入，与 DSH 自身的会话持久化同一模式；`ctx.fs` 是模型侧的沙箱接口，不适用于宿主插件的自有存储。
-```sh
-node scripts/build-client.mjs   # 改 src/ 后重新打包客户端
-node scripts/smoke.mjs          # 宿主冒烟测试（真实临时目录 + 模拟 DSH 服务）
-node scripts/smoke-client.mjs   # 客户端 bundle 冒烟（握手 / schema / 标签页注册 / SSR）
-```
+定时备份策略、敏感文件脱敏、GitHub 同步、恢复的保护机制、配置参考、故障排查、开发说明——都在[进阶文档](docs/advanced.zh.md)。
 ## 致谢