dsh-plugin-guide 0.3.29 → 0.3.31

package/README-es.md

@@ -1,12 +1,15 @@
 <div align="center">
 
 # 🐳 dsh-plugin-guide
-- **Canal 1024 store**: `npm i -g dsh1024` una vez, luego `dsh1024 plugin --profile web add dsh-plugin-guide` (cuenta para el ranking de instalaciones de [deepseek1024.com](https://deepseek1024.com)).
 
 **Todo lo que necesitas para construir plugins de [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).**
 
 *Archivo de documentación oficial · primer de Cordis · deep-dives de la comunidad · trampas probadas en batalla · agent skill · toolchain CLI*
 
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
 [![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -27,6 +30,22 @@
 
 **📖 ¿Prefieres leerlo como sitio web?** [perrylink.github.io/dsh-plugin-guide](https://perrylink.github.io/dsh-plugin-guide/) — cada capítulo en su propia página, más un [llms.txt](https://perrylink.github.io/dsh-plugin-guide/llms.txt) legible por máquina para asistentes.
 
+## Why not just read the official docs?
+
+Porque está escrita para quien ya sabe qué página abrir, y DSH publica **una versión preliminar cada 1,7–2,8 días** con cambios que rompen compatibilidad. Este plugin cubre las tres brechas que más tiempo cuestan:
+
+| Brecha | Qué añade este plugin |
+|---|---|
+| **"¿Contra qué versión estoy desarrollando?"** | Una [matriz de versiones](guide/version-matrix.md): los cuatro valores que se llaman "latest", las etiquetas `latest` congeladas de los subpaquetes, las fallas de compatibilidad y cómo elegir un rango en `peerDependencies`. **No existe una línea estable** — toda versión publicada es preliminar. |
+| **"¿Qué rompe esta versión?"** | Una [guía de migración](guide/migration-0.2.md) que expone `0.1.6-alpha.2` → `0.2.1-alpha.2` como **seams citables**, cada uno con síntoma *y* arreglo y su fuente oficial — incluida una pérdida de datos y un cambio que hace fallar los prompts antes de construir la petición al modelo. |
+| **"¿Mi plugin es realmente correcto?"** | Una [CLI sin dependencias](SKILL.md) (`dsh-plugin-dev new / check / verify`) y un [espejo literal y sin conexión](references/official-docs/) de la documentación oficial, para que el agente cite la página exacta. |
+
+**Compruébalo en 60 segundos:**
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
+
 <!-- star-cta -->
 ## ⭐ 如果它帮到了你
 
@@ -72,6 +91,10 @@ content counts as stated in the README (What you get)
 - **Deep-dives de la comunidad** — 114 repositorios de la comunidad archivados (15 con deep-dive), más un índice fuente completo donde cada hecho enlaza a su origen.
 - **Toolchain CLI** — `dsh-plugin-dev new / check / verify`: genera, verifica estáticamente y valida el empaquetado de plugins DSH; cada check enlaza a la sección de la skill que aplica.
 
+- **Adaptabilidad de versión** — [guide/version-matrix.md](guide/version-matrix.md): los cuatro valores "latest", las etiquetas `latest` congeladas, las fallas de compatibilidad, cómo elegir el rango de peers y los 19 cambios de `0.2.1-alpha.2`.
+- **Enrutador de la cadena de herramientas** — [guide/family-toolchain.md](guide/family-toolchain.md): qué herramienta responde a cada pregunta, el catálogo completo de 33 comprobaciones de `dsh-plugin-doctor` y su cruce con las 16 de este repositorio.
+- **Decisión sobre el alcance del espejo** — [references/mirror-scope-decision.md](references/mirror-scope-decision.md): por qué "eliminar lo no referenciado para ahorrar un 80%" **no se sostiene** al volver a medirlo.
+- **Destilado de la skill oficial** — [references/official-plugin-dev-skill.md](references/official-plugin-dev-skill.md): prohibiciones, metadatos de presentación y reglas de UI/rendimiento de la skill oficial `cordis-plugin-development`.
 ## Knowledge base
 
 | Path | Qué es |
@@ -89,6 +112,10 @@ content counts as stated in the README (What you get)
 | `bin/` · `src/cli/` · `dist/` | El CLI `dsh-plugin-dev`: scaffolder, checker, verifier (TypeScript, empaquetado con tsdown) |
 | `templates/` | Esqueletos TS + JS: plantilla de contrato, Config, tests, cordis.patch.yml, READMEs en cinco idiomas |
 | `downloads/` | Instantáneas crudas — generadas por `scripts/`, no confirmadas |
+| `guide/version-matrix.md` | **Matriz de adaptabilidad de versión**: los cuatro valores "latest", etiquetas congeladas, fallas de compatibilidad, selección de rango de peers, linaje del formato de sesión y los 19 cambios de `0.2.1-alpha.2` |
+| `guide/family-toolchain.md` | **Enrutador de la cadena de herramientas**: pregunta → propietario → artefacto citable; catálogo completo de 33 comprobaciones de `dsh-plugin-doctor` y cruce con las 16 de este repositorio |
+| `guide/migration-0.2.md` | Guía de cambios que rompen compatibilidad de la generación 0.2 (§0–§12 hasta `0.2.1-alpha.1`; **§13 cubre los 19 seams de `0.2.1-alpha.2`**) |
+| `references/mirror-scope-decision.md` | Registro de decisión sobre el alcance del espejo: por qué no se recorta por "cero referencias", con el script de medición reproducible |
 
 ## CLI toolchain
 

package/README-hi.md

@@ -1,12 +1,15 @@
 <div align="center">
 
 # 🐳 dsh-plugin-guide
-- **1024 स्टोर चैनल**: एक बार `npm i -g dsh1024`, फिर `dsh1024 plugin --profile web add dsh-plugin-guide` ([deepseek1024.com](https://deepseek1024.com) इंस्टॉल रैंकिंग में गिना जाता है)।
 
 **[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) प्लगइन बनाने के लिए आपकी ज़रूरत की हर चीज़।**
 
 *आधिकारिक दस्तावेज़ संग्रह · Cordis प्राइमर · सामुदायिक गहन-विश्लेषण · युद्ध-परीक्षित नुकसान · agent skill · CLI टूलचेन*
 
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
 [![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -27,6 +30,22 @@
 
 **📖 इसे वेबसाइट के रूप में पढ़ना चाहें?** [perrylink.github.io/dsh-plugin-guide](https://perrylink.github.io/dsh-plugin-guide/) — हर अध्याय अपने पृष्ठ पर, साथ ही असिस्टेंट के लिए मशीन-पठनीय [llms.txt](https://perrylink.github.io/dsh-plugin-guide/llms.txt)।
 
+## Why not just read the official docs?
+
+क्योंकि वे उसके लिए लिखे गए हैं जिसे पहले से पता है कौन-सा पृष्ठ खोलना है, और DSH **हर 1.7–2.8 दिन में एक प्रीरिलीज़** जारी करता है जिसमें संगतता तोड़ने वाले बदलाव होते हैं। यह प्लगइन वही तीन अंतराल भरता है जो सबसे अधिक समय लेते हैं:
+
+| अंतराल | यह प्लगइन क्या जोड़ता है |
+|---|---|
+| **"मैं किस संस्करण के लिए विकसित कर रहा हूँ?"** | एक [संस्करण मैट्रिक्स](guide/version-matrix.md): चार भिन्न मान जो स्वयं को "latest" कहते हैं, उप-पैकेजों के जमे हुए `latest` टैग, संगतता-भंग बिंदु, और `peerDependencies` रेंज कैसे चुनें। **कोई स्थिर पंक्ति नहीं है** — हर प्रकाशित संस्करण प्रीरिलीज़ है। |
+| **"यह संस्करण क्या तोड़ता है?"** | एक [माइग्रेशन गाइड](guide/migration-0.2.md) जो `0.1.6-alpha.2` → `0.2.1-alpha.2` को **उद्धरण-योग्य seams** के रूप में देता है, प्रत्येक में लक्षण *और* समाधान तथा आधिकारिक स्रोत — जिसमें एक डेटा-हानि जोखिम भी शामिल है। |
+| **"मेरा प्लगइन वास्तव में सही है?"** | एक [शून्य-निर्भरता CLI](SKILL.md) (`dsh-plugin-dev new / check / verify`) और आधिकारिक दस्तावेज़ों का [शब्दशः ऑफ़लाइन प्रतिबिंब](references/official-docs/), ताकि एजेंट अनुमान के बजाय सटीक पृष्ठ उद्धृत करे। |
+
+**60 सेकंड में सत्यापित करें:**
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
+
 <!-- star-cta -->
 ## ⭐ 如果它帮到了你
 
@@ -72,6 +91,10 @@ content counts as stated in the README (What you get)
 - **सामुदायिक गहन-विश्लेषण** — 114 सामुदायिक रिपॉज़िटरी संग्रहीत (15 गहन-विश्लेषित), साथ ही पूर्ण स्रोत सूची जहाँ हर तथ्य अपने मूल से जुड़ा है।
 - **CLI टूलचेन** — `dsh-plugin-dev new / check / verify`: DSH प्लगइन स्कैफ़ोल्ड करना, स्थैतिक जाँच और पैक-सत्यापन; हर जाँच उस skill अनुभाग से जुड़ती है जिसे वह लागू करती है।
 
+- **संस्करण अनुकूलनशीलता** — [guide/version-matrix.md](guide/version-matrix.md): चार "latest" मान, जमे हुए उप-पैकेज टैग, संगतता-भंग बिंदु, peer रेंज का चयन और `0.2.1-alpha.2` के 19 बदलाव।
+- **टूलचेन राउटर** — [guide/family-toolchain.md](guide/family-toolchain.md): कौन-सा प्रश्न किस टूल का है, `dsh-plugin-doctor` की पूरी 33-जाँच सूची, और इस रिपॉज़िटरी की 16 जाँचों से तुलना।
+- **मिरर स्कोप निर्णय** — [references/mirror-scope-decision.md](references/mirror-scope-decision.md): "संदर्भ-रहित सामग्री हटाकर 80% बचाने" का सुझाव दोबारा मापने पर **टिकता नहीं**।
+- **आधिकारिक skill का सार** — [references/official-plugin-dev-skill.md](references/official-plugin-dev-skill.md): आधिकारिक `cordis-plugin-development` skill के निषेध, प्रदर्शन मेटाडेटा और UI/प्रदर्शन नियम।
 ## Knowledge base
 
 | Path | यह क्या है |
@@ -89,6 +112,10 @@ content counts as stated in the README (What you get)
 | `bin/` · `src/cli/` · `dist/` | `dsh-plugin-dev` CLI: स्कैफ़ोल्डर, जाँचकर्ता, सत्यापक (TypeScript, tsdown-बंडल) |
 | `templates/` | TS + JS स्कैफ़ोल्ड कंकाल: अनुबंध टेम्प्लेट, Config, टेस्ट, cordis.patch.yml, पाँच-भाषा README |
 | `downloads/` | कच्चे स्नैपशॉट — `scripts/` से उत्पन्न, कमिट नहीं |
+| `guide/version-matrix.md` | **संस्करण अनुकूलनशीलता मैट्रिक्स**: चार "latest" मान, जमे हुए टैग, संगतता-भंग बिंदु, peer रेंज चयन, सत्र-प्रारूप वंशावली और `0.2.1-alpha.2` के 19 बदलाव |
+| `guide/family-toolchain.md` | **टूलचेन राउटर**: प्रश्न → स्वामी → उद्धरण-योग्य कलाकृति; `dsh-plugin-doctor` की 33-जाँच सूची और इस रिपॉज़िटरी की 16 जाँचों से तुलना |
+| `guide/migration-0.2.md` | 0.2 पीढ़ी के संगतता-भंग बदलावों की माइग्रेशन गाइड (§0–§12 `0.2.1-alpha.1` तक; **§13 `0.2.1-alpha.2` के 19 seams**) |
+| `references/mirror-scope-decision.md` | मिरर स्कोप निर्णय रिकॉर्ड: "शून्य संदर्भ" के आधार पर कटौती क्यों नहीं, साथ में पुनरुत्पाद्य मापन स्क्रिप्ट |
 
 ## CLI toolchain
 

package/README-pt.md

@@ -1,12 +1,15 @@
 <div align="center">
 
 # 🐳 dsh-plugin-guide
-- **Canal 1024 store**: `npm i -g dsh1024` uma vez, depois `dsh1024 plugin --profile web add dsh-plugin-guide` (conta para o ranking de instalações do [deepseek1024.com](https://deepseek1024.com)).
 
 **Tudo o que você precisa para construir plugins do [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).**
 
 *Arquivo de documentação oficial · primer de Cordis · deep-dives da comunidade · armadilhas testadas em batalha · agent skill · toolchain CLI*
 
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
 [![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -27,6 +30,22 @@
 
 **📖 Prefere ler como site?** [perrylink.github.io/dsh-plugin-guide](https://perrylink.github.io/dsh-plugin-guide/) — cada capítulo em sua própria página, além de um [llms.txt](https://perrylink.github.io/dsh-plugin-guide/llms.txt) legível por máquina para assistentes.
 
+## Why not just read the official docs?
+
+Porque ela é escrita para quem já sabe qual página abrir, e o DSH publica **uma versão preliminar a cada 1,7–2,8 dias** com mudanças que quebram compatibilidade. Este plugin cobre as três lacunas que mais custam tempo:
+
+| Lacuna | O que este plugin acrescenta |
+|---|---|
+| **"Contra qual versão estou desenvolvendo?"** | Uma [matriz de versões](guide/version-matrix.md): os quatro valores que se chamam "latest", as tags `latest` congeladas dos subpacotes, as falhas de compatibilidade e como escolher um intervalo em `peerDependencies`. **Não existe linha estável** — toda versão publicada é preliminar. |
+| **"O que esta versão quebra?"** | Um [guia de migração](guide/migration-0.2.md) que expõe `0.1.6-alpha.2` → `0.2.1-alpha.2` como **seams citáveis**, cada um com sintoma *e* correção e sua fonte oficial — incluindo uma perda de dados e uma mudança que faz os prompts falharem antes de montar a requisição ao modelo. |
+| **"Meu plugin está realmente correto?"** | Uma [CLI sem dependências](SKILL.md) (`dsh-plugin-dev new / check / verify`) e um [espelho literal e offline](references/official-docs/) da documentação oficial, para o agente citar a página exata. |
+
+**Comprove em 60 segundos:**
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
+
 <!-- star-cta -->
 ## ⭐ 如果它帮到了你
 
@@ -72,6 +91,10 @@ O `dsh-plugin-guide` é a base de conhecimento de desenvolvimento de plugins DSH
 - **Deep-dives da comunidade** — 114 repositórios da comunidade arquivados (15 com deep-dive), mais um índice fonte completo onde cada fato aponta para sua origem.
 - **Toolchain CLI** — `dsh-plugin-dev new / check / verify`: gerar, verificar estaticamente e validar o empacotamento de plugins DSH; cada check aponta para a seção da skill que ele aplica.
 
+- **Adaptabilidade de versão** — [guide/version-matrix.md](guide/version-matrix.md): os quatro valores "latest", tags `latest` congeladas, falhas de compatibilidade, escolha do intervalo de peers e as 19 mudanças de `0.2.1-alpha.2`.
+- **Roteador da cadeia de ferramentas** — [guide/family-toolchain.md](guide/family-toolchain.md): qual ferramenta responde a cada pergunta, o catálogo completo de 33 verificações do `dsh-plugin-doctor` e o cruzamento com as 16 deste repositório.
+- **Decisão sobre o escopo do espelho** — [references/mirror-scope-decision.md](references/mirror-scope-decision.md): por que "remover o não referenciado para economizar 80%" **não se sustenta** ao medir de novo.
+- **Destilado da skill oficial** — [references/official-plugin-dev-skill.md](references/official-plugin-dev-skill.md): proibições, metadados de apresentação e regras de UI/desempenho da skill oficial `cordis-plugin-development`.
 ## Knowledge base
 
 | Path | O que é |
@@ -89,6 +112,10 @@ O `dsh-plugin-guide` é a base de conhecimento de desenvolvimento de plugins DSH
 | `bin/` · `src/cli/` · `dist/` | O CLI `dsh-plugin-dev`: scaffolder, checker, verifier (TypeScript, empacotado com tsdown) |
 | `templates/` | Esqueletos TS + JS: modelo de contrato, Config, tests, cordis.patch.yml, READMEs em cinco idiomas |
 | `downloads/` | Instantâneas cruas — geradas por `scripts/`, não commitadas |
+| `guide/version-matrix.md` | **Matriz de adaptabilidade de versão**: os quatro valores "latest", tags congeladas, falhas de compatibilidade, seleção de intervalo de peers, linhagem do formato de sessão e as 19 mudanças de `0.2.1-alpha.2` |
+| `guide/family-toolchain.md` | **Roteador da cadeia de ferramentas**: pergunta → responsável → artefato citável; catálogo completo de 33 verificações do `dsh-plugin-doctor` e cruzamento com as 16 deste repositório |
+| `guide/migration-0.2.md` | Guia de mudanças que quebram compatibilidade da geração 0.2 (§0–§12 até `0.2.1-alpha.1`; **§13 cobre os 19 seams de `0.2.1-alpha.2`**) |
+| `references/mirror-scope-decision.md` | Registro de decisão sobre o escopo do espelho: por que não se recorta por "zero referências", com o script de medição reproduzível |
 
 ## CLI toolchain
 

package/README-zh.md

@@ -1,7 +1,6 @@
 <div align="center">
 
 # 🐳 dsh-plugin-guide
-- **1024 商店渠道**：先 `npm i -g dsh1024`，再 `dsh1024 plugin --profile web add dsh-plugin-guide`（计入 [deepseek1024.com](https://deepseek1024.com) 安装排行）。
 
 **构建 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件所需的一切。**
 
@@ -9,6 +8,10 @@
 
 > **官方仓库。** 本仓库是 dsh-plugin-guide 的唯一官方仓库，由 PerryLink 维护。其他账号下的同名仓库与本项目无关。
 
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
 [![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -29,6 +32,22 @@
 
 **📖 想在网页上读？** [perrylink.github.io/dsh-plugin-guide](https://perrylink.github.io/dsh-plugin-guide/) —— 每章独立成页，另有给助手用的机器可读 [llms.txt](https://perrylink.github.io/dsh-plugin-guide/llms.txt)。
 
+## Why not just read the official docs?
+
+因为官方文档是写给"已经知道该翻哪一页"的人的，而 DSH **每 1.7–2.8 天发一个 prerelease**，且带破坏性变更。本插件补的正是最耗时间的三处缺口：
+
+| 缺口 | 本插件补什么 |
+|---|---|
+| **"我到底在对着哪一版开发？"** | [版本矩阵](guide/version-matrix.md)：四个都自称"最新"的值、子包 `latest` 冻结陷阱、破坏性变更断层，以及 `peerDependencies` 区间怎么选。**不存在稳定版**——所有已发布版本都是 prerelease。 |
+| **"这一版破坏了什么？"** | [迁移指南](guide/migration-0.2.md)：把 `0.1.6-alpha.2` → `0.2.1-alpha.2` 整理成**可引用的 seam**，每条含症状*与*修法并附官方出处——其中包括一处数据丢失风险和一处"模型请求还没发出就失败"的变更。 |
+| **"我的插件真的对吗？"** | [零依赖 CLI](SKILL.md)（`dsh-plugin-dev new / check / verify`）+ [官方文档逐字离线镜像](references/official-docs/)，让 agent 能引确切页面而不是靠猜。 |
+
+**60 秒自证：**
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
+
 <!-- star-cta -->
 ## ⭐ 如果它帮到了你
 
@@ -75,6 +94,9 @@ content counts as stated in the README (What you get)
 - **社区深读** —— 归档 114 个社区仓库（15 个深读），外加每条事实都链回出处的完整来源索引。
 - **CLI 工具链** —— `dsh-plugin-dev new / check / verify`：脚手架、静态检查、打包验证 DSH 插件；每个检查项都链回它强制执行的技能章节。
 
+- **家族工具链路由** —— [guide/family-toolchain.md](guide/family-toolchain.md)：哪个工具负责哪个问题、`dsh-plugin-doctor` 33 项检查全表，以及与本库 16 项检查的交叉对照。
+- **镜像范围决策** —— [references/mirror-scope-decision.md](references/mirror-scope-decision.md)：为什么"删掉零引用内容以省 80% 体积"经复测**不成立**（它们被本库自己声明的宽 glob 覆盖）。
+- **官方自带技能要点** —— [references/official-plugin-dev-skill.md](references/official-plugin-dev-skill.md)：官方 `cordis-plugin-development` 技能的禁则、展示元数据清单与 UI/性能规则。
 ## Knowledge base
 
 | Path | 是什么 |
@@ -93,6 +115,9 @@ content counts as stated in the README (What you get)
 | `bin/` · `src/cli/` · `dist/` | `dsh-plugin-dev` CLI：脚手架、检查器、验证器（TypeScript，tsdown 打包） |
 | `templates/` | TS + JS 脚手架骨架：契约模板、Config、tests、cordis.patch.yml、五语 README |
 | `downloads/` | 原始快照 —— 由 `scripts/` 生成、不入库 |
+| `guide/family-toolchain.md` | **家族工具链路由**：问题→所有者→可引用产物；`dsh-plugin-doctor` 33 项检查全表与裁定语义；本库 16 项检查的交叉对照 |
+| `guide/migration-0.2.md` | 0.2 世代破坏性变更迁移指南（§0–§12 覆盖到 `0.2.1-alpha.1`，**§13 覆盖 `0.2.1-alpha.2` 的 19 个 seam**） |
+| `references/mirror-scope-decision.md` | 镜像范围决策记录：为什么不按"零引用"裁剪（附可复跑的测量脚本） |
 
 ## CLI toolchain
 

package/README.md

@@ -1,15 +1,21 @@
 <div align="center">
 
 # 🐳 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](https://deepseek1024.com) install ranking).
+
+**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.
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
+
+Then just ask: *"Use the dsh-plugin-guide skill to build me a … plugin."*
+
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
 [![dshfind](https://dshfind.com/api/badge/PerryLink/dsh-plugin-guide?metric=downloads)](https://dshfind.com/plugins/PerryLink/dsh-plugin-guide?ref=badge)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-plugin-guide/badge)](https://api.securityscorecards.dev/projects/github.com/PerryLink/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 · 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.
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
@@ -28,8 +34,28 @@
 
 ---
 
+## 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](guide/version-matrix.md): 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](guide/migration-0.2.md) 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](SKILL.md) (`dsh-plugin-dev new / check / verify`) plus an [offline verbatim mirror](references/official-docs/) of the official docs, so your agent can cite the exact page instead of guessing. |
+
+**Prove it works in 60 seconds:**
+
+```sh
+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](https://perrylink.github.io/dsh-plugin-guide/) — every chapter as its own page, plus a machine-readable [llms.txt](https://perrylink.github.io/dsh-plugin-guide/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](https://deepseek1024.com) install ranking).
+
 <!-- star-cta -->
 ## ⭐ 如果它帮到了你
 
@@ -44,6 +70,7 @@ Everything you need to build [DeepSeek Harness](https://github.com/deepseek-ai/d
 
 Official docs archive · Cordis primer · community deep-dives · battle-tested pitfalls · agent skill · CLI toolchain
 
+
 ![Terminal demo of dsh-plugin-guide: dsh-plugin-guide — install the bundle, then run the checker](https://raw.githubusercontent.com/PerryLink/dsh-plugin-guide/main/docs/assets/dsh-plugin-guide-demo.png)
 
 ![Animated terminal demo of dsh-plugin-guide](https://raw.githubusercontent.com/PerryLink/dsh-plugin-guide/main/docs/assets/dsh-plugin-guide-demo.gif)
@@ -60,7 +87,7 @@ content counts as stated in the README (What you get)
 
 | 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 and `guide/migration-0.2.md` are pinned one release back, at `dsh-v0.2.1-alpha.1` (`5badb15009`, 2026-10-03); the 20 breaking-change guides added since are captured in [guide/version-matrix.md](guide/version-matrix.md) §3. |
+| 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](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) |
@@ -137,16 +164,19 @@ The CLI has no hardcoded tunables — each is a flag or an environment variable.
 ## Quick start
 
 ```sh
-# 1. install the bundle into your profile
-dsh plugin --profile web add github:PerryLink/dsh-plugin-guide
-
-# or from npm (published releases)
+# 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](#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:
@@ -159,8 +189,8 @@ 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`.
+- **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#<sha>` — 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](references/official-docs/docs/user/develop/basic/publish.md)).
 - **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`.
 

package/SKILL.md

@@ -19,7 +19,14 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 
 ## 开发前置（第一步必做）
 
-0. **先认版本**：`dsh --version`，然后读 `guide/version-matrix.md`（**版本适配矩阵**：五个"最新"的区分、子包 `latest` 冻结陷阱、破坏性变更断层、peer 区间选择、会话格式谱系）。要点：`0.1.7-alpha.1`（2026-09-22）起包含本世代全部破坏性变更（会话格式 V4、settings 重写、`readBytes`、Messages-only 适配器）；**npm `latest`=`0.2.0-rc.2`、`next`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.2`，而 master 最新 tag 是 `dsh-v0.2.1-alpha.2`——这四个"最新"不是同一个东西**。**不存在稳定版**：全部 31 个 npm 版本都是 prerelease。目标宿主不是 matrix 基线时，按 `guide/migration-0.2.md` 逐条对照；目标宿主**更新**（如 `0.2.1-alpha.2`）时另见 `guide/version-matrix.md` §3 的 19 条新破坏性变更。
+0. **先认版本**：跑 `dsh --version`，然后按下表决定读什么。**不要跳过这一步**——本库 17 篇文档里对当前宿主不适用的部分不会自己标注。
+   | 你的 `dsh --version` | 含义 | 读什么 |
+   |---|---|---|
+   | `< 0.1.7-alpha.1` | 旧基线 | 本世代破坏性变更**全部适用** → `guide/migration-0.2.md` §0–§12 逐条改 |
+   | `0.1.7-alpha.1` – `0.2.1-alpha.1` | 中间线 | 会话格式 V4 已生效；§13 的 19 条**不适用** |
+   | `0.2.1-alpha.2` 或更新 | 最新线 | §13 的 19 条**适用** → `guide/version-matrix.md` §3 |
+   | **npm `latest`（= `0.2.0-rc.2`）** | **默认安装拿到的就是这一版** | ⚠️ 它**早于** master 一版：§13 不适用，但 `version-matrix.md` §1.1 的"不存在稳定版"警告适用 |
+   **四个"最新"不是同一个东西**：npm `latest`=`next`=`0.2.0-rc.2`、npm `alpha`=`0.2.1-alpha.2`、master 最新 tag = `dsh-v0.2.1-alpha.2`。**不存在稳定版**（全部 31 个 npm 版本都是 prerelease）。完整谱系、子包 `latest` 冻结陷阱与 peer 区间选择见 `guide/version-matrix.md`。
 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`。排查官方运行时行为/未修复 bug 时查 `guide/unfixed-issues.md`（master 基线源码核实的问题清单 + 已修复提交号 + 设计行为对照 + 本世代新核实的 T1–T11）。决定一个插件**该不该继续维护**（官方已进内核 / 第三方采用度显著更高）时查 `guide/when-to-retire-a-plugin.md`（判据 + 实测倍数表）；判断某个能力面谁领先时查 `guide/choosing-a-plugin.md`。
 2b. **要判断"该改哪一行 / 该找哪个工具"时**，读 `guide/family-toolchain.md`（家族工具链路由：问题→所有者→可引用产物；`dsh-plugin-doctor` 33 项检查全表与裁定语义；本库 16 项检查与 doctor 的交叉对照）。发布流水线（多插件组合的持续可安装/可发布/可升级）见 `guide/release-engineering.md`。
@@ -55,8 +62,11 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 - **新服务/能力**：`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 插件（Web）**：`references/official-plugin-dev-skill.md` §3.2 + `docs/subsystems/slots.md`、`sidebar-right.md`、`client-modules.md`、`web-client.md`、`ui-radius.md`；Chat 行业务节点用 `ctx.uiConversation.events.register()` + `conversation.chat.node` slot。
+- **UI 插件（Web）**：`references/official-plugin-dev-skill.md` §3.2 + `docs/subsystems/slots.md`、`sidebar-right.md`、`client-modules.md`、`web-client.md`、**`docs/ui-radius.md`**（注意 `ui-radius` 在 `docs/` 顶层，**不在** `docs/subsystems/` 下）；Chat 行业务节点用 `ctx.uiConversation.events.register()` + `conversation.chat.node` slot。
 - **插件配置表单**：`docs/subsystems/settings.md`（已改名 "Plugin Configuration Forms"）+ `docs/cookbook/adding-a-settings-card.md`（已重写）。
+- **斜杠命令**：`docs/subsystems/commands.md`——命令是**面向人**的入口，与工具（面向模型）是两套注册面；只加工具而想让用户能敲 `/x` 时要另注册命令。
+- **权限 / 审批 / 沙箱**：`docs/subsystems/approval.md`（审批流与 `ask` 决策）+ `docs/subsystems/permission-presets.md`（预设档位）+ `docs/subsystems/sandbox.md`（进程约束及其已知边界：Windows ACL 部分强制）。需要拦截工具调用时读 `docs/cookbook/extension-cookbook.md` 的 permission-gate 范例。
+- **上下文 / 压缩 / 性能**：`docs/subsystems/compaction.md`（压缩缝与阈值语义）+ `docs/subsystems/spill.md`（溢出存储：只负责存储，无保留策略、无检索 API）；`ctx` 自身的 API 面见 `docs/cordis-api/context.md`（**没有** subsystems 版的 context 页）。per-session 派生状态用 `ctx.sessionProjections`（见 §4.8 第 5 条）。
 - **打包/发布**：`docs/user/develop/basic/publish.md`（bundle/profile、层顺序、多 patch 数组、peer 解析、git 安装坑）。
 - **升级/迁移**：`guide/version-matrix.md`（**版本适配矩阵：先读这个**——五个"最新"、子包 `latest` 冻结、破坏性变更断层、peer 区间选择、会话格式 V0→V4）→ `guide/migration-0.2.md`（本库综述，0.1.6→0.2.1-alpha.1）→ `docs/upgrade-guide/**`（官方逐版本迁移指南）+ `docs/persistence-changes/**`（持久化类型变更记录）+ `docs/session-format-status.md`（会话格式版本权威）。⚠️ **目标宿主是 `0.2.1-alpha.2` 或更新时**：`version-matrix.md` §3 列了该版落的 **19 条破坏性变更**（`webRuntime`→`webStartup`、`mode: both` 被拒、`backgroundMode`/`run_in_background` 移除、`{{cwd}}` 移除、`BundleInfo` 新增必填字段、`dsh plugin --profile` 位置强制等），`migration-0.2.md` **尚未并入**。
 - **查服务/事件精确签名**：**优先用会话内 inspection**（`cordis_inspect_list` / `cordis_inspect_query`：Service / Event / Config / Tool / Slots / Theme），其次 `docs/subsystems/*.md` 生成式 Cordis API 区 + `docs/cordis-api/*`；**不要自造第二份静态清单**。站点 URL ↔ 本地副本对照见 `guide/links.md`，社区链接完整清单见 `references/community-ecosystem.md`。
@@ -82,11 +92,16 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 
 ## CLI 工具链（dsh-plugin-dev）
 
-本仓库随 bundle 附带零依赖 CLI `dsh-plugin-dev`，把机械检查自动化（知识库仍是认知层，CLI 是机械层）：
+本仓库随 bundle 附带零依赖 CLI `dsh-plugin-dev`，把机械检查自动化（知识库仍是认知层，CLI 是机械层）。
 
-- `dsh-plugin-dev new <name>`：参数化脚手架，生成 TS 或 JS 插件仓库骨架（`src/index.ts` 契约模板、Schemastery Config、tests、tsdown/vitest、注释齐全的 `cordis.patch.yml`、五语 README），模板与 `references/official-docs` 同步更新。
-- `dsh-plugin-dev check [--json] [--strict]`：静态检查（`cordis.patch.yml` 合法性、`package.json` 元数据（`dsh.bundle.patch` 指向/peer 依赖/engines/files 白名单）、五语 README 一致性、工程红线模式），输出 CI 可消费的结构化 JSON；每个检查项在输出里引用本知识库对应章节（skill 联动），agent 可继续人工审计。
-- `dsh-plugin-dev verify`：`pnpm pack` 后装入干净临时 `DSH_HOME` profile 做安装+启动+卸载冒烟（对齐官方 verify:self-contained）；失败给出日志尾部与建议。
+> ⚠️ **调用方式**：`dsh-plugin-dev` **通常不在 PATH 上**（bundle 安装只登记技能，不安装二进制）。
+> 用本 SKILL.md 所在目录下的入口调用：`node "<resourceBase>/bin/dsh-plugin-dev.js" <子命令>`。
+> bundle 安装的包已带 `dist/`；从源码副本用则先跑一次 `pnpm run build`。
+> 只有全局 `npm i -g dsh-plugin-guide` 之后才可以直接敲 `dsh-plugin-dev`。
+
+- `new <name>`：参数化脚手架，生成 TS 或 JS 插件仓库骨架（`src/index.ts` 契约模板、Schemastery Config、tests、tsdown/vitest、注释齐全的 `cordis.patch.yml`、五语 README），模板与 `references/official-docs` 同步更新。标志：`--lang <ts|js>`、`--dir <path>`、`--force`、`--git`。
+- `check [--json] [--strict] [--cwd <dir>]`：静态检查（`cordis.patch.yml` 合法性、`package.json` 元数据（`dsh.bundle.patch` 指向/peer 依赖/engines/files 白名单）、五语 README 一致性、工程红线模式），输出 CI 可消费的结构化 JSON；每个检查项在输出里引用本知识库对应章节（skill 联动），agent 可继续人工审计。**这 16 项是同族 `dsh-plugin-doctor` 33 项的子集**（逐项对照见 `guide/family-toolchain.md` §3）；发布前建议两个都跑。
+- `verify [--cwd <dir>] [--base <spec>] [--headless <spec>] [--profile <name>]`：`pnpm pack` 后装入干净临时 `DSH_HOME` profile 做安装+启动+卸载冒烟（对齐官方 verify:self-contained）；失败给出日志尾部与建议。
 
 三个子命令均可逆/幂等；网络/子进程尊重超时与 AbortSignal；只清理自己 mkdtemp 的目录。CLI 零运行时依赖，构建产物经 tsdown 打包为单文件 `dist/dsh-plugin-dev.js`。