xiaoyuyu6420/dsh-backup

English | 简体中文

Your entire DeepSeek Harness (DSH) workspace lives in one folder: ~/.dsh. One failed upgrade, one accidental delete, one new laptop — without a backup, sessions, settings and skills are all gone. dsh-backup gives them back with one command.

dsh plugin --profile web add @xiaoyuyu6420/dsh-backup   # install
# restart dsh web, then type:
/backup                                                  # → a verified archive lands in ~/Desktop/dsh-backups/

Real output from a fresh v0.9.0 install:

备份完成: dsh-20260826-195150036.tar.gz
sha256: 8f9ae6322ef782d21554981cf4547220d5bb3e64d7964a883317415ad54e3cbb
轮换删除 0 份（保留 7 份）

Prefer clicking? There's a visual panel in dsh web → Settings → Plugins → Backup: list, verify, restore, delete, edit settings — no restart.

Why you want this

Fear	What dsh-backup does about it
"An upgrade broke my setup"	Auto-takes a dsh-pre-upgrade- snapshot the moment the host version changes — try the new release, roll back if it bites
"I deleted / broke something"	/backup restore latest --dry-run previews exactly what comes back; a failed restore auto-rolls-back and shows a result receipt
"DSH won't even boot anymore"	Every backup drops a zero-dependency rescue console (dsh-rescue / rescue.mjs, or double-click「点我恢复」) next to the archives — a web UI that restores outside of DSH
"My API keys will end up in a cloud backup"	Credentials are redacted from archives by default; plaintext only ever lives in a local vault on your machine
"My session logs got corrupted"	/backup doctor scans and repairs session logs from a known-good backup; corrupt files are quarantined before they rotate away
"Old sessions won't open after an upgrade"	/backup migrate-check statically predicts which sessions the new host will refuse (and under which rule) before you upgrade; the credential sentinel preserves pre-migration copies of legacy .credentials.yaml
"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)

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 trains are all tested; verified up to 0.1.5-rc.2).

dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
# or straight from GitHub:
dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup

Restart dsh web afterwards — the plugin only takes effect after a restart.

The installer may print ✕ missing peer @deepseek-ai/... warnings. These are expected: the peer packages are provided by the DSH host at runtime. As long as the command ends with Done, the plugin is installed.

Quickstart

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

Want it on a schedule? /backup auto 12 (every 12 hours; off stops it, status checks it).

Command cheat sheet

Task	Command
Back up now	/backup
Typed backup (selected types only)	/backup --types skills,sessions (types: credentials·mcp·skills·sessions·settings·profiles; --only works too)
Schedule (survives restarts)	/backup auto 12 · off · status
Restore (preview first)	/backup restore latest --dry-run
Restore for real	/backup restore latest
Typed restore (merge, other types untouched)	/backup restore <archive> --types skills
List backups	/backup list
Verify integrity	/backup verify [prefix|all]
Check & repair session logs	/backup doctor · --repair [prefix|latest]
Pre-upgrade migration precheck	/backup migrate-check
Rescue when DSH won't boot	double-click「点我恢复」in the backup dir, or dsh-rescue / node rescue.mjs
Delete / retention	/backup delete <prefix|latest> · /backup --keep N (default 7)

Typed backup

Only need certain kinds of data? Use --types (or --only) to operate on a subset. Available types: credentials (API keys), mcp (MCP config), skills, sessions, settings, profiles.

• Back up: /backup --types skills,sessions creates a dsh-t- subset archive; rotation is tracked separately from full backups
• Restore: /backup restore <archive> --types skills merges only skills back into your existing ~/.dsh (preview with --dry-run; overwritten files are kept aside as .pre-merge-*). Everything else stays untouched.
• Credentials caveat: --types credentials puts API keys into the archive in plaintext (full backups redact them). Such archives never go to GitHub sync — keep them local or copy them to a new machine yourself.
• Guardrail: restoring a typed archive without --types is rejected (prevents accidental data loss); the rescue channel likewise won't list or fully restore them.
• The Settings panel supports this too: check types under the backup button; typed archives get their own section.

New machine

Prerequisite: GitHub sync was configured on the old one (setup, Chinese).

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

FAQ

