dsh-plugin-toolkit
An agent skill and a zero-dependency CLI for the same problem: getting a DeepSeek Harness (dsh) plugin installed, mounted, and actually loading — instead of dying at boot.
| Path | What it is |
|---|---|
skills/dsh-plugin-install/SKILL.md |
Agent skill: install / repair / version-fix a dsh plugin, including the desktop profile the CLI refuses to touch. |
tools/dsh-preflight/ |
dsh-preflight — static, read-only checker that answers "will this profile boot?" before you boot it. Zero deps, Node ≥ 18. |
They are complementary: the skill tells an agent what to do, the tool tells it what would break.
Why this exists
A dsh profile composes plugins through cordis.patch.yml layers. The failure mode
is asymmetric: a single bad row does not disable that one plugin — it stops the
whole harness from booting. When that happens every plugin is already down, so
no in-process plugin can diagnose it. You are left with a black window and no
error surface.
Two separate things are needed, and they are genuinely different:
- Before boot — decide statically whether the composed patch set can load:
duplicate mount ids, bundles declared but not installed, patch layouts that
differ per package,
!!jsexpressions whose state cannot be decided. - During install — know that the kernel validates
@deepseek-ai/dsh-*peerDependencies with{ includePrerelease: true }, so>=0.1.7-rc.1passes against0.2.0-rc.1while^0.1.7-alpha.1fails; and know that thedesktopprofile is rejected by name (rejectElectronProfile) with no override flag, so the only path is editingpackage.json(dependenciesanddsh.profile.bundles) plus a profile-levelcompatibility.jsonexemption.
Both halves are documented in the skill and encoded in the tool.
Quick start
# 1. check a profile before booting it
node tools/dsh-preflight/bin/preflight.mjs --profile desktop --verbose
# 2. ask the harder question: will THIS patch break the stack I already have?
node tools/dsh-preflight/bin/preflight.mjs --profile desktop \
--candidate-peer ./new-plugin/cordis.patch.yml
Exit codes: 0 clean · 1 findings · 2 usage/IO error. --json for machines,
DSH_PREFLIGHT_ASCII=1 for terminals without box-drawing glyphs.
cd tools/dsh-preflight && npm test # 14 parser cases + 22 end-to-end cases
Installing the skill
The skill is a plain SKILL.md with YAML front matter — drop the directory into
whatever skills root your agent reads:
cp -r skills/dsh-plugin-install ~/.dsh/skills/
# or any other skills directory your harness scans
It has no runtime dependency on the CLI in tools/; the two are independently
useful.
What the checker actually parses
Real cordis.patch.yml files are not plain YAML, and the parser was written
against shapes taken from installed packages rather than from a spec:
disabled: !!js "[...ctx.loader.entries()].some(...)"— quoted expression; state is unknowable, so the row is treated as opaque and never as enableddisabled: !!js >-followed by an indented multi-line arrow functionconfig:holding a nested list of- id:/name:entries — those are components of that row, not additional mounts- id-targeted override rows: a second top-level
- id: vision-router/disabled: falseis an overlay, not a second mount - use: <pkg>provider lists- subpath mounts (
name: billion-context/dsh) resolved throughexports - manifest-driven patch filenames:
billion-contextshipsdsh.bundle.patch.yml,@furongjun1999/dsh-memoryshipsdsh/cordis.patch.yml
Rules and their severities are listed in
tools/dsh-preflight/README.md. The
design principle there is deliberate: a checker that cries wolf is worse than
one that stays quiet, so anything that cannot be proven statically is a note,
never an error.
Scope and honest limits
- Static only. It cannot see a conflict that appears only at runtime.
- Structure, not behaviour. No version-range checking inside the checker; that
is the skill's job (
semver.satisfies(..., {includePrerelease:true})). - Bound to a moving kernel. Everything here was verified against dsh kernel
0.1.7-rc.1/0.2.0-rc.1(October 2026). The kernel is evolving fast — if a claim contradicts what you observe, trust the installed source. Both the skill and this README say so where it matters.
License
MIT
No comments yet. Be the first to write one.