PerryLink/dsh-plugin-guide

🐳 dsh-plugin-guide

Your agent stops inventing DSH plugin APIs.

The DeepSeek Harness plugin-development knowledge base, installed *as an agent skill* — official docs, a version-compatibility matrix, migration seams and battle-tested pitfalls, plus a scaffolder/checker CLI.

dsh plugin --profile web add dsh-plugin-guide

Then just ask: *"Use the dsh-plugin-guide skill to build me a … plugin."*

Official repository. This is the only official repository of dsh-plugin-guide, maintained by PerryLink. Same-name repositories under other accounts are not affiliated.

English · 简体中文 · Español · Português · हिन्दी

dsh plugin --profile <name> add dsh-plugin-guide

Install & uninstall

• npm channel (published releases — the default; start here): dsh plugin --profile web add dsh-plugin-guide. The published tarball already contains dist/, so no build step runs.
• git channel (latest main, or an unreleased commit): dsh plugin --profile web add github:PerryLink/dsh-plugin-guide# — pin a commit for reproducibility. ⚠️ dist/ is not committed, so pnpm must run this package's prepare and will refuse until the build is allowlisted; add it to the profile's allowBuilds (see publish.md).
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./dsh-plugin-guide-.tgz.
• uninstall: dsh plugin --profile web remove dsh-plugin-guide.

Why not just read the official docs?

Because the official docs are written for someone who already knows which page to open, and DSH ships a prerelease every 1.7–2.8 days with breaking changes. This plugin closes the three gaps that costs authors the most time:

Gap · What this plugin adds "Which DSH am I even targeting?" · A version matrix: the four different values that all call themselves "latest", the frozen sub-package latest tags, the breaking-change seams, and how to pick a peerDependencies range. There is no stable line — every published version is a prerelease. "What does this break?" · A migration guide covering 0.1.6-alpha.2 → 0.2.1-alpha.2 as citable seams with symptom *and* fix, each with its official source — including a data-loss hazard and a change that makes prompts fail before a model request is built. "Is my plugin actually correct?" · A zero-dependency CLI (dsh-plugin-dev new / check / verify) plus an offline verbatim mirror of the official docs, so your agent can cite the exact page instead of guessing.

Prove it works in 60 seconds:

dsh plugin --profile web add dsh-plugin-guide
npx dsh-plugin-guide new hello-plugin      # scaffold a plugin
cd hello-plugin && npx dsh-plugin-guide check --json   # 16 static checks

📖 Prefer reading it as a site? perrylink.github.io/dsh-plugin-guide — every chapter as its own page, plus a machine-readable llms.txt for assistants.

Also on the 1024 store channel: npm i -g dsh1024, then dsh1024 plugin --profile web add dsh-plugin-guide (counts toward the deepseek1024.com install ranking).

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

*English:* part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

What is dsh-plugin-guide?

Everything you need to build DeepSeek Harness plugins.

Official docs archive · Cordis primer · community deep-dives · battle-tested pitfalls · agent skill · CLI toolchain

*Workflow overview: request → policy / review → verdict. The examples below use the real command surface.*

Comparison

content counts as stated in the README (What you get)

Compatibility

Surface · Status Harness · DeepSeek Harness dsh-v0.2.1-alpha.2 (d743267388641bc76f17c45ce8b4c231aed1d32c, the newest master tag and master HEAD, 2026-10-09); npm latest = next = 0.2.0-rc.2, alpha = 0.2.1-alpha.2. There is no stable line — all 31 npm versions and all 26 GitHub Releases are prereleases. The official-docs mirror is pinned to that same commit (429 md pages, re-synced 2026-10-13; see references/official-docs/SNAPSHOT.md). guide/migration-0.2.md covers 0.1.6-alpha.2 → 0.2.1-alpha.1 in §0–§12 and 0.2.1-alpha.1 → 0.2.1-alpha.2 as 19 citable seams in §13; the 20 breaking-change guides added since the previous baseline (19 under v0.2.1-alpha.1 plus one backfilled into v0.2.0-rc.2) are all in the mirror. Node · ^22.19.0 · >=24.0.0 (DeepSeek Harness runtime) Platforms · All (plain ESM bundle; no native code, no network) Model · Any (no model interaction)

What you get

dsh-plugin-guide is the DSH plugin-development knowledge base plus a CLI toolchain, packaged as one installable bundle. The knowledge base registers as the dsh-plugin-guide agent skill (visible in every session catalog, loading workflow steps, official docs, and community deep-dives on demand); the dsh-plugin-dev CLI adds three mechanical layers on top of it.

