Preface¶

In DeepSeek Harness (DSH), installing plugins often carries the risk not of “installation failure,” but of the dsh web service failing to start afterward: configurations get altered, node_modules become inconsistent, or a bundled plugin crashes during the startup phase. Manual rollback typically involves sifting through package.json, cordis.yml, and lock files, then running pnpm install again—a time-consuming process prone to missing steps.

dsh-plugin-guard (maintained by lxzy-7) addresses this scenario: it automatically creates a snapshot before each plugin change, automatically rolls back upon startup failure, and generates an incident report for analysis in the next Agent session. It is categorized under admin-security in the SkillHub community directory and currently holds 31 GitHub stars.

What This Is¶

In one sentence: DSH’s plugin installation safety net—automatic snapshotting before installation, one-click or automatic rollback, startup safeguarding, and automatic incident report triggering for Agent analysis.

It does not statically audit plugin source code nor “sandbox-test” plugins separately; instead, through file snapshots and real startup health checks, it ensures that every change is reversible, startup failures can be automatically recovered, and incidents are traceable with evidence.

Workflow¶

Below is the complete chain of guard after a plugin installation:

Install plugin (any method)
   │  tools.guard hook: automatic in-process snapshot before installation
   ▼
Startup safeguarding (boot-guard script)
   │  Pre-startup snapshot → Start dsh web → Health check
   ├─ Healthy ─────────────────────────────► Proceed normally
   └─ Unhealthy ─► Automatically roll back to the last good snapshot → Retry once
                   → Write incident report + set pending marker
                   → Next session prompts Agent to analyze
                   → After fix, call incident_resolved to clear marker

How Problems Are Detected¶

Understanding the detection boundaries is key to determining what guard can and cannot prevent.

1. Snapshots are pure file copies. The snapshot copies only 5 configuration files: package.json, pnpm-lock.yaml, pnpm-workspace.yaml, cordis.yml, cordis.patch.yml. It does not run plugins or evaluate behavior.

2. Startup-level detection runs the harness fully. The boot-guard script starts the complete dsh web process (loading all installed plugins, including the newly installed one) and performs a health check on the HTTP / endpoint within a timeout. If the plugin causes loading errors, startup crashes, or unresponsive service, the check fails, and guard kills the process tree, automatically rolls back to the last good snapshot, and retries once.

Since v0.3.1, the check also confirms whether the Web client actually renders—some plugins may crash the page but still return HTTP 200; in such cases, the client reports a rendering crash, and boot-guard rolls back instead of misdiagnosing it as healthy. The incident report also records the dsh version for each snapshot and flags issues when harness upgrades cause plugin incompatibility or profile rollback cannot resolve them.

Since v0.3.2, if rollback plus retry still fails (e.g., due to DSH upgrade causing plugin incompatibility), boot-guard locates the problematic plugin from the startup log and quarantines it (appending disabled: true to cordis.patch.yml), starts without loading that plugin, and reports the quarantined plugin along with recovery steps (dsh-guard quarantine --undo <id>).

3. Pure runtime issues are not detected at installation time. Plugins may install and start normally but only crash or corrupt state under specific operations; guard cannot predict these during installation. For such cases, you can manually invoke dsh_rollback action=incident to generate a diagnostic report (recent startup logs, server stderr, config diff from the last good snapshot) and set a pending marker; since snapshots exist before each change, manual rollback is also always available.

Core Features¶

Automatic Pre-Installation Snapshot¶

Via the tools.guard hook, it automatically takes a snapshot in-process before plugin installation. If manually running dsh plugin add in the terminal, you can use the dsh-guard CLI to first execute dsh-guard snapshot.

Startup Safeguarding and Automatic Rollback¶

Recommended to start via scripts/boot-guard.sh (macOS/Linux) or scripts/boot-guard.ps1 (Windows) instead of directly running dsh web. Automatically rolls back and retries on startup failure; if still failing, quarantines the problematic plugin.

Web UI Backup Management¶

Under Settings → Backup Management: view snapshot lists by environment, load specific backups, manually create snapshots, and set the number of snapshots retained per environment (minimum 2). Since v0.3.0, a settings card is also registered under Settings → Plugins → Plugin Configuration, editable via the harness settings service, keeping the same retention count in sync with the backup management panel and CLI through config.json.

Agent Tools¶

