dsh-plugin-guide 0.3.23 → 0.3.25

package/README-es.md

@@ -179,6 +179,17 @@ El bundle de skill no expone ningún `Config` de Schemastery — registra la bas
 - **`downloads/` es generado, no confirmado.** Las instantáneas crudas (archivos de repos de la comunidad, Discussions, artículos) deben generarse con los scripts antes de usarse.
 - **El contenido de `awesome-dsh-plugins` es solo local.** Su upstream declara una restricción de uso interno, por lo que no se redistribuye con el repo.
 
+## Release channels
+
+Todos los canales resuelven desde este repositorio o desde npm, así que **una etiqueta llega a todos**; solo el espejo de Gitee es una copia programada:
+
+| Canal | Fuente de verdad | Cómo se actualiza |
+|---|---|---|
+| npm (`dsh-plugin-guide`) | el `package.json` de este repositorio | `.github/workflows/release.yml` en una etiqueta `v*`: puerta `verify-kit` → comprobación de la sección del CHANGELOG → `npm publish --provenance` (se omite si la versión ya existe) |
+| GitHub Release | la misma etiqueta | el mismo workflow la crea de forma idempotente |
+| Insignias de descubrimiento (versión npm, etiqueta de GitHub, DSH Market, dsh-doctor) | consultas en vivo | no hay nada que publicar: leen npm/el registro en cada render |
+| Espejo de Gitee | este repositorio | **espejo programado de solo lectura**, no un destino de publicación: el workflow `gitee-sync` de la familia lo alinea al tip de GitHub con `--force-with-lease`, así que `main` suele ir una ejecución programada por detrás. **Aquí nunca se empuja una etiqueta a Gitee**; compara con `git ls-remote` antes de reportar el espejo como obsoleto |
+| DSH Desktop Market / dsh1024 | npm | el mercado instala el paquete de npm, así que una versión publicada es instalable de inmediato; no hay envío por versión |
 ## Keeping it fresh
 
 ```sh

package/README-hi.md

@@ -179,6 +179,17 @@ skill बंडल कोई Schemastery `Config` उजागर नहीं
 - **`downloads/` उत्पन्न है, कमिट नहीं।** कच्चे स्नैपशॉट (सामुदायिक रेपो संग्रह, Discussions, लेख) उपयोग से पहले स्क्रिप्ट से उत्पन्न करने चाहिए।
 - **`awesome-dsh-plugins` सामग्री केवल स्थानीय है।** इसका अपस्ट्रीम आंतरिक-उपयोग प्रतिबंध घोषित करता है, इसलिए इसे रेपो के साथ पुनर्वितरित नहीं किया जाता।
 
+## Release channels
+
+हर channel इस repo या npm से resolve होता है, इसलिए **एक tag सब जगह पहुँच जाता है**; केवल Gitee mirror एक शेड्यूल्ड कॉपी है:
+
+| Channel | सत्य-स्रोत | कैसे अपडेट होता है |
+|---|---|---|
+| npm (`dsh-plugin-guide`) | इस repo का `package.json` | `v*` tag पर `.github/workflows/release.yml`: `verify-kit` गेट → CHANGELOG में उस संस्करण का section जाँच → `npm publish --provenance` (संस्करण पहले से हो तो छोड़ देता है) |
+| GitHub Release | वही tag | वही workflow इसे idempotent तरीके से बनाता है |
+| Discovery बैज (npm version, GitHub tag, DSH Market, dsh-doctor) | लाइव lookup | प्रकाशित करने को कुछ नहीं — हर render पर npm/registry पढ़ते हैं |
+| Gitee mirror | यह repo | **read-only शेड्यूल्ड mirror**, प्रकाशन लक्ष्य नहीं: परिवार का `gitee-sync` workflow इसे `--force-with-lease` से GitHub tip पर align करता है, इसलिए `main` सामान्यतः एक शेड्यूल्ड रन पीछे रहता है। **यहाँ से Gitee पर tag कभी push नहीं होता**; mirror को पुराना बताने से पहले `git ls-remote` से तुलना करें |
+| DSH Desktop Market / dsh1024 | npm | market npm पैकेज इंस्टॉल करता है, इसलिए प्रकाशित संस्करण तुरंत इंस्टॉल-योग्य है; प्रति-संस्करण सबमिशन नहीं |
 ## Keeping it fresh
 
 ```sh

package/README-pt.md

@@ -179,6 +179,17 @@ O bundle de skill não expõe nenhum `Config` de Schemastery — ele registra a
 - **`downloads/` é gerado, não commitado.** As instantâneas cruas (arquivos de repos da comunidade, Discussions, artigos) devem ser geradas com os scripts antes do uso.
 - **O conteúdo de `awesome-dsh-plugins` é somente local.** Seu upstream declara uma restrição de uso interno, então não é redistribuído com o repo.
 
