@xiaoyuyu6420/dsh-backup 0.7.0 → 0.7.2

package/README.md

@@ -7,198 +7,60 @@
 
 English | [简体中文](README.zh.md)
 
-One-command backup **and restore** for DeepSeek Harness user data — sessions,
-settings, credentials, skills, and plugin config under `~/.dsh`, excluding
-reinstallable `node_modules` — with sha256 checksums, integrity verification,
-automatic rotation, and scheduled auto-backup that survives restarts.
-**Credentials are redacted by default**: plaintext never enters an archive or
-the GitHub sync, only a local vault, and is restored automatically. Cross-machine
-restores get preflight hints and a one-command `github pull`. Works on macOS,
-Linux, and Windows.
-
-## Scenario cheat sheet
-
-| Scenario | What to run |
-|---|---|
-| Everyday backup | `/backup` (or Settings → Plugins → Backup → Back up now) |
-| Don't trust yourself to remember | `/backup auto 12` — scheduled, survives restarts |
-| Broke a config / bad plugin install | `/backup restore latest --dry-run`, then drop the flag |
-| `~/.dsh` is gone entirely | `/backup restore latest` — no existing data means no snapshot, straight to restore |
-| New machine | Install the plugin, set the same `githubRepo` → `/backup github pull` → `/backup restore latest --sync-deps` |
-| Suspect a corrupt archive | `/backup verify all` |
-| Cloud copy | `/backup github repo name/dsh-backups` (private repo); every backup pushes afterwards |
-
-## Commands
-
-- **`/backup`** — immediately back up `~/.dsh` to `~/Desktop/dsh-backups/dsh-<timestamp>.tar.gz`
-- **`/backup list`** — list existing backups (name + size) and auto-backup status
-- **`/backup verify [prefix|all]`** — validate archive checksums (default: the newest)
-- **`/backup restore <prefix|latest> [--dry-run] [--sync-deps]`** — restore `~/.dsh` from an archive (`--sync-deps` reinstalls per-profile plugin dependencies afterwards)
-- **`/backup auto <N>|off|status`** — auto-backup every N hours (1–720; retains 3 copies below 24h, 7 otherwise, unless `config.keep` overrides; persisted across restarts)
-- **`/backup --keep N`** — override the rotation count (default 7)
-- **`/backup github status|sync|pull [--restore <prefix|latest>]|repo <address|off>`** — sync status / push now / pull backups from the repo / set the sync repository
-- **`/backup delete|rm <prefix|latest>`** — delete a backup and its sidecars
-- **`backup_dsh` tool** — same capability for the model (`mode=backup|list|verify|restore|auto`; restore accepts `syncDeps`)
-
-## Credential redaction & the local vault
-
-Credential files (by default `.credentials.yaml`, `.env`, `qq-bridge/config.json`;
-extend or disable via `config.redact`) **never enter an archive**:
-
-- On backup, plaintext copies are mirrored into `vault/` under the backup
-  directory (POSIX mode 700/600); archives and the GitHub sync carry only
-  redacted data.
-- Restoring on the same machine copies the credentials back from the vault —
-  full fidelity.
-- Restoring on a new machine (no vault) lists the missing credential files and
-  tells you to re-enter them.
-- Each archive ships with `.redacted.json` (the redaction list) and
-  `.meta.json` (host / home / timestamp) sidecars; restore preflight uses them
-  to flag cross-machine path risks and credentials to re-enter.
-- `config.redact: false` restores the v0.6.x plaintext behavior (not recommended).
-
-## GitHub sync
-
-With `config.githubRepo` set, every backup (manual, automatic, or panel) is
-also pushed to a Git repository — archives, checksum sidecars, and rotation
-deletions stay in sync:
-
-```yaml
-- id: dsh-backup
-  name: 'dsh-backup'
-  config:
-    githubRepo: 'your-name/dsh-backups'   # owner/repo, full URL, or a local path
-```
-
-Use a **private** repository — archives are redacted but still contain session
-content. For an `https` remote, set the token in the environment
-(`DSH_BACKUP_GITHUB_TOKEN` or `GITHUB_TOKEN`); it is only written into the sync
-worktree's credential file (never process args). Push is `HEAD:main
---force-with-lease`; archives over 90 MB are skipped with a notice. State (last
-push, last error) lives in `<destination>/auto.json` and shows in the panel and
-`/backup github status`.
-
-**Restoring on a new machine**: install the plugin, configure the same
-`githubRepo`, then run `/backup github pull` — it fetches every remote backup
-(each one sha256-verified; corrupt archives are skipped and reported), then
-`/backup restore latest --sync-deps` restores and reinstalls plugin
-dependencies. The restore report reads `.meta.json` to flag the cross-machine
-restore (absolute-path risks) and lists the credentials to re-enter.
-`--restore <prefix|latest>` restores a specific archive right after pulling.
-
-## Settings panel (Web)
-
-The same controls have a visual entry: a **Backup** tab inside Settings → Plugins
-(`dsh web`). It shows the destination, auto-backup state, GitHub sync status, and
-every archive with its size, and offers one-click back-up-now, per-archive
-verify, download, restore with a dry-run preview plus explicit confirmation,
-and **pull from GitHub** (the first step of a new-machine restore).
-Downloads stream from the loopback-only route `GET /backup-download/<name>`.
-The tab talks to the host through the `backupPanel` Typert Remote namespace
-(`/api` RPC); the browser bundle ships prebuilt in `lib/client.js` — no build
-step at install time.
-
-## How restore works
-
-Restore is safe by construction:
-
-1. The archive's sha256 is verified first — a corrupt archive never touches existing data.
-2. Entries are listed and any path outside the backup root rejects the restore (tar path-traversal guard).
-3. Preflight: `.meta.json` flags a backup from another machine/home (absolute-path risks); redacted archives note that credentials come back from the local vault (or must be re-entered cross-machine).
-4. The current `~/.dsh` is snapshotted, then moved aside to `~/.dsh.pre-restore-<timestamp>` — restore replaces rather than merges. A missing `~/.dsh` (data gone / first restore on a new machine) skips the snapshot and extracts directly.
-5. The archive is extracted; redacted archives then restore credentials from the vault; `--sync-deps` runs `pnpm install` per profile (node_modules never travel inside archives).
-6. Restart `dsh` afterwards so restored sessions and settings take effect.
-
-`--dry-run` shows the archive summary and preflight hints without writing anything.
-
-## Configuration (optional)
-
-Plugin `config` in the active cordis profile:
-
-```yaml
-- id: dsh-backup
-  name: 'dsh-backup'
-  config:
-    destination: '~/Backups/dsh'   # default ~/Desktop/dsh-backups
-    keep: 10                       # manual rotation count (default 7); when set, also the auto-backup retention — auto keeps 3 copies below 24h, 7 otherwise by default
-    exclude:                       # extra tar --exclude patterns
-      - '*cache*'
-    redact:                        # extra redacted files (relative to ~/.dsh); false/'off' disables redaction
-      - 'some-plugin/token.json'
-    githubRepo: 'name/dsh-backups' # optional GitHub sync (see below)
-```
+**dsh-backup is a DeepSeek Harness (DSH) plugin that backs up and restores `~/.dsh` with a single command.**
 
-Auto-backup state lives in `<destination>/auto.json` and resumes after restart — the next run is scheduled from the last auto-backup time, never reset by the restart.
-
-## Security note
-
-Credential files are redacted by default (see above): archives and the GitHub
-sync carry no plaintext credentials — plaintext lives only in the local
-`vault/` under the backup directory (POSIX 700/600). Archives may still contain
-sensitive session content, so keep the sync repository private. Archives and
-checksum sidecars are chmod 600 on POSIX (Windows relies on per-user profile
-ACLs).
-
-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 — the `ctx.fs` capability is the model-facing sandboxed
-surface and does not apply to host-owned storage.
+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
 
 ```sh
 dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