Registered in each profile session:

CLI (dsh-guard)¶

Usable even when the application cannot start:

snapshot  [--profile X] [--tag T] [--reason R] [--force]
list      [--profile X]
rollback  [--profile X] [--id I | --good] [--skip-install]
keep      [N]                     # View or set per-profile retention cap (minimum 2)
health    [--port N]
incident  [--kind K] [--no-marker]
resolve
profiles

One-Click Rollback on Windows¶

The package includes scripts/rollback.cmd, located after installation at $DSH_HOME/profiles/<profile>/node_modules/dsh-plugin-guard/scripts/rollback.cmd. You can create a shortcut; double-clicking restores all profiles to their last good snapshot and runs pnpm install --frozen-lockfile. It works even when the application cannot start and will infer DSH_HOME if the environment variable is unset.

Installation and Enablement¶

Current version 0.3.2, requires Node.js >= 18, licensed under MIT. Installation commands from the README:

# Install from GitHub source
dsh plugin --profile web add github:lxzy-7/dsh-plugin-guard

# Install from tarball in the repo
dsh plugin --profile web add https://raw.githubusercontent.com/lxzy-7/dsh-plugin-guard/main/dist/dsh-plugin-guard-0.3.2.tgz

After installation, restart dsh web. This is a standard bundle plugin that takes effect once added to the profile layer stack. (After publication, it can also be installed from npm via dsh plugin --profile web add dsh-plugin-guard.)

Enable Startup Safeguarding (strongly recommended): Replace direct dsh web execution with the boot-guard script. Windows launcher example:

@echo off
set DSH_HOME=%~dp0.dsh-home
cd /d %~dp0
powershell -NoProfile -ExecutionPolicy Bypass -File node_modules\dsh-plugin-guard\scripts\boot-guard.ps1

Optional CLI Shim: Add the package’s dsh-guard (scripts/guard-cli.js) to PATH, run dsh-guard snapshot before dsh plugin add in the terminal, or wrap your own dsh commands with it to override manual installations that bypass the tools.guard hook.

Configuration and Storage Paths¶

$DSH_HOME/guard/config.json (auto-created on first write, all fields optional):

{
  "keepSnapshots": 10,
  "port": 3080
}

• keepSnapshots: Number of snapshots retained per profile, range 2–100, default 10; older snapshots are pruned when exceeded.
• port: Web port for health checks and incident reports, default 3080; modify accordingly if dsh web uses a different port; CLI can also pass --port.

All paths are rooted at $DSH_HOME (defaults to ~/.dsh if the environment variable is unset):

$DSH_HOME/rollbacks/<profile>/<stamp>/    Snapshot (5 config files + manifest.json)
$DSH_HOME/guard/logs/                     Startup/service logs, incident reports, last-boot.txt
$DSH_HOME/guard/pending-incident.json     Pending incident marker
$DSH_HOME/guard/config.json               Guard settings

Rollback Semantics¶

Rollback = restoring 4 config files + pnpm install --frozen-lockfile to precisely reproduce node_modules. Rollback also removes residual bundle plugin symlinks in node_modules (pnpm does not automatically clean up invalid link: entries).

Use Cases and Caveats¶

Who it’s for: DSH users who frequently try community plugins, stack multiple bundles in profiles, or need unattended installation rollback. Especially suitable for those who use dsh web as their daily development entry point and dislike manual troubleshooting when configurations are corrupted.

Note:

• Guard runs with the permissions of the current dsh process; always inspect source code and licenses before installing any plugin (this plugin is MIT-licensed).
• It guarantees reversibility of changes and recovery from startup failures, but cannot replace business-level auditing of plugin behavior.
• Pure runtime faults require actively triggering incident or relying on manual rollback; do not assume “safe forever if installed without errors.”
• Health checks fully start the harness and all installed plugins; if the environment is sensitive to startup side effects, verify in a test profile first.

Links¶

• SkillHub Directory Page: https://www.skillhub.cn/plugins/lxzy-7/dsh-plugin-guard
• GitHub Repository: https://github.com/lxzy-7/dsh-plugin-guard

SkillHub is a community directory for skills targeting Chinese users, with no official affiliation to DeepSeek / High-Flyer. The DSH ecosystem follows the “everything is a plugin” philosophy; guard adds a safety net to the plugin installation process within this ecosystem.