@xiaoyuyu6420/dsh-backup 0.13.3 → 0.14.0

package/README.en.md

@@ -15,7 +15,7 @@ English | [简体中文](README.md)
 ```sh
 dsh plugin --profile web add @xiaoyuyu6420/dsh-backup   # install
 # restart dsh web, then type:
-/backup                                                  # → a verified archive lands in ~/Desktop/dsh-backups/
+/backup                                                  # → a verified archive lands in ~/Desktop/DSH Backups/
 ```
 
 Real output from a fresh v0.9.0 install:
@@ -30,6 +30,12 @@ Prefer clicking? There's a visual panel in `dsh web` → Settings → Plugins
 
 ![Backup panel](docs/assets/panel-backups.png)
 
+**Three promises** (full parity & delivery standard in [ALIGNMENT.md](docs/ALIGNMENT.md)):
+
+- 🔐 **Credentials never leave this machine** — API keys / tokens are redacted by default; plaintext lives only in the local vault. For more, opt into password-encrypted backups (AES-256-GCM).
+- ↩️ **Restore never overwrites silently** — the current data is auto-snapshotted and the write-back is previewed first; a failed restore rolls back automatically.
+- 🧭 **You'll know what to do from the start** — a three-step onboarding plus one plain-sentence explanation per advanced feature; three tabs (Backup / Restore / Settings) with a single primary action: "Back up now".
+
 ## Why you want this
 
 | Fear | What dsh-backup does about it |
@@ -43,12 +49,17 @@ Prefer clicking? There's a visual panel in `dsh web` → Settings → Plugins
 | "I got a new machine" | GitHub sync: `/backup github pull` fetches remote archives, `restore --sync-deps` reinstalls plugins |
 | "Backups rot silently" | Every archive ships a sha256; `/backup verify all` checks integrity; daily/weekly tiered retention keeps useful history longer |
 | "I'll forget to back up" | `/backup auto 12` — every 12 hours, survives restarts, rotates old copies (default keep 7) |
+| "A new machine means reinstalling everything" | Single-file ZIP **export/import** + local `link:`/`file:` plugin migration; sync over WebDAV / S3-compatible / Gist too |
+| "My config lives in another AI tool" | Import **skills & global instructions** from Claude Code / Cursor / Codex after a preview (MCP detected and reported only) |
+| "I want to go back to an earlier point in a conversation" | Conversation **rewind fork**: branch at a chosen turn while the original stays intact |
+| "Backups are eating my disk" | **Disk-usage report** + tiered cleanup: only regenerable caches and expired backups; snapshots and sync data are never touched |
+| "I want a ready-made community config" | **Config market**: index validation, preview install, supply-chain notes — nothing is written until you confirm |
 
 ![Backup settings](docs/assets/panel-settings.png)
 
 ## Install
 