+## Release channels
+
+Todos os canais resolvem deste repositório ou do npm, então **uma tag chega a todos**; só o espelho do Gitee é uma cópia agendada:
+
+| Canal | Fonte da verdade | Como atualiza |
+|---|---|---|
+| npm (`dsh-plugin-guide`) | o `package.json` deste repositório | `.github/workflows/release.yml` numa tag `v*`: portão `verify-kit` → verificação da seção do CHANGELOG → `npm publish --provenance` (ignorado quando a versão já existe) |
+| GitHub Release | a mesma tag | o mesmo workflow a cria de forma idempotente |
+| Selos de descoberta (versão npm, tag do GitHub, DSH Market, dsh-doctor) | consultas ao vivo | nada a publicar — leem o npm/o registro a cada render |
+| Espelho do Gitee | este repositório | **espelho agendado somente leitura**, não um destino de publicação: o workflow `gitee-sync` da família o alinha ao tip do GitHub com `--force-with-lease`, então `main` costuma ficar uma execução atrás. **Aqui nunca se envia tag ao Gitee**; compare com `git ls-remote` antes de reportar o espelho desatualizado |
+| DSH Desktop Market / dsh1024 | npm | o mercado instala o pacote do npm, então uma versão publicada é instalável de imediato; não há envio por versão |
 ## Keeping it fresh
 
 ```sh

package/README-zh.md

@@ -181,6 +181,17 @@ pwsh -File scripts/install-skill.ps1 -Target ~/.deepseek/skills/dsh-plugin-guide
 - **`downloads/` 由脚本生成、不入库。** 原始快照（社区仓库归档、Discussions、文章）使用前需用脚本生成。
 - **`awesome-dsh-plugins` 内容仅本地。** 其上游声明内部使用约束，故不随仓库再分发。
 
+## Release channels
+
+所有渠道都从本仓库或 npm 解析，因此**推一个 tag 就能到所有渠道**；只有 Gitee 镜像是定时拷贝：
+
+| 渠道 | 真源 | 更新方式 |
+|---|---|---|
+| npm（`dsh-plugin-guide`） | 本仓库的 `package.json` | `v*` tag 触发 `.github/workflows/release.yml`：`verify-kit` 门禁 → 校验 CHANGELOG 有该版本段 → `npm publish --provenance`（版本已存在则跳过） |
+| GitHub Release | 同一个 tag | 同一 workflow 幂等创建 |
+| 展示徽章（npm 版本、GitHub tag、DSH Market、dsh-doctor） | 实时查询 | 无需发布——每次渲染都读 npm/registry |
+| Gitee 镜像 | 本仓库 | **只读定时镜像**，不是发布目标：由家族仓的 `gitee-sync` workflow 用 `--force-with-lease` 强制对齐 GitHub tip，所以 `main` 通常落后一次定时运行。**这里从不对 Gitee 推 tag**；报"镜像过期"前先用 `git ls-remote` 与 GitHub 对比 |
+| DSH Desktop Market / dsh1024 | npm | 市场装的就是 npm 包，发布即可安装，无需逐版本投稿 |
 ## Keeping it fresh
 
 ```sh

package/README.md

@@ -189,6 +189,18 @@ The skill bundle exposes no Schemastery `Config` — it registers the knowledge
 - **`downloads/` is generated, not committed.** Raw snapshots (community repo archives, Discussions, articles) must be generated with the scripts before use.
 - **`awesome-dsh-plugins` content is local-only.** Its upstream declares an internal-use constraint, so it is not redistributed with the repo.
 
