dsh-plugin-debugging

<p align="center">

<img src="icon.svg" alt="dsh-plugin-debugging" width="80" height="80">

</p>

<h1 align="center">dsh-plugin-debugging</h1>

<p align="center">

<img src="assets/banner.gif" alt="dsh-plugin-debugging: letting a DSH agent inspect and fix its own runtime" width="600">

</p>

<div align="center">

<p><strong>Let your DSH agent inspect and fix its own runtime</strong></p>

<p><em>让 DSH agent 自检自修它身处的运行时</em></p>

<p>

<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by_dsh-4D6BFE?style=flat&logo=deepseek&logoColor=white" alt="powered by dsh"></a>

</p>

<p>

<a href="https://github.com/dsh-plugin-lab/dsh-plugin-debugging/actions/workflows/ci.yml"><img src="https://github.com/dsh-plugin-lab/dsh-plugin-debugging/actions/workflows/ci.yml/badge.svg" alt="CI"></a>

<a href="https://www.npmjs.com/package/dsh-plugin-debugging"><img src="https://img.shields.io/npm/v/dsh-plugin-debugging.svg?style=flat" alt="npm"></a>

<a href="https://www.npmjs.com/package/dsh-plugin-debugging"><img src="https://img.shields.io/badge/SLSA-Build%20L2-green?logo=slsa&style=flat" alt="SLSA Build L2"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat" alt="MIT License"></a>

<!-- Whether the SLSA badge can be shown is governed by [docs/PUBLISHING.md](docs/PUBLISHING.md) (check the attestations endpoint for a specific version; do not claim it from memory). -->

</p>

<p>

Per-version changes → <a href="https://github.com/dsh-plugin-lab/dsh-plugin-debugging/releases">Releases</a>

</p>

<p>

<strong><a href="README.md">English</a></strong> · <a href="README_zh.md">简体中文</a>

</p>

</div>

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

• 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.
• Host code: a process loads code once at startup, so edits need a restart.
• 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.

<p align="center">

<img src="assets/invoke-skill.png" alt="Invoking the skill with a slash command" width="600">

</p>

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 so a script or CLI client 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 --pro

…(truncated)