-Requires macOS / Linux / Windows 10+ (ships `tar`) and DSH `0.1.1-rc.2`+ (the 0.1.1 / 0.1.2 / 0.1.5 / 0.1.6 / 0.1.7 trains are all tested; the 0.2.0 train is supported since 0.13.2 — see the [compatibility matrix](docs/compatibility.md) for the current status).
+Requires macOS / Linux / Windows 10+ (ships `tar`) and DSH `0.1.1-rc.2`+ (the 0.1.1 / 0.1.2 / 0.1.5 / 0.1.6 / 0.1.7 trains are all tested; the 0.2.0 and 0.2.1 trains are supported since 0.13.2 / 0.14.0 — see the [compatibility matrix](docs/compatibility.md) for the current status).
 
 ```sh
 dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
@@ -66,7 +77,7 @@ Restart `dsh web` afterwards — the plugin only takes effect after a restart.
 
 1. Install (above) and restart `dsh web`
 2. Type `/backup`
-3. Done — the archive lands in `~/Desktop/dsh-backups/`, timestamped, with a `.sha256` next to it
+3. Done — the archive lands in `~/Desktop/DSH Backups/`, timestamped, with a `.sha256` next to it
 
 Want it on a schedule? `/backup auto 12` (every 12 hours; `off` stops it, `status` checks it).
 
@@ -124,7 +135,10 @@ Don't keep clicking them. Run `/backup migrate-check`: it statically scans all s
 Yes — Windows 10+ with the bundled `tar`. The rescue launcher becomes a `.bat` file.
 
 **Where do backups go by default?**
-`~/Desktop/dsh-backups/` — change it any time in the panel (Settings → Plugins → Backup) or via settings; takes effect immediately, no restart.
+`~/Desktop/DSH Backups/` — change it any time in the panel (Settings → Plugins → Backup) or via settings; takes effect immediately, no restart. Since 0.14.0 the default directory was renamed from the old `~/Desktop/dsh-backups`: users who never configured a destination get the old folder renamed in place on first start (same volume, atomic, no backups lost), while explicitly configured destinations are left untouched.
+
+**What are all those files in the backup folder?**
+Every backup writes a plain-language guide to the folder root (`使用说明.txt`, Chinese with a short English section) explaining the archives, `.sha256` sidecars, rescue kit, `vault/` credentials and `auto.json` — plus the three ways to restore. You'll know what can be deleted and where to start.
 
 ## Feedback
 
@@ -138,6 +152,8 @@ Tried it? Tell us what broke, what's missing, what you liked — it directly sha
 <details>
 <summary>Recent releases</summary>
 
+- **0.14.0** — one big release: backup-folder UX + panel redesign + full capability parity. ① **Directory rename**: default `~/Desktop/dsh-backups` → `~/Desktop/DSH Backups`; users who never configured a destination get the old folder renamed in place on first start (atomic, no lost backups), explicit destinations are untouched, and a failed rename keeps the old folder working; every backup writes `使用说明.txt` (what each file is + three restore paths). ② **Panel redesign**: three tabs (Backup / Restore / Settings), three-step onboarding, typed-backup chips, plain-language copy, responsive. ③ **Backup upgrades**: optional password encryption (scrypt+AES-256-GCM, password never persisted), single-file ZIP export/import (section preview → conflicts keep existing by default → auto snapshot → auto rollback), local `link:`/`file:` plugin migration. ④ **Sync & ops**: WebDAV / S3-compatible / Gist channels, GFS monthly/yearly retention, operation lock + stale-lock reclaim, disk-usage report + tiered cleanup, weekly schedules. ⑤ **Ecosystem**: config market (index validation + preview install + supply-chain notes), import skills & global instructions from Claude Code / Cursor / Codex (MCP detected and reported only), Profiles management (built-ins read-only), conversation rewind fork (original untouched), About panel, agent tools 1→6, cross-tool chat-history import (Claude Code → new DSH session, originals untouched), offline CLI (reinstall / sessions repair / recover-stale-lock). ⑥ **Compatibility & acceptance**: real-host e2e 66/66 on DSH **0.2.1-rc.2**, smoke 578 / settings 47 / client 60 green; also fixed `doctor --repair` on Windows failing because bsdtar refuses to overwrite existing objects (#131) — it now extracts to a staging directory and copies only the targets, leaving non-target files untouched. peers/engines unchanged (`^0.2.0-rc.1` covers the 0.2.1 train, next peer boundary 0.3.0).
+- **0.13.4** — Metadata-only release (**no code or behavior change**): the npm description and keywords now carry the terms people actually search for — migration, moving to a new machine, plugins, MCP, skills, sessions, workspace — so dsh-backup shows up for "upgrade went wrong" and "moving my DSH setup" queries. Features, archive format, settings and RPC are identical to 0.13.3; staying on 0.13.3 behaves exactly the same.
 - **0.13.3** — Three fixes from real user reports plus two self-found defects, all re-verified on four host trains (0.1.5-rc.3 / 0.1.7-rc.2 / 0.2.0-rc.2 / 0.2.1-alpha.1) with e2e 41/41 each: ① **archives containing attachments could not be restored at all** (#112, @zevs281): DSH's attachment store uses hard links (tar typeflag `h`) while the restore validator only allowed `-`/`d` — full restore, dry-run, typed merge and doctor repair all refused on 0.13.2 and earlier. Hard links are now allowed when both the entry and its target stay inside the backup root (symlinks/devices still rejected). ② **large archives were falsely rejected on restore** (#119, @Yoshino-JF): when the `tar -tvzf` listing exceeds the host subprocess spill cap the host discards the spill file and only the last 8 KB remain; the validator then treats a mid-filename fragment as an unsafe entry and refuses the whole archive (backup succeeds, verify passes, only restore fails). The listing is now consumed as a raw stream line by line (no cap; terminate on the first violation). ③ **doctor/migrate were blind to v4 session logs** (#117, @xiuwufangoc-design): the host moved to format v4 (`session.v4.jsonl.zstd`) in 0.1.7 while filenames and the calibrated generation were hardcoded to generation 0/v3 — scans found nothing. Filenames are now matched by the host's own pattern, the calibrated generation moved to v4, and newer generations only warn. ④ **one-click update could not cross minors** (#115): pnpm `update` only upgrades within the declared range and the receipt claimed success regardless — now `update --latest`, with the actually-installed version read back and verified. ⑤ **migration precheck false alarms** (#113, @zevs281): unknown `source.kind` values are hints now instead of "will not open" verdicts, and the known set is aligned with the host's authoritative tables.
 - **0.13.2** — dsh **0.2.0 train** adaptation: peers/engines gain `^0.2.0-rc.1` (the host rejects incompatible peers at install time since 0.1.7-rc.1); **settings form fixed for 0.1.7+** (the host derives forms from the entry's Config schema and only honors `volatile` fields — the plugin exports `Config` with per-field `.volatile()`); Windows scheduler boot hang fixed (#103: streaming hash + boot grace + persisted attempt anchor); review P2 debt cleared and an in-product Star entry.
 - **0.13.1** — Two panel fixes, both from user reports: ① **the panel tab silently disappears on host 0.1.6+** (#94, @jackovibe): since 0.1.6 the host requires a `create()` lazy factory on strict codecs in client Remote contributions (older hosts only read `schema`); without it `$mount` throws during validation with only a console log, so the tab is never registered. Fix: `strictCodec()` now provides both `schema` and `create()` sharing one zod instance; `$mount` waits declaratively for the `remote` service (0.1.6 settles client modules by dependency graph); and a new `BackupTabFallback` **degraded tab** shows a visible hint plus command pointers if the mount ever fails — no more silent disappearance. peers/engines gain `^0.1.6-alpha.1 || ^0.1.7-alpha.1` (verified on real hosts 0.1.6-alpha.2 / 0.1.7-alpha.2 / 0.1.7-rc.1 / 0.1.7-rc.2). ② **the "GitHub Token" save button errored** (#97, @CheeseTJ): the client `panel` proxy never re-exported `setGithubToken` (that RPC landed in the host half in 0.12.0 and the omission lay dormant while no UI called it). Fix: wire it up, plus a new smoke-client assertion that the panel surface must mirror the contribution descriptors one-for-one.
@@ -159,7 +175,7 @@ Tried it? Tell us what broke, what's missing, what you liked — it directly sha
 
 ## More
 
-Retention policy, credential redaction internals, GitHub sync, restore safeguards, config reference, troubleshooting, and development notes — in the [advanced guide](docs/advanced.zh.md) (Chinese). Cross-runtime compatibility notes: [compatibility.md](docs/compatibility.md).
+Retention policy, credential redaction internals, GitHub sync, restore safeguards, config reference, troubleshooting, and development notes — in the [advanced guide](docs/advanced.zh.md) (Chinese). Portable install & config: [INSTALL.md](docs/INSTALL.md). Cross-runtime compatibility notes: [compatibility.md](docs/compatibility.md). Full feature-parity and acceptance standard vs. similar tools: [ALIGNMENT.md](docs/ALIGNMENT.md). Release notes & promo copy: [docs/promo/](docs/promo/).
 
 ## Acknowledgements
 

package/README.md

@@ -15,7 +15,7 @@
 ```sh
 dsh plugin --profile web add @xiaoyuyu6420/dsh-backup   # 安装
 # 重启 dsh web，然后输入：