• Plugin contract & hard rules — effects/disposers, waterfall next(), host-owned session events, MessageSourceMap, the weakest-mechanism ordering, Schemastery config, UI and performance rules.
• Official docs archive — a verbatim copy of the official repo docs (EN + ZH), byte-identical to upstream at the last verified snapshot, including the pages that never reach the documentation site.
• Version adaptivity — guide/version-matrix.md: the five different "latest" values, the frozen sub-package latest tags, the four breaking-change seams, the canonical peer range and how to pick one, the session-format lineage V0→V4, and the 19 breaking changes that landed in 0.2.1-alpha.2.
• Migration guide — guide/migration-0.2.md: every breaking change from 0.1.6-alpha.2 to 0.2.1-alpha.1 (session format V4, the settings rebuild, invariant removal, readBytes, new slots, retired plugin message source), each with its official source and a 12-item checklist.
• Official in-repo skill, distilled — references/official-plugin-dev-skill.md: the harness's own cordis-plugin-development workflow, prohibitions, display-metadata checklist, practices, and UI/performance rules.
• Cordis primer — the five concepts and the mechanism timeline (repository-plugin introduced 0809, removed 0811; the two install channels).
• Verified issue index — guide/unfixed-issues.md: 22 unfixed + 11 newly verified items with path:line, workarounds, fixing commits, design-vs-bug table, and an explicit "unreproducible" section.
• 30+ real-world pitfalls with root cause + fix (cordis dual copies, tsconfig trio, multi-frame zstd sessions, Windows junctions, stale npm latest, file: installs loading a copy, live patch writes, …).
• Community deep-dives — 114 community repositories archived (15 deep-dived), plus a full source index where every fact links to its origin.
• CLI toolchain — dsh-plugin-dev new / check / verify: scaffold, static-check (including display metadata and multi-patch manifests), and pack-verify DSH plugins; every check links back to the skill section it enforces.

Knowledge base

Path · What it is SKILL.md · The dsh-plugin-guide agent skill: hard rules + task-based development paths package.json · cordis.patch.yml · index.js · locale/ · icon.svg · The installable DSH bundle: dsh.bundle.patch manifest, entry point that registers the skill, and the display metadata Plugin Manager reads guide/plugin-dev-guide.md · The complete development guide (10 chapters) guide/version-matrix.md · Version adaptivity matrix: the five "latest" values, frozen sub-package latest tags, breaking-change seams, peer-range selection, session-format lineage, and the 19 changes in 0.2.1-alpha.2 guide/migration-0.2.md · Breaking-change migration guide for the 0.2 generation guide/unfixed-issues.md · Source-verified bug index + fixed-on-master list + design-vs-bug table guide/quick-reference.md · One-page cheat sheet (5 languages) guide/links.md · Curated URL index: official dev docs (site ↔ local copies) + community doc links + repo-only pages guide/when-to-retire-a-plugin.md · Retiring and freezing plugins: the criteria and the measured data behind a portfolio audit (EN + ZH) guide/choosing-a-plugin.md · Choosing a plugin: who leads each capability surface, with the measured numbers and the verification caveats (EN + ZH) references/official-docs/ · Verbatim copy of the official repo docs (EN + ZH) references/official-plugin-dev-skill.md · Distilled official in-repo plugin-development skill references/*.md · Research reports: repo docs, website, Cordis, the paper, community ecosystem, 114-repo archive (15 deep-dived) scripts/ · Idempotent download scripts + integrity checker + topic snapshot generator bin/ · src/cli/ · dist/ · The dsh-plugin-dev CLI: scaffolder, checker, verifier (TypeScript, tsdown-bundled) templates/ · TS + JS scaffold skeletons: contract template, Config, tests, cordis.patch.yml, locale metadata, icon, five-language READMEs downloads/ · Raw snapshots — generated by scripts/, not committed

CLI toolchain

The bundle ships the zero-runtime-dependency dsh-plugin-dev CLI (bin/ → tsdown-bundled dist/dsh-plugin-dev.js). Each check cites the skill section it enforces, so an agent can keep auditing manually.

dsh-plugin-dev new <name> [--lang ts|js] [--dir <path>] [--force] [--git]
dsh-plugin-dev check [--cwd <dir>] [--json] [--strict]
dsh-plugin-dev verify [--cwd <dir>] [--dsh <bin>] [--pnpm <bin>]
dsh-plugin-dev seams <query> | --since <version>   # is this API in my target host?

Subcommand · What it does new · Scaffolds a TS or JS plugin repo: src/index.ts contract template, Schemastery Config, tests, tsdown/vitest, commented cordis.patch.yml, five-language READMEs. Idempotent; refuses non-empty targets without --force. check · Static checks: cordis.patch.yml validity, package.json metadata (dsh.bundle.patch pointer, peer deps, engines, files whitelist), five-language README consistency, engineering red-line patterns. Emits CI-consumable JSON. verify · pnpm pack, then install/start/uninstall the bundle in a clean mkdtemp DSH_HOME profile (aligned with verify:self-contained). Failures report the log tail plus suggestions.

CLI configuration

The CLI has no hardcoded tunables — each is a flag or an environment variable.

Tunable · Flag · Env · Default Templates directory · — · DSH_PLUGIN_DEV_TEMPLATES · /templates dsh binary · --dsh · DSH_PLUGIN_DEV_DSH · dsh pnpm binary · --pnpm · DSH_PLUGIN_DEV_PNPM · pnpm Install/pack timeout · --timeout · DSH_PLUGIN_DEV_TIMEOUT · 300000 ms Headless smoke timeout · --smoke-timeout · DSH_PLUGIN_DEV_SMOKE_TIMEOUT · 120000 ms

Upstream roadmap

dsh-plugin-dev is an upstream candidate for the official plugin-development CLI (planned item C12): the scaffolder/checker/verifier are the mechanical layers, while SKILL.md + guide/ stay the cognitive layer.

Quick start

# 1. install the bundle into your profile — npm first
dsh plugin --profile web add dsh-plugin-guide

# 2. restart and verify the row
dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-guide'

⚠️ Use the npm channel, not the git channel, for a first install. The git channel pulls source, and dist/ is not committed, so pnpm has to run this package's prepare build script — which pnpm 10+ blocks until you explicitly allowlist it (allowBuilds). That is a documented pitfall of git installs, not a defect, but it makes the git channel a poor first experience. See Install & uninstall for the git and tarball channels when you specifically want an unreleased commit.

Then just ask your agent: *"Use the dsh-plugin-guide skill to build me a … plugin."*

Or drive the CLI directly:

npx dsh-plugin-guide new hello-plugin            # scaffold a TS plugin repo
npx dsh-plugin-guide check --json                # static-check it
npx dsh-plugin-guide verify                      # pack + clean-profile smoke

Copy as a plain agent skill

You can also copy the whole folder into your agent's skill directory (relative paths stay intact):

# Windows (PowerShell)
pwsh -File scripts/install-skill.ps1 `
  -Target "$env:USERPROFILE\.deepseek\skills\dsh-plugin-guide"   # or <project>\.agents\skills\dsh-plugin-guide

# macOS / Linux
pwsh -File scripts/install-skill.ps1 -Target ~/.deepseek/skills/dsh-plugin-guide   # or <project>/.agents/skills/dsh-plugin-guide

The installer skips downloads/ (generated) and .github/, then verifies every copied file byte-for-byte. A manual Copy-Item -Recurse of the whole folder also works.

Examples

These are the plugin's real entry points; install once, then call one.

Detailed example

Command

~~~sh dsh-plugin-dev seams L3 ~~~

Output

~~~text 1 seam(s):

L3 webRuntime service replaced by webStartup kind service-renamed lands in 0.2.1-alpha.2 confidence documented official docs/upgrade-guide/v0.2.1-alpha.1/web-listener-trust-config/guide.md removed service webRuntime; row web-runtime; ctx.webRuntime.lanAddresses; wildcard --host instead webStartup (row web-startup), concrete host literals detectable yes — inspect: src/**/*.ts, cordis.patch.yml ~~~

