dsh-plugin-guide 0.1.2 → 0.2.0

package/README.es.md

@@ -4,7 +4,7 @@
 
 **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*
+*Archivo de documentación oficial · primer de Cordis · deep-dives de la comunidad · trampas probadas en batalla · agent skill · toolchain CLI*
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -38,6 +38,7 @@
 - **Primer de Cordis** — los cinco conceptos y la línea de tiempo de mecanismos (repository-plugin introducido 0809, eliminado 0811; los dos canales de instalación).
 - **20+ trampas del mundo real** con causa raíz + arreglo (copias duales de cordis, trío tsconfig, sesiones zstd multi-frame, junctions de Windows, `latest` obsoleto de npm, …).
 - **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.
 
 ## Knowledge base
 
@@ -51,8 +52,42 @@
 | `references/official-docs/` | Copia textual de la documentación oficial del repo (EN + ZH) |
 | `references/*.md` | Informes de investigación: documentación del repo, sitio web, Cordis, el paper, ecosistema de la comunidad, archivo de 114 repos (15 con deep-dive) |
 | `scripts/` | Scripts de descarga idempotentes + verificador de integridad + generador de instantáneas de tema |
+| `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 |
 
+## CLI toolchain
+
+El bundle incluye el CLI `dsh-plugin-dev` sin dependencias de runtime (`bin/` → `dist/dsh-plugin-dev.js` empaquetado con tsdown). Cada check cita la sección de la skill que aplica, para que un agente pueda seguir auditando manualmente.
+
+```sh
+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>]
+```
+
+| Subcomando | Qué hace |
+|---|---|
+| `new <name>` | Genera un repo de plugin TS o JS: plantilla de contrato `src/index.ts`, Config de Schemastery, tests, tsdown/vitest, `cordis.patch.yml` comentado, READMEs en cinco idiomas. Idempotente; rechaza destinos no vacíos sin `--force`. |
+| `check` | Checks estáticos: validez de `cordis.patch.yml`, metadatos de `package.json` (puntero `dsh.bundle.patch`, peer deps, engines, lista blanca de files), consistencia de READMEs en cinco idiomas, patrones de línea roja de ingeniería. Emite JSON consumible por CI. |
+| `verify` | `pnpm pack`, luego instala/inicia/desinstala el bundle en un perfil `DSH_HOME` mkdtemp limpio (alineado con `verify:self-contained`). Los fallos reportan la cola del log más sugerencias. |
+
+### CLI configuration
+
+El CLI no tiene ajustes hardcodeados — cada uno es un flag o una variable de entorno.
+
+| Ajuste | Flag | Env | Por defecto |
+|---|---|---|---|
+| Directorio de plantillas | — | `DSH_PLUGIN_DEV_TEMPLATES` | `<package>/templates` |
+| Binario dsh | `--dsh` | `DSH_PLUGIN_DEV_DSH` | `dsh` |
+| Binario pnpm | `--pnpm` | `DSH_PLUGIN_DEV_PNPM` | `pnpm` |
+| Timeout de instalación/pack | `--timeout` | `DSH_PLUGIN_DEV_TIMEOUT` | `300000` ms |
+| Timeout de smoke headless | `--smoke-timeout` | `DSH_PLUGIN_DEV_SMOKE_TIMEOUT` | `120000` ms |
+
+### Upstream roadmap
+
+`dsh-plugin-dev` es un candidato upstream para el CLI oficial de desarrollo de plugins (ítem C12): el scaffolder/checker/verifier son las capas mecánicas, mientras que `SKILL.md` + `guide/` siguen siendo la capa cognitiva.
+
 ## Quick start
 
 ```sh
@@ -68,6 +103,14 @@ dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-guide'
 
 Luego pídele a tu agente: *"Usa la skill dsh-plugin-guide para construirme un plugin de …."*
 
+O maneja el CLI directamente:
+
+```sh
+npx dsh-plugin-guide new hello-plugin            # genera un repo de plugin TS
+npx dsh-plugin-guide check --json                # check estático
+npx dsh-plugin-guide verify                      # pack + smoke de perfil limpio
+```
+
 ## Install & uninstall
 
 - **canal git** (último `main`): `dsh plugin --profile web add github:PerryLink/dsh-plugin-guide#<sha>` — fija un commit para reproducibilidad; el punto de entrada es JS ESM plano, sin paso de build.
