🐳 dsh-plugin-guide

Everything you need to build DeepSeek Harness plugins.

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

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

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