-/backup                                                  # → 一份带校验的备份落在 ~/Desktop/dsh-backups/
+/backup                                                  # → 一份带校验的备份落在 ~/Desktop/DSH Backups/
 ```
 
 v0.9.0 全新安装的真实输出：
@@ -30,6 +30,12 @@ sha256: 8f9ae6322ef782d21554981cf4547220d5bb3e64d7964a883317415ad54e3cbb
 
 ![备份面板](docs/assets/panel-backups.png)
 
+**三条承诺**（完整对齐与交付标准见 [ALIGNMENT.md](docs/ALIGNMENT.md)）：
+
+- 🔐 **凭据不离开本机** —— API Key / Token 默认脱敏，明文只留在本机 vault；要更强，可选口令加密备份（AES-256-GCM）。
+- ↩️ **恢复绝不静默覆盖** —— 恢复前先自动快照当前数据、预览要写入的内容，失败自动回滚。
+- 🧭 **装上就知道怎么用** —— 首屏三步引导 + 每个高级功能一句人话说明；三个 Tab（备份 / 恢复 / 设置），主按钮只有一个「立即备份」。
+
 ## 它替你挡掉哪些事
 
 | 你担心的 | dsh-backup 做的事 |
@@ -43,6 +49,11 @@ sha256: 8f9ae6322ef782d21554981cf4547220d5bb3e64d7964a883317415ad54e3cbb
 | 「换新电脑了」 | GitHub 同步：`/backup github pull` 拉回云端备份，`restore --sync-deps` 顺手重装插件 |
 | 「备份悄悄坏了没人知道」 | 每份归档带 sha256，`/backup verify all` 随时体检；每日/每周分级保留，留得住有用的历史 |
 | 「我会忘记备份」 | `/backup auto 12`——每 12 小时自动跑，重启不中断，旧副本自动轮换（默认保留 7 份） |
+| 「换新电脑，插件和配置都要重装」 | 单文件 ZIP **导出/导入** + 本地 link:/file: 插件迁移；也能 WebDAV / S3 兼容 / Gist 多通道同步 |
+| 「想从别的 AI 工具搬过来」 | 从 Claude Code / Cursor / Codex 读取**技能与全局指令**，预览后导入（MCP 只检测报告） |
+| 「想回到对话里的某个时刻」 | 会话 **Rewind 分叉**：从指定轮次开新分支，原会话完整保留 |
+| 「备份把磁盘占满了」 | **磁盘占用报告** + 分级清理：只清可再生缓存/过期备份，快照与同步数据不动 |
+| 「想装社区现成配置」 | **配置市场**：索引校验 + 预览安装 + 供应链提示，逐个确认才写入 |
 
 **遇到具体报错？** 按症状与报错原文查的排错手册：[故障排查](docs/troubleshooting.zh.md)（会话打不开、29 字节空包、面板消失、Token 按钮报错、换机迁移……各条的版本与修法都写明）。
 
@@ -50,7 +61,7 @@ sha256: 8f9ae6322ef782d21554981cf4547220d5bb3e64d7964a883317415ad54e3cbb
 
 ## 安装
 
-要求：macOS / Linux / Windows 10+（自带 `tar`），DSH `0.1.1-rc.2`+（0.1.1 / 0.1.2 / 0.1.5 / 0.1.6 / 0.1.7 列车均已实测，0.2.0 列车自 0.13.2 起支持；当前兼容状态见 [兼容性矩阵](docs/compatibility.md)）。
+要求：macOS / Linux / Windows 10+（自带 `tar`），DSH `0.1.1-rc.2`+（0.1.1 / 0.1.2 / 0.1.5 / 0.1.6 / 0.1.7 列车均已实测，0.2.0 / 0.2.1 列车分别自 0.13.2 / 0.14.0 起支持；当前兼容状态见 [兼容性矩阵](docs/compatibility.md)）。
 
 ```sh
 dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
