🗺️ Every fact links to its origin — official docs, upstream repos, or community repos. When in doubt, the verbatim official copy wins.

⏱️ Last verified 2026-08-15 — official docs byte-identical to upstream master (47f9438, see SNAPSHOT.md); npm tags and the dsh-plugin topic (API total_count climbed 2668 → 2671 during the 08-15 snapshot, ~1000 repos captured, see sources.md §D.2) re-checked live. Upstream HEAD unchanged (47f9438), npm @deepseek-ai/dsh unchanged (0.1.0-rc.6).

📊 At a glance

Official docs	Community deep-dives	Battle-tested pitfalls	dsh-plugin topic	Languages	Agent skill
215 pages (EN + ZH)	114 repos	20+	998 snapshot (API ≈2670)	EN · 中文 · ES · PT · HI	dsh-plugin-guide

🚀 Quick start

🧩 Install as a DSH plugin (recommended)

This repository is an installable DSH bundle: it registers the whole knowledge base as the dsh-plugin-guide agent skill. The skill stays visible in every session catalog and loads its workflow steps, official docs, and community deep-dives on demand (./guide/, ./references/) — no copying, no searching.

# from a git checkout (sources; pin a commit for reproducibility):
dsh plugin --profile <profile> add github:PerryLink/dsh-plugin-guide#<sha>

# or a packed tarball (no build step needed — the entry point is plain ESM JS):
pnpm pack
dsh plugin --profile <profile> add ./dsh-plugin-guide-<version>.tgz

The bundle declares dsh.bundle.patch and pins the harness train via an optional peer dependency on @deepseek-ai/dsh@0.1.0-rc.6. Verify the layer landed with dsh --profile <profile> --dump-config (look for the dsh-plugin-guide layer).

🤖 Or copy it as a plain agent skill

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.

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

📖 Or just read

You want…	Read
The one-page cheat sheet	guide/quick-reference.md
The full 10-chapter path	guide/plugin-dev-guide.md
Official & community doc links	guide/links.md · references/community-ecosystem.md
Exact service/event APIs	references/official-docs/docs/subsystems/ and docs/cordis-api/

🧭 What's inside

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 knowledge base as the dsh-plugin-guide 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
downloads/	Raw snapshots — generated by scripts/, not committed

✨ Highlights

• 📜 Plugin contract & hard rules — effects/disposers, waterfall next(), model-visible ⇔ logged, Schemastery config.
• 🕰️ Mechanism timeline — repository-plugin introduced 0809, removed 0811; the two install channels (bundle vs plain cordis plugin).
• 🕳️ 20+ real-world pitfalls with root cause + fix: cordis dual copies, tsconfig trio, tsc emitting on errors, Windows junctions, multi-frame zstd sessions, DSH_* env layers, stale npm latest…
• 🔬 111 community repos archived (15 deep-dived) — templates, scaffolds, pitfalls archives, plugin-check rules, Fabric layer, MCP bridge, plus a 15-language guide, an s01–s23 course, handbooks, TS/Rust SDKs, and a fresh 2026-08-15 batch (desktop shells, QQ bridge, security PoCs, Python port).
• 🔗 Full source index — every fact links to its origin (official docs, upstream repos, community repos).
• 🗃️ 1654 official GitHub Discussions archived (comments included for selected threads) + 100+ community articles (zh/en/HN) snapshotted — refresh with scripts/archive-discussions.ps1 / scripts/download-community-articles.ps1.
• 🆕 Freshness stamp — re-verified against upstream master, npm, and the live dsh-plugin topic on 2026-08-15.

🔄 Keeping it fresh

pwsh -File scripts/sync-official-docs.ps1                     # verbatim docs copy from a local checkout (origin/master only)
pwsh -File scripts/download-sources.ps1                       # official site/docs, Cordis, paper
pwsh -File scripts/download-community-repos.ps1               # 111 community repositories (codeload tarballs, ETag refresh)
pwsh -File scripts/download-community-articles.ps1            # zh/en/HN community articles (HTML snapshots)
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 report

CI runs verify-kit on every push and pull request.

🏷️ Topics

This repository is discoverable under the GitHub topics dsh and dsh-plugin — browse both topic pages to find hundreds of plugins and developer resources.

🤝 Get involved

• ⭐ Star the repo — it helps other DSH plugin authors discover it.
• Found an error, a new pitfall, or a missing repo to deep-dive? Open an issue or a pull request — see CONTRIBUTING.md.
• Join the community: DeepSeek Harness Discord · official discussions · dsh-plugin topic.

💛 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).

📄 License & attribution

• Our own text (SKILL.md, guide/, references/ reports, scripts/, this README): Apache-2.0 — see LICENSE.
• Bundled third-party content is documented in NOTICE.md, including its distribution boundaries (e.g. downloads/ is local-only; awesome-dsh-plugins must not be redistributed).

⚖️ 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.

PerryLink DSH Plugin Family

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

Plugin	One-liner
dsh-mcp-panel	Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors
dsh-doublecheck	Engineering-discipline guard: requirements grill, test gates, adversary review
dsh-background-agents	Durable background child agents with a Web UI sidebar, messaging and interrupt
dsh-lsp-actions	LSP diagnostics, formatting, completion, code actions and rename over language servers
dsh-output-styles	Claude Code outputStyles-equivalent runtime style switching
dsh-checkpoint-rewind	Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore
dsh-permission-rules	Claude Code-style declarative allow/deny/ask permission rules with audit
dsh-auto-review	Second-model auto-review on the approval chain, fail-closed by default
dsh-memento	Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool
dsh-skill-pack-security	Security-audit skill pack: secret scan, dependency and supply-chain review
dsh-session-pin	Pin sessions in the Web sidebar with durable ordering
dsh-composer-history	Terminal-style input history for the web composer: arrows, Ctrl+R search
dsh-github	GitHub PR/issues integration for DSH, every write gated by approval
dsh-plugin-guide	Plugin-development knowledge base as an on-demand agent skill
dsh-claude-move	Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH