@xiaoyuyu6420/dsh-backup 0.5.2 → 0.6.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.
Files changed (5) hide show
  1. package/README.md +41 -7
  2. package/README.zh.md +37 -7
  3. package/lib/client.js +7 -7
  4. package/lib/index.js +193 -44
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,11 @@
1
1
  # dsh-backup
2
2
 
3
3
  [![dsh-plugin](https://img.shields.io/badge/ecosystem-dsh--plugin-8b5cf6)](https://github.com/topics/dsh-plugin)
4
+ [![npm](https://img.shields.io/npm/v/@xiaoyuyu6420/dsh-backup)](https://www.npmjs.com/package/@xiaoyuyu6420/dsh-backup)
5
+ [![Publish to npm](https://github.com/xiaoyuyu6420/dsh-backup/actions/workflows/publish.yml/badge.svg)](https://github.com/xiaoyuyu6420/dsh-backup/actions/workflows/publish.yml)
6
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+
8
+ English | [简体中文](README.zh.md)
4
9
 
5
10
  One-command backup **and restore** for DeepSeek Harness user data — sessions,
6
11
  settings, credentials, skills, and plugin config under `~/.dsh`, excluding
@@ -14,9 +19,10 @@ macOS, Linux, and Windows.
14
19
  - **`/backup list`** — list existing backups (name + size) and auto-backup status
15
20
  - **`/backup verify [prefix|all]`** — validate archive checksums (default: the newest)
16
21
  - **`/backup restore <prefix|latest> [--dry-run]`** — restore `~/.dsh` from an archive
17
- - **`/backup auto <N>|off|status`** — auto-backup every N hours (1–720; keeps 3 copies below 24h, 7 otherwise; persisted across restarts)
22
+ - **`/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)
18
23
  - **`/backup --keep N`** — override the rotation count (default 7)
19
- - **`/backup github status|sync`** — GitHub sync status / push now
24
+ - **`/backup github status|sync|repo <address|off>`** — GitHub sync status / push now / set the sync repository
25
+ - **`/backup delete|rm <prefix|latest>`** — delete a backup and its checksum sidecar
20
26
  - **`backup_dsh` tool** — same capability for the model (`mode=backup|list|verify|restore|auto`)
21
27
 
22
28
  ## GitHub sync
@@ -70,13 +76,13 @@ Plugin `config` in the active cordis profile:
70
76
  name: 'dsh-backup'
71
77
  config:
72
78
  destination: '~/Backups/dsh' # default ~/Desktop/dsh-backups
73
- keep: 10 # default rotation count
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
74
80
  exclude: # extra tar --exclude patterns
75
81
  - '*cache*'
76
82
  githubRepo: 'name/dsh-backups' # optional GitHub sync (see below)
77
83
  ```
78
84
 
79
- Auto-backup state lives in `<destination>/auto.json` and resumes after restart.
85
+ 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.
80
86
 
81
87
  ## Security note
82
88
 
@@ -93,11 +99,24 @@ does not apply to host-owned storage.
93
99
  ## Install
94
100
 
95
101
  ```sh
96
- dsh plugin --profile web add dsh-backup
102
+ dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
103
+ # or from git:
104
+ dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
97
105
  ```
98
106
 
99
- Then restart `dsh web` (plugin discovery is cached per process) and run `/backup`,
100
- or open Settings → Plugins → Backup.
107
+ > ⚠️ The npm package name is the **scoped** `@xiaoyuyu6420/dsh-backup`. The
108
+ > unscoped `dsh-backup` on npm is an unrelated third-party package — don't
109
+ > install it.
110
+
111
+ ## Quickstart
112
+
113
+ Your first backup is about 30 seconds away:
114
+
115
+ 1. Install the plugin — `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup`
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/`.
118
+
119
+ Prefer clicking? The same flow lives in Settings → Plugins → Backup.
101
120
 
102
121
  ## Requirements
103
122
 
@@ -106,6 +125,12 @@ or open Settings → Plugins → Backup.
106
125
  and fall back to an in-process hash on Windows)
107
126
  - DSH `0.1.0-rc.6` or compatible
108
127
 
128
+ ## Troubleshooting
129
+
130
+ - **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`.
131
+ - **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.
132
+ - **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.
133
+
109
134
  ## Development
110
135
 
111
136
  Zero runtime dependencies — the host plugin is `lib/index.js`. The browser half
@@ -118,6 +143,15 @@ node scripts/smoke.mjs # host smoke suite (real temp dir, mocked DSH se
118
143
  node scripts/smoke-client.mjs # client bundle: handshake, schemas, tab registration, SSR
119
144
  ```
120
145
 
146
+ ## Acknowledgements
147
+
148
+ - [@beastrobin](https://github.com/beastrobin) — the reserved-method-name root
149
+ cause analysis in #1 that directly led to the v0.5.1 fix
150
+ - [@mlosun](https://github.com/mlosun) — the thorough reproduction and root
151
+ cause report in #2
152
+ - [@Choi-Peng](https://github.com/Choi-Peng) — triage help pointing affected
153
+ users to the fix in #5
154
+
121
155
  ## License
122
156
 
123
157
  MIT
package/README.zh.md CHANGED
@@ -1,6 +1,11 @@
1
1
  # dsh-backup
2
2
 
3
3
  [![dsh-plugin](https://img.shields.io/badge/ecosystem-dsh--plugin-8b5cf6)](https://github.com/topics/dsh-plugin)
4
+ [![npm](https://img.shields.io/npm/v/@xiaoyuyu6420/dsh-backup)](https://www.npmjs.com/package/@xiaoyuyu6420/dsh-backup)
5
+ [![Publish to npm](https://github.com/xiaoyuyu6420/dsh-backup/actions/workflows/publish.yml/badge.svg)](https://github.com/xiaoyuyu6420/dsh-backup/actions/workflows/publish.yml)
6
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+
8
+ [English](README.md) | 简体中文
4
9
 
5
10
  一键备份**与恢复** DeepSeek Harness 用户数据——`~/.dsh` 下的会话、设置、凭据、
6
11
  技能与插件配置（排除可重装的 node_modules），自动生成 sha256 校验和、完整性
@@ -12,9 +17,10 @@
12
17
  - **`/backup list`** —— 列出已有备份（名称 + 大小）与自动备份状态
13
18
  - **`/backup verify [前缀|all]`** —— 校验归档完整性（缺省校验最新一份）
14
19
  - **`/backup restore <前缀|latest> [--dry-run]`** —— 从归档恢复 `~/.dsh`
15
- - **`/backup auto <N小时>|off|status`** —— 每 N 小时自动备份（1~720；<24h 保留 3 份，否则 7 份；状态持久化，重启续跑）
20
+ - **`/backup auto <N小时>|off|status`** —— 每 N 小时自动备份（1~720；保留份数默认 <24h 3 份、否则 7 份，config.keep 可覆盖；状态持久化，重启续跑）
16
21
  - **`/backup --keep N`** —— 覆盖轮换保留份数（默认 7）
17
- - **`/backup github status|sync`** —— GitHub 同步状态 / 立即推送
22
+ - **`/backup github status|sync|repo <地址|off>`** —— GitHub 同步状态 / 立即推送 / 设置同步仓库
23
+ - **`/backup delete|rm <前缀|latest>`** —— 删除指定备份（归档 + 校验边车）
18
24
  - **`backup_dsh` 工具** —— 模型可调用同一能力（`mode=backup|list|verify|restore|auto`）
19
25
 
20
26
  ## GitHub 同步
@@ -64,13 +70,13 @@ credential 文件（不进进程参数）。推送为 `HEAD:main --force-with-le
64
70
  name: 'dsh-backup'
65
71
  config:
66
72
  destination: '~/Backups/dsh' # 默认 ~/Desktop/dsh-backups
67
- keep: 10 # 默认轮换保留份数
73
+ keep: 10 # 手动备份轮换份数（默认 7）；配置后同时作为自动备份保留份数（未配置时 auto 默认 <24h 3 份 / 否则 7 份）
68
74
  exclude: # 额外的 tar --exclude 模式
69
75
  - '*cache*'
70
76
  githubRepo: '账号/dsh-backups' # 可选 GitHub 同步（见下文）
71
77
  ```
72
78
 
73
- 自动备份状态保存在 `<destination>/auto.json`，重启后续跑。
79
+ 自动备份状态保存在 `<destination>/auto.json`，重启后按上次自动执行时间推算下次触发（不重置节奏）。
74
80
 
75
81
  ## 安全说明
76
82
 
@@ -85,11 +91,23 @@ credential 文件（不进进程参数）。推送为 `HEAD:main --force-with-le
85
91
  ## 安装
86
92
 
87
93
  ```sh
88
- dsh plugin --profile web add dsh-backup
94
+ dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
95
+ # 或从 git 安装：
96
+ dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
89
97
  ```
90
98
 
91
- 然后重启 `dsh web`（插件发现按进程缓存），输入 `/backup` 或打开
92
- Settings → Plugins → 备份。
99
+ > ⚠️ npm 包名是 **scoped** 的 `@xiaoyuyu6420/dsh-backup`。npm 上不带 scope
100
+ > 的 `dsh-backup` 是无关的第三方包，请勿安装。
101
+
102
+ ## 快速上手
103
+
104
+ 约 30 秒拿到第一个备份：
105
+
106
+ 1. 安装插件 —— `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup`
107
+ 2. 重启 `dsh web` —— 插件发现按进程缓存。
108
+ 3. 跑 `/backup` —— 归档连同 sha256 校验文件落到 `~/Desktop/dsh-backups/`。
109
+
110
+ 更喜欢点鼠标？同一套流程在 Settings → Plugins → 备份 标签页。
93
111
 
94
112
  ## 依赖
95
113
 
@@ -98,6 +116,12 @@ Settings → Plugins → 备份。
98
116
  Windows 上回退进程内哈希）
99
117
  - DSH `0.1.0-rc.6` 或兼容版本
100
118
 
119
+ ## 故障排查
120
+
121
+ - **插件加载失败，报 `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` 即可。
122
+ - **Windows 上用哪个 `tar`？** 都可以——Windows 自带 System32 里的 bsdtar，Git Bash 里则是 GNU tar。校验和优先用 `sha256sum`/`shasum`，缺失时自动回退进程内哈希，两种 shell 下 `/backup verify` 都能正常工作。
123
+ - **装错了包** —— npm 包名是 **scoped** 的 `@xiaoyuyu6420/dsh-backup`；不带 scope 的 `dsh-backup` 是无关的第三方包。检查 profile 的插件列表，改用 scoped 名重装。
124
+
101
125
  ## 开发
102
126
 
103
127
  运行时零依赖——宿主插件就是 `lib/index.js`。浏览器半边源码在 `src/`，
@@ -110,6 +134,12 @@ node scripts/smoke.mjs # 宿主冒烟（真实临时目录 + 模拟 DSH
110
134
  node scripts/smoke-client.mjs # 客户端 bundle：握手/schema/标签页注册/SSR
111
135
  ```
112
136
 
137
+ ## 致谢
138
+
139
+ - [@beastrobin](https://github.com/beastrobin) —— #1 中对保留方法名的根因分析，直接促成 v0.5.1 修复
140
+ - [@mlosun](https://github.com/mlosun) —— #2 中详尽的复现与根因报告
141
+ - [@Choi-Peng](https://github.com/Choi-Peng) —— #5 中协助把受影响用户指引到修复版本
142
+
113
143
  ## 许可证
114
144
 
115
145
  MIT