+## Release channels
+
+Every channel resolves from this repository or from npm, so one tag reaches all of them; only the Gitee mirror is a scheduled copy:
+
+| Channel | Source of truth | How it updates |
+|---|---|---|
+| npm (`dsh-plugin-guide`) | this repo's `package.json` | `.github/workflows/release.yml` on a `v*` tag: `verify-kit` gate → CHANGELOG section check → `npm publish --provenance` (skipped when the version already exists) |
+| GitHub Release | the same tag | the same workflow creates it idempotently from the tag |
+| Discovery badges (npm version, GitHub tag, DSH Market, dsh-doctor) | live lookups | nothing to publish — they read npm/the registry on each render |
+| Gitee mirror | this repo | a **read-only scheduled mirror**, not a publish target: it is force-aligned to the GitHub tip (`--force-with-lease`) by the family's `gitee-sync` workflow, so `main` is normally one scheduled run behind. Gitee never receives a tag push from here; compare `git ls-remote` against GitHub before reporting the mirror stale |
+| DSH Desktop Market / dsh1024 | npm | the market installs the npm package, so a published version is immediately installable; no per-version submission |
+
 ## Keeping it fresh
 
 ```sh

package/dist/dsh-plugin-dev.js

@@ -140,9 +140,16 @@ function isDir(path) {
 * `{{dshPeerRange}}` placeholder. Keep it identical to the canonical range in
 * `dsh-plugin-kit/data/peer-range.json`: one clause per prerelease tuple is
 * required by semver's prerelease rule, and the `-0` floor covers the whole
-* 0.1.6 tuple (never the bare `>=0.1.6` form).
+* tuple (never a bare `>=0.2.0` form, which semver's prerelease rule would
+* reject for `0.2.1-alpha.1`).
+*
+* The 0.2 line is load-bearing: `dsh` enforces peer ranges at install time and
+* rejects any plugin whose declared range excludes the running runtime, so a
+* range that stops at 0.1.x makes every scaffolded plugin uninstallable on a
+* 0.2.x harness (`installation rejected: ... is incompatible with dsh
+* 0.2.1-alpha.1`).
 */
-const DSH_PEER_RANGE = ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0";
+const DSH_PEER_RANGE = ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0";
 /** Resolve the templates root: env override first, then candidate walks. */
 function resolveTemplatesRoot() {
 	const env = process.env.DSH_PLUGIN_DEV_TEMPLATES;
@@ -1605,6 +1612,22 @@ async function initGit(targetDir) {
 
 //#endregion
 //#region src/cli/commands/verify.ts
+/**
+* The verified harness line `verify` installs into its throwaway profile.
+*
+* Keep these in lockstep with `.github/workflows/compat.yml`, which installs the
+* same versions. `dsh` rejects an incompatible plugin/base pair at install time,
+* so a stale pin turns `verify` into a failure that names the *base bundle*
+* rather than the plugin under test:
+*
+*   dsh: installation rejected: Plugin @deepseek-ai/dsh-headless@<old> is
+*   incompatible with dsh <new>
+*
+* `tests/verify.test.ts` asserts these match compat.yml, so the two cannot drift
+* apart silently again. Override per run with `--base` / `--headless`.
+*/
+const VERIFY_BASE_SPEC = "@deepseek-ai/dsh-base@0.2.1-alpha.1";
+const VERIFY_HEADLESS_SPEC = "@deepseek-ai/dsh-headless@0.2.1-alpha.1";
 const PROFILE_WORKSPACE = `# scratch profile allowlist (mirrors the repo's compat workflow)
 packages:
   - .
@@ -1794,21 +1817,38 @@ function suggestionsFor(step, result) {
 	const base = [`tail of "${step}":\n${tailOf(result)}`];
 	if (result.timedOut) base.push(`command timed out; raise --timeout or --smoke-timeout`);
 	if (step === "install") {
-		base.push("ensure the dsh CLI is @deepseek-ai/dsh@0.1.7-rc.2 (older builds such as the rc.6 line do not satisfy the compat pin)");
+		base.push("ensure the dsh CLI is @deepseek-ai/dsh@0.2.1-alpha.1 (older builds such as the rc.6 line do not satisfy the compat pin)");
 		base.push("confirm the profile allowlist matches the repo compat workflow (native builds allowlisted)");
 	}
 	if (step === "headless") base.push("a hang usually means an injected service stayed pending; the smoke timeout surfaces exactly that");
 	return base;
 }