Are my API keys / credentials inside the archive? No. Known credential files are redacted before archiving; the plaintext stays in a local vault that never leaves the machine. Restoring puts them back.

What exactly gets backed up? Everything under ~/.dsh — sessions, settings, skills, plugin config — minus your exclude patterns and node_modules.

I messed up ~/.dsh and now dsh won't start. Am I out of options? No — that's exactly what the rescue channel is for. Every backup writes rescue.mjs and a double-clickable launcher (点我恢复.command / .bat / .sh) into the backup directory. It runs on plain Node, no DSH required, and serves a local web UI to browse and restore archives.

Old sessions refuse to open after a host upgrade — what now? Don't keep clicking them. Run /backup migrate-check: it statically scans all session logs and tells you which sessions the new host will refuse and under which rule (legacy subagent descriptor versions, plugin-injected historical events, ...), plus whether your filesystem supports hardlink publishing. Take a /backup snapshot before upgrading; broken sessions can be repaired from an earlier archive with /backup doctor --repair.

Windows support? 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.

Feedback

Tried it? Tell us what broke, what's missing, what you liked — it directly shapes the roadmap:

• 💬 Share feedback (GitHub Discussions)
• 🐛 Report a bug

What's new

• 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.
• 0.13.0 — Update awareness + one-command self-update: ① /backup check-update and a new "Plugin updates" card in the panel — checks the npm registry for a newer version (8s timeout, degrades silently offline, never blocks the plugin); when a newer version exists an "Update to x.y.z" button appears; the updateCheck setting (default off) silently checks on panel open. ② /backup update [--profile <name>] — takes a dsh-pre-upgrade- snapshot automatically before updating (roll back with /backup restore), then runs the official dsh plugin --profile <name> update (pnpm semantics; the plugin never rewrites its own dependency files), and tells you to restart dsh web afterwards. Note: the host settles the plugin Loader tree at startup and plugins are pnpm dependencies of the profile, so true hot-swap (no restart) is not possible in the current host architecture — one-command update + restart is the best form it can take.
• 0.12.2 — Fix a Windows data-safety hazard (#88, thanks @Liuyeyuyangy0 for the outstanding report): when DSH_HOME sits directly under a drive root (e.g. D:\dsh_data), the string-slice parent computation degrades to the bare drive letter D:, and tar -C D: fails on both bsdtar and GNU tar — worse, tar creates the -f target before writing, leaving a 29-byte empty shell that the panel lists as a normal backup (no .sha256/.meta.json; silently zero usable backups, and the restore / doctor repair / rescue channels are hit by the same bug). All 7 tar -C call sites (backup, typed & full restore, doctor point-repair, rescue snapshot/restore/repair) now receive a separator-completed parent; paths() normalizes trailing slashes off DSH_HOME like HOME (a trailing slash used to empty the tar positional and produce 0-byte archives); failed tar runs now delete the empty shell before rethrowing, so failures are visible. Smoke gains scenario 28 (four path-layout assertions + a trailing-slash real-backup e2e). Archive format, settings and RPC unchanged.
• 0.12.1 — Fix client bundle leaking top-level var module / var exports as globals (#85, thanks @geyonder): the CJS shim now lives inside the __ModuleLoader__.load factory body instead of creating window.module, which made Monaco's AMD loader (dsh-vscode-mode and friends) misdetect a Node environment and break sibling plugins on the same page. Client smoke suite gains a classic-script global-leak regression assertion (vm.runInContext). Client-half only; node-side behavior and archive format unchanged.
• 0.12.0 — Migration safety net, round one, aimed at the community-wide "old sessions won't open after upgrade" wave (#6151/#6297/#6355): 1) /backup migrate-check statically scans all session logs (v0/v1/v2/v3) before you upgrade and predicts which sessions will refuse to open and under which rule (descriptor v2, permission/preset origin, event types outside the frozen lists, custom source kinds, seq drift, filename/generation mismatch — rules baked from host 0.1.5-rc.2, with the coverage boundary stated in every report), plus a filesystem hardlink probe (the exFAT publish-failure scenario from #6358); 2) a credential sentinel — the legacy flat-layout .credentials.yaml gets atomically replaced by the host with an irreversible versioned form, so on detection it is preserved into the vault before the host touches it. 3) configure the GitHub sync token right in the Settings panel (or /backup github token <token>) — stored locally as github.token (0600) in the backup directory, never archived or synced, taking precedence over environment variables; re-enter after cross-machine restore. Also: engines.dsh declaration (read by plugin-market compatibility cards).
• 0.11.3 — Follow the dsh 0.1.5 train: peerDependencies now include ^0.1.5-rc.1 (0.11.2 raised peer warnings on 0.1.5 hosts). Verified against host 0.1.5-rc.2: real-host e2e 32/32; all six node-side peer packages are byte-identical between rc.1 and rc.2 (tarball diff) and the client train hasn't moved — zero adaptation surface this time; a cross-train in-place upgrade e2e (rc.1 host + 0.11.2 → rc.2 host + 0.11.3) passed 14/14 with settings and archives intact. Also fixed a latent bug in the upgrade e2e itself: the expected new version is now derived from the tarball instead of hardcoded.
• 0.11.2 — doctor line-level SessionHeader validation aligned with the host isHeaderLine (closes the known gap from 0.11.0): version/createdAt/delegationDepth type + non-negative-safe-integer checks (including -0 rejection), optional seedLength/origin/agentPreset branches, and retired sandboxMode/approvalPolicy fields the host reader rejects — headers the host refuses to load are now flagged instead of reported healthy. Verified field-by-field against the compiled host source (both trains; the rc.1 checker is the strict superset) with an independent review verdict of ALIGN; 11 bad-header negative samples + repair round-trip added to the suite.
• 0.11.1 — dsh 0.1.2-rc.1 compatibility: adapts to the removal of settingsNamespace from @deepseek-ai/dsh-settings (settings now register under the plain dsh-backup namespace — value-identical, so existing settings, backups and archives survive an in-place update), works behind the new forced web auth (303 + HttpOnly cookie), and widens peer ranges to ^0.1.1-rc.2 || ^0.1.2-rc.1. Verified on both trains with real-host e2e (32/32 each) plus an in-place 0.11.0 → 0.11.1 upgrade test (settings preserved, old archives restorable).
• 0.11.0 — doctor container-contract check: the first zstd frame must decode to exactly one header line, byte-precise (non-empty, first newline at the last byte — aligned with the host reader). Single-frame rewrites, stray blank lines in the first frame, a missing trailing newline and skippable frames are now flagged corrupt (previously reported healthy while the host refused to load them); the rescue console checks in sync. Found via a community audit on deepseek-harness #1047.
• 0.10.0 — typed backups: back up just what you need (/backup --types skills,sessions) and merge-restore a subset (/backup restore <archive> --types skills); per-type archives rotate in their own bucket. Credential-type archives stay out of GitHub sync; cross-machine guardrails unchanged.
• 0.9.1 — feedback entry point in the panel; README overhaul. UX hardening from a six-agent review: restore-confirm button made visible again (missing theme fallback), snapshot self-deletion during snapshot-restore fixed, node discovery for the double-click rescue launcher, friendlier error messages with concrete next steps.
• 0.9.0 — /backup doctor session-log health check with targeted repair; out-of-process rescue channel (dsh-rescue / launcher in the backup dir) that works even when the host won't boot; restore auto-rollback with a result-oriented receipt; smart backup: pre-upgrade snapshots on host train changes, quarantine of corrupt session logs before they rotate away, tiered daily/weekly retention.
• 0.8.0 — edit backup settings right in the panel (destination, retention, exclude patterns), saved instantly to settings.yaml, no restart; stale edits get a conflict warning instead of silent overwrite.
• 0.7.x — credential redaction with a local vault; cross-machine restore.

More

Retention policy, credential redaction internals, GitHub sync, restore safeguards, config reference, troubleshooting, and development notes — in the advanced guide (Chinese). Cross-runtime compatibility notes: compatibility.md.

Acknowledgements

• @beastrobin — the reserved-method-name root cause analysis in #1 that directly led to the v0.5.1 fix
• @mlosun — the thorough reproduction and root cause report in #2
• @Choi-Peng — triage help pointing affected users to the fix in #5

Support this project

If dsh-backup has been useful: ⭐ a star is the simplest way to say thanks — and it helps other DSH users find it. Questions or ideas? Drop them in the feedback thread.

License

MIT