lxzy-7/dsh-plugin-guard

dsh-plugin-guard

Install safety net for DeepSeek Harness: pre-install snapshots, one-click / automatic rollback, guarded boot, and incident reports that auto-trigger agent analysis.

DeepSeek Harness 的插件安装安全网：安装前自动快照、一键/自动回退、守护启动、事故报告自动触发 Agent 分析。

English

What it does

A bad plugin install can leave the app unable to boot, and fixing it by hand usually means digging through config files. This plugin automates the whole chain:

Install a plugin (any method)
   │  tools.guard hook: automatic snapshot BEFORE the install (in-process)
   ▼
Guarded boot (boot-guard script)
   │  snapshot before boot → start dsh web → health check
   ├─ healthy ─────────────────────────────► passes through untouched
   └─ unhealthy ─► auto-rollback to last good snapshot → retry once
                   → write an incident report + set a pending marker
                   → the next session's prompt tells the agent to analyze it
                   → after fixing, call `incident_resolved` to clear the marker

How it detects problems (important to understand)

The guard does not statically inspect plugin code, and it does not try to "test" a plugin in isolation. Detection works at three levels:

1. Snapshots are pure file copies. Taking a snapshot just copies 5 config files (package.json, pnpm-lock.yaml, pnpm-workspace.yaml, cordis.yml, cordis.patch.yml). No plugin is run, no behavior is evaluated.

2. Boot-level detection does run the harness — with your plugin loaded. The boot-guard script starts the whole dsh web process (which loads every installed plugin, including the one you just added) and then health-checks HTTP / within a timeout. If a plugin breaks boot — load error, startup crash, unresponsive server — the check fails, and the guard automatically kills the tree, rolls back to the last good snapshot, and retries once. So yes: to catch a boot-breaking plugin, the harness (and therefore that plugin) has to actually start. That is the one moment where "running the plugin" is part of detection. Since v0.3.1 the check also confirms the web client actually rendered (a plugin crash that black-screens the page with an error leaves HTTP 200 up — the guard's client reports render crashes, and the boot-guard rolls back instead of calling a black screen "healthy"); incident reports additionally record the dsh version per snapshot and flag when a boot failure follows a harness update that a profile rollback cannot undo. Since v0.3.2, when rollback and the retry both fail (a DSH update made a plugin incompatible), the boot-guard diagnoses the offending plugin from the boot logs, quarantines it (appends disabled: true to cordis.patch.yml), boots without it, and clearly reports which plugin was pulled out and how to restore it (dsh-guard quarantine --undo <id>).