@@ -94,13 +137,14 @@ El instalador omite `downloads/` (generado) y `.github/`, y luego verifica cada
 
 ## Configuration
 
-`dsh-plugin-guide` no expone ningún `Config` de Schemastery — registra la base de conocimiento como una skill de agente sin claves ajustables.
+El bundle de skill no expone ningún `Config` de Schemastery — registra la base de conocimiento como una skill de agente sin claves ajustables. El CLI `dsh-plugin-dev` lee sus ajustes de flags y variables de entorno `DSH_PLUGIN_DEV_*` (ver [CLI toolchain](#cli-toolchain)).
 
 ## Tools & surfaces
 
 | Surface | Kind | Notes |
 |---|---|---|
 | `dsh-plugin-guide` | skill | Registrada vía `ctx.skills`; carga `SKILL.md` + `./guide/` + `./references/` bajo demanda |
+| `dsh-plugin-dev` | bin (CLI) | Subcomandos `new` / `check` / `verify`; no es una fila de plugin DSH |
 
 ## Permissions & data
 
@@ -133,9 +177,16 @@ pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>        # rutas críticas
 
 ## Development
 
-El bundle es ESM plano — sin paso de build. CI ejecuta la puerta de integridad en cada push y pull request:
+El bundle de skill (`index.js`) es ESM plano, sin paso de build; el CLI `dsh-plugin-dev` es TypeScript compilado con tsdown. Puertas:
 
 ```sh
+pnpm install --frozen-lockfile
+pnpm run typecheck && pnpm run typecheck:ci
+pnpm test
+pnpm run build
+pnpm run verify:artifacts        # auto-check + smoke de scaffold (sin red)
+pnpm run verify:self-contained   # pack + smoke de instalación/inicio/desinstalación en perfil limpio
+pnpm pack
 pwsh -File scripts/verify-kit.ps1   # rutas críticas + escaneo de enlaces (+ deriva de docs con -Checkout <checkout>)
 ```
 

package/README.hi.md

@@ -4,7 +4,7 @@
 
 **[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) प्लगइन बनाने के लिए आपकी ज़रूरत की हर चीज़।**
 
-*आधिकारिक दस्तावेज़ संग्रह · Cordis प्राइमर · सामुदायिक गहन-विश्लेषण · युद्ध-परीक्षित नुकसान · agent skill*
+*आधिकारिक दस्तावेज़ संग्रह · Cordis प्राइमर · सामुदायिक गहन-विश्लेषण · युद्ध-परीक्षित नुकसान · agent skill · CLI टूलचेन*
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -38,6 +38,7 @@
 - **Cordis प्राइमर** — पाँच अवधारणाएँ और तंत्र समयरेखा (repository-plugin 0809 को जोड़ा, 0811 को हटाया; दो इंस्टॉल चैनल)।
 - **20+ वास्तविक-दुनिया नुकसान** मूल कारण + समाधान सहित (cordis दोहरी प्रतियाँ, tsconfig त्रयी, बहु-फ़्रेम zstd सत्र, Windows junction, पुराना npm `latest`, …)।
 - **सामुदायिक गहन-विश्लेषण** — 114 सामुदायिक रिपॉज़िटरी संग्रहीत (15 गहन-विश्लेषित), साथ ही पूर्ण स्रोत सूची जहाँ हर तथ्य अपने मूल से जुड़ा है।
+- **CLI टूलचेन** — `dsh-plugin-dev new / check / verify`: DSH प्लगइन स्कैफ़ोल्ड करना, स्थैतिक जाँच और पैक-सत्यापन; हर जाँच उस skill अनुभाग से जुड़ती है जिसे वह लागू करती है।
 
 ## Knowledge base
 
@@ -51,8 +52,42 @@
 | `references/official-docs/` | आधिकारिक रेपो दस्तावेज़ों की शब्दशः प्रति (EN + ZH) |
 | `references/*.md` | शोध रिपोर्ट: रेपो दस्तावेज़, वेबसाइट, Cordis, पेपर, सामुदायिक पारिस्थितिकी, 114-रेपो संग्रह (15 गहन-विश्लेषित) |
 | `scripts/` | इडेम्पोटेंट डाउनलोड स्क्रिप्ट + अखंडता जाँचकर्ता + विषय स्नैपशॉट जनरेटर |
+| `bin/` · `src/cli/` · `dist/` | `dsh-plugin-dev` CLI: स्कैफ़ोल्डर, जाँचकर्ता, सत्यापक (TypeScript, tsdown-बंडल) |
+| `templates/` | TS + JS स्कैफ़ोल्ड कंकाल: अनुबंध टेम्प्लेट, Config, टेस्ट, cordis.patch.yml, पाँच-भाषा README |
 | `downloads/` | कच्चे स्नैपशॉट — `scripts/` से उत्पन्न, कमिट नहीं |
 
+## CLI toolchain
+
+बंडल शून्य-रनटाइम-निर्भरता `dsh-plugin-dev` CLI लेकर आता है (`bin/` → tsdown-बंडल `dist/dsh-plugin-dev.js`). हर जाँच उस skill अनुभाग को उद्धृत करती है जिसे वह लागू करती है, ताकि एजेंट मैन्युअल ऑडिट जारी रख सके।
+
+```sh
+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>]
+```
+
+| उप-कमांड | क्या करता है |
+|---|---|
+| `new <name>` | TS या JS प्लगइन रेपो स्कैफ़ोल्ड करता है: `src/index.ts` अनुबंध टेम्प्लेट, Schemastery Config, टेस्ट, tsdown/vitest, टिप्पणी-युक्त `cordis.patch.yml`, पाँच-भाषा README। इडेम्पोटेंट; `--force` के बिना गैर-खाली लक्ष्य को अस्वीकार करता है। |
+| `check` | स्थैतिक जाँच: `cordis.patch.yml` वैधता, `package.json` मेटाडेटा (`dsh.bundle.patch` पॉइंटर, peer deps, engines, files श्वेतसूची), पाँच-भाषा README संगति, इंजीनियरिंग रेड-लाइन पैटर्न। CI-उपभोज्य JSON उत्सर्जित करता है। |
+| `verify` | `pnpm pack`, फिर साफ़ mkdtemp `DSH_HOME` प्रोफ़ाइल में बंडल को इंस्टॉल/स्टार्ट/अनइंस्टॉल स्मोक (आधिकारिक `verify:self-contained` से संरेखित)। विफलता लॉग टेल + सुझाव देती है। |
+
+### CLI configuration
+
+CLI में कोई हार्डकोडेड ट्यूनेबल नहीं — हर एक flag या पर्यावरण चर है।
+
+| ट्यूनेबल | Flag | Env | डिफ़ॉल्ट |
+|---|---|---|---|
+| टेम्प्लेट निर्देशिका | — | `DSH_PLUGIN_DEV_TEMPLATES` | `<package>/templates` |
+| dsh बाइनरी | `--dsh` | `DSH_PLUGIN_DEV_DSH` | `dsh` |
+| pnpm बाइनरी | `--pnpm` | `DSH_PLUGIN_DEV_PNPM` | `pnpm` |
+| इंस्टॉल/पैक टाइमआउट | `--timeout` | `DSH_PLUGIN_DEV_TIMEOUT` | `300000` ms |
+| हेडलेस स्मोक टाइमआउट | `--smoke-timeout` | `DSH_PLUGIN_DEV_SMOKE_TIMEOUT` | `120000` ms |
+
+### Upstream roadmap
+
+`dsh-plugin-dev` आधिकारिक प्लगइन-विकास CLI (नियोजित आइटम C12) का अपस्ट्रीम उम्मीदवार है: स्कैफ़ोल्डर/जाँचकर्ता/सत्यापक यांत्रिक परतें हैं, जबकि `SKILL.md` + `guide/` संज्ञानात्मक परत बने रहते हैं।
+
 ## Quick start
 
 ```sh
@@ -68,6 +103,14 @@ dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-guide'
 
 फिर बस अपने एजेंट से पूछें: *"मुझे … प्लगइन बनाने के लिए dsh-plugin-guide skill का उपयोग करो।"*
 
+या सीधे CLI चलाएँ:
+
+```sh
+npx dsh-plugin-guide new hello-plugin            # TS प्लगइन रेपो स्कैफ़ोल्ड करें
+npx dsh-plugin-guide check --json                # स्थैतिक जाँच
+npx dsh-plugin-guide verify                      # पैक + साफ़ प्रोफ़ाइल स्मोक
+```
+
 ## Install & uninstall
 
 - **git चैनल** (नवीनतम `main`): `dsh plugin --profile web add github:PerryLink/dsh-plugin-guide#<sha>` — पुनरुत्पादन के लिए एक कमिट पिन करें; प्रवेश बिंदु सादा ESM JS है, कोई बिल्ड चरण नहीं।
@@ -94,13 +137,14 @@ pwsh -File scripts/install-skill.ps1 -Target ~/.deepseek/skills/dsh-plugin-guide
 
 ## Configuration
 
-`dsh-plugin-guide` कोई Schemastery `Config` उजागर नहीं करता — यह ज्ञान-आधार को बिना किसी ट्यूनेबल कुंजी के एक agent skill के रूप में पंजीकृत करता है।
+skill बंडल कोई Schemastery `Config` उजागर नहीं करता — यह ज्ञान-आधार को बिना किसी ट्यूनेबल कुंजी के एक agent skill के रूप में पंजीकृत करता है। `dsh-plugin-dev` CLI अपने ट्यूनेबल flags और `DSH_PLUGIN_DEV_*` पर्यावरण चरों से पढ़ता है ([CLI toolchain](#cli-toolchain) देखें)।
 
 ## Tools & surfaces
 
 | Surface | Kind | Notes |
 |---|---|---|
 | `dsh-plugin-guide` | skill | `ctx.skills` से पंजीकृत; माँग पर `SKILL.md` + `./guide/` + `./references/` लोड करता है |
+| `dsh-plugin-dev` | bin (CLI) | `new` / `check` / `verify` उप-कमांड; DSH प्लगइन पंक्ति नहीं |
 
 ## Permissions & data
 
@@ -133,9 +177,16 @@ pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>        # महत्व
 
 ## Development
 
-बंडल सादा ESM है — कोई बिल्ड चरण नहीं। CI हर push और pull request पर अखंडता द्वार चलाता है:
+skill बंडल (`index.js`) सादा ESM है, कोई बिल्ड चरण नहीं; `dsh-plugin-dev` CLI TypeScript है, tsdown से बिल्ट। द्वार:
 
 ```sh
+pnpm install --frozen-lockfile
+pnpm run typecheck && pnpm run typecheck:ci
+pnpm test
+pnpm run build
+pnpm run verify:artifacts        # आत्म-जाँच + स्कैफ़ोल्ड स्मोक (कोई नेटवर्क नहीं)
+pnpm run verify:self-contained   # पैक + साफ़ प्रोफ़ाइल इंस्टॉल/स्टार्ट/अनइंस्टॉल स्मोक
+pnpm pack
 pwsh -File scripts/verify-kit.ps1   # महत्वपूर्ण पथ + लिंक स्कैन (-Checkout <checkout> से दस्तावेज़ विचलन)
 ```
 

package/README.md

@@ -5,7 +5,7 @@
 
 **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*
+*Official docs archive · Cordis primer · community deep-dives · battle-tested pitfalls · agent skill · CLI toolchain*
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -32,13 +32,14 @@
 
 ## What you get
 
-`dsh-plugin-guide` is the DSH plugin-development knowledge base, packaged as an installable bundle that registers the whole thing 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.
+`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
 
@@ -52,8 +53,42 @@
 | `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.
+
+```sh
+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
 
 ```sh
@@ -69,6 +104,14 @@ 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:
+
+```sh
+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.
@@ -95,13 +138,14 @@ The installer skips `downloads/` (generated) and `.github/`, then verifies every
 
 ## Configuration
 
-`dsh-plugin-guide` exposes no Schemastery `Config` — it registers the knowledge base as an agent skill with no tunable keys.
+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](#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
 
@@ -134,9 +178,16 @@ pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>        # critical paths +
 
 ## Development
 
-The bundle is plain ESM — no build step. CI runs the integrity gate on every push and pull request:
+The skill bundle (`index.js`) is plain ESM with no build step; the `dsh-plugin-dev` CLI is TypeScript built by tsdown. Gates:
 
 ```sh
+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>)
 ```
 

package/README.pt.md

@@ -4,7 +4,7 @@
 
 **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*
+*Arquivo de documentação oficial · primer de Cordis · deep-dives da comunidade · armadilhas testadas em batalha · agent skill · toolchain CLI*
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -38,6 +38,7 @@ O `dsh-plugin-guide` é a base de conhecimento de desenvolvimento de plugins DSH
 - **Primer de Cordis** — os cinco conceitos e a linha do tempo de mecanismos (repository-plugin introduzido 0809, removido 0811; os dois canais de instalação).
 - **20+ armadilhas do mundo real** com causa raiz + correção (cópias duplas de cordis, trio tsconfig, sessões zstd multi-frame, junctions do Windows, `latest` obsoleto do npm, …).
 - **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.
 
 ## Knowledge base
 
@@ -51,8 +52,42 @@ O `dsh-plugin-guide` é a base de conhecimento de desenvolvimento de plugins DSH
 | `references/official-docs/` | Cópia textual da documentação oficial do repo (EN + ZH) |
 | `references/*.md` | Relatórios de pesquisa: docs do repo, site, Cordis, o paper, ecossistema da comunidade, arquivo de 114 repos (15 com deep-dive) |
 | `scripts/` | Scripts de download idempotentes + verificador de integridade + gerador de instantânea de tópico |
+| `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 |
 
+## CLI toolchain
+
+O bundle inclui o CLI `dsh-plugin-dev` sem dependências de runtime (`bin/` → `dist/dsh-plugin-dev.js` empacotado com tsdown). Cada check cita a seção da skill que ele aplica, para que um agente possa continuar auditando manualmente.
+
+```sh
+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>]
+```
+
+| Subcomando | O que faz |
+|---|---|
+| `new <name>` | Gera um repo de plugin TS ou JS: modelo de contrato `src/index.ts`, Config de Schemastery, tests, tsdown/vitest, `cordis.patch.yml` comentado, READMEs em cinco idiomas. Idempotente; recusa destinos não vazios sem `--force`. |
+| `check` | Checks estáticos: validade de `cordis.patch.yml`, metadados de `package.json` (ponteiro `dsh.bundle.patch`, peer deps, engines, whitelist de files), consistência de READMEs em cinco idiomas, padrões de linha vermelha de engenharia. Emite JSON consumível por CI. |
+| `verify` | `pnpm pack`, depois instala/inicia/desinstala o bundle em um perfil `DSH_HOME` mkdtemp limpo (alinhado com `verify:self-contained`). Falhas reportam a cauda do log mais sugestões. |
+
+### CLI configuration
+
+O CLI não tem ajustes hardcoded — cada um é um flag ou uma variável de ambiente.
+
+| Ajuste | Flag | Env | Padrão |
+|---|---|---|---|
+| Diretório de templates | — | `DSH_PLUGIN_DEV_TEMPLATES` | `<package>/templates` |
+| Binário dsh | `--dsh` | `DSH_PLUGIN_DEV_DSH` | `dsh` |
+| Binário pnpm | `--pnpm` | `DSH_PLUGIN_DEV_PNPM` | `pnpm` |
+| Timeout de instalação/pack | `--timeout` | `DSH_PLUGIN_DEV_TIMEOUT` | `300000` ms |
+| Timeout de smoke headless | `--smoke-timeout` | `DSH_PLUGIN_DEV_SMOKE_TIMEOUT` | `120000` ms |
+
+### Upstream roadmap
+
+O `dsh-plugin-dev` é um candidato upstream para o CLI oficial de desenvolvimento de plugins (item C12): o scaffolder/checker/verifier são as camadas mecânicas, enquanto `SKILL.md` + `guide/` seguem sendo a camada cognitiva.
+
 ## Quick start
 
 ```sh
@@ -68,6 +103,14 @@ dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-guide'
 
 Depois é só pedir ao seu agente: *"Use a skill dsh-plugin-guide para me construir um plugin de …."*
 
+Ou use o CLI diretamente:
+
+```sh
+npx dsh-plugin-guide new hello-plugin            # gera um repo de plugin TS
+npx dsh-plugin-guide check --json                # check estático
+npx dsh-plugin-guide verify                      # pack + smoke de perfil limpo
+```
+
 ## Install & uninstall
 
 - **canal git** (último `main`): `dsh plugin --profile web add github:PerryLink/dsh-plugin-guide#<sha>` — fixe um commit para reprodutibilidade; o ponto de entrada é JS ESM puro, sem etapa de build.
@@ -94,13 +137,14 @@ O instalador pula `downloads/` (gerado) e `.github/`, e então verifica cada arq
 
 ## Configuration
 
-O `dsh-plugin-guide` não expõe nenhum `Config` de Schemastery — ele registra a base de conhecimento como uma agent skill sem chaves ajustáveis.
+O bundle de skill não expõe nenhum `Config` de Schemastery — ele registra a base de conhecimento como uma agent skill sem chaves ajustáveis. O CLI `dsh-plugin-dev` lê seus ajustes de flags e variáveis de ambiente `DSH_PLUGIN_DEV_*` (veja [CLI toolchain](#cli-toolchain)).
 
 ## Tools & surfaces
 
 | Surface | Kind | Notes |
 |---|---|---|
 | `dsh-plugin-guide` | skill | Registrada via `ctx.skills`; carrega `SKILL.md` + `./guide/` + `./references/` sob demanda |
+| `dsh-plugin-dev` | bin (CLI) | Subcomandos `new` / `check` / `verify`; não é uma linha de plugin DSH |
 
 ## Permissions & data
 
@@ -133,9 +177,16 @@ pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>        # caminhos crític
 
 ## Development
 
-O bundle é ESM puro — sem etapa de build. O CI executa a porta de integridade em cada push e pull request:
+O bundle de skill (`index.js`) é ESM puro, sem etapa de build; o CLI `dsh-plugin-dev` é TypeScript compilado com tsdown. Portas:
 
 ```sh
+pnpm install --frozen-lockfile
+pnpm run typecheck && pnpm run typecheck:ci
+pnpm test
+pnpm run build
+pnpm run verify:artifacts        # auto-check + smoke de scaffold (sem rede)
+pnpm run verify:self-contained   # pack + smoke de instalação/início/desinstalação em perfil limpo
+pnpm pack
 pwsh -File scripts/verify-kit.ps1   # caminhos críticos + varredura de links (+ deriva de docs com -Checkout <checkout>)
 ```
 

package/README.zh.md

@@ -4,7 +4,7 @@
 
 **构建 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件所需的一切。**
 
-*官方文档档案 · Cordis 入门 · 社区深读 · 实战踩坑 · agent 技能*
+*官方文档档案 · Cordis 入门 · 社区深读 · 实战踩坑 · agent 技能 · CLI 工具链*
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -31,13 +31,14 @@
 
 ## What you get
 
-`dsh-plugin-guide` 是 DSH 插件开发知识库，打包为可安装 bundle，把整份内容注册为 `dsh-plugin-guide` agent 技能。该技能在每个会话目录中都可见，并按需加载其工作流步骤、官方文档与社区深读。
+`dsh-plugin-guide` 是 DSH 插件开发知识库加 CLI 工具链，打包为一个可安装 bundle。知识库注册为 `dsh-plugin-guide` agent 技能（在每个会话目录可见，按需加载工作流步骤、官方文档与社区深读）；`dsh-plugin-dev` CLI 在其之上提供三个机械层。
 
 - **插件契约与红线** —— effect/disposer、waterfall `next()`、模型可见 ⟺ 已记录、Schemastery 配置。
 - **官方文档档案** —— 官方仓库文档（英 + 中）逐字副本，在最近核验快照处与上游逐字节一致。
 - **Cordis 入门** —— 五个概念与机制时间线（repository-plugin 0809 引入、0811 移除；两条安装通道）。
 - **20+ 个实战踩坑** —— 附根因 + 修法（cordis 双副本、tsconfig 三件套、多帧 zstd 会话、Windows junction、过期 npm `latest`…）。
 - **社区深读** —— 归档 114 个社区仓库（15 个深读），外加每条事实都链回出处的完整来源索引。
+- **CLI 工具链** —— `dsh-plugin-dev new / check / verify`：脚手架、静态检查、打包验证 DSH 插件；每个检查项都链回它强制执行的技能章节。
 
 ## Knowledge base
 
@@ -51,8 +52,42 @@
 | `references/official-docs/` | 官方仓库文档逐字副本（英 + 中） |
 | `references/*.md` | 调研报告：仓库文档、网站、Cordis、论文、社区生态、114 仓库归档（15 个深读） |
 | `scripts/` | 幂等下载脚本 + 完整性检查器 + 话题快照生成器 |
+| `bin/` · `src/cli/` · `dist/` | `dsh-plugin-dev` CLI：脚手架、检查器、验证器（TypeScript，tsdown 打包） |
+| `templates/` | TS + JS 脚手架骨架：契约模板、Config、tests、cordis.patch.yml、五语 README |
 | `downloads/` | 原始快照 —— 由 `scripts/` 生成、不入库 |
 
+## CLI toolchain
+
+bundle 附带零运行时依赖的 `dsh-plugin-dev` CLI（`bin/` → tsdown 打包的 `dist/dsh-plugin-dev.js`）。每个检查项都引用它强制执行的技能章节，agent 可继续人工审计。
+
+```sh
+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>]
+```
+
+| 子命令 | 作用 |
+|---|---|
+| `new <name>` | 脚手架生成 TS 或 JS 插件仓库：`src/index.ts` 契约模板、Schemastery Config、tests、tsdown/vitest、注释齐全的 `cordis.patch.yml`、五语 README。幂等；无 `--force` 时拒绝覆盖非空目录。 |
+| `check` | 静态检查：`cordis.patch.yml` 合法性、`package.json` 元数据（`dsh.bundle.patch` 指向、peer 依赖、engines、files 白名单）、五语 README 一致性、工程红线模式。输出 CI 可消费的 JSON。 |
+| `verify` | `pnpm pack` 后装入干净 mkdtemp `DSH_HOME` profile 做安装/启动/卸载冒烟（对齐 `verify:self-contained`）。失败给出日志尾部与建议。 |
+
+### CLI configuration
+
+CLI 无硬编码可调参数——每个都是 flag 或环境变量。
+
+| 可调项 | Flag | 环境变量 | 默认 |
+|---|---|---|---|
+| 模板目录 | — | `DSH_PLUGIN_DEV_TEMPLATES` | `<package>/templates` |
+| dsh 二进制 | `--dsh` | `DSH_PLUGIN_DEV_DSH` | `dsh` |
+| pnpm 二进制 | `--pnpm` | `DSH_PLUGIN_DEV_PNPM` | `pnpm` |
+| 安装/打包超时 | `--timeout` | `DSH_PLUGIN_DEV_TIMEOUT` | `300000` ms |
+| headless 冒烟超时 | `--smoke-timeout` | `DSH_PLUGIN_DEV_SMOKE_TIMEOUT` | `120000` ms |
+
+### Upstream roadmap
+
+`dsh-plugin-dev` 是官方插件开发 CLI（规划项 C12）的上游候选：脚手架/检查器/验证器是机械层，`SKILL.md` + `guide/` 仍是认知层。
+
 ## Quick start
 
 ```sh
@@ -68,6 +103,14 @@ dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-guide'
 
 然后直接问你的 agent：*"用 dsh-plugin-guide 技能帮我构建一个 … 插件。"*
 
+或者直接驱动 CLI：
+
+```sh
+npx dsh-plugin-guide new hello-plugin            # 脚手架生成 TS 插件仓库
+npx dsh-plugin-guide check --json                # 静态检查
+npx dsh-plugin-guide verify                      # 打包 + 干净 profile 冒烟
+```
+
 ## Install & uninstall
 
 - **git channel**（最新 `main`）：`dsh plugin --profile web add github:PerryLink/dsh-plugin-guide#<sha>` —— 固定提交以可复现；入口是纯 ESM JS，无构建步骤。
@@ -94,13 +137,14 @@ pwsh -File scripts/install-skill.ps1 -Target ~/.deepseek/skills/dsh-plugin-guide
 
 ## Configuration
 
-`dsh-plugin-guide` 不暴露任何 Schemastery `Config` —— 它把知识库注册为 agent 技能，无可调键。
+技能 bundle 不暴露任何 Schemastery `Config` —— 它把知识库注册为 agent 技能，无可调键。`dsh-plugin-dev` CLI 从 flag 与 `DSH_PLUGIN_DEV_*` 环境变量读取可调项（见 [CLI toolchain](#cli-toolchain)）。
 
 ## Tools & surfaces
 
 | Surface | Kind | Notes |
 |---|---|---|
 | `dsh-plugin-guide` | skill | 经 `ctx.skills` 注册；按需加载 `SKILL.md` + `./guide/` + `./references/` |
+| `dsh-plugin-dev` | bin (CLI) | `new` / `check` / `verify` 子命令；非 DSH 插件行 |
 
 ## Permissions & data
 
@@ -133,9 +177,16 @@ pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>        # 关键路径 +
 
 ## Development
 
-bundle 是纯 ESM —— 无构建步骤。CI 在每次 push 与 pull request 运行完整性门禁：
+技能 bundle（`index.js`）是纯 ESM、无构建步骤；`dsh-plugin-dev` CLI 是 TypeScript，经 tsdown 构建。门禁：
 
 ```sh
+pnpm install --frozen-lockfile
+pnpm run typecheck && pnpm run typecheck:ci
+pnpm test
+pnpm run build
+pnpm run verify:artifacts        # 自检 + 脚手架冒烟（无网络）
+pnpm run verify:self-contained   # 打包 + 干净 profile 安装/启动/卸载冒烟
+pnpm pack
 pwsh -File scripts/verify-kit.ps1   # 关键路径 + 链接扫描（加 -Checkout <checkout> 做文档漂移）
 ```
 

package/SKILL.md

@@ -62,8 +62,18 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 - 安装/刷新 agent 技能副本：`pwsh -File ./scripts/install-skill.ps1 -Target <skill目录>`（跳过 downloads/ 与 .github/，逐字节校验）。
 - 冲突裁决：与官方文档冲突时以 `references/official-docs/`（官方仓库原文）为准。
 
+## CLI 工具链（dsh-plugin-dev）
+
+本仓库随 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）；失败给出日志尾部与建议。
+
+三个子命令均可逆/幂等；网络/子进程尊重超时与 AbortSignal；只清理自己 mkdtemp 的目录。CLI 零运行时依赖，构建产物经 tsdown 打包为单文件 `dist/dsh-plugin-dev.js`。
+
 ## 边界
 
-- 本技能是"指引 + 约束 + 资料索引"，不是脚本/清单的机械执行；精确 API 以生成式参考为准。
+- 本技能是"指引 + 约束 + 资料索引"；机械检查由 `dsh-plugin-dev check` 承担，精确 API 以生成式参考为准。
 - 不得修改知识库外的 harness 仓库文件，除非用户明确要求；vendor/ 与 `.agents/notes/archived/` 只读。
 - 引用 `downloads/` 内容前先确认其存在（该目录不入 git，需按上文脚本生成）；`awesome-dsh-plugins` 的归档仅供本地参考，**不得随仓库再分发**（其上游声明内部使用约束，见 NOTICE.md）。

package/bin/dsh-plugin-dev.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// dsh-plugin-dev CLI entry shim. The real implementation is the tsdown-bundled
+// `dist/dsh-plugin-dev.js` (built by `pnpm run build` / `prepack`). Keeping this
+// shim as a stable path lets the bin stay fixed while the bundle filename may
+// change across tsdown versions.
+import '../dist/dsh-plugin-dev.js'

package/cordis.patch.yml

@@ -1,4 +1,9 @@
 # dsh-plugin-guide bundle layer: register the packaged knowledge base as an agent skill.
+# This file is the `dsh.bundle.patch` layer (see package.json#dsh.bundle.patch).
+# Layer semantics: a YAML array of row verbs; `insert` adds plugin rows to the
+# composed config. Later layers override a row by `id` (whole-config replacement).
 - insert:
+    # `id`: stable row identifier used by later layers to override this row.
     - id: dsh-plugin-guide
+      # `name`: the module the loader imports; resolves to this package's entry (package.json#main → index.js).
       name: dsh-plugin-guide