PerryLink/dsh-plugin-guide

🐳 dsh-plugin-guide

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

Everything you need to build DeepSeek Harness plugins.

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

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 插件家族的一员（40+ 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

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

Compatibility

Surface	Status
Harness	DeepSeek Harness dsh-v0.1.7-rc.2 (re-synced 2026-09-24, ddefc45): the official-docs snapshot is refreshed to rc.1, the checker now expects the four-clause peer range (`…
Node	`^22.19.0
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(), model-visible ⟺ logged, Schemastery config.
• Official docs archive — a verbatim copy of the official repo docs (EN + ZH), byte-identical to upstream at the last verified snapshot.
• Cordis primer — the five concepts and the mechanism timeline (repository-plugin introduced 0809, removed 0811; the two install channels).
• 20+ real-world pitfalls with root cause + fix (cordis dual copies, tsconfig trio, multi-frame zstd sessions, Windows junctions, stale npm latest, …).
• 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, 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	The installable DSH bundle: dsh.bundle.patch manifest + entry point that registers the skill
guide/plugin-dev-guide.md	The complete development guide (10 chapters)
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
references/official-docs/	Verbatim copy of the official repo docs (EN + ZH)
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, 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>]

Subcommand	What it does
new <name>	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	<package>/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
dsh plugin --profile web add "github:PerryLink/dsh-plugin-guide#main"

# or from npm (published releases)
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'

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

Install & uninstall

• git channel (latest main): dsh plugin --profile web add github:PerryLink/dsh-plugin-guide#<sha> — pin a commit for reproducibility; the entry point is plain ESM JS, no build step.
• npm channel (published releases): dsh plugin --profile web add dsh-plugin-guide.
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./dsh-plugin-guide-<version>.tgz.
• uninstall: dsh plugin --profile web remove dsh-plugin-guide.

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.

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.

Keeping it fresh

pwsh -File scripts/sync-official-docs.ps1                     # verbatim docs copy from a local checkout
pwsh -File scripts/download-sources.ps1                       # official site/docs, Cordis, paper
pwsh -File scripts/download-community-repos.ps1               # community repositories (codeload tarballs)
pwsh -File scripts/download-community-articles.ps1            # zh/en/HN community articles
pwsh -File scripts/archive-discussions.ps1                    # official Discussions (needs $env:GH_TOKEN)
pwsh -File scripts/gen-topic-snapshot.ps1 -OutDir <dir>       # dsh-plugin topic census
pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>        # critical paths + link scan + docs drift

Development

The skill bundle (index.js) is plain ESM with no build step; the dsh-plugin-dev CLI is TypeScript built by tsdown. Gates:

pnpm install --frozen-lockfile
pnpm run typecheck && pnpm run typecheck:ci
pnpm test
pnpm run build
pnpm run verify:artifacts        # dogfood self-check + scaffold smoke (no network)
pnpm run verify:self-contained   # pack + clean-profile install/start/uninstall smoke
pnpm pack
pwsh -File scripts/verify-kit.ps1   # critical paths + link scan (+ docs drift with -Checkout <checkout>)

Topics

dsh, deepseek-harness, dsh-plugin, cordis, agent-skill, plugin-development, knowledge-base, cli, scaffold, checker

Contributors

• PerryLink — creator and maintainer: knowledge-base content, the installable-bundle transformation, ecosystem submissions, and community engineering.
• Day-to-day maintenance is assisted by DeepSeek Harness agents (they hold no GitHub account and are listed here for transparency, not as contributors).

PerryLink DSH Plugin Family

This project is one of the 45 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