*Observed from README.md:152 (CLI toolchain); src/cli/commands/seams.ts:54; data/seams/index.json:44*

Failure branch

Input

~~~text node bin/dsh-plugin-dev.js seams no-such-seam-xyz ~~~

Output

~~~text no seam or capability matches "no-such-seam-xyz". This is an absence of evidence in the knowledge base, not evidence that the API is absent from your target host — check references/official-docs/ before concluding either way. ~~~

*Observed from plugins/dsh-plugin-guide/src/cli/lib/seams.ts:122-130; plugins/dsh-plugin-guide/src/cli/commands/seams.ts:87-92; plugins/dsh-plugin-guide/tests/seams.test.ts:88-90*

Brief examples

Configuration

The skill bundle exposes no Schemastery Config — it registers the knowledge base as an agent skill with no tunable keys. The dsh-plugin-dev CLI reads its tunables from flags and DSH_PLUGIN_DEV_* environment variables (see CLI toolchain).

Tools & surfaces

Surface · Kind · Notes dsh-plugin-guide · skill · Registered via ctx.skills; loads SKILL.md + ./guide/ + ./references/ on demand dsh-plugin-dev · bin (CLI) · new / check / verify subcommands; not a DSH plugin row

Permissions & data

• Permissions: declares filesystem:read in its workshop manifest.
• Data: read-only — reads its own bundled guide/ and references/ files. No network requests, no writes, no model calls.

Security boundaries

• Read-only knowledge base. The bundle only reads its own files; it never writes, never calls the network, and never invokes a model.
• Official docs are verbatim copies. references/official-docs/ is never edited here; report issues upstream and re-sync only with scripts/sync-official-docs.ps1.
• Distribution boundaries. Bundled third-party content keeps its upstream license; see NOTICE.md (e.g. downloads/ is local-only; awesome-dsh-plugins must not be redistributed).

Known limitations

• Official docs are a snapshot. Re-sync with scripts/sync-official-docs.ps1 when upstream moves; the freshness stamp and commit hash reference references/official-docs/SNAPSHOT.md.
• `downloads/` is generated, not committed. Raw snapshots (community repo archives, Discussions, articles) must be generated with the scripts before use.
• `awesome-dsh-plugins` content is local-only. Its upstream declares an internal-use constraint, so it is not redistributed with the repo.

Release channels