# π©Ί dsh-doctor
### Your personal doctor for DeepSeek Harness
**Diagnose Β· Reversible Repair Β· One-click Rollback Β· Runtime Self-healing**
[](https://www.npmjs.com/package/@jorinyang/dsh-doctor)
[](https://www.npmjs.com/package/@jorinyang/dsh-doctor)
[](LICENSE)
[](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!