-# or from git:
+# or from GitHub:
 dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
 ```
 
-> ⚠️ The npm package name is the **scoped** `@xiaoyuyu6420/dsh-backup`. The
-> unscoped `dsh-backup` on npm is an unrelated third-party package — don't
-> install it.
+Then restart `dsh web`. Requires macOS / Linux / Windows 10+ (ships `tar`) and DSH `0.1.0-rc.6` or compatible.
 
 ## Quickstart
 
-Your first backup is about 30 seconds away:
+1. Install (above) and restart `dsh web`
+2. Run `/backup`
+3. Done — the archive lands in `~/Desktop/dsh-backups/`, named with a timestamp
 
-1. Install the plugin — `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup`
-2. Restart `dsh web` — plugin discovery is cached per process.
-3. Run `/backup` — the archive and its sha256 sidecar land in `~/Desktop/dsh-backups/`.
+Want it on a schedule? `/backup auto 12` — every 12 hours, keeps going across restarts.
 
-Prefer clicking? The same flow lives in Settings → Plugins → Backup.
+## Commands
 
-## Requirements
+| Task | Command |
+|---|---|
+| 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` |
 
-- macOS, Linux, or Windows 10+ with `tar` in PATH (Windows ships bsdtar in
-  System32; Git Bash's GNU tar also works — checksums prefer `sha256sum`/`shasum`
-  and fall back to an in-process hash on Windows)
-- DSH `0.1.0-rc.6` or compatible
+Prefer clicking? There's a visual panel in `dsh web` settings.
 
