@xiaoyuyu6420/dsh-backup 0.6.2 → 0.7.1
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.
- package/README.md +131 -93
- package/README.zh.md +131 -81
- package/lib/client.js +7 -7
- package/lib/index.js +402 -51
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -7,150 +7,188 @@
|
|
|
7
7
|
|
|
8
8
|
English | [简体中文](README.zh.md)
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
10
|
+
**dsh-backup is a DeepSeek Harness (DSH) plugin that backs up and restores `~/.dsh` with a single command.**
|
|
11
|
+
|
|
12
|
+
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.
|
|
13
|
+
|
|
14
|
+
What you get:
|
|
15
|
+
|
|
16
|
+
- **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.
|
|
17
|
+
- **Scheduled backups** — set an interval and forget it. It keeps the schedule across restarts.
|
|
18
|
+
- **Credentials never enter an archive** — plaintext stays in a local `vault/` folder and is restored automatically (details below).
|
|
19
|
+
- **New machine, no panic** — backups sync to your private GitHub repo; pull them down on the new machine and restore.
|
|
20
|
+
- **A web panel** — prefer clicking? There's a visual UI for everything.
|
|
21
|
+
|
|
22
|
+
Works on macOS, Linux, and Windows.
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
|
|
28
|
+
# or from GitHub:
|
|
29
|
+
dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Then restart `dsh web`.
|
|
33
|
+
|
|
34
|
+
> ⚠️ **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.
|
|
35
|
+
|
|
36
|
+
## Quickstart
|
|
37
|
+
|
|
38
|
+
About 30 seconds:
|
|
39
|
+
|
|
40
|
+
1. Install (above) and restart `dsh web`
|
|
41
|
+
2. Run `/backup`
|
|
42
|
+
3. Done — the archive lands in `~/Desktop/dsh-backups/`, named with a timestamp
|
|
43
|
+
|
|
44
|
+
That one command covers day-to-day use. Want it to run on a schedule? See below.
|
|
45
|
+
|
|
46
|
+
## Scenario cheat sheet
|
|
47
|
+
|
|
48
|
+
| Situation | What to do |
|
|
49
|
+
|---|---|
|
|
50
|
+
| Routine backup | `/backup` (or "Back up now" in the panel) |
|
|
51
|
+
| Afraid you'll forget | `/backup auto 12` — every 12 hours, keeps going across restarts |
|
|
52
|
+
| Broke a config or a plugin install | `/backup restore latest --dry-run` to preview, then drop the flag to do it |
|
|
53
|
+
| `~/.dsh` is gone entirely | `/backup restore latest` |
|
|
54
|
+
| New machine | See "New machine" below |
|
|
55
|
+
| Suspect a corrupt archive | `/backup verify all` |
|
|
56
|
+
| Keep a copy in the cloud | `/backup github repo name/dsh-backups` — every backup pushes from then on (use a private repo) |
|
|
15
57
|
|
|
16
58
|
## Commands
|
|
17
59
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
60
|
+
| Command | What it does |
|
|
61
|
+
|---|---|
|
|
62
|
+
| `/backup` | Back up now |
|
|
63
|
+
| `/backup list` | List backups (name, size) and the auto-backup status |
|
|
64
|
+
| `/backup verify [prefix\|all]` | Check that archives are intact (default: newest only) |
|
|
65
|
+
| `/backup restore <prefix\|latest>` | Restore; `--dry-run` previews, `--sync-deps` reinstalls plugin dependencies afterwards |
|
|
66
|
+
| `/backup auto <hours>\|off\|status` | Start / stop / check scheduled backups |
|
|
67
|
+
| `/backup --keep N` | Override how many copies to keep (default 7) |
|
|
68
|
+
| `/backup github …` | Cloud sync — see "GitHub sync" |
|
|
69
|
+
| `/backup delete <prefix\|latest>` | Delete a backup and its sidecar files |
|
|
27
70
|
|
|
28
|
-
|
|
71
|
+
The model can call the same operations directly via the `backup_dsh` tool (`mode=backup|list|verify|restore|auto`; restore accepts `syncDeps`).
|
|
29
72
|
|
|
30
|
-
|
|
31
|
-
also pushed to a Git repository — archives, checksum sidecars, and rotation
|
|
32
|
-
deletions stay in sync:
|
|
73
|
+
## Scheduled backups
|
|
33
74
|
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
name: 'dsh-backup'
|
|
37
|
-
config:
|
|
38
|
-
githubRepo: 'your-name/dsh-backups' # owner/repo, full URL, or a local path
|
|
75
|
+
```
|
|
76
|
+
/backup auto 12
|
|
39
77
|
```
|
|
40
78
|
|
|
41
|
-
|
|
42
|
-
`https` remote, set the token in the environment (`DSH_BACKUP_GITHUB_TOKEN` or
|
|
43
|
-
`GITHUB_TOKEN`); it is only written into the sync worktree's credential file
|
|
44
|
-
(never process args). Push is `HEAD:main --force-with-lease`; archives over
|
|
45
|
-
90 MB are skipped with a notice. State (last push, last error) lives in
|
|
46
|
-
`<destination>/auto.json` and shows in the panel and `/backup github status`.
|
|
79
|
+
From then on, a backup runs every 12 hours (any interval from 1 to 720).
|
|
47
80
|
|
|
48
|
-
|
|
81
|
+
- `/backup auto off` — stop
|
|
82
|
+
- `/backup auto status` — check
|
|
49
83
|
|
|
50
|
-
|
|
51
|
-
(`dsh web`). It shows the destination, auto-backup state, GitHub sync status, and
|
|
52
|
-
every archive with its size, and offers one-click back-up-now, per-archive
|
|
53
|
-
verify, download, and restore with a dry-run preview plus explicit confirmation.
|
|
54
|
-
Downloads stream from the loopback-only route `GET /backup-download/<name>`.
|
|
55
|
-
The tab talks to the host through the `backupPanel` Typert Remote namespace
|
|
56
|
-
(`/api` RPC); the browser bundle ships prebuilt in `lib/client.js` — no build
|
|
57
|
-
step at install time.
|
|
84
|
+
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`).
|
|
58
85
|
|
|
59
|
-
##
|
|
86
|
+
## New machine
|
|
60
87
|
|
|
61
|
-
|
|
88
|
+
Prerequisite: the old machine had GitHub sync configured (next section).
|
|
62
89
|
|
|
63
|
-
1.
|
|
64
|
-
2.
|
|
65
|
-
3.
|
|
66
|
-
4.
|
|
90
|
+
1. Install the plugin on the new machine and set the same `githubRepo`
|
|
91
|
+
2. `/backup github pull` — fetches every remote backup (each one checksum-verified; corrupt copies are skipped and reported)
|
|
92
|
+
3. `/backup restore latest --sync-deps` — restore, then reinstall plugin dependencies per profile
|
|
93
|
+
4. Restart `dsh`
|
|
67
94
|
|
|
68
|
-
|
|
95
|
+
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.
|
|
69
96
|
|
|
70
|
-
##
|
|
97
|
+
## Credentials (passwords, tokens)
|
|
98
|
+
|
|
99
|
+
Files like `.credentials.yaml`, `.env`, and `qq-bridge/config.json` never enter an archive, by default:
|
|
100
|
+
|
|
101
|
+
- 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.
|
|
102
|
+
- Restoring on the same machine: credentials are copied back from the vault automatically.
|
|
103
|
+
- Restoring on a new machine: there's no vault, so the report lists the missing files — re-enter them once.
|
|
104
|
+
- To change the list, edit `config.redact`; `redact: false` turns the whole mechanism off (not recommended — that's the pre-v0.7 plaintext behavior).
|
|
105
|
+
|
|
106
|
+
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.
|
|
107
|
+
|
|
108
|
+
Archives and checksum files are chmod 600 on macOS/Linux; Windows relies on per-user profile ACLs.
|
|
109
|
+
|
|
110
|
+
## GitHub sync (optional)
|
|
71
111
|
|
|
72
|
-
|
|
112
|
+
Set `githubRepo` in the plugin config, and every backup (manual, scheduled, or from the panel) is pushed to that Git repository. Deletions sync too:
|
|
73
113
|
|
|
74
114
|
```yaml
|
|
75
115
|
- id: dsh-backup
|
|
76
116
|
name: 'dsh-backup'
|
|
77
117
|
config:
|
|
78
|
-
|
|
79
|
-
keep: 10 # manual rotation count (default 7); when set, also the auto-backup retention — auto keeps 3 copies below 24h, 7 otherwise by default
|
|
80
|
-
exclude: # extra tar --exclude patterns
|
|
81
|
-
- '*cache*'
|
|
82
|
-
githubRepo: 'name/dsh-backups' # optional GitHub sync (see below)
|
|
118
|
+
githubRepo: 'your-name/dsh-backups' # owner/repo, a full URL, or a local path
|
|
83
119
|
```
|
|
84
120
|
|
|
85
|
-
|
|
121
|
+
Things to know:
|
|
86
122
|
|
|
87
|
-
|
|
123
|
+
- **Use a private repository.** Archives carry no plaintext credentials, but they do contain your session content.
|
|
124
|
+
- 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.
|
|
125
|
+
- 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.
|
|
126
|
+
- Archives over 90 MB are skipped from sync, with a notice.
|
|
127
|
+
- 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.
|
|
88
128
|
|
|
89
|
-
|
|
90
|
-
Archives and checksum sidecars are chmod 600 on POSIX (Windows relies on
|
|
91
|
-
per-user profile ACLs), but do **not** sync the backup directory to untrusted
|
|
92
|
-
locations, and treat archives as sensitive as your API keys.
|
|
129
|
+
## Web panel
|
|
93
130
|
|
|
94
|
-
|
|
95
|
-
`auto.json`) directly through `node:fs`, the same pattern as DSH's own session
|
|
96
|
-
persistence — the `ctx.fs` capability is the model-facing sandboxed surface and
|
|
97
|
-
does not apply to host-owned storage.
|
|
131
|
+
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.
|
|
98
132
|
|
|
99
|
-
##
|
|
133
|
+
## How restore works
|
|
100
134
|
|
|
101
|
-
|
|
102
|
-
dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
|
|
103
|
-
# or from git:
|
|
104
|
-
dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
|
|
105
|
-
```
|
|
135
|
+
Restore touches your live data, so every step is guarded:
|
|
106
136
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
137
|
+
1. **Verify first**: a corrupt archive aborts the restore before anything is touched.
|
|
138
|
+
2. **Path check**: any entry escaping the backup root (tar path traversal) rejects the restore.
|
|
139
|
+
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).
|
|
140
|
+
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.
|
|
141
|
+
5. **Extract**: the archive is unpacked; credentials return from the vault; `--sync-deps` runs `pnpm install` per profile (node_modules never travel inside archives).
|
|
142
|
+
6. **Restart `dsh`** and the restored sessions and settings take effect.
|
|
110
143
|
|
|
111
|
-
|
|
144
|
+
`--dry-run` shows the summary and preflight hints without writing anything. When in doubt, dry-run first.
|
|
112
145
|
|
|
113
|
-
|
|
146
|
+
## Configuration (optional)
|
|
114
147
|
|
|
115
|
-
|
|
116
|
-
2. Restart `dsh web` — plugin discovery is cached per process.
|
|
117
|
-
3. Run `/backup` — the archive and its sha256 sidecar land in `~/Desktop/dsh-backups/`.
|
|
148
|
+
Defaults work out of the box. To adjust, add `config` to the plugin in your active cordis profile:
|
|
118
149
|
|
|
119
|
-
|
|
150
|
+
```yaml
|
|
151
|
+
- id: dsh-backup
|
|
152
|
+
name: 'dsh-backup'
|
|
153
|
+
config:
|
|
154
|
+
destination: '~/Backups/dsh' # where backups go (default ~/Desktop/dsh-backups)
|
|
155
|
+
keep: 10 # copies to keep for manual backups (default 7); also applies to scheduled ones when set
|
|
156
|
+
exclude: # extra tar --exclude patterns
|
|
157
|
+
- '*cache*'
|
|
158
|
+
redact: # extra credential files (relative to ~/.dsh); false/'off' disables redaction
|
|
159
|
+
- 'some-plugin/token.json'
|
|
160
|
+
githubRepo: 'name/dsh-backups' # GitHub sync (optional)
|
|
161
|
+
```
|
|
120
162
|
|
|
121
163
|
## Requirements
|
|
122
164
|
|
|
123
|
-
- macOS, Linux, or Windows 10
|
|
124
|
-
|
|
125
|
-
and fall back to an in-process hash on Windows)
|
|
165
|
+
- macOS, Linux, or Windows 10+, with `tar` in PATH (Windows ships it)
|
|
166
|
+
- Checksums prefer `sha256sum`/`shasum` and fall back to a built-in hash when absent (that's the norm on Windows)
|
|
126
167
|
- DSH `0.1.0-rc.6` or compatible
|
|
127
168
|
|
|
128
169
|
## Troubleshooting
|
|
129
170
|
|
|
130
|
-
- **
|
|
131
|
-
- **
|
|
132
|
-
- **
|
|
171
|
+
- **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.
|
|
172
|
+
- **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`.
|
|
173
|
+
- **Which `tar` on Windows?** Either. System32 ships bsdtar and Git Bash provides GNU tar; verification works in both shells.
|
|
133
174
|
|
|
134
175
|
## Development
|
|
135
176
|
|
|
136
|
-
Zero runtime dependencies — the host plugin is `lib/index.js`. The browser half
|
|
137
|
-
|
|
138
|
-
`
|
|
177
|
+
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>`.
|
|
178
|
+
|
|
179
|
+
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.
|
|
139
180
|
|
|
140
181
|
```sh
|
|
141
182
|
node scripts/build-client.mjs # rebuild the client bundle after editing src/
|
|
142
183
|
node scripts/smoke.mjs # host smoke suite (real temp dir, mocked DSH services)
|
|
143
|
-
node scripts/smoke-client.mjs # client bundle: handshake, schemas, tab registration, SSR
|
|
184
|
+
node scripts/smoke-client.mjs # client bundle smoke: handshake, schemas, tab registration, SSR
|
|
144
185
|
```
|
|
145
186
|
|
|
146
187
|
## Acknowledgements
|
|
147
188
|
|
|
148
|
-
- [@beastrobin](https://github.com/beastrobin) — the reserved-method-name root
|
|
149
|
-
|
|
150
|
-
- [@
|
|
151
|
-
cause report in #2
|
|
152
|
-
- [@Choi-Peng](https://github.com/Choi-Peng) — triage help pointing affected
|
|
153
|
-
users to the fix in #5
|
|
189
|
+
- [@beastrobin](https://github.com/beastrobin) — the reserved-method-name root cause analysis in #1 that directly led to the v0.5.1 fix
|
|
190
|
+
- [@mlosun](https://github.com/mlosun) — the thorough reproduction and root cause report in #2
|
|
191
|
+
- [@Choi-Peng](https://github.com/Choi-Peng) — triage help pointing affected users to the fix in #5
|
|
154
192
|
|
|
155
193
|
## License
|
|
156
194
|
|
package/README.zh.md
CHANGED
|
@@ -7,131 +7,181 @@
|
|
|
7
7
|
|
|
8
8
|
[English](README.md) | 简体中文
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
技能与插件配置（排除可重装的 node_modules），自动生成 sha256 校验和、完整性
|
|
12
|
-
校验、自动轮换，定时自动备份状态落盘、重启续跑。支持 macOS / Linux / Windows。
|
|
10
|
+
**dsh-backup 是 DeepSeek Harness（DSH）的备份插件：一条命令备份 `~/.dsh`，一条命令恢复。**
|
|
13
11
|
|
|
14
|
-
|
|
12
|
+
你在 DSH 里的会话记录、设置、技能、插件配置，全都在 `~/.dsh` 这一个目录里。误删了、改坏了、换电脑了——只要有过备份，就能找回来。
|
|
15
13
|
|
|
16
|
-
|
|
17
|
-
- **`/backup list`** —— 列出已有备份（名称 + 大小）与自动备份状态
|
|
18
|
-
- **`/backup verify [前缀|all]`** —— 校验归档完整性（缺省校验最新一份）
|
|
19
|
-
- **`/backup restore <前缀|latest> [--dry-run]`** —— 从归档恢复 `~/.dsh`
|
|
20
|
-
- **`/backup auto <N小时>|off|status`** —— 每 N 小时自动备份（1~720；保留份数默认 <24h 3 份、否则 7 份，config.keep 可覆盖；状态持久化，重启续跑）
|
|
21
|
-
- **`/backup --keep N`** —— 覆盖轮换保留份数（默认 7）
|
|
22
|
-
- **`/backup github status|sync|repo <地址|off>`** —— GitHub 同步状态 / 立即推送 / 设置同步仓库
|
|
23
|
-
- **`/backup delete|rm <前缀|latest>`** —— 删除指定备份（归档 + 校验边车）
|
|
24
|
-
- **`backup_dsh` 工具** —— 模型可调用同一能力（`mode=backup|list|verify|restore|auto`）
|
|
14
|
+
它能做到：
|
|
25
15
|
|
|
26
|
-
|
|
16
|
+
- **一键备份、一键恢复** —— 每份备份自动附带校验文件，随时能检查备份有没有损坏；旧备份自动清理，不会越积越多。
|
|
17
|
+
- **定时自动备份** —— 设好间隔就不用管了，重启 DSH 后照常继续。
|
|
18
|
+
- **密码等敏感文件不进备份包** —— 明文只留在本机的 `vault/` 目录里，恢复时自动放回原处（详见下文）。
|
|
19
|
+
- **换电脑不慌** —— 备份可以自动同步到你的 GitHub 私有仓库，新电脑拉回来就能恢复。
|
|
20
|
+
- **有图形界面** —— 不想敲命令，网页设置里有可视化面板。
|
|
27
21
|
|
|
28
|
-
|
|
29
|
-
边车与轮换删除一并推送到 Git 仓库：
|
|
22
|
+
支持 macOS、Linux、Windows。
|
|
30
23
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
24
|
+
## 安装
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
|
|
28
|
+
# 或者从 GitHub 安装：
|
|
29
|
+
dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
|
|
36
30
|
```
|
|
37
31
|
|
|
38
|
-
|
|
39
|
-
（`DSH_BACKUP_GITHUB_TOKEN` 或 `GITHUB_TOKEN`），token 只写入同步工作树的
|
|
40
|
-
credential 文件（不进进程参数）。推送为 `HEAD:main --force-with-lease`；
|
|
41
|
-
超过 90MB 的归档会跳过并提示。同步状态（上次推送 / 错误）存于
|
|
42
|
-
`<destination>/auto.json`，面板与 `/backup github status` 可见。
|
|
32
|
+
装完重启 `dsh web`。
|
|
43
33
|
|
|
44
|
-
|
|
34
|
+
> ⚠️ **别装错包**：正确的包名是 `@xiaoyuyu6420/dsh-backup`，带前缀。npm 上另有一个不带前缀的 `dsh-backup`，那是无关的第三方项目，请勿安装。
|
|
45
35
|
|
|
46
|
-
|
|
47
|
-
显示备份目录、自动备份状态、GitHub 同步状态和每份归档的大小，支持一键立即
|
|
48
|
-
备份、逐份校验、**下载**、带 dry-run 预览与二次确认的恢复。下载走仅限本机的
|
|
49
|
-
`GET /backup-download/<归档名>` 路由。面板经 `backupPanel` Typert Remote
|
|
50
|
-
命名空间（`/api` RPC）与宿主通信；浏览器 bundle 预构建在 `lib/client.js`，
|
|
51
|
-
安装时无需构建。
|
|
36
|
+
## 快速上手
|
|
52
37
|
|
|
53
|
-
|
|
38
|
+
大约 30 秒：
|
|
54
39
|
|
|
55
|
-
|
|
40
|
+
1. 按上面装好插件，重启 `dsh web`
|
|
41
|
+
2. 输入 `/backup`
|
|
42
|
+
3. 搞定 —— 备份文件出现在 `~/Desktop/dsh-backups/`，文件名带时间戳
|
|
56
43
|
|
|
57
|
-
|
|
58
|
-
2. 列出归档条目，任何超出备份根目录的路径都会拒绝恢复（tar 路径穿越防护）。
|
|
59
|
-
3. 当前 `~/.dsh` 先自动快照，再移动到 `~/.dsh.pre-restore-<时间戳>`——恢复是替换而不是合并。
|
|
60
|
-
4. 解压归档后重启 `dsh`，恢复的会话与配置即生效。
|
|
44
|
+
之后日常最常用的就是这一条命令。想定时自动备份？看下文。
|
|
61
45
|
|
|
62
|
-
|
|
46
|
+
## 场景速查
|
|
63
47
|
|
|
64
|
-
|
|
48
|
+
| 遇到什么情况 | 怎么办 |
|
|
49
|
+
|---|---|
|
|
50
|
+
| 日常备份一次 | `/backup`（或在面板里点「立即备份」） |
|
|
51
|
+
| 怕自己忘备份 | `/backup auto 12`（每 12 小时一次，重启不中断） |
|
|
52
|
+
| 配置改坏了、插件装坏了 | `/backup restore latest --dry-run` 先预览，确认后去掉 `--dry-run` 真正恢复 |
|
|
53
|
+
| `~/.dsh` 整个没了 | `/backup restore latest` |
|
|
54
|
+
| 换新电脑 | 见「换新电脑」一节 |
|
|
55
|
+
| 怀疑备份文件坏了 | `/backup verify all` |
|
|
56
|
+
| 想把备份放云端 | `/backup github repo 账号/dsh-backups`，之后每次备份自动推送（务必用私有仓库） |
|
|
57
|
+
|
|
58
|
+
## 命令一览
|
|
59
|
+
|
|
60
|
+
| 命令 | 作用 |
|
|
61
|
+
|---|---|
|
|
62
|
+
| `/backup` | 立即备份 |
|
|
63
|
+
| `/backup list` | 列出所有备份（名称、大小）和自动备份状态 |
|
|
64
|
+
| `/backup verify [前缀\|all]` | 校验备份是否完好，默认只查最新一份 |
|
|
65
|
+
| `/backup restore <前缀\|latest>` | 恢复，支持 `--dry-run`（只预览不动手）和 `--sync-deps`（恢复后重装插件依赖） |
|
|
66
|
+
| `/backup auto <小时数>\|off\|status` | 定时备份的开启、关闭、状态 |
|
|
67
|
+
| `/backup --keep N` | 覆盖保留份数（默认 7） |
|
|
68
|
+
| `/backup github …` | 云同步相关，见「GitHub 同步」 |
|
|
69
|
+
| `/backup delete <前缀\|latest>` | 删除某份备份及其附属文件 |
|
|
70
|
+
|
|
71
|
+
以上能力模型也能直接调用（工具 `backup_dsh`，`mode=backup|list|verify|restore|auto`，restore 支持 `syncDeps`）。
|
|
72
|
+
|
|
73
|
+
## 定时自动备份
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
/backup auto 12
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
从现在起每 12 小时自动备份一次（间隔可设 1~720 小时）。
|
|
80
|
+
|
|
81
|
+
- `/backup auto off` —— 关闭
|
|
82
|
+
- `/backup auto status` —— 查看状态
|
|
83
|
+
|
|
84
|
+
状态记录在备份目录的 `auto.json` 里。重启 DSH 后会接着上次的节奏排期，不会重新计时。保留份数：间隔不足 24 小时的默认留 3 份，更长的留 7 份（可用配置 `keep` 覆盖）。
|
|
85
|
+
|
|
86
|
+
## 换新电脑
|
|
87
|
+
|
|
88
|
+
前提：旧电脑已经配置了 GitHub 同步（见下一节）。
|
|
65
89
|
|
|
66
|
-
|
|
90
|
+
1. 新电脑装好插件，配置里填同一个 `githubRepo`
|
|
91
|
+
2. `/backup github pull` —— 把云端备份全部拉回本地（每份都做校验，损坏的自动跳过并报告）
|
|
92
|
+
3. `/backup restore latest --sync-deps` —— 恢复数据，并重装各 profile 的插件依赖
|
|
93
|
+
4. 重启 `dsh`
|
|
94
|
+
|
|
95
|
+
恢复报告会提示两件事：这份备份来自另一台电脑（留意配置里的绝对路径），以及哪些敏感文件需要重新填（它们不在备份包里，见下节）。想省一步，可以用 `/backup github pull --restore latest` 拉取后直接恢复。
|
|
96
|
+
|
|
97
|
+
## 敏感文件的处理（密码、token）
|
|
98
|
+
|
|
99
|
+
`.credentials.yaml`、`.env`、`qq-bridge/config.json` 这类存凭据的文件，默认**不打进备份包**：
|
|
100
|
+
|
|
101
|
+
- 备份时：明文复制到备份目录下的 `vault/` 文件夹，权限收紧到只有你能读（目录 700、文件 600）。备份包和云端同步的都是脱敏后的版本。
|
|
102
|
+
- 同一台电脑恢复：凭据自动从 `vault/` 放回原位，不用你动手。
|
|
103
|
+
- 新电脑恢复：本机没有 `vault/`，恢复报告会列出缺了哪些文件，重新填一遍即可。
|
|
104
|
+
- 想增减敏感文件：改配置里的 `redact` 列表；`redact: false` 可整个关闭这个机制（不推荐，等于回到 v0.7 之前的明文行为）。
|
|
105
|
+
|
|
106
|
+
每个备份还附带两个信息文件：`.meta.json`（备份来自哪台机器、哪个用户目录、什么时间）和 `.redacted.json`（哪些文件被脱敏了）。恢复前的预检会读取它们，跨机器恢复时提前给出提醒。
|
|
107
|
+
|
|
108
|
+
备份文件和校验文件在 macOS / Linux 上权限都是 600（只有你能读）；Windows 靠用户目录的访问控制。
|
|
109
|
+
|
|
110
|
+
## GitHub 同步（可选）
|
|
111
|
+
|
|
112
|
+
在插件配置里填上 `githubRepo`，之后每次备份（手动、定时、面板点的）都会自动推送到这个 Git 仓库，删除旧备份也会一并同步：
|
|
67
113
|
|
|
68
114
|
```yaml
|
|
69
115
|
- id: dsh-backup
|
|
70
116
|
name: 'dsh-backup'
|
|
71
117
|
config:
|
|
72
|
-
|
|
73
|
-
keep: 10 # 手动备份轮换份数（默认 7）；配置后同时作为自动备份保留份数（未配置时 auto 默认 <24h 3 份 / 否则 7 份）
|
|
74
|
-
exclude: # 额外的 tar --exclude 模式
|
|
75
|
-
- '*cache*'
|
|
76
|
-
githubRepo: '账号/dsh-backups' # 可选 GitHub 同步（见下文）
|
|
118
|
+
githubRepo: '你的账号/dsh-backups' # 支持 owner/repo、完整 URL 或本地路径
|
|
77
119
|
```
|
|
78
120
|
|
|
79
|
-
|
|
121
|
+
几个要点：
|
|
80
122
|
|
|
81
|
-
|
|
123
|
+
- **务必用私有仓库** —— 备份虽然不含密码明文，但有你的会话内容。
|
|
124
|
+
- 走 https 需要 token：环境变量 `DSH_BACKUP_GITHUB_TOKEN` 或 `GITHUB_TOKEN`。token 只写进同步工作树的凭据文件，不会出现在进程参数里。
|
|
125
|
+
- 推送方式是 `HEAD:main --force-with-lease`，也就是远端 main 会被对齐成本地备份目录的状态——别往这个仓库里手动放别的东西。
|
|
126
|
+
- 单个备份超过 90MB 会跳过推送并提示。
|
|
127
|
+
- 同步状态（上次推送、最近错误）在 `/backup github status` 和面板里都能看到；`/backup github sync` 可以不等下一次备份，立即推送一次。
|
|
82
128
|
|
|
83
|
-
|
|
84
|
-
文件在 POSIX 上为 `chmod 600`（Windows 依赖用户目录 ACL），但请**不要**把备份
|
|
85
|
-
目录同步到不受信的位置，并像对待 API key 一样对待备份文件。
|
|
129
|
+
## 可视化面板
|
|
86
130
|
|
|
87
|
-
|
|
88
|
-
与 DSH 自身的会话持久化同一模式——`ctx.fs` 能力是模型面的沙箱 surface，
|
|
89
|
-
不适用于宿主插件的自有存储。
|
|
131
|
+
打开 `dsh web` 的 **Settings → Plugins → 备份** 标签页：查看备份列表与大小、自动备份状态、GitHub 同步状态，支持一键备份、逐份校验、**下载**备份、恢复（先预览再二次确认），以及**从 GitHub 拉取**备份（新电脑恢复的第一步）。下载只走本机回环地址的接口，不对外暴露。
|
|
90
132
|
|
|
91
|
-
##
|
|
133
|
+
## 恢复是怎么工作的
|
|
92
134
|
|
|
93
|
-
|
|
94
|
-
dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
|
|
95
|
-
# 或从 git 安装：
|
|
96
|
-
dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
|
|
97
|
-
```
|
|
135
|
+
恢复动的是你现有的数据，所以每一步都有保护：
|
|
98
136
|
|
|
99
|
-
|
|
100
|
-
|
|
137
|
+
1. **先校验**：备份文件损坏就直接中止，绝不碰现有数据。
|
|
138
|
+
2. **路径检查**：备份包里出现越界路径（tar 路径穿越）就拒绝恢复。
|
|
139
|
+
3. **预检提醒**：备份来自别的机器或用户目录时，提示绝对路径风险；脱敏备份则说明凭据会从本机 vault 还原（跨机恢复会列出要重填的）。
|
|
140
|
+
4. **先留后路**：现有的 `~/.dsh` 先自动快照，再移到 `~/.dsh.pre-restore-<时间戳>`。恢复是整体替换，不是合并，不会被旧文件搅浑；如果 `~/.dsh` 已经不存在（数据已经丢了，或新机首次恢复），跳过快照直接解压。
|
|
141
|
+
5. **解压还原**：解压备份；凭据从 vault 放回；`--sync-deps` 给各 profile 跑 `pnpm install`（node_modules 不进备份包，靠这步重装）。
|
|
142
|
+
6. **重启生效**：重启 `dsh`，会话和配置就回来了。
|
|
101
143
|
|
|
102
|
-
|
|
144
|
+
`--dry-run` 只显示概览和预检提示，不写入任何东西。拿不准就先 dry-run 一次。
|
|
103
145
|
|
|
104
|
-
|
|
146
|
+
## 配置（可选）
|
|
105
147
|
|
|
106
|
-
|
|
107
|
-
2. 重启 `dsh web` —— 插件发现按进程缓存。
|
|
108
|
-
3. 跑 `/backup` —— 归档连同 sha256 校验文件落到 `~/Desktop/dsh-backups/`。
|
|
148
|
+
默认开箱即用，以下都可不配。想调整时，在生效的 cordis profile 里给插件加 `config`：
|
|
109
149
|
|
|
110
|
-
|
|
150
|
+
```yaml
|
|
151
|
+
- id: dsh-backup
|
|
152
|
+
name: 'dsh-backup'
|
|
153
|
+
config:
|
|
154
|
+
destination: '~/Backups/dsh' # 备份存放位置（默认 ~/Desktop/dsh-backups）
|
|
155
|
+
keep: 10 # 手动备份保留几份（默认 7）；设了以后定时备份也按这个数
|
|
156
|
+
exclude: # 额外排除的内容（tar --exclude 语法）
|
|
157
|
+
- '*cache*'
|
|
158
|
+
redact: # 追加敏感文件（相对 ~/.dsh 的路径）；false 或 'off' 关闭脱敏
|
|
159
|
+
- 'some-plugin/token.json'
|
|
160
|
+
githubRepo: '账号/dsh-backups' # GitHub 同步，见上文
|
|
161
|
+
```
|
|
111
162
|
|
|
112
|
-
##
|
|
163
|
+
## 系统要求
|
|
113
164
|
|
|
114
|
-
- macOS、Linux 或 Windows 10+，PATH
|
|
115
|
-
|
|
116
|
-
Windows 上回退进程内哈希）
|
|
165
|
+
- macOS、Linux 或 Windows 10+，PATH 里有 `tar`（Windows 自带）
|
|
166
|
+
- 校验优先用 `sha256sum` / `shasum`，没有就自动改用内置哈希（Windows 上就是这样）
|
|
117
167
|
- DSH `0.1.0-rc.6` 或兼容版本
|
|
118
168
|
|
|
119
169
|
## 故障排查
|
|
120
170
|
|
|
121
|
-
-
|
|
122
|
-
-
|
|
123
|
-
-
|
|
171
|
+
- **装错了包** —— 正确的包名是 `@xiaoyuyu6420/dsh-backup`（带前缀）。不带前缀的 `dsh-backup` 是无关的第三方包。检查 profile 的插件列表，用正确名字重装。
|
|
172
|
+
- **插件加载失败，报 `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` 即可。
|
|
173
|
+
- **Windows 上用哪个 `tar`？** 都行。系统自带 System32 里的 bsdtar，Git Bash 里是 GNU tar，校验功能在两种 shell 下都能正常工作。
|
|
124
174
|
|
|
125
175
|
## 开发
|
|
126
176
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
177
|
+
运行时零依赖，宿主插件就是 `lib/index.js`。浏览器端源码在 `src/`，打包产物 `lib/client.js` 直接提交进仓库（zod 内联，React / Cordis 保持 external），从 git 安装不需要构建。面板通过 `backupPanel` 命名空间（`/api` RPC）与宿主通信；下载走仅限本机的 `GET /backup-download/<归档名>` 路由。
|
|
178
|
+
|
|
179
|
+
存储说明：插件自有数据（归档、校验文件、`auto.json`、`vault/`）直接用 `node:fs` 写入，与 DSH 自身的会话持久化同一模式；`ctx.fs` 是模型侧的沙箱接口，不适用于宿主插件的自有存储。
|
|
130
180
|
|
|
131
181
|
```sh
|
|
132
182
|
node scripts/build-client.mjs # 改 src/ 后重新打包客户端
|
|
133
|
-
node scripts/smoke.mjs #
|
|
134
|
-
node scripts/smoke-client.mjs # 客户端 bundle
|
|
183
|
+
node scripts/smoke.mjs # 宿主冒烟测试（真实临时目录 + 模拟 DSH 服务）
|
|
184
|
+
node scripts/smoke-client.mjs # 客户端 bundle 冒烟（握手 / schema / 标签页注册 / SSR）
|
|
135
185
|
```
|
|
136
186
|
|
|
137
187
|
## 致谢
|