dsh-plugin-guide 0.1.0

package/README.md

@@ -0,0 +1,165 @@
+<div align="center">
+
+# 🐳 dsh-plugin-guide
+
+**Everything you need to build [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugins.**
+
+Official docs archive · Cordis primer · community deep-dives · battle-tested pitfalls · agent skill
+
+[English](README.md) · [中文](README.zh-CN.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+[![GitHub stars](https://img.shields.io/github/stars/PerryLink/dsh-plugin-guide?style=for-the-badge&color=yellow&label=%E2%AD%90%20Stars)](https://github.com/PerryLink/dsh-plugin-guide/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/PerryLink/dsh-plugin-guide?style=for-the-badge&color=blue&label=Forks)](https://github.com/PerryLink/dsh-plugin-guide/network/members)
+[![verify-kit CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-plugin-guide/verify.yml?branch=main&style=for-the-badge&label=CI)](https://github.com/PerryLink/dsh-plugin-guide/actions/workflows/verify.yml)
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-guide?style=for-the-badge&label=npm)](https://www.npmjs.com/package/dsh-plugin-guide)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-guide?style=for-the-badge&label=downloads)](https://www.npmjs.com/package/dsh-plugin-guide)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue?style=for-the-badge)](LICENSE)
+[![Topic: dsh](https://img.shields.io/badge/Topic-dsh-4D6BFE?style=for-the-badge)](https://github.com/topics/dsh)
+[![Topic: dsh-plugin](https://img.shields.io/badge/Topic-dsh--plugin-8257D0?style=for-the-badge)](https://github.com/topics/dsh-plugin)
+[![Docs: EN/ZH](https://img.shields.io/badge/Docs-EN%2FZH-8257D0?style=for-the-badge)](references/official-docs/)
+
+</div>
+
+> 🗺️ **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](references/official-docs/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](references/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.
+
+```sh
+# 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)**
+
+```powershell
+pwsh -File scripts/install-skill.ps1 `
+  -Target "$env:USERPROFILE\.deepseek\skills\dsh-plugin-guide"   # or <project>\.agents\skills\dsh-plugin-guide
+```
+
+**macOS / Linux**
+
+```bash
+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`](guide/quick-reference.md) |
+| The full 10-chapter path | [`guide/plugin-dev-guide.md`](guide/plugin-dev-guide.md) |
+| Official & community doc links | [`guide/links.md`](guide/links.md) · [`references/community-ecosystem.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
+
+```sh
+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`](https://github.com/topics/dsh)** and **[`dsh-plugin`](https://github.com/topics/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](https://github.com/PerryLink/dsh-plugin-guide/issues) or a pull request — see [CONTRIBUTING.md](CONTRIBUTING.md).
+- Join the community: [DeepSeek Harness Discord](https://discord.gg/Ycq5dCaS4) · [official discussions](https://github.com/deepseek-ai/deepseek-harness/discussions) · [`dsh-plugin` topic](https://github.com/topics/dsh-plugin).
+
+## 💛 Contributors
+
+- [PerryLink](https://github.com/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](LICENSE).
+- Bundled third-party content is documented in [NOTICE.md](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](https://github.com/PerryLink) maintained by [PerryLink](https://github.com/PerryLink). If this one helps you, the others likely will too:
+
+| Plugin | One-liner |
+|---|---|
+| [dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel) | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors |
+| [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | Engineering-discipline guard: requirements grill, test gates, adversary review |
+| [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | Durable background child agents with a Web UI sidebar, messaging and interrupt |
+| [dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions) | LSP diagnostics, formatting, completion, code actions and rename over language servers |
+| [dsh-output-styles](https://github.com/PerryLink/dsh-output-styles) | Claude Code outputStyles-equivalent runtime style switching |
+| [dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind) | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore |
+| [dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules) | Claude Code-style declarative allow/deny/ask permission rules with audit |
+| [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | Second-model auto-review on the approval chain, fail-closed by default |
+| [dsh-memento](https://github.com/PerryLink/dsh-memento) | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool |
+| [dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security) | Security-audit skill pack: secret scan, dependency and supply-chain review |
+| [dsh-session-pin](https://github.com/PerryLink/dsh-session-pin) | Pin sessions in the Web sidebar with durable ordering |
+| [dsh-composer-history](https://github.com/PerryLink/dsh-composer-history) | Terminal-style input history for the web composer: arrows, Ctrl+R search |
+| [dsh-github](https://github.com/PerryLink/dsh-github) | GitHub PR/issues integration for DSH, every write gated by approval |
+| **[dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide)** | Plugin-development knowledge base as an on-demand agent skill |
+| [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH |

package/README.pt.md

@@ -0,0 +1,139 @@
+<div align="center">
+
+# 🐳 dsh-plugin-guide
+
+**Tudo o que você precisa para criar plugins do [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).**
+
+Arquivo da documentação oficial · Introdução ao Cordis · Análise da comunidade · Armadilhas reais · Skill para agentes
+
+[English](README.md) · [中文](README.zh-CN.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+[![GitHub stars](https://img.shields.io/github/stars/PerryLink/dsh-plugin-guide?style=for-the-badge&color=yellow&label=%E2%AD%90%20Stars)](https://github.com/PerryLink/dsh-plugin-guide/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/PerryLink/dsh-plugin-guide?style=for-the-badge&color=blue&label=Forks)](https://github.com/PerryLink/dsh-plugin-guide/network/members)
+[![verify-kit CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-plugin-guide/verify.yml?branch=main&style=for-the-badge&label=CI)](https://github.com/PerryLink/dsh-plugin-guide/actions/workflows/verify.yml)
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-guide?style=for-the-badge&label=npm)](https://www.npmjs.com/package/dsh-plugin-guide)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-guide?style=for-the-badge&label=downloads)](https://www.npmjs.com/package/dsh-plugin-guide)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue?style=for-the-badge)](LICENSE)
+[![Topic: dsh](https://img.shields.io/badge/Topic-dsh-4D6BFE?style=for-the-badge)](https://github.com/topics/dsh)
+[![Topic: dsh-plugin](https://img.shields.io/badge/Topic-dsh--plugin-8257D0?style=for-the-badge)](https://github.com/topics/dsh-plugin)
+[![Docs: EN/ZH](https://img.shields.io/badge/Docs-EN%2FZH-8257D0?style=for-the-badge)](references/official-docs/)
+
+</div>
+
+> 🗺️ **Cada fato aponta para sua origem** — documentação oficial, repos upstream ou repos comunitários. Em caso de dúvida, a cópia oficial textual prevalece.
+>
+> ⏱️ **Última verificação em 2026-08-15** — documentação oficial idêntica byte a byte ao `master` upstream (47f9438, veja [SNAPSHOT.md](references/official-docs/SNAPSHOT.md)); tags npm e o tópico `dsh-plugin` (API total_count subiu **2668 → 2671** durante o snapshot de 08-15; 998 repositórios capturados, veja [sources.md](references/sources.md) §D.2) re-verificados ao vivo; HEAD upstream (47f9438) e npm `@deepseek-ai/dsh` (0.1.0-rc.6) sem mudanças.
+
+## 📊 Em resumo
+
+| Documentação oficial | Análises comunitárias | Armadilhas reais | Tópico `dsh-plugin` | Idiomas | Skill de agente |
+|---|---|---|---|---|---|
+| 215 páginas (EN + ZH) | 114 repos | 20+ | 998 snapshot (API ≈2670) | EN · 中文 · ES · PT · HI | `dsh-plugin-guide` |
+
+## 🚀 Início rápido
+
+### 🧩 Instale como plugin do DSH (recomendado)
+
+Este repositório é um **bundle DSH** instalável: registra toda a base de conhecimento como a skill de agente `dsh-plugin-guide`. A skill fica visível no catálogo de cada sessão e o modelo carrega fluxos de trabalho, documentação oficial e análises comunitárias sob demanda (`./guide/`, `./references/`) — sem copiar nem buscar.
+
+```sh
+dsh plugin --profile <profile> add github:PerryLink/dsh-plugin-guide#<sha>
+# ou um tarball: pnpm pack && dsh plugin --profile <profile> add ./dsh-plugin-guide-<version>.tgz
+```
+
+O bundle declara `dsh.bundle.patch` e fixa o trem `@deepseek-ai/dsh@0.1.0-rc.6` como peerDependency opcional.
+
+### 🤖 Use como skill de agente
+
+Copie a pasta inteira para o diretório de skills do seu agente (os caminhos relativos permanecem válidos):
+
+**Windows (PowerShell)**
+
+```powershell
+pwsh -File scripts/install-skill.ps1 `
+  -Target "$env:USERPROFILE\.deepseek\skills\dsh-plugin-guide"   # ou <projeto>\.agents\skills\dsh-plugin-guide
+```
+
+**macOS / Linux**
+
+```bash
+pwsh -File scripts/install-skill.ps1 -Target ~/.deepseek/skills/dsh-plugin-guide   # ou <projeto>/.agents/skills/dsh-plugin-guide
+```
+
+O instalador pula `downloads/` (gerado) e `.github/`, e verifica byte a byte cada arquivo copiado. Um `Copy-Item -Recurse` manual da pasta inteira também funciona.
+
+Depois é só pedir ao seu agente: *"Use a skill dsh-plugin-guide para criar um plugin de …"*.
+
+### 📖 Ou apenas leia
+
+| Você quer… | Leia |
+|---|---|
+| A folha de consulta de uma página | [`guide/quick-reference.md`](guide/quick-reference.md) |
+| O caminho completo de 10 capítulos | [`guide/plugin-dev-guide.md`](guide/plugin-dev-guide.md) |
+| Links de documentação oficial e comunitária | [`guide/links.md`](guide/links.md) · [`references/community-ecosystem.md`](references/community-ecosystem.md) |
+| APIs exatas de serviços/eventos | `references/official-docs/docs/subsystems/` e `docs/cordis-api/` |
+
+## 🧭 Conteúdo
+
+| Caminho | O que é |
+|---|---|
+| `SKILL.md` | A skill `dsh-plugin-guide`: regras rígidas + caminhos de desenvolvimento por tipo de tarefa |
+| `guide/plugin-dev-guide.md` | O guia de desenvolvimento completo (10 capítulos) |
+| `guide/quick-reference.md` | Folha de consulta de uma página (5 idiomas) |
+| `guide/links.md` | Índice de URLs curado: documentação oficial de desenvolvimento (site ↔ cópias locais) + links comunitários |
+| `references/official-docs/` | Cópia integral da documentação oficial do repo (EN + ZH) |
+| `references/*.md` | Relatórios de pesquisa: docs do repo, site, Cordis, o paper, ecossistema comunitário, arquivo de 114 repos (15 analisados) |
+| `scripts/` | Scripts de download idempotentes + verificador de integridade + gerador de censo do tópico |
+| `downloads/` | Instantâneos brutos — gerados por `scripts/`, não versionados |
+
+## ✨ Destaques
+
+- 📜 **Contrato do plugin e regras rígidas** — efeitos/disposers, `next()` no waterfall, visível-para-o-modelo ⇔ registrado, configuração Schemastery.
+- 🕰️ **Linha do tempo dos mecanismos** — repository-plugin introduzido em 0809, removido em 0811; os dois canais de instalação (bundle vs plugin cordis simples).
+- 🕳️ **Mais de 20 armadilhas reais** com causa e solução: cópias duplas do cordis, trio do tsconfig, `tsc` emitindo mesmo com erros, junctions do Windows, sessões zstd multiframe, variáveis `DSH_*`, `latest` do npm desatualizado…
+- 🔬 **114 repositórios comunitários arquivados** (15 analisados) — modelos, scaffolds, arquivos de armadilhas, regras do plugin-check, camada Fabric, ponte MCP, mais um guia em 15 idiomas, um curso s01–s23, manuais, SDKs TS/Rust e o lote 08-15 (shells de desktop, ponte QQ, PoCs de segurança, port Python).
+- 🔗 **Índice de fontes completo** — cada fato aponta para sua origem (docs oficiais, repos upstream, repos comunitários).
+- 🗃️ **1654 Discussions oficiais arquivadas** (com comentários de threads selecionadas) + 100+ artigos comunitários (zh/en/HN) — atualize com `scripts/archive-discussions.ps1` / `scripts/download-community-articles.ps1`.
+- 🆕 **Selo de atualidade** — re-verificado contra o `master` upstream, npm e o tópico `dsh-plugin` ao vivo em 2026-08-15.
+
+## 🔄 Mantendo-o atualizado
+
+```sh
+pwsh -File scripts/sync-official-docs.ps1                     # cópia integral dos docs a partir de um checkout local (apenas origin/master)
+pwsh -File scripts/download-sources.ps1                       # site/docs oficiais, Cordis, paper
+pwsh -File scripts/download-community-repos.ps1               # 114 repositórios comunitários (tarballs codeload, atualização por ETag)
+pwsh -File scripts/download-community-articles.ps1            # artigos comunitários zh/en/HN (snapshots HTML)
+pwsh -File scripts/archive-discussions.ps1                    # Discussions oficiais (requer $env:GH_TOKEN)
+pwsh -File scripts/gen-topic-snapshot.ps1 -OutDir <dir>       # censo do tópico dsh-plugin
+pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>        # caminhos críticos + links quebrados + relatório de deriva dos docs
+```
+
+O CI executa `verify-kit` em cada push e pull request.
+
+## 🏷️ Topics
+
+Este repositório é visível sob os topics do GitHub **[`dsh`](https://github.com/topics/dsh)** e **[`dsh-plugin`](https://github.com/topics/dsh-plugin)** — navegue pelas duas páginas de topic para encontrar centenas de plugins e recursos para desenvolvedores.
+
+## 🤝 Participe
+
+- ⭐ **Dê uma estrela** — ajuda outros autores de plugins DSH a encontrá-lo.
+- Encontrou um erro, uma nova armadilha ou um repo que merece análise? Abra uma [issue](https://github.com/PerryLink/dsh-plugin-guide/issues) ou um pull request — veja [CONTRIBUTING.md](CONTRIBUTING.md).
+- Junte-se à comunidade: [Discord do DeepSeek Harness](https://discord.gg/Ycq5dCaS4) · [discussões oficiais](https://github.com/deepseek-ai/deepseek-harness/discussions) · [topic `dsh-plugin`](https://github.com/topics/dsh-plugin).
+
+## 💛 Contribuidores
+
+- [PerryLink](https://github.com/PerryLink) — criador e mantenedor: conteúdo da base de conhecimento, a transformação em bundle instalável, as contribuições ao ecossistema e a engenharia comunitária.
+- A manutenção diária conta com a assistência de agentes do DeepSeek Harness (eles não têm conta no GitHub e são listados aqui apenas por transparência, não como contribuidores).
+
+
+## 📄 Licença e atribuição
+
+- Texto próprio (`SKILL.md`, `guide/`, relatórios de `references/`, `scripts/`, este README): **Apache-2.0** — veja [LICENSE](LICENSE).
+- O conteúdo de terceiros incluído está documentado em [NOTICE.md](NOTICE.md), com seus limites de distribuição
+  (ex.: `downloads/` é apenas local; `awesome-dsh-plugins` não deve ser redistribuído).
+
+## ⚖️ Aviso legal
+
+Mantido pela comunidade; **não** é um produto oficial da DeepSeek. O DeepSeek Harness está em prévia de
+desenvolvedor e publica mudanças incompatíveis; em caso de dúvida, a documentação oficial em
+`references/official-docs/` é a fonte da verdade.

package/README.zh-CN.md

@@ -0,0 +1,164 @@
+<div align="center">
+
+# 🐳 dsh-plugin-guide
+
+**开发 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件所需的一切。**
+
+官方文档存档 · Cordis 入门 · 社区深读 · 实测踩坑 · 智能体技能
+
+[English](README.md) · [中文](README.zh-CN.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+[![GitHub stars](https://img.shields.io/github/stars/PerryLink/dsh-plugin-guide?style=for-the-badge&color=yellow&label=%E2%AD%90%20Stars)](https://github.com/PerryLink/dsh-plugin-guide/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/PerryLink/dsh-plugin-guide?style=for-the-badge&color=blue&label=Forks)](https://github.com/PerryLink/dsh-plugin-guide/network/members)
+[![verify-kit CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-plugin-guide/verify.yml?branch=main&style=for-the-badge&label=CI)](https://github.com/PerryLink/dsh-plugin-guide/actions/workflows/verify.yml)
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-guide?style=for-the-badge&label=npm)](https://www.npmjs.com/package/dsh-plugin-guide)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-guide?style=for-the-badge&label=downloads)](https://www.npmjs.com/package/dsh-plugin-guide)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue?style=for-the-badge)](LICENSE)
+[![Topic: dsh](https://img.shields.io/badge/Topic-dsh-4D6BFE?style=for-the-badge)](https://github.com/topics/dsh)
+[![Topic: dsh-plugin](https://img.shields.io/badge/Topic-dsh--plugin-8257D0?style=for-the-badge)](https://github.com/topics/dsh-plugin)
+[![Docs: EN/ZH](https://img.shields.io/badge/Docs-EN%2FZH-8257D0?style=for-the-badge)](references/official-docs/)
+
+</div>
+
+> 🗺️ **每条事实都链接到出处**——官方文档、上游仓库或社区仓库。有疑问时以官方原文副本为准。
+>
+> ⏱️ **最后核验 2026-08-15**——官方文档与上游 `master`（47f9438，见 [SNAPSHOT.md](references/official-docs/SNAPSHOT.md)）逐字节一致；npm 标签与 `dsh-plugin` 话题（08-15 快照抓取期间 API total_count **2668 → 2671 持续增长**，分页快照收录 998 个仓库，见 [sources.md](references/sources.md) §D.2）已实时重核；上游 HEAD 与 npm `@deepseek-ai/dsh`（0.1.0-rc.6）无变化。
+
+## 📊 一览
+
+| 官方文档 | 社区深读 | 实测踩坑 | `dsh-plugin` 话题 | 语言 | 智能体技能 |
+|---|---|---|---|---|---|
+| 215 篇（中英） | 114 个仓库 | 20+ | 998 快照（API ≈2670） | EN · 中文 · ES · PT · HI | `dsh-plugin-guide` |
+
+## 🚀 快速开始
+
+### 🧩 作为 DSH 插件安装（推荐）
+
+本仓库本身是一个可安装的 **DSH bundle**：安装后把整套知识库注册为 `dsh-plugin-guide` 智能体技能——每个会话的技能目录里都可见，模型按需加载工作流、官方文档与社区深读（`./guide/`、`./references/`），无需复制、无需搜索。
+
+```sh
+# 从 git 安装（源码；建议钉住 commit 保证可复现）：
+dsh plugin --profile <profile> add github:PerryLink/dsh-plugin-guide#<sha>
+
+# 或打 tarball 安装（入口是纯 ESM JS，无需构建步骤）：
+pnpm pack
+dsh plugin --profile <profile> add ./dsh-plugin-guide-<version>.tgz
+```
+
+bundle 声明了 `dsh.bundle.patch`，并以可选 peerDependency 钉住 `@deepseek-ai/dsh@0.1.0-rc.6` 版本火车。用 `dsh --profile <profile> --dump-config` 验证 `dsh-plugin-guide` 层已生效。
+
+### 🤖 或复制为普通智能体技能
+
+把整个目录复制进你的 agent 技能目录（相对路径保持不变）：
+
+**Windows（PowerShell）**
+
+```powershell
+pwsh -File scripts/install-skill.ps1 `
+  -Target "$env:USERPROFILE\.deepseek\skills\dsh-plugin-guide"   # 或 <项目>\.agents\skills\dsh-plugin-guide
+```
+
+**macOS / Linux**
+
+```bash
+pwsh -File scripts/install-skill.ps1 -Target ~/.deepseek/skills/dsh-plugin-guide   # 或 <项目>/.agents/skills/dsh-plugin-guide
+```
+
+安装脚本会跳过 `downloads/`（脚本生成）与 `.github/`，并对每个复制的文件做逐字节校验；手工 `Copy-Item -Recurse` 整个目录也可以。
+
+然后对智能体说：*"用 dsh-plugin-guide 技能帮我开发一个 XX 插件。"*
+
+### 📖 或者直接阅读
+
+| 想要什么 | 读哪里 |
+|---|---|
+| 一页速查表 | [`guide/quick-reference.md`](guide/quick-reference.md) |
+| 完整 10 章路径 | [`guide/plugin-dev-guide.md`](guide/plugin-dev-guide.md) |
+| 官方与社区文档链接 | [`guide/links.md`](guide/links.md) · [`references/community-ecosystem.md`](references/community-ecosystem.md) |
+| 服务/事件精确 API | `references/official-docs/docs/subsystems/` 与 `docs/cordis-api/` |
+
+## 🧭 目录结构
+
+| 路径 | 内容 |
+|---|---|
+| `SKILL.md` | `dsh-plugin-guide` 技能：硬性红线 + 按任务类型的开发路径 |
+| `package.json` · `cordis.patch.yml` · `index.js` | 可安装的 DSH bundle：`dsh.bundle.patch` 清单 + 把知识库注册为 `dsh-plugin-guide` 技能的入口 |
+| `guide/plugin-dev-guide.md` | 完整开发指南（10 章） |
+| `guide/quick-reference.md` | 一页速查表（5 语种） |
+| `guide/links.md` | 精选 URL 索引：官方开发文档（线上 ↔ 本地副本）+ 社区开发文档链接 |
+| `references/official-docs/` | 官方文档逐字副本（中英双语） |
+| `references/*.md` | 调研报告：仓库文档、文档站、Cordis、论文、社区生态、111 仓库归档（15 个深读） |
+| `scripts/` | 幂等下载脚本 + 完整性检查器 + 话题快照生成器 |
+| `downloads/` | 原始下载物——由 `scripts/` 生成，不入版本库 |
+
+## ✨ 亮点
+
+- 📜 **插件契约与红线**——注册即 effect、waterfall 必须 `next()`、模型可见⟺已记录、Schemastery 配置。
+- 🕰️ **机制时间线**——repository-plugin 机制 0809 推出、0811 移除；bundle 与纯 cordis 两条安装通道。
+- 🕳️ **20+ 个实测坑**（根因+修法）：cordis 双副本、tsconfig 三件套、`tsc` 报错仍产出、Windows junction、多帧 zstd 会话、`DSH_*` 环境变量、npm `latest` 过期……
+- 🔬 **114 个社区仓库归档**（15 个深读）——模板、脚手架、踩坑档案、plugin-check 规则、Fabric 层、MCP 桥，另有 15 语言指南、s01–s23 课程、深度手册、TS/Rust SDK 等 26 个文档型仓库与 08-15 第七批 14 个仓库（桌面端/QQ 桥接/安全 PoC/Python 移植）。
+- 🔗 **全量来源索引**——每条结论都链接到出处（官方文档、上游仓库、社区仓库）。
+- 🗃️ **官方 Discussions 全量归档（1654 条，含精选线程评论）+ 中英文社区文章快照 100+ 篇**——用 `scripts/archive-discussions.ps1` / `scripts/download-community-articles.ps1` 一键刷新。
+- 🆕 **新鲜度印章**——2026-08-15 对照上游 `master`、npm 与实时 `dsh-plugin` 话题复核。
+
+## 🔄 保持新鲜
+
+```sh
+pwsh -File scripts/sync-official-docs.ps1                     # 从本地 checkout 同步官方文档逐字副本（只取 origin/master）
+pwsh -File scripts/download-sources.ps1                       # 官网/文档站、Cordis、论文
+pwsh -File scripts/download-community-repos.ps1               # 114 个社区仓库（codeload tarball，ETag 增量刷新）
+pwsh -File scripts/download-community-articles.ps1            # 中/英/HN 社区文章 HTML 快照
+pwsh -File scripts/archive-discussions.ps1                    # 官方 Discussions（需 $env:GH_TOKEN）
+pwsh -File scripts/gen-topic-snapshot.ps1 -OutDir <目录>      # dsh-plugin 话题普查
+pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>        # 关键路径 + 断链扫描 + 官方文档漂移报告
+```
+
+每次 push 与 PR 都会由 CI 运行 `verify-kit`。
+
+## 🏷️ 话题
+
+本仓库以 GitHub 话题 **[`dsh`](https://github.com/topics/dsh)** 与 **[`dsh-plugin`](https://github.com/topics/dsh-plugin)** 对外可见——逛这两个话题页可以发现数百个插件与开发资源。
+
+## 🤝 参与共建
+
+- ⭐ **给仓库点 Star**——帮助更多 DSH 插件开发者发现它。
+- 发现错误、新坑或值得深读的仓库？提 [issue](https://github.com/PerryLink/dsh-plugin-guide/issues) 或 Pull Request——见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+- 加入社区：[DeepSeek Harness Discord](https://discord.gg/Ycq5dCaS4) · [官方讨论区](https://github.com/deepseek-ai/deepseek-harness/discussions) · [`dsh-plugin` 话题页](https://github.com/topics/dsh-plugin)。
+
+## 💛 贡献者
+
+- [PerryLink](https://github.com/PerryLink) — 创建者与维护者：知识库内容、插件化改造（bundle 契约）、生态投递与社区工程。
+- 日常维护由 DeepSeek Harness 智能体协助完成（其无 GitHub 账号，此处仅为透明性列出，不计入贡献者）。
+
+
+## 📄 许可与归属
+
+- 自有文本（`SKILL.md`、`guide/`、`references/` 报告、`scripts/`、本 README）：**Apache-2.0**——见 [LICENSE](LICENSE)。
+- 收录的第三方内容及其分发边界见 [NOTICE.md](NOTICE.md)（例如 `downloads/` 仅限本地、`awesome-dsh-plugins` 禁止再分发）。
+
+## ⚖️ 免责声明
+
+社区维护，**不是** DeepSeek 官方产品。DeepSeek Harness 处于开发者预览期、会发布破坏性变更；有疑问时以
+`references/official-docs/` 中的官方文档为准。
+
+## PerryLink DSH 插件家族
+
+本项目是 [PerryLink](https://github.com/PerryLink) 维护的 [15 个 DeepSeek Harness 插件](https://github.com/PerryLink)之一。如果你觉得这个插件有用，其余的很可能同样有用：
+
+| 插件 | 一句话说明 |
+|---|---|
+| [dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel) | 只读 MCP 运行时面板：/mcp 命令 + 设置页，状态/工具/错误一览 |
+| [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | 工程纪律守门：需求审讯、测试证据门、对抗评审 |
+| [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | 持久化后台子代理：Web 侧边栏进度、随时留言与打断 |
+| [dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions) | 基于语言服务器的诊断/格式化/补全/代码动作/重命名 |
+| [dsh-output-styles](https://github.com/PerryLink/dsh-output-styles) | 对标 Claude Code outputStyles 的运行时风格切换 |
+| [dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind) | 对标 Claude Code /rewind：快照、会话 fork、一键回退 |
+| [dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules) | Claude Code 风格声明式 allow/deny/ask 权限规则，带审计 |
+| [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | 审批链上的第二模型自动审查，默认 fail-closed |
+| [dsh-memento](https://github.com/PerryLink/dsh-memento) | 带审批门的跨会话记忆：ctx.memory + SQLite + memory 工具 |
+| [dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security) | 安全审计技能包：密钥扫描、依赖与供应链审查 |
+| [dsh-session-pin](https://github.com/PerryLink/dsh-session-pin) | 在 Web 侧边栏置顶会话，持久排序 |
+| [dsh-composer-history](https://github.com/PerryLink/dsh-composer-history) | Web 作曲器终端式输入历史：方向键、Ctrl+R 搜索 |
+| [dsh-github](https://github.com/PerryLink/dsh-github) | DSH 的 GitHub PR/issue 集成，所有写操作经审批门 |
+| **[dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide)** | 插件开发知识库，随 bundle 安装的按需 agent 技能 |
+| [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | 把 Claude Code 会话、记忆、技能和 CLAUDE.md 迁入 DSH |

package/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: dsh-plugin-guide
+description: Use when developing, reviewing, packaging, debugging, or answering questions about DeepSeek Harness (DSH) plugins — the plugin-based agent harness on vendored Cordis. Applies the official plugin-development constraints (plugin contract, cordis.yml layers, services/events/effects, tool DSL, bundles/profiles) backed by the dsh-plugin-guide knowledge base.
+---
+
+# DeepSeek Harness 插件开发（dsh-plugin-guide）
+
+依据官方资料开发 DeepSeek Harness 插件。本技能是**工作流与约束清单**；事实细节一律引用知识库原文，不凭记忆编造。所有"必须/不得"条款来自官方仓库 `AGENTS.md`、`docs/` 与文档站，冲突时以官方原文为准。
+
+## 知识库位置（按顺序找，用第一个存在的）
+
+本技能与知识库随同一目录分发（本 SKILL.md 所在目录即知识库根），路径均为相对路径；单独复制本文件而不带 `guide/`、`references/` 时按回退路径找。以 `dsh-plugin-guide` 插件（bundle）安装时，技能 resourceBase 即包目录，下文的 `./guide/`、`./references/` 相对路径由 DSH 的 `skill` 工具按此目录解析：
+
+1. **本文件同目录**（= 插件包目录 `dsh-plugin-guide`，或 `scripts/install-skill.ps1` 安装的独立技能目录）：`./guide/`（综合指南+速查表+文档链接索引）、`./references/`（调研报告与官方文档全文副本 `references/official-docs/docs/`）、`./downloads/`（原始下载物，可选，需按 §知识库维护 的脚本生成）
+2. 官方仓库 checkout：`D:\deepseek-harness\`（示例路径，按本机实际安装位置调整；`docs/`、`vendor/cordis/`、`packages/`、`examples/`）
+3. 线上：https://github.com/deepseek-ai/deepseek-harness 、 https://deepseek-harness.github.io/deepseek-harness/develop/basic/ 、 https://github.com/cordiverse/cordis
+
+下文相对路径默认相对上述第 1 条（本技能文件所在目录）。
+
+## 开发前置（第一步必做）
+
+1. 若未读过 Cordis 概念：读 `references/official-docs/docs/cordis-primer.md`（5 个概念，5 分钟）；需要动手跟练时跑 `references/official-docs/docs/cordis-tutorial/` 01-07（无 API key 可跑）。
+2. 打开 `guide/quick-reference.md`（契约速查）+ `guide/plugin-dev-guide.md`（完整路径）。官方/社区文档 URL 对照见 `guide/links.md`。
+3. 确认目标扩展点：读 `references/official-docs/docs/architecture.md` 的「Where new behavior goes」表与 `references/official-docs/docs/cookbook/extension-cookbook.md` 的 feature→mechanism 表——**新行为必须挂到已文档化扩展点，不得改 agent-loop**。
+
+## 必须遵守的插件契约（官方红线，逐条核对）
+
+- 插件 = 模块导出 `name` + `apply(ctx, config)`（+可选 `inject: string[]`）；依赖的服务在 `apply` 前就绪；依赖服务消失会自动卸载、恢复后自动重载。
+- **注册即 effect**：一切贡献走 `ctx.effect()` / `ctx.on()` / 服务 `register()`（返回 disposer）；绝不手动 removeListener/clearInterval 式收尾。
+- **waterfall 监听器必须调用 `next()`**；不调=故意短路（拦截语义）。`emit/waterfall/parallel/serial/bail` 语义见速查表。
+- **模型可见 ⟺ 已记录**：进入模型请求的一切必须能从会话日志重建；新增模型可见输入必须新增 `SessionEventMap` 会话事件。
+- 类型安全事件/服务用 declaration merging（`declare module '@deepseek-ai/cordis'`）；事件文档标注 `@mode`。
+- 配置用 Schemastery `Schema<Config>`（禁止普通对象）；非法配置加载期响亮失败；**不得硬编码可调参数**（判断：cordis.yml 能否改）。
+- 工具走 `defineTool`：`execute` 只返回 `output.schema` 声明的规范 JSON 值；尊重 `exec.signal`；人类可读内容放 `output.render`；UI 卡片 presenter 是**纯函数**（禁 I/O/时钟/随机）。
+- 可替换能力按三层接缝设计：Service Definition / Provider / Consumer；不提前拆。
+- 打包：bundle 清单 `"dsh":{"bundle":{"patch":"..."}}`；覆盖按 `id` 整行替换 config；`!!js`（双感叹号）；git 安装需要 `prepare` 脚本与用户侧 `allowBuilds`，发布 npm/tarball 免构建许可。
+
+## 按任务类型的开发路径
+
+（以下路径均在 `references/official-docs/` 下，为官方文档全文副本）
+
+- **新工具**：`docs/user/develop/basic/tool.md`（教程）→ `docs/cookbook/adding-a-tool.md`（完整契约：参数校验、规范值、后台任务 `ctx.jobs`、策略钩子、Code Mode、UI 卡片）→ 参考实现 `packages/shell/tool-bash`（本地 checkout）。
+- **新服务/能力**：`docs/user/develop/framework/service.md` + `docs/user/develop/practice/`（三层拆分完整代码）。
+- **拦截/策略/hook**：`docs/cookbook/extension-cookbook.md`（permission-gate 范例）+ `docs/event-producer-consumer.md`（全事件矩阵）。
+- **新 LLM 提供商**：`docs/user/develop/practice/llm-adapter.md`（StreamChunk 协议）。
+- **UI/会话节点**：`docs/cookbook/adding-a-conversation-node.md` + `docs/subsystems/session.md`、`client-modules.md`。
+- **打包/发布**：`docs/user/develop/basic/publish.md`（bundle/profile、层顺序、git 安装坑）。
+- **查服务/事件精确签名**：`docs/subsystems/*.md` 生成式 Cordis API 区 + `docs/cordis-api/*`；**不要自造第二份静态清单**。站点 URL ↔ 本地副本对照见 `guide/links.md`，社区链接完整清单见 `references/community-ecosystem.md`。
+- **参考社区实现与实测坑**：`references/community-ecosystem.md`、`references/community-repo-deep-dive.md`（首批 15 个开发仓库深读）、`downloads/community-repos/`（**114 个仓库完整源码副本**，需先跑 `scripts/download-community-repos.ps1` 生成；含 08-14 晚扫描的 26 个文档型仓库——15 语言指南/s01–s23 课程/深度手册/TS·Rust SDK 等，及 08-15 第七批 14 个（桌面端/桥接/安全 PoC）与第八批 3 个（主题/WhaleHub/dsh-market 市场）仓库）。社区已确认的机制变化（如 repository-plugin 0811 移除、bundle vs 纯 cordis 双通道）与 20 个实测坑（cordis 双副本/tsconfig 三件套/多帧 zstd/Windows junction 等）在 `guide/plugin-dev-guide.md` §7。官方 Discussions 全量归档（**1654 条，2026-08-15 刷新**，含 #1629 官方插件脚手架 RFC）与 npm 全家桶元数据分别在 `downloads/github/harness/discussions/` 与 `downloads/npm/`；中英文社区文章 HTML 快照（100+ 篇）在 `downloads/web/community-articles/`。
+
+## 验证（交付前）
+
+- 加载验证：`dsh --profile <name> --dump-config` 检查 patch 行是否生效；启动日志无 FAILED。
+- 行为验证：Web UI 或 `dsh --profile headless "…"` 实测；工具返回/模型可见文本即行为，改动必须重测。
+- 仓库内改动额外走：类型检查、目标包测试、keyless snapshot（模型/产品可见行为必须有组装后转录快照）、双语文档成对、Agent Note（非平凡变更同 PR）。
+- 独立插件包：`pnpm pack` 后试装到干净 profile 验证（含 `lib/` 构建产物）。
+
+## 知识库维护（需要时）
+
+- 同步官方文档副本：`pwsh -File ./scripts/sync-official-docs.ps1 [-Checkout <deepseek-harness checkout>]`——只同步 git 已跟踪文件（未跟踪草稿与未推送提交不会进来），并刷新 `references/official-docs/SNAPSHOT.md`；README 的"最后核验"日期与提交号引用 SNAPSHOT.md，不要手改。漂移校验：`pwsh -File ./scripts/verify-kit.ps1 -Checkout <checkout>`。
+- 刷新线上资料：`pwsh -File ./scripts/download-sources.ps1`；刷新社区仓库：`pwsh -File ./scripts/download-community-repos.ps1`；刷新社区文章快照：`pwsh -File ./scripts/download-community-articles.ps1`（三个脚本幂等，产出进 `./downloads/`）。刷新官方 Discussions 归档：`$env:GH_TOKEN=<token>; pwsh -File ./scripts/archive-discussions.ps1`（list.json + 精选线程评论，防缩水保护）。话题清单计数重核：`pwsh -File ./scripts/gen-topic-snapshot.ps1 -OutDir <dir> -MaxPages 10`（GitHub Search API `q=topic:dsh-plugin`；分页上限 1000 条，去重数与 API total_count 都要记录进 sources.md §D.2；08-15 期快照在 `downloads/topic-snapshots/dsh-plugin-topic-2026-08-15/`）。
+- 安装/刷新 agent 技能副本：`pwsh -File ./scripts/install-skill.ps1 -Target <skill目录>`（跳过 downloads/ 与 .github/，逐字节校验）。
+- 冲突裁决：与官方文档冲突时以 `references/official-docs/`（官方仓库原文）为准。
+
+## 边界
+
+- 本技能是"指引 + 约束 + 资料索引"，不是脚本/清单的机械执行；精确 API 以生成式参考为准。
+- 不得修改知识库外的 harness 仓库文件，除非用户明确要求；vendor/ 与 `.agents/notes/archived/` 只读。
+- 引用 `downloads/` 内容前先确认其存在（该目录不入 git，需按上文脚本生成）；`awesome-dsh-plugins` 的归档仅供本地参考，**不得随仓库再分发**（其上游声明内部使用约束，见 NOTICE.md）。

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-plugin-guide bundle layer: register the packaged knowledge base as an agent skill.
+- insert:
+    - id: dsh-plugin-guide
+      name: dsh-plugin-guide