Plugin	One-liner
dsh-auto-review	Second-model auto-review on the approval chain, fail-closed by default
dsh-autotier	Automatic strong/cheap model-tier routing with deterministic risk guards and a /tier command
dsh-background-agents	Durable background child agents with a Web UI sidebar, messaging and interrupt
dsh-budget	Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel.
dsh-catalog	DSH Desktop Market standard catalog source for the PerryLink family
dsh-cert-mcp	Read-only MCP server exposing the certification registry: grades, snapshots and five-dimension evidence
dsh-checkpoint-rewind	Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore
dsh-claude-move	Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH
dsh-click	Cross-platform native desktop control for DeepSeek Harness — Windows first.
dsh-composer-history	Terminal-style input history for the web composer: arrows, Ctrl+R search
dsh-data-quality	Dataset quality checks and citation cross-checks (the optional numeric bridge consumed here)
dsh-defend	Prompt-injection, jailbreak, and secret-leak defense for DeepSeek Harness.
dsh-doublecheck	Engineering-discipline guard: requirements grill, test gates, adversary review
dsh-draw	Unified static-image generation routing for DeepSeek Harness.
dsh-fast	Read-only performance diagnostics for DeepSeek Harness.
dsh-fund-research	Deterministic research reports for Chinese public mutual funds
dsh-github	GitHub PR/issues integration for DSH, every write gated by approval
dsh-industry-research	Industry research orchestration that seals its deliverables through this plugin's ctx.researchReport.assemble
dsh-laya	Laya typed decisions (noul/choice/score) as a first-class Cordis service and model-visible tools
dsh-library	Local document knowledge base for DeepSeek Harness.
dsh-local-ai	Local-model (Ollama) integration for DeepSeek Harness.
dsh-lsp-actions	LSP diagnostics, formatting, completion, code actions and rename over language servers
dsh-mask	PII masking middleware: anonymize at the model boundary, restore at the display layer
dsh-mcp-panel	Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors
dsh-memento	Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool
dsh-observe	OpenTelemetry and Langfuse observability exporter for DeepSeek Harness.
dsh-output-styles	Claude Code outputStyles-equivalent runtime style switching
dsh-permission-rules	Claude Code-style declarative allow/deny/ask permission rules with audit
dsh-plugin-certification	Community certification registry with repro-checkable grades and badges
dsh-plugin-doctor	Zero-dependency static + sandbox smoke detector for DSH plugins
dsh-plugin-guide	Plugin-development knowledge base as an on-demand agent skill
dsh-plugin-kit	Shared zero-runtime-dependency toolkit for the PerryLink DSH plugins
dsh-plugin-upgrade	One-package, one-corridor-index plugin upgrade skill: routes a repository to the matching closed corridor card
dsh-plugin-upgrade-015	Merged 0.1.3-alpha.1 → 0.1.5-rc.1 upgrade corridor card plus a zero-dependency seam scanner
dsh-reach	Multi-channel approval/question bridge: WeChat/Telegram/Feishu, session console
dsh-research-report	Verifiable research-report engine: content-addressed evidence ledger and sealed versions
dsh-score	Multi-dimensional quality scoring for DeepSeek Harness plugins.
dsh-session-pin	Pin sessions in the Web sidebar with durable ordering
dsh-session-sync	Cross-device session sync for DeepSeek Harness — a dedicated git mirror of your session store.
dsh-skill-pack-security	Security-audit skill pack: secret scan, dependency and supply-chain review
dsh-talk	Voice-first session loop for DeepSeek Harness: talk to it, hear it answer.
dsh-team-rooms	Cross-session team rooms: shared message bus, task board and timeline
dsh-test-drive	Isolated install-and-smoke test drives for DeepSeek Harness plugins.
dsh-ticktick	TickTick/Dida365 task bridge: session-header panel + 11 tools
dsh-translate	Vendor parameter translation and deterministic JSON repair for DeepSeek Harness.

Disclaimer

Community-maintained, not an official DeepSeek product. DeepSeek Harness is in developer preview and ships breaking changes; when in doubt, the official docs in references/official-docs/ are the source of truth.

Install from the DSH Desktop Market

All PerryLink plugins are browsable in the built-in DSH Desktop Market: Market → Sources → add source → paste https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → select it. Installation still goes through the Market's npm-identity verification and your confirmation.

License

Apache License 2.0 © 2026 dsh-plugin-guide contributors — our own text (SKILL.md, guide/, references/, scripts/, this README) is Apache-2.0; bundled third-party content is documented in NOTICE.md.