-## Troubleshooting
+## New machine
 
-- **Plugin fails to load with `client api: method "backupPanel/remove" conflicts with its namespace service`** — you are on v0.5.0, whose delete-endpoint method name collided with a reserved name in the DSH client (issues [#2](https://github.com/xiaoyuyu6420/dsh-backup/issues/2), [#5](https://github.com/xiaoyuyu6420/dsh-backup/issues/5)). v0.5.1 renamed the method to `removeEntry`; upgrade with `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup@latest` and restart `dsh web`.
-- **Which `tar` on Windows?** Either one works — Windows ships bsdtar in System32, and Git Bash provides GNU tar. Checksums prefer `sha256sum`/`shasum` when present and fall back to an in-process hash, so `/backup verify` works in both shells.
-- **Installed the wrong package** — the npm package is the **scoped** `@xiaoyuyu6420/dsh-backup`; the unscoped `dsh-backup` is an unrelated third-party package. Check your profile's plugin list and reinstall with the scoped name.
+Prerequisite: GitHub sync was configured on the old one ([setup](docs/advanced.zh.md#github-同步可选)).
 
-## Development
+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`
 
-Zero runtime dependencies — the host plugin is `lib/index.js`. The browser half
-lives in `src/` and is bundled (zod inlined, React/Cordis external) into
-`lib/client.js`, which is committed so git installs never build:
+## More
 
-```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: 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
 
-- [@beastrobin](https://github.com/beastrobin) — the reserved-method-name root
-  cause analysis in #1 that directly led to the v0.5.1 fix
-- [@mlosun](https://github.com/mlosun) — the thorough reproduction and root
-  cause report in #2
-- [@Choi-Peng](https://github.com/Choi-Peng) — triage help pointing affected
-  users to the fix in #5
+- [@beastrobin](https://github.com/beastrobin) — the reserved-method-name root cause analysis in #1 that directly led to the v0.5.1 fix
+- [@mlosun](https://github.com/mlosun) — the thorough reproduction and root cause report in #2
+- [@Choi-Peng](https://github.com/Choi-Peng) — triage help pointing affected users to the fix in #5
 
 ## License
 

package/README.zh.md

@@ -7,174 +7,54 @@
 
 [English](README.md) | 简体中文
 
-一键备份**与恢复** DeepSeek Harness 用户数据——`~/.dsh` 下的会话、设置、
-技能与插件配置（排除可重装的 node_modules），自动生成 sha256 校验和、完整性
-校验、自动轮换，定时自动备份状态落盘、重启续跑。**凭据默认脱敏**：明文绝不
-进归档、不进 GitHub 同步，只存本机 vault，恢复时自动还原。跨机恢复有预检
-提示与 `github pull` 一键拉取。支持 macOS / Linux / Windows。
+**dsh-backup 是 DeepSeek Harness（DSH）的备份插件：一条命令备份 `~/.dsh`，一条命令恢复。**
 
-## 场景速查
-
-| 场景 | 怎么做 |
-|---|---|
-| 日常备份 | `/backup`（或 Settings → Plugins → 备份 → 立即备份） |
-| 担心忘备份 | `/backup auto 12` —— 定时备份，重启续跑 |
-| 改坏了配置/装坏了插件 | `/backup restore latest --dry-run` 预览确认后去掉 `--dry-run` |
-| `~/.dsh` 整个没了 | `/backup restore latest` —— 无现有数据时跳过快照直接恢复 |
-| 换新电脑 | 新机装好插件并配置同一 `githubRepo` → `/backup github pull` 拉回备份 → `/backup restore latest --sync-deps` |
-| 怀疑备份损坏 | `/backup verify all` |
-| 归档同步到云端 | `/backup github repo 账号/dsh-backups`（私有仓库），此后每次备份自动推送 |
-
-## 命令
-
-- **`/backup`** —— 立即备份 `~/.dsh` 到 `~/Desktop/dsh-backups/dsh-<时间戳>.tar.gz`
-- **`/backup list`** —— 列出已有备份（名称 + 大小）与自动备份状态
-- **`/backup verify [前缀|all]`** —— 校验归档完整性（缺省校验最新一份）
-- **`/backup restore <前缀|latest> [--dry-run] [--sync-deps]`** —— 从归档恢复 `~/.dsh`（`--sync-deps` 恢复后对各 profile 重装插件依赖）
-- **`/backup auto <N小时>|off|status`** —— 每 N 小时自动备份（1~720；保留份数默认 <24h 3 份、否则 7 份，config.keep 可覆盖；状态持久化，重启续跑）
-- **`/backup --keep N`** —— 覆盖轮换保留份数（默认 7）
-- **`/backup github status|sync|pull [--restore <前缀|latest>]|repo <地址|off>`** —— 同步状态 / 立即推送 / 从仓库拉取备份到本地 / 设置同步仓库
-- **`/backup delete|rm <前缀|latest>`** —— 删除指定备份（归档 + 全部边车）
-- **`backup_dsh` 工具** —— 模型可调用同一能力（`mode=backup|list|verify|restore|auto`，restore 支持 `syncDeps`）
-
-## 凭据脱敏与本机 vault
-
-凭据文件（默认 `.credentials.yaml`、`.env`、`qq-bridge/config.json`，
-`config.redact` 可增删）**不进归档**：
-
-- 备份时，敏感文件的明文副本镜像到备份目录下的 `vault/`（POSIX 上目录 700、
-  文件 600），归档与 GitHub 同步只含脱敏后的数据。
-- 本机恢复时，凭据自动从 vault 拷回 `~/.dsh`，完整还原。
-- 跨机恢复（新机没有 vault）时，恢复报告会列出缺失的凭据文件清单，提示重填。
-- 归档附带的 `.redacted.json`（脱敏清单）与 `.meta.json`（主机/家目录/时间）
-  边车随归档走，恢复预检据此提示跨机路径风险与需重填的凭据。
-- `config.redact: false` 可回到 v0.6.x 的明文行为（不推荐）。
-
-## GitHub 同步
-
-配置 `config.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 只写入
-同步工作树的 credential 文件（不进进程参数）。推送为 `HEAD:main
---force-with-lease`；超过 90MB 的归档会跳过并提示。同步状态（上次推送 / 错误）
-存于 `<destination>/auto.json`，面板与 `/backup github status` 可见。
-
-**换新机器恢复**：新机装好插件、配好同一 `githubRepo` 后执行
-`/backup github pull` —— 拉回远端全部备份（逐份 sha256 校验，损坏即跳过并
-报告），再 `/backup restore latest --sync-deps` 恢复并重装插件依赖；恢复报告
-会按 `.meta.json` 提示这是跨机恢复（绝对路径风险）并列出需重填的凭据清单。
-加 `--restore <前缀|latest>` 可在拉取后直接恢复指定备份。
-
-## Settings 可视面板（Web）
-
-同样的能力在 `dsh web` 的 **Settings → Plugins → 备份** 标签页有可视化入口：
-显示备份目录、自动备份状态、GitHub 同步状态和每份归档的大小，支持一键立即
-备份、逐份校验、**下载**、带 dry-run 预览与二次确认的恢复，以及**从 GitHub
-拉取**备份（新机恢复第一步）。下载走仅限本机的
-`GET /backup-download/<归档名>` 路由。面板经 `backupPanel` Typert Remote
-命名空间（`/api` RPC）与宿主通信；浏览器 bundle 预构建在 `lib/client.js`，
-安装时无需构建。
-
-## 恢复的工作方式
-
-恢复安全性是设计出来的：
-
-1. 先校验归档 sha256——损坏的归档绝不触碰现有数据。
-2. 列出归档条目，任何超出备份根目录的路径都会拒绝恢复（tar 路径穿越防护）。
-3. 预检：`.meta.json` 显示备份来自另一台机器/用户目录时提示绝对路径风险；
-   脱敏归档提示凭据将从本机 vault 还原（跨机则提示重填）。
-4. 当前 `~/.dsh` 先自动快照，再移动到 `~/.dsh.pre-restore-<时间戳>`——恢复是
-   替换而不是合并；`~/.dsh` 已不存在（数据全失/新机首恢复）时跳过快照直接解压。
-5. 解压归档；脱敏归档随后从 vault 还原凭据文件；`--sync-deps` 对各 profile
-   执行 `pnpm install` 重装插件依赖（node_modules 不随归档走）。
-6. 重启 `dsh`，恢复的会话与配置即生效。
-
-`--dry-run` 只显示归档概要与预检提示，不写入任何内容。
-
-## 配置（可选）
-
-在生效的 cordis profile 中为插件声明 `config`：
-
-```yaml
-- id: dsh-backup
-  name: 'dsh-backup'
-  config:
-    destination: '~/Backups/dsh'   # 默认 ~/Desktop/dsh-backups
-    keep: 10                       # 手动备份轮换份数（默认 7）；配置后同时作为自动备份保留份数（未配置时 auto 默认 <24h 3 份 / 否则 7 份）
-    exclude:                       # 额外的 tar --exclude 模式
-      - '*cache*'
-    redact:                        # 追加脱敏文件（相对 ~/.dsh）；false/'off' 关闭脱敏
-      - 'some-plugin/token.json'
-    githubRepo: '账号/dsh-backups' # 可选 GitHub 同步（见下文）
-```
-
-自动备份状态保存在 `<destination>/auto.json`，重启后按上次自动执行时间推算下次触发（不重置节奏）。
-
-## 安全说明
-
-凭据文件默认脱敏（见上文「凭据脱敏与本机 vault」）：归档与 GitHub 同步不含
-明文凭据，明文只存备份目录下的本机 `vault/`（POSIX 700/600）。归档仍可能含
-会话中的敏感内容，请使用私有同步仓库。归档与校验文件在 POSIX 上为
-`chmod 600`（Windows 依赖用户目录 ACL）。
-
-存储说明：插件自有数据（归档、校验和、`auto.json`、`vault/`）直接经
-`node:fs` 写入，与 DSH 自身的会话持久化同一模式——`ctx.fs` 能力是模型面的
-沙箱 surface，不适用于宿主插件的自有存储。
+会话记录、设置、技能、插件配置全在 `~/.dsh` 一个目录里。误删了、改坏了、换电脑了——有备份就能找回来。密码等敏感文件不进备份包，还支持定时自动备份和 GitHub 云同步（细节见[进阶文档](docs/advanced.zh.md)）。
 
 ## 安装
 
 ```sh
 dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
-# 或从 git 安装：
+# 或者从 GitHub 安装：
 dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
 ```
 
-> ⚠️ npm 包名是 **scoped** 的 `@xiaoyuyu6420/dsh-backup`。npm 上不带 scope
-> 的 `dsh-backup` 是无关的第三方包，请勿安装。
+装完重启 `dsh web`。要求：macOS / Linux / Windows 10+（自带 `tar`），DSH `0.1.0-rc.6` 或兼容版本。
 
 ## 快速上手
 
-约 30 秒拿到第一个备份：
+1. 按上面装好插件，重启 `dsh web`
+2. 输入 `/backup`
+3. 搞定 —— 备份出现在 `~/Desktop/dsh-backups/`，文件名带时间戳
 
-1. 安装插件 —— `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup`
-2. 重启 `dsh web` —— 插件发现按进程缓存。
-3. 跑 `/backup` —— 归档连同 sha256 校验文件落到 `~/Desktop/dsh-backups/`。
+想定时自动跑？`/backup auto 12`（每 12 小时一次，重启不中断）。
 
-更喜欢点鼠标？同一套流程在 Settings → Plugins → 备份 标签页。
+## 命令速查
 
-## 依赖
+| 场景 | 命令 |
+|---|---|
+| 立即备份 | `/backup` |
+| 定时备份 | `/backup auto 12`（`off` 关闭，`status` 看状态） |
+| 恢复 | `/backup restore latest`（`--dry-run` 先预览） |
+| 列出备份 | `/backup list` |
+| 校验是否完好 | `/backup verify [前缀\|all]` |
+| 删除某份备份 | `/backup delete <前缀\|latest>` |
+| 保留份数（默认 7） | `/backup --keep N` |
 
-- macOS、Linux 或 Windows 10+，PATH 中有 `tar`（Windows 自带 System32 的
-  bsdtar，Git Bash 的 GNU tar 也可以；校验和优先 `sha256sum`/`shasum`，
-  Windows 上回退进程内哈希）
-- DSH `0.1.0-rc.6` 或兼容版本
+不想敲命令？`dsh web` 设置里有可视化面板。
 
-## 故障排查
+## 换新电脑
 
-- **插件加载失败，报 `client api: method "backupPanel/remove" conflicts with its namespace service`** —— 你装的是 v0.5.0：删除接口的方法名撞上了 DSH 客户端的保留方法名（见 [#2](https://github.com/xiaoyuyu6420/dsh-backup/issues/2)、[#5](https://github.com/xiaoyuyu6420/dsh-backup/issues/5)）。v0.5.1 已将方法改名 `removeEntry` 修复；执行 `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup@latest` 升级后重启 `dsh web` 即可。
-- **Windows 上用哪个 `tar`？** 都可以——Windows 自带 System32 里的 bsdtar，Git Bash 里则是 GNU tar。校验和优先用 `sha256sum`/`shasum`，缺失时自动回退进程内哈希，两种 shell 下 `/backup verify` 都能正常工作。
-- **装错了包** —— npm 包名是 **scoped** 的 `@xiaoyuyu6420/dsh-backup`；不带 scope 的 `dsh-backup` 是无关的第三方包。检查 profile 的插件列表，改用 scoped 名重装。
+前提：旧电脑配过 GitHub 同步（[配置方法](docs/advanced.zh.md#github-同步可选)）。
 
-## 开发
+1. 新电脑装好插件，配置里填同一个 `githubRepo`
+2. `/backup github pull` —— 拉回云端备份
+3. `/backup restore latest --sync-deps` —— 恢复并重装插件依赖
+4. 重启 `dsh`
 
-运行时零依赖——宿主插件就是 `lib/index.js`。浏览器半边源码在 `src/`，
-打包（zod 内联、React/Cordis 保持 external）产物 `lib/client.js` 提交进仓库，
-git 安装无需构建：
+## 更多
 
-```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)。
 
 ## 致谢