+/** Error signatures a headless smoke prints only *after* the tree loaded. */
+const SMOKE_LOADED_SIGNATURES = [
+	"MISSING_CREDENTIAL",
+	"TRANSPORT:",
+	"transport failed",
+	"UNAUTHORIZED",
+	"invalid api key",
+	"API key is invalid"
+];
 /**
-* True when a headless smoke run proves the plugin tree loaded: keyless runs
-* print `MISSING_CREDENTIAL` (on stderr), keyed runs print `ok`.
+* True when a headless smoke run proves the plugin tree loaded. Three accepted
+* outcomes, all of which require that the tree mounted and the turn dispatched:
+* a keyless run printing `MISSING_CREDENTIAL`, a keyed run printing `ok`, or a
+* keyed run whose provider call failed at the transport/auth layer.
+*
+* The third case is not a fallback for a broken plugin: a plugin that never
+* mounted produces no provider traffic at all, so it prints none of these
+* signatures and still fails this check.
+*
 * @param stdout - captured stdout.
 * @param stderr - captured stderr.
 */
 function isSmokeOk(stdout, stderr) {
 	const text = `${stdout}\n${stderr}`;
-	return text.includes("MISSING_CREDENTIAL") || /(^|[^a-z])ok([^a-z]|$)/i.test(text);
+	if (SMOKE_LOADED_SIGNATURES.some((signature) => text.includes(signature))) return true;
+	return /(^|[^a-z])ok([^a-z]|$)/i.test(text);
 }
 /** Resolve the dsh binary: explicit flag/env first, then PATH `dsh`. */
 function resolveDsh(flag) {
@@ -1915,8 +1955,8 @@ async function main(argv, cwd = process.cwd()) {
 					dshBin: resolveDsh(flagString(flags, "dsh")),
 					pnpmBin: resolvePnpm(flagString(flags, "pnpm")),
 					profile: flagString(flags, "profile", "compat") ?? "compat",
-					base: flagString(flags, "base", "@deepseek-ai/dsh-base@0.1.7-rc.2") ?? "@deepseek-ai/dsh-base@0.1.7-rc.2",
-					headless: flagString(flags, "headless", "@deepseek-ai/dsh-headless@0.1.7-rc.2") ?? "@deepseek-ai/dsh-headless@0.1.7-rc.2",
+					base: flagString(flags, "base", "@deepseek-ai/dsh-base@0.2.1-alpha.1") ?? "@deepseek-ai/dsh-base@0.2.1-alpha.1",
+					headless: flagString(flags, "headless", "@deepseek-ai/dsh-headless@0.2.1-alpha.1") ?? "@deepseek-ai/dsh-headless@0.2.1-alpha.1",
 					timeoutMs: timeoutMs(flags, "timeout", "DSH_PLUGIN_DEV_TIMEOUT", DEFAULT_TIMEOUT_MS),
 					smokeTimeoutMs: timeoutMs(flags, "smoke-timeout", "DSH_PLUGIN_DEV_SMOKE_TIMEOUT", DEFAULT_SMOKE_TIMEOUT_MS)
 				});

package/guide/migration-0.2.md

@@ -20,7 +20,7 @@
 | npm `alpha` / `next` | `alpha`=`0.2.1-alpha.1`、`next`=`0.2.0-rc.2` |
 | 区间内发布线（9 个） | `0.1.6-alpha.2`(09-17) → `0.1.7-alpha.1`(09-22) → `0.1.5-rc.3`(09-22) → `0.1.7-alpha.2`(09-22) → `0.1.7-rc.1`(09-23) → `0.1.7-rc.2`(09-24) → `0.2.0-rc.1`(09-28) → `0.2.0-rc.2`(09-29) → `0.2.1-alpha.1`(10-03) |
 | Node 门槛 | `^22.19.0 \|\| >=24.0.0`，**区间内未变**（无 `.nvmrc`/`.node-version` 文件） |
-| `dsh.version` 字段 | **不存在**。DSH 的包清单只有 `dsh.bundle` / `dsh.profile` / `dsh.client` 三组键，且官方明确"不校验 peer 版本范围"——声明的 peer 范围只是文档意图，**不是加载期门禁** |
+| `dsh.version` 字段 | **不存在**。DSH 的包清单只有 `dsh.bundle` / `dsh.profile` / `dsh.client` 三组键 |
 | 官方发布说明在哪 | 仓库里**没有 `CHANGELOG.md`**、也没有 `docs/persistence-changes/releases/*` 新条目，所以逐版本说明只在 GitHub **Releases** 的 body 里（`gh release view <tag>` 或 Releases API）。本文件的每一条都对照过 tag `dsh-v0.1.7-alpha.1` / `dsh-v0.2.0-rc.2` / `dsh-v0.2.1-alpha.1` 的发布说明 |
 
 **官方 0.1.7-alpha.1 发布说明里点名的四条插件必改**（原文"其他变更"段）：Session 日志升级 V4、工作区文件读取统一为 `readBytes`（旧接口必须迁移）、官方 DeepSeek 适配器**只用 Messages API**（移除 Chat Completions 与 `protocol` 选项）、设置改由当前 Profile 的插件配置保存（旧 `settings.yaml` 只尝试导入一次）。同版本还改了：Agent 预设改由插件组合包声明/安装（旧目录预设需迁移）、组合包支持按序多 patch、插件可声明"无需重载的配置字段"、新增 `--dump-config-schema`、插件可用 locale 声明多语言标题描述 + `package.json` 图标。
@@ -29,7 +29,7 @@
 
 **npm 陷阱（最贵的一条）**：库包（`dsh-tools`、`dsh-base`、`dsh-headless`、`dsh-session-persistence-jsonl`、`dsh-session`、`dsh-settings`、`dsh-workflow` …）的 `latest` 至今钉在 **`0.0.1-rc.1`**。写 `"@deepseek-ai/dsh-session": "latest"` 会装到远古版本；必须写死版本或钉 `next`/`alpha`。唯一的例外是 CLI 包 `@deepseek-ai/dsh`（`latest`=`0.2.0-rc.2`）。
 
