# 💾 Kidai Snapshot Guard **The automatic in-DSH backup manager** — save on close · verify on boot · rollback in one click [**简体中文**](README.md) · **English**
--- ## ✨ Why? DeepSeek Harness (DSH) config changes (install / update / toggle) can leave DSH unbootable — the thing you need most is "what it looked like before". **Kidai Snapshot Guard** runs **inside** DSH and automates the snapshot loop (save → verify → restore), sharing one store with the external [**Kidai Plugin Remote**](https://github.com/NokorinNishikino/kidai-plugin-remote) — so even when DSH can't boot, the external manager can still roll back. - 💾 **Auto save on close** — every graceful close keeps a known-good snapshot (config + settings + third-party plugin dirs), rolling the latest 3 - ✅ **Verified on boot** — each successful start promotes pending snapshots → **verified** ("kept until the next successful run") - 📦 **Single-zip backup** — export / import / restore a whole snapshot as one offline zip — even when DSH can't boot - 🔄 **Isolation auto-recovery** — if the external manager's one-shot isolated run was interrupted, the previous config is restored on next launch - 🔔 **Launch notices** — success / auto-recovery toasts on the 纪代备份 page - 🧩 **Compatibility** — reads and restores dsh-plugin-guard rollbacks and dsh-config-manager snapshots - ✏️ **Snapshot notes** — annotate any snapshot to tell them apart (synced with the external manager) > **Install and forget** — starts with DSH, no setup needed; open > 设置 → 纪代备份 to manage. --- ## 🚀 Quick start ### Install ```bash # Option A: direct from GitHub (once published) dsh plugin --profile desktop add github:NokorinNishikino/kidai-snapshot-guard # Option B: local development (from the kidai-plugin-remote checkout) powershell -ExecutionPolicy Bypass -File scripts\install-guard.ps1 ``` **Restart DSH** afterwards, then open 设置 → 纪代备份. ### Uninstall ```bash dsh plugin --profile desktop remove kidai-snapshot-guard ``` or manually: remove the `kidai-snapshot-guard` dependency and bundle entry from `profiles/desktop/package.json`, then delete the `node_modules/kidai-snapshot-guard` directory. > **Standalone**: KSG is a **fully independent backup plugin** — it works > without Kidai Plugin Remote (auto snapshots, export, restore); the external > manager is only an extra rollback entry for when DSH can't boot. Then, inside DSH: - Open **设置 → 纪代备份** — manage snapshots, export/import, quota. - Or use the `/kidai-snapshot` slash command for a read-only summary. --- ## 🔗 Ecosystem | Repo | Role | Runs where | |---|---|---| | **kidai-snapshot-guard** (you are here) | snapshots, pending→verified, isolation recovery | inside DSH | | [**kidai-plugin-remote**](https://github.com/NokorinNishikino/kidai-plugin-remote) | external management & rollback UI | outside DSH | | [**kidai-plugin-remote-client**](https://github.com/NokorinNishikino/kidai-plugin-remote-client) | same manager, native window, zero deps | outside DSH | The store (`$DSH_HOME/.kidai-snapshots`) and the guard directory (`$DSH_HOME/guard/`) are shared: a snapshot saved here is visible and rollback-able from the external manager, and vice versa. --- ## 📸 How it works (technical) - **On close** — a dispose effect takes a FULL snapshot (config + settings + third-party package dirs) while the shutdown flow awaits it; a synchronous `exit`-event light snapshot (config + settings, no package dirs) is the universal fallback. Deduped within 30 s so one shutdown = one snapshot. - **On boot** — pending snapshots are promoted to `verified`; a rolling `known-good` snapshot is maintained (pinned id) and refreshed when the profile's plugin set changes (30 s watcher). - **One-shot isolation** — reads the external manager's isolation marker; if the DSH that launched is not the one the manager spawned (PID mismatch: manager killed, or DSH launched directly from a shortcut), the pre-isolation config is restored and the marker cleared — isolation only ever affects ONE launch, no matter who starts DSH. - **API** — `/api/kidai-snapshot/*` on the DSH webServer: status / list / save / known-good / delete / export / exports / import / restore / foreign / foreign-restore / settings / quota / meta / notice / note. - **Host-only & defensive** — every operation is wrapped so the guard can never break boot or block shutdown beyond a bounded timeout. ``` kidai-snapshot-guard/ ├── lib/ │ ├── index.js # plugin entry: boot hooks, close hooks, route registration │ ├── backup.js # snapshot engine: create/export/import/restore, quota, isolation marker │ ├── api.js # webServer routes under /api/kidai-snapshot/* │ └── client.js # 设置 → 纪代备份 page (injected into DSH's settings) ├── cordis.patch.yml └── package.json # dsh bundle manifest ``` ## 📄 License MIT