@@ -68,7 +79,7 @@ dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
 
 1. 按上面装好插件，重启 `dsh web`
 2. 输入 `/backup`
-3. 搞定 —— 备份出现在 `~/Desktop/dsh-backups/`，文件名带时间戳，旁边一份 `.sha256`
+3. 搞定 —— 备份出现在 `~/Desktop/DSH Backups/`，文件名带时间戳，旁边一份 `.sha256`
 
 想定时自动跑？`/backup auto 12`（每 12 小时一次；`off` 关闭，`status` 看状态）。
 
@@ -126,7 +137,10 @@ dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
 支持——Windows 10+（用系统自带 `tar`），救援启动器是 `.bat` 文件。
 
 **备份默认放哪？**
-`~/Desktop/dsh-backups/`——在面板（设置 → 插件 → 备份）里随时可改，立即生效不用重启。
+`~/Desktop/DSH Backups/`——在面板（设置 → 插件 → 备份）里随时可改，立即生效不用重启。0.14.0 起默认目录由旧的 `~/Desktop/dsh-backups` 改名而来：从未配置过备份目录的用户，升级后首次启动会把旧目录自动改名（同盘、原子、不丢备份）；显式配置过目录的一律不动。
+
+**备份目录里那些文件都是什么？**
+每次备份会在目录根写一份「使用说明.txt」，逐个解释归档、`.sha256` 校验边车、救援工具、`vault/` 凭据、`auto.json` 状态，以及恢复的三条路。第一次打开文件夹看完就知道哪个能删、恢复从哪下手。
 
 ## 反馈
 
