DSH plugin minimal repro: three files, one command
The worst outcome of a broken plugin: two hours of deleting code, then shipping the whole repository, and hearing "it does not run here either". A minimal repro is not politeness toward the person helping; it is the last step of your own diagnosis.
When a DSH plugin repro bundle is worth it
A DSH plugin repro bundle is worth it for environment-only bugs, public requests, and a self-inflicted mess.
Not every bug needs one. Three cases pay off most:
The bug only appears in some environments. It works on your machine and fails on a colleague's, which means the difference is environmental or configurational, not logical. A repro compresses that difference to a specific line. You need to ask in an issue or a chat. Without a repro, the thread degrades into "try this" and "still broken", and the bug survives several rounds.
You have edited yourself into a corner. Logs everywhere, half the code commented out, original state unknowable. Rebuilding a minimal directory beats excavating the ruins. Conversely, skip it when the bug reproduces reliably and five minutes of reading locates it. Paste the command and the error; that is enough.
Three files are enough for a DSH plugin repro
A runnable minimal repro usually contains exactly three files:
repro/
├── cordis.yml # one insert line pointing at the entry
├── entry.ts # the plugin, only the code that triggers
└── README.md # versions, command, expected and actual
cordis.yml stays as small as possible:
- insert:
- id: repro
name: './entry.ts'
The entry must run standalone, with no imports from private project packages. If it depends on an internal toolkit, nobody else can run it and the bundle is worthless. The readme is not optional. Three lines suffice: dsh version, reproduction command, expected versus actual. Without the expected result, the other person cannot tell whether they reproduced anything.
Five DSH plugin repro deletion passes, re-run after each
Cut one DSH plugin repro category per pass and re-run after every deletion.
Order decides efficiency:
- Remove unrelated plugin rows: keep one row, restart, and continue only if the bug survives;
- Remove unrelated config: keep only the fields involved, let the rest fall back to defaults;
- Remove code branches: keep only the triggering path; events, tools, and background jobs only if needed;
- Remove dependencies: replace internal imports with minimal implementations or inline code, so the directory runs alone;
- Confirm the boundary: delete the last remaining piece once; if the bug disappears, that piece is the trigger, and if not, keep cutting.
Delete one category per pass and re-run. Removing three categories at once means a vanished bug cannot be attributed, and you start over.
Do not fear cutting too far. When the bug disappears, add back the last removed piece. You now have the precise trigger, which is worth far more than "probably related to that plugin".
A DSH plugin repro template you can paste
A pasteable DSH plugin repro template states environment, steps, expected, actual, and ruled-out items.
Write the readme in this shape and nobody has to ask follow-ups:
## Environment
- dsh: <output of dsh --version>
- Node: <node -v>
- OS: <macOS 14 / Ubuntu 24.04>
- profile: web
## Steps
1. Unzip the repro directory
2. Run: dsh --profile web --patch ./repro/cordis.yml
3. Watch the terminal output
## Expected
The log shows [repro] loaded and the tool list contains repro_tool
## Actual
The log stops waiting for a service and the process never exits
## Ruled out
- Changing the port had no effect
- Removing other plugins had no effect
"Ruled out" is the highest-value section. It tells the reader which directions not to retry and saves half the round trips. Paste raw version output rather than a description; "latest" stops being latest within days.
Four ways to ruin a DSH plugin repro
First, importing private packages. Nobody can install the dependencies, so step one fails.
Second, screenshots instead of commands. A screenshot hides flags, ports, and profile names; one missing flag changes the result.
Third, one long script covering install, build, and start. When it fails midway, nobody knows whether it was environment or plugin.
Fourth, deleting "irrelevant" config. Some bugs are triggered by a default value; before removing a field, check whether its default differs from the current value.
Running someone else's DSH plugin repro
To run someone else's DSH plugin repro, compare versions, use a temporary DSH_HOME, and run the command as written.
When roles reverse, work in the opposite order. Three things first:
- Compare versions: run
dsh --versionagainst the stated version and note any mismatch; - Use a temporary DSH_HOME:
DSH_HOME=$(mktemp -d), so your own profiles stay clean; - Run the command exactly as written, without "improving" flags; reproduce first, then investigate.
Step 3 is the one people skip. Changing the port, upgrading, or adding logs immediately means you may not reproduce at all, and both sides conclude the other has an environment problem. If it does not reproduce, do not conclude anything yet. Compare version, Node, OS, and command line by line; the difference is usually one of them.
The goal of a minimal repro is not "make someone see an error" but "make someone see the same error". Agreement on that is what makes the discussion productive. For fixes to common failures, read common plugin errors; for combining debugging commands, read local debugging; for the four-layer self-test, read testing a plugin.
FAQ
Not recommended — a full repository carries unrelated plugins, private dependencies, and config, which makes the trigger hard to identify. A DSH plugin minimal repro needs only one patch line, one entry file, and three diagnostic commands, so it is cheaper to deliver and faster to locate.
Delete unrelated plugin rows first, then code paths not involved in the symptom. Remove one category at a time and re-run after each step; the moment removing one more thing stops the bug, you have found the minimal surface.
At least three: the output of dsh --version, the Node version, and the profile name. Without them, someone may run a different generation of behavior and the discussion is no longer about the same problem.
Prefer one pasteable DSH plugin command that includes the patch path and port. It removes differences caused by a missing flag, but do not bundle install, build, and start into one script, or a failure becomes unattributable.
Related Terms
- minimal repro
- A minimal repro is the smallest set of code and config that still triggers a bug, so another person can follow the same steps and see the same result.— DeepSeek Harness docs
- repro bundle
- A repro bundle is the minimal directory handed to someone else, usually a config file, a plugin entry, and a short readme.— DeepSeek Harness docs
- overlay
- An overlay is a patch file passed with --patch that inserts or overrides plugin rows without editing the profile.— DeepSeek Harness CLI reference
- dump-config
- dump-config is a DSH plugin CLI flag that prints the combined configuration tree without starting the service, confirming effective values after patches.— DeepSeek Harness CLI reference
Sources
- DeepSeek Harness docs: your first plugin· deepseek-harness
- DeepSeek Harness docs: plugin config· deepseek-harness
- DeepSeek Harness CLI reference· deepseek-ai