# 🩺 dsh-doctor ### Your personal doctor for DeepSeek Harness **Diagnose Β· Reversible Repair Β· One-click Rollback Β· Runtime Self-healing** [![npm](https://img.shields.io/npm/v/@jorinyang/dsh-doctor?style=for-the-badge&color=2563eb&label=npm)](https://www.npmjs.com/package/@jorinyang/dsh-doctor) [![downloads](https://img.shields.io/npm/dm/@jorinyang/dsh-doctor?style=for-the-badge&color=16a34a&label=downloads)](https://www.npmjs.com/package/@jorinyang/dsh-doctor) [![license](https://img.shields.io/npm/l/@jorinyang/dsh-doctor?style=for-the-badge&color=dc2626&label=MIT)](LICENSE) [![stars](https://img.shields.io/github/stars/jorinyang/dsh-doctor?style=for-the-badge&color=f59e0b&label=Star)](https://github.com/jorinyang/dsh-doctor) **δΈ­ζ–‡** Β· [README.md](./README.md)
--- > **DSH crashed? Can't start?** > > Two commands to catch your emotions and fix the root cause. ```bash # β‘  Install dsh plugin --profile web add @jorinyang/dsh-doctor # β‘‘ Fix dsh-doctor ``` **Built-in CLI, auto-registered to system PATH on install. Repairs are fully reversible β€” roll back anytime.** --- ## πŸ’‘ What it is DeepSeek Harness ships no built-in `doctor` command. When DSH crashes, fails to start, or a plugin breaks the profile, you're left staring at errors and hoping a restart will help. **dsh-doctor** is the first all-in-one "diagnose + repair + rollback" tool for DSH, and it's also a **runtime self-healing service**: | Capability | Form | Description | |-----------|------|-------------| | πŸ” **Diagnose** | `dsh_doctor` tool / `dsh-doctor` CLI | Read-only 9-category checks | | πŸ”§ **Repair** | `dsh_doctor_fix` tool / `dsh-doctor fix` | Graded repair, every reversible change journaled | | ↩️ **Rollback** | `dsh_doctor_rollback` tool / `dsh-doctor rollback` | LIFO undo to the pre-repair state | | ⚑ **Runtime service** | `dsh-doctor` Cordis service | Live diagnose/self-heal/lifecycle monitoring | --- ## ✨ Why dsh-doctor ### 🎯 Two commands to revive a crashed DSH No need to read error logs or hand-edit configs: ```bash dsh-doctor # diagnose first dsh-doctor fix # then repair ``` ### ↩️ Reversible repairs β€” safe to fix Every fix writes a **journal** recording the undo step of each change. Broke something? One command to undo: ```bash dsh-doctor rollback # undo the most recent repair dsh-doctor rollback --list # list all journals dsh-doctor rollback --id # undo a specific journal ``` ### ⚑ Runtime self-healing β€” works while DSH is alive Not just stop-and-fix. dsh-doctor wires into Cordis's native runtime: - `ctx.provide('dsh-doctor')` β€” expose diagnose/repair/rollback to other plugins - `ctx.on('internal/status')` β€” reactive plugin-lifecycle monitoring with FAILED alerts - `ctx.effect()` β€” reversible effects, no residue on unload ### 🌍 Cross-platform, zero config Auto-registers to system PATH on install β€” Windows / macOS / Linux / fish. --- ## πŸš€ Quick start ### Option A: DSH plugin (for the agent) ```bash # install from npm dsh plugin --profile web add @jorinyang/dsh-doctor # restart dsh web dsh web ``` Then ask the agent: ```text run dsh_doctor # diagnose run dsh_doctor_fix with scope safe # repair run dsh_doctor_rollback # rollback if needed ``` ### Option B: global CLI ```bash npm install -g @jorinyang/dsh-doctor # or npx @jorinyang/dsh-doctor ``` ### Demo ```bash $ dsh-doctor diagnose --profile web DSH Diagnostic Report (profile: web, port: 3080) DSH home: ~/.dsh [OK] Node.js v24.15.0 [OK] pnpm 11.9.0 [OK] DSH 0.1.0-rc.6 [OK] DSH home exists [OK] profile dir exists: web ... [XX] bundle missing: some-broken-plugin fix: Run pnpm install in profile dir 48 pass 0 fail 3 warn βœ“ No blocking issues found; DSH should start normally. ``` --- ## πŸ“– Command reference | Command | Description | Alias | |---------|-------------|-------| | `dsh-doctor` | Read-only diagnose (default) | `diagnose` / `check` | | `dsh-doctor fix` | Reversible repair | `repair` | | `dsh-doctor rollback` | LIFO undo | `undo` | | `dsh-doctor rollback --list` | List journals | `journals` / `list` | | `dsh-doctor setup` | Register to PATH | `install` / `register` | ### Options | Option | Description | Default | |--------|-------------|---------| | `--profile ` | DSH profile name | `web` | | `--port ` | Web port | `3080` | | `--scope ` | safe / deps / full | `safe` | | `--id ` | Journal id to roll back | most recent | | `-h, --help` | Help | | | `-V, --version` | Version | | ### Repair scopes | Scope | Actions | Risk | |-------|---------|------| | `safe` ⭐ | create missing dirs/files; fix allowBuilds | 🟒 Low β€” files/config | | `deps` | safe + `pnpm install --fix-lockfile` | 🟑 Medium β€” network + deps | | `full` | deps + stop residual processes (skip if healthy) | πŸ”΄ Higher β€” process kill | --- ## πŸ—οΈ How it works dsh-doctor aligns with DeepSeek Harness / Cordis's **Spatiotemporal Composability** paradigm: ```mermaid flowchart LR subgraph CLI["πŸ”§ dsh-doctor CLI (offline)"] D[Diagnose] F[Repair] R[Rollback] end subgraph Runtime["⚑ Runtime service (online)"] SVC[dsh-doctor service] WATCH[Lifecycle monitor] end DSH["πŸ–₯️ DeepSeek Harness"] D -->|finds issues| F F -->|writes journal| R R -->|LIFO restore| DSH F -->|reversible changes| DSH SVC -->|diagnose/repair/rollback| DSH WATCH -->|internal/status| DSH ``` ### Temporal β€” reversible repairs Every change records a **reverse undo function**; rollback replays LIFO: - overwritten file β†’ original saved, restored on rollback - created file/dir β†’ deleted on rollback (empty dirs only) - system-boundary ops (pnpm install, killed processes) β†’ flagged manual ### Spatial β€” runtime self-healing Wires into Cordis primitives to declare deps and react to changes: - `ctx.provide` β€” provide services - `ctx.on` β€” reactive listeners - `ctx.effect` β€” reversible effects --- ## πŸ†š vs. traditional approaches | | Restart roulette | Hand-edit config | **dsh-doctor** | |---|---|---|---| | Diagnose | ❌ guesswork | ⚠️ experience | βœ… 9 automated checks | | Repair | ❌ kill & retry | ⚠️ error-prone | βœ… graded auto-repair | | Rollback | ❌ none | ❌ none | βœ… one-click LIFO | | Runtime adjust | ❌ restart only | ❌ downtime | βœ… Cordis service | | Cross-platform | β€” | β€” | βœ… Win/macOS/Linux/fish | --- ## ❓ FAQ **Q: DSH is so broken the plugin can't load β€” still usable?** Yes. `dsh-doctor` is a self-contained CLI that doesn't depend on DSH running. Just run `dsh-doctor fix`. **Q: Will repair break my config?** No. Every reversible change records an undo step first. `dsh-doctor rollback` restores it. **Q: safe / deps / full β€” which to pick?** Start with `safe` (files/config only, zero risk). Escalate to `deps` (reinstall) then `full` (process cleanup) only if needed. **Q: Does it conflict with built-in DSH commands?** No. It's an independent plugin + CLI; it doesn't modify DSH core. --- ## 🀝 Contributing Issues and PRs welcome. For bug reports, please include `dsh-doctor diagnose` output. ## πŸ“„ License [MIT](LICENSE) ---
**DeepSeek Harness, painlessly.** πŸŽ‰ If it helped you, ⭐ Star this repo!