@@ -140,6 +154,8 @@ dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
 <details>
 <summary>最近的版本</summary>
 
+- **0.14.0** —— 一次大版本：备份目录 UX + 面板重构 + 与同类方案对齐的完整能力。① **目录改名**：默认 `~/Desktop/dsh-backups` → `~/Desktop/DSH Backups`，从未配置过 destination 的用户升级后首次启动同盘自动改名（原子、不丢备份），显式配置不动，失败继续用旧目录；每次备份在根目录写「使用说明.txt」（每个文件是什么 + 三条恢复路径）。② **面板重构**：三个 Tab（备份 / 恢复 / 设置）+ 首启三步引导 + 分类型 chips + 文案去术语 + 响应式。③ **备份增强**：可选口令加密（scrypt+AES-256-GCM，口令不落盘）、单文件 ZIP 导出/导入（节段预览 → 冲突默认保留 → 自动快照 → 失败回滚）、本地 link:/file: 插件迁移。④ **同步与运维**：WebDAV / S3 兼容 / Gist 多通道同步、GFS 月/年保留、操作锁 + 残留锁回收、磁盘占用报告 + 分级清理、每周调度。⑤ **生态**：配置市场（索引校验 + 预览安装 + 供应链提示）、从 Claude Code / Cursor / Codex 导入技能与全局指令（MCP 只检测报告）、Profiles 管理（内置只读）、会话 Rewind 分叉（原会话零改动）、About 面板、agent 工具 1→6、跨工具聊天记录导入(Claude Code → 新 DSH 会话,原数据不动)、离线 CLI（reinstall / sessions repair / recover-stale-lock）。⑥ **兼容与验收**：DSH **0.2.1-rc.2** 真机 e2e 66/66，smoke 578 / settings 47 / client 60 全绿；另修复 Windows 上 `doctor --repair` 因 bsdtar 拒绝覆盖同名对象而失败（#131）：改为暂存区解包 + 按目标拷贝，非目标文件零改动。peers/engines 不变（`^0.2.0-rc.1` 覆盖 0.2.1 列车，下一 peer 边界 0.3.0）。
+- **0.13.4** —— 元数据版（**无代码与行为变更**）：npm 描述与关键词对齐检索用词——补入「迁移 / 换机 / 插件 / MCP / 技能 / 会话 / 工作区」等，让"搬家换机、升级翻车"场景的人在 npm 搜索里能找到本插件。功能、归档格式、设置项、RPC 与 0.13.3 完全一致；升级到本版与停留在 0.13.3 在行为上没有任何区别。
 - **0.13.3** —— 三条真实用户报障的修复 + 两个自建缺陷修复，全部在四条宿主列车（0.1.5-rc.3 / 0.1.7-rc.2 / 0.2.0-rc.2 / 0.2.1-alpha.1）真机 e2e 各 41/41 复验：① **含附件的归档恢复全链路不可用**（#112，@zevs281）：DSH 附件库用硬链接（tar 记为 `h` 条目），而恢复校验器只放行 `-`/`d`——0.13.2 及更早对这类归档的完整恢复/dry-run/分类型合并/doctor 修复一律拒绝。修法：条目与目标都在备份根内的硬链接放行（符号链接、设备仍拒）。② **大归档恢复被误拒**（#119，@Yoshino-JF）：归档清单超过宿主 subprocess 的 spill 上限时宿主会**丢弃 spill 文件**、只留 8 KB 尾窗，校验器把"断在文件名中间的碎片"当成不安全条目 → 整包拒绝（备份成功、verify 报完整、只在恢复时炸）。修法：清单改走原始流逐行校验（无上限，发现违规立即终止）。③ **doctor/migrate 看不见 v4 会话日志**（#117，@xiuwufangoc-design）：宿主 0.1.7 起会话格式为 v4（`session.v4.jsonl.zstd`），而文件名与校准代写死到第 0 代/v3——体检与迁移预检一份都扫不到。修法：按宿主同源形态匹配文件名、校准代推进到 v4、更新代只提示。④ **一键更新跨不过 minor**（#115）：pnpm `update` 只在声明范围内升级，跨 minor 停在旧版且回执谎报成功。修法：`update --latest` + 跑完读回 profile 内真实版本核对。⑤ **迁移预检误报**（#113，@zevs281）：未知 `source.kind` 从"判打不开"降级为提示，名单对齐宿主权威集合（真机曾把 81/82 份健康日志误报）。
 - **0.13.2** —— 适配 dsh **0.2.0 列车**：peers/engines 追加 `^0.2.0-rc.1`（宿主自 0.1.7-rc.1 起有安装期兼容闸门，不覆盖会被拒绝安装）；**修复 0.1.7 起失效的设置表单**（宿主改从条目 Config schema 派生表单且只认 `volatile` 字段——本插件导出 `Config` 并逐字段 `.volatile()`，设置卡片恢复可读可写）；修复 Windows 调度器启动卡死（#103：流式哈希 + 启动宽限 + 尝试锚点落盘）；review P2 债清偿与产品内 Star 入口。
 - **0.13.1** —— 修复两个面板问题（均感谢用户报告）：① **0.1.6+ 宿主上面板标签静默消失**（#94，@jackovibe）：宿主 0.1.6 起要求客户端 Remote 贡献的 strict codec 带 `create()` 惰性工厂（旧版只读 `schema`），缺失时 `$mount` 在校验阶段抛错且只有 console 日志——标签页因此永不注册。修法：`strictCodec()` 同时提供 `schema` 与 `create()`，两代宿主共用同一 zod 实例；`$mount` 改为声明式等待 `remote` 服务就绪（0.1.6 客户端模块按依赖图结算）；并新增 `BackupTabFallback` **降级标签页**——万一挂载失败会在面板位置给出可见提示与命令指路，不再静默消失。peers/engines 追加 `^0.1.6-alpha.1 || ^0.1.7-alpha.1`（0.1.6-alpha.2 / 0.1.7-alpha.2 / 0.1.7-rc.1 / 0.1.7-rc.2 实机验证通过）。② **「GitHub Token」保存按钮报错**（#97，@CheeseTJ）：客户端 `panel` 代理漏接了 `setGithubToken`（该 RPC 0.12.0 加入宿主半时即漏，因当时面板无入口而潜伏两版）。修法：补接该行，并给 smoke-client 加「panel 面必须与贡献 descriptors 一一对应」的防漏断言。
@@ -161,7 +177,7 @@ dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
 
 ## 更多
 
-定时备份策略、敏感文件脱敏、GitHub 同步、恢复保护机制、配置参考、故障排查、开发说明——都在[进阶文档](docs/advanced.zh.md)。跨运行时兼容性说明：[compatibility.md](docs/compatibility.md)。
+定时备份策略、敏感文件脱敏、GitHub 同步、恢复保护机制、配置参考、故障排查、开发说明——都在[进阶文档](docs/advanced.zh.md)。便携安装与配置：[INSTALL.md](docs/INSTALL.md)。跨运行时兼容性说明：[compatibility.md](docs/compatibility.md)。与同类方案的完整能力对齐与验收标准：[ALIGNMENT.md](docs/ALIGNMENT.md)。发布说明与宣发物料：[docs/promo/](docs/promo/)。
 
 ## 致谢