-**跨线 peer 范围**：`^0.1.x` 与 `^0.2.x` 互不覆盖，要同时支持两条线必须写两侧范围（本知识库自身用 `>=0.1.2-rc.1 <0.3.0`）。因为 DSH 不校验范围，真正的兼容手段是**运行时特性探测**。
+**跨线 peer 范围**：`^0.1.x` 与 `^0.2.x` 互不覆盖，要同时支持两条线必须写两侧范围。⚠️ **peer 范围会被安装期强制**（本节早期版本写成"DSH 不校验范围"，已更正）：`dsh plugin add` 会拿运行时的版本去比插件声明的 peer 范围，不匹配就**拒绝安装**并把声明的范围原样打印出来。跨线支持因此必须**在范围里同时列出两侧的 prerelease 元组**（每个元组一个 clause），否则 0.2.x 宿主装不上——详见 [plugin-dev-guide.md](plugin-dev-guide.md) §7.3 的 `dsh-plugin` 段。范围之外仍要配**运行时特性探测**，因为范围只能表达"能不能装"，表达不了"某个 API 在不在"。
 
 ## 2. 会话格式 V3 → V4（影响最深，涉及历史日志）
 
@@ -84,7 +84,7 @@
 
 - `dsh.bundle.patch` 现在接受**有序数组**：`{ "patch": ["./base.patch.yml", "./web.patch.yml"] }`，按序作为同一层应用，且每个文件里的相对插件路径**相对该文件所在目录**解析。校验失败信息：`dsh.bundle.patch must be a file path or a list of file paths`。
 - 层顺序未变：`dsh.profile.bundles` 顺序 → profile 自己的 `cordis.patch.yml` → `$DSH_HOME/cordis.patch.yml` → 各 `--patch`（argv 顺序）。**按 id 覆盖时整段 `config` 被替换，不做深合并。**
-- 包清单还可以声明 `dsh.manifestVersion`（格式标识，当前 `1`，与 npm 版本、会话格式版本无关）与 `engines.dsh`（作者声明的兼容范围，**当前安装器/加载器都不强制**）。类型定义见 `@deepseek-ai/dsh-package-manifest`。
+- 包清单还可以声明 `dsh.manifestVersion`（格式标识，当前 `1`，与 npm 版本、会话格式版本无关）与 `engines.dsh`（作者声明的兼容范围，**当前安装器/加载器都不强制**——真正会被强制的是 `@deepseek-ai/dsh-*` 的 **peerDependencies**，安装期即拒绝不匹配者，见 [plugin-dev-guide.md](plugin-dev-guide.md) §7.3）。类型定义见 `@deepseek-ai/dsh-package-manifest`。
 - 展示元数据契约（Plugin Manager / Settings 在**不激活插件**的前提下读取）：包根读 `package.json` 的 `name`/`description`/`icon`，或导出 `./locale/*.json` 的 `meta.title`/`meta.description` 与 `./icon`；图标支持 SVG/PNG/JPEG/WebP，**≤ 256 KiB 且必须落在包内**（绝对路径、URL、指向包外的 symlink 都被拒）。子路径插件**永远不读** `<subpath>/package.json`——标题/描述走 `locale/*.json` 的 `meta.*`，图片走导出的 `<subpath>/icon`。
 - `dsh.client` 键**未变**：`platform`（web）、`inject`（仅排序，不是 cordis 服务注入）、`immediately`（一阶段预取）、`external`（基线与注入边之外的精确模块请求）。但客户端半侧只挂在**说明符恰为裸包名**的那一行上：把一个包拆成多行的组合包，其 UI 只随根行启停。
 

package/guide/plugin-dev-guide.md

@@ -76,7 +76,7 @@ export function apply(ctx: Context) {
 - **bundle（分发层）**：npm 包，`package.json` 声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`；patch 里是"插入/覆盖插件行"的 YAML 数组。**`patch` 也可以是有序数组**：`{ "patch": ["./base.patch.yml", "./web.patch.yml"] }`，按序作为同一层应用，且每个文件里的相对插件路径**相对该文件所在目录**解析（校验失败信息：`dsh.bundle.patch must be a file path or a list of file paths`）。
 - **profile（可运行组合）**：`$DSH_HOME/profiles/<name>/`，`package.json` 声明 `"dsh": { "profile": { "bundles": [...] } }`；由 `dsh plugin` / `plugin_manager` 维护，手写不允许。
 - **client（浏览器半侧）**：`package.json` 声明 `"dsh": { "client": { "platform": "web", "inject": [...], "immediately": true, "external": [...] } }` 并导出编译好的 `./client`。`inject` **只决定激活顺序**（不是 cordis 服务注入），`immediately` 标记一阶段预取，`external` 列出基线之外的精确模块请求。客户端半侧只挂在**说明符恰为裸包名**的那一行上。
-- 另有两个可选作者字段：`dsh.manifestVersion`（清单格式标识，当前 `1`，与 npm 版本、会话格式版本无关）与 `engines.dsh`（兼容范围声明，**当前安装器/加载器都不校验**）。类型定义来自 `@deepseek-ai/dsh-package-manifest`。
+- 另有两个可选作者字段：`dsh.manifestVersion`（清单格式标识，当前 `1`，与 npm 版本、会话格式版本无关）与 `engines.dsh`（兼容范围声明，**当前安装器/加载器都不校验**；会被校验的是 `@deepseek-ai/dsh-*` 的 peerDependencies，见 §7.3）。类型定义来自 `@deepseek-ai/dsh-package-manifest`。
 
 bundle 最小结构：
 
@@ -394,6 +394,7 @@ Plugin Manager 与 Settings 会**在不激活插件的前提下**读展示信息
 - `files` 必须包含 patch、locale、图标与**每个运行时文件**——但**本地目录安装是链接 checkout，`files` 不过滤链接目录**，要直接核对文件；
 - **子路径插件（`my-plugins/search`）不是包，永远不读 `package.json`**：标题/描述走 `my-plugins/search/locale/*.json` 的 `meta.*`，图片走导出的 `my-plugins/search/icon`。
 - 可选作者字段：`dsh.manifestVersion`（当前 `1`）与 `engines.dsh`（**当前不校验**，只作声明）。类型来自 `@deepseek-ai/dsh-package-manifest`。
+- **真正会被强制的是 peerDependencies**（见 §7.3）：`dsh plugin add` 会用运行时的版本比对插件声明的 `@deepseek-ai/dsh-*` 范围，不匹配即**拒绝安装**。
 
 ### 7.1 从 GitHub 安装的 build-script 坑
 
@@ -420,7 +421,28 @@ bundle 挂一个普通 provider 插件：`inject = ['cmdlineArgs']`，用 `@deep
 - **cordis 双副本 / 双 Cordis 分裂**：插件构建时若从 `.pnpm` 副本解析 cordis，与 harness 的 vendored 副本是"两个模块"，`declare module` 增强合并不了 → 报 `Property 'tools' does not exist on type 'Context'`。构建期把 cordis 解析到 harness 的 `vendor/cordis`；npm 安装路径下 peer 必须与宿主同一身份——**scoped `@deepseek-ai/cordis` 与 unscoped `cordis` 混用同样分裂**（dsh-tools 的类型只增强 scoped 版本）。独立包把 cordis 设为 peerDependency（+ dev），版本对齐宿主。
 - **官方 `@deepseek-ai/*` 包曾未发布公共 npm**（rc 早期）：社区 bundle 的 `dependencies` 留空，靠 profile 的 pnpm 闭包 flat fallback（`$DSH_HOME/profiles/node_modules`）注入；声明了反而解析失败。rc.6 起公开包可用（from-scratch 教程锁 `0.1.0-rc.6`、cordis `4.0.1`），两条时间线的资料都要知道，按当时宿主版本取舍。
 - **npm `latest` 标签是过期版本**：库包（`dsh-tools`、`dsh-base`、`dsh-headless`、`dsh-session-persistence-jsonl`、`dsh-settings`、`dsh-workflow` …）的 `latest` **至今**钉在 `0.0.1-rc.1`，所以写 `"latest"` 会装到远古版本，必须写死版本或钉 `next`/`alpha`。**2026-10-06 复核**：`@deepseek-ai/dsh` `latest`=`next`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.1`；dsh-tools / dsh-base / dsh-headless / dsh-session-persistence-jsonl 的 `latest` 仍 `0.0.1-rc.1`、`next`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.1`；`@deepseek-ai/cordis` `latest`=4.0.4 并有新标签 `dsh-0-2-1-alpha-1`=4.0.5-alpha.1；`@deepseek-ai/schemastery` `latest`=3.18.4；`create-dsh-plugin` `latest`=0.2.3；dsh-core、dsh-sdk 仍 404。历史两次复核（2026-08-14 与 09-04）的数值保留在上一条记录里，可见"`latest` 陷阱"从 rc 早期持续到 0.2 世代。**无作用域 `dsh` 包是无关项目 node-dsh**（"A shell written in JavaScript"）——官方 CLI 包是 `@deepseek-ai/dsh`，别装错。
-- **profile 内安装的 `@deepseek-ai/*` 会静默遮蔽运行时自带版本**（解析优先级 `profile > runtime`）：把共享实例的 dsh 包写进 **dependencies** 是错的做法——pnpm 会把它装进 profile，盖掉宿主自带的版本，然后核心服务注册失败（实测 `settings service is absent: mount @deepseek-ai/dsh-settings with @deepseek-ai/dsh-config-editor`，桌面端每次崩溃）。**共享实例的 dsh 包只放 `peerDependencies` + `devDependencies`**；独立版本演进或纯工具型包才放 `dependencies`。另注意 **DSH 不校验 peer 版本范围**（官方明文），peer 范围只是声明意图，真正的兼容要靠运行时探测。
+- **profile 内安装的 `@deepseek-ai/*` 会静默遮蔽运行时自带版本**（解析优先级 `profile > runtime`）：把共享实例的 dsh 包写进 **dependencies** 是错的做法——pnpm 会把它装进 profile，盖掉宿主自带的版本，然后核心服务注册失败（实测 `settings service is absent: mount @deepseek-ai/dsh-settings with @deepseek-ai/dsh-config-editor`，桌面端每次崩溃）。**共享实例的 dsh 包只放 `peerDependencies` + `devDependencies`**；独立版本演进或纯工具型包才放 `dependencies`。
+- ⚠️ **peer 范围会被安装期强制**（本节早期版本写成"DSH 不校验 peer 版本范围"，**已更正**）：`dsh plugin add` 用运行时版本比对插件声明的 `@deepseek-ai/dsh-*` 范围，不匹配即**拒绝安装**，打印声明的范围并给出豁免命令。实测原文：
+
+  ```
+  dsh: installation rejected: Plugin dsh-nurse-record-check@0.1.0 is incompatible with
+  dsh 0.2.1-alpha.1: peerDependencies {"@deepseek-ai/dsh-tools":">=0.1.2-rc.1 <0.2.0 || …"}.
+  To accept this risk explicitly, grant the exact-version exemption for
+  dsh-nurse-record-check@0.1.0 on dsh 0.2.1-alpha.1 with `dsh plugin allow-version` or the
+  plugin manager, then retry the installation or restart dsh.
+  ```
+
+  两个后果：① 范围**少列一个 0.2.x 的 prerelease 元组**，插件在 0.2.x 宿主上就装不上（拦在安装期，不是运行期）；② 用**旧版本宿主**打的 tarball 用新版本 `verify` 跑，报错会指向 base bundle 而不是你的插件（`dsh-plugin-dev verify` 的 `--base`/`--headless` 默认值因此必须与 compat workflow 同步）。
+- **豁免机制**（被拒后唯一的出路，可用 `dsh plugin --profile <p> --help` 复核）：
+
+  ```sh
+  dsh plugin --profile <profile> version-exemptions              # 列出已授予的豁免
+  dsh plugin --profile <profile> allow-version <pkg@version> \
+      --dsh-version <runtime> --accept-risk                      # 授予精确版本豁免
+  dsh plugin --profile <profile> revoke-version <pkg@version>    # 撤销
+  ```
+
+  豁免是**按 `<包@精确版本> × <宿主版本>` 的精确配对**（不是范围），所以宿主升级后要重新授予。`plugin_manager` 工具面里有对应入口，Web 侧边栏与插件管理页也能授予。**给用户写 README 排错节时把这三条命令抄进去**——这是被拒绝安装时用户唯一能自救的手段。
 - **`file:` 安装载入的是副本**：`dsh plugin add file:../my-plugin` 之后，profile 的 `node_modules` 下是**拷贝**（`nodeLinker: hoisted` + 锁文件只记 `version: file:<path>`），所以**改源码不生效、`update` 是 no-op**——只有 `remove` + `add` 才会重装。调试期要频繁改就用 `--patch` 直挂源码目录，或每次显式重装。
 
 **tsconfig 三件套 + 构建陷阱**
@@ -482,7 +504,7 @@ bundle 挂一个普通 provider 插件：`inject = ['cmdlineArgs']`，用 `@deep
 ## 9.1 版本兼容与迁移（0.2 世代必读）
 
 - **先认版本**：`dsh --version`。`0.1.7-alpha.1` 起包含本世代全部破坏性变更（会话格式 V4）。npm 上 `latest`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.1`，而 master 最新 tag 是 `0.2.1-alpha.1`——**三个"最新"不是一个东西**。
-- **peer 范围写两侧**（如 `>=0.1.2-rc.1 <0.3.0`），但要记住 **DSH 不校验它**；真正的兼容靠运行时探测与发版纪律。
+- **peer 范围要写全两侧的 prerelease 元组**（如 `>=0.1.2-rc.1 <0.2.0 || … || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0`）。⚠️ **这个范围会被安装期强制**，不是文档意图：`dsh plugin add` 用运行时版本比对它，不匹配就拒绝安装并打印你声明的范围。所以少一个 0.2.x clause，插件在 0.2.x 宿主上**根本装不上**（拦在安装期，不是运行期）。范围之外仍要靠运行时特性探测——范围只表达"能不能装"，表达不了"某个 API 在不在"。
 - **共享实例的 dsh 包只放 peer + dev**，绝不放 dependencies（否则 profile 内副本会遮蔽运行时版本）。
 - **升级后必做**：`dsh --profile <name> --dump-config` 看有没有 `patch: entry <id> not found`（上游删行/改名后，你的 override 会**静默失效**）；再跑一次真实能力。
 - **逐项迁移清单**：见 [migration-0.2.md](migration-0.2.md)（含会话格式 V4、settings 重写、invariants 删除、`readBytes`、客户端 slot/Remote 改名、`agent.inject()` 的 source 包装退役、preset 分叉等全部条目与官方原文出处）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "description": "The dsh-plugin-guide knowledge base plus the dsh-plugin-dev CLI toolchain: official docs, Cordis primer, community deep-dives, and battle-tested pitfalls registered as an on-demand agent skill, with a scaffolder, static checker, and pack verifier for building DSH plugins.",
   "type": "module",
   "main": "index.js",
@@ -23,7 +23,8 @@
     "icon.svg",
     "SKILL.md",
     "guide",
-    "references",    "scripts",
+    "references",
+    "scripts",
     "LICENSE",
     "NOTICE.md",
     "README.md",
@@ -70,6 +71,8 @@
   "devDependencies": {
     "@deepseek-ai/dsh-attachment": "0.2.1-alpha.1",
     "@types/node": "^22.20.1",
+    "@types/semver": "^7.8.0",
+    "semver": "^7.8.5",
     "vitest": "^3.2.7"
   },
   "peerDependencies": {
@@ -110,8 +113,14 @@
       "filesystem:read"
     ],
     "compatibility": {
-      "dshVersions": ["0.1.2-rc.1","0.1.5-rc.2","0.1.7-alpha.2","0.1.7-rc.1", "0.1.7-rc.2",
-        "0.2.1-alpha.1"]
+      "dshVersions": [
+        "0.1.2-rc.1",
+        "0.1.5-rc.2",
+        "0.1.7-alpha.2",
+        "0.1.7-rc.1",
+        "0.1.7-rc.2",
+        "0.2.1-alpha.1"
+      ]
     },
     "capability": {
       "id": "dsh-plugin-guide",

package/scripts/verify-artifacts.mjs

@@ -5,7 +5,7 @@
 //   3. the scaffolder produces TS and JS skeletons inside a mkdtemp sandbox
 //      (never touching a real home directory), which are then removed.
 import { spawnSync } from 'node:child_process'
-import { existsSync, mkdtempSync, rmSync, readdirSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, rmSync, readdirSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -59,6 +59,18 @@ try {
     check(result.status === 0 && hasEntry && hasPatch, `${lang} scaffold produces entry + cordis.patch.yml (exit ${result.status})`)
     check(readmeCount === 5, `${lang} scaffold produces 5 README languages (${readmeCount})`)
   }
+
+  // 3b. Extension contract for the TS scaffold. `platform: node` makes tsdown
+  // force `.mjs`/`.cjs` unless `fixedExtension` is disabled, while the scaffolded
+  // package.json declares `lib/index.js` + `lib/index.d.ts`. When those two
+  // disagree the build succeeds and `main` resolves to nothing, so the plugin
+  // installs and then silently never loads — with no error anywhere. Asserted
+  // offline (no install, no build) so the gate stays network-free.
+  const tsConfig = readFileSync(join(root, 'templates', 'ts', 'tsdown.config.mjs'), 'utf8')
+  check(
+    /fixedExtension\s*:\s*false/.test(tsConfig),
+    'ts template disables tsdown fixedExtension so the build emits the declared lib/index.js',
+  )
 } finally {
   rmSync(sandbox, { recursive: true, force: true })
 }

package/templates/ts/tsdown.config.mjs

@@ -12,4 +12,10 @@ export default defineConfig({
   clean: true,
   sourcemap: false,
   outDir: 'lib',
+  // With `platform: node` tsdown forces `.mjs`/`.cjs`; disable that so ESM output
+  // follows the package `"type": "module"` and emits `lib/index.js` +
+  // `lib/index.d.ts` — the paths this template's package.json declares. Without
+  // this flag the build emits `lib/index.mjs`/`lib/index.d.mts`, `main` resolves
+  // to nothing, and the plugin silently never loads.
+  fixedExtension: false,
 })