dsh-plugin-debugging

dsh-plugin-debugging

Let your DSH agent inspect and fix its own runtime

让 DSH agent 自检自修它身处的运行时

Per-version changes → Releases

English · 简体中文

---

You changed a plugin and it didn't take effect? In DSH, that usually means one of three things:

• Plugin config: re-read on every change, so edits apply immediately. This presumes hmr is mounted in profile; without hmr, every change degrades to restart-required.
• Plugin host code: a process loads code once at startup, so edits need a restart.
• Plugin front-end assets: the browser swaps assets by fingerprint, so edits need a hot reload or refresh.

This plugin lets the agent decide which case you're in, and what to do next.

What it does

After installation, the agent gains a set of tools and a skill document. The skill loads on demand; you invoke it with a slash command.

Tools

Read-only — they change nothing on the host.

| Tool | Arguments | What it does | Web | Desktop |

|---|---|---|---|---|

| dsh_list_instances | port | List the DSH hosts running on this machine. A port counts as DSH only when an unauthenticated GET / returns the exact DSH body. "Could not probe" and "not DSH" are reported separately. | ✓ | ✓ |

| dsh_check_auth | host, port | Tell "not running" apart from "not authenticated". | ✓ | ✓ |

| dsh_diagnose_plugin_load | package, port, dshHome | Check whether a plugin actually loaded: bundle membership, mount form, loader tree, with observed evidence kept separate from inferred evidence. | ✓ | ✓ |

| dsh_check_effect_mode | change: config / bundle-added / host-code / client-code, alreadyInDependencies, dshHome | Tell whether a change takes effect live, needs a restart, or needs a hot reload. It probes the running profile instead of guessing. | ✓ | ✗ |

| dsh_dump_config | profile, dshHome | Show what a profile resolved to: the composed tree, plus the diagnostics that explain it. | ✓ | ✗ |

| dsh_sign_cookie | host, port, maxAgeDays, dshHome | Sign a browser-session cookie into a file, so a script or browser automation can reach your own DSH instance. | ✓ | ✓ |

Changes state — the first two swap code or end the host you are debugging.

| Tool | Arguments | What it does | Web | Desktop |

|---|---|---|---|---|

| dsh_hot_reload | exactly one of entryId / module / serverName, plus dryRun | Swap a mounted entry to the latest code on disk without restarting. Rolled back on failure. | ✓ | ✓ |

| dsh_restart | reason, delayMs, dryRun, force | Restart this host when a change truly requires it. Off by default. | ✓ | ✗ |

Rows follow the order you would use them, so the two tables split on a single line: whether they change anything. The last column is availability by carrier; reasons live under [Platform support](#platform-support).

Three common traps:

• A 401 from dsh_check_auth does not mean the session expired. A request carrying no cookie always gets 401, so an auth probe's 401 only proves the service is running and wants authentication. To tell "the session is still valid" apart from "the authority is wrong", you must open that host:port in a browser. An old cookie keeps working after a restart on the same port; only a changed port produces 401.
• dsh_hot_reload may leak. Resources the framework does not track — a timer or socket, for example — leak silently after a swap.
• dsh_restart has its own section below.

The skill document behind it

The skill document lives at [skills/dsh-plugin-debugging/SKILL.md](skills/dsh-plugin-debugging/SKILL.md) and carries the full reasoning behind install forms, credential acquisition, process identification, and isolated instances.

The tools are accelerators; if a tool's output conflicts with the skill document, the skill document wins.

Install

Install from the Plugins page:

Open the Plugins page, click Add plugin in the upper-right corner, enter dsh-plugin-debugging, and install.

Install from npm:

dsh plugin --profile web add dsh-plugin-debugging

Install from source:

git clone https://github.com/dsh-plugin-lab/dsh-plugin-debugging.git
cd dsh-plugin-debugging
pnpm install && pnpm run build
dsh plugin --profile web add "$PWD"

Notes:

• Do not skip pnpm install: with a link: install, dependencies come from the repository itself; skipping it makes the plugin show up as not running and report ERR_MODULE_NOT_FOUND.
• Restart to take effect: restart dsh --profile web after installing.
• link: and dsh.bundle are two separate things: link: only decides whether editing source needs a reinstall; whether the patch layer applies depends on whether the package declares dsh.bundle.

Requirements:

Node >= 20, and a DSH version that satisfies the range in [package.json](package.json).

Maintenance rules:

The profile's dependency and bundle list are managed by dsh plugin add; do not edit them by hand. Do not create packages under $DSH_HOME, and do not run a package manager inside a profile directory.

Safety and boundaries

Except for dsh_restart, these tools never restart a process, never rewrite a profile, and never write to host data. Tests enforce this rule: as soon as any write targets a host-data path (profiles / sessions / storages / logs / cache / attachments / backups / integrations / mcp / settings.yaml / .credentials.yaml …), or uses DSH_HOME itself as the target, pnpm run test fails.

The only write exception is this plugin's own namespace, $DSH_HOME//: only the first directory directly under $DSH_HOME must exactly match the package name; anything below that is unrestricted.

What each one touches:

• Read-only, no requests: dsh_check_effect_mode, `dsh_diagnose