dsh-plugin-guide 0.3.27 → 0.3.29

package/README-es.md

@@ -56,7 +56,7 @@ content counts as stated in the README (What you get)
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (`5badb15009`, el tag más nuevo de master, 2026-10-03); npm `latest` = `0.2.0-rc.2`, `alpha` = `0.2.1-alpha.1`. Re-verificado el 2026-10-06 contra ese checkout (cadena de gates + smoke de instalación de perfil). La base de conocimiento, el espejo de docs oficiales y [guide/migration-0.2.md](guide/migration-0.2.md) usan esta línea base. |
+| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.2` (`d743267388641bc76f17c45ce8b4c231aed1d32c`, el tag más nuevo de master **y** HEAD, 2026-10-09); npm `latest` = `0.2.0-rc.2`, `alpha` = `0.2.1-alpha.2`. Re-verificado el 2026-10-06 contra ese checkout (cadena de gates + smoke de instalación de perfil). La base de conocimiento, el espejo de docs oficiales y [guide/migration-0.2.md](guide/migration-0.2.md) usan esta línea base. |
 | Node | `^22.19.0 || >=24.0.0` (runtime de DeepSeek Harness) |
 | Platforms | Todas (bundle ESM plano; sin código nativo, sin red) |
 | Model | Cualquiera (sin interacción con el modelo) |
@@ -246,7 +246,7 @@ pwsh -File scripts/verify-kit.ps1   # rutas críticas + escaneo de enlaces (+ de
 
 ## PerryLink DSH Plugin Family
 
-Este proyecto es uno de los **33 plugins activamente mantenidos** de DeepSeek Harness de [PerryLink](https://github.com/PerryLink): el registro tiene **42**, de los cuales **6** están congelados y **3** retirados; cada uno conserva su fila abajo, con el motivo en la columna Estado. Si este te ayuda, probablemente los demás también:
+Este proyecto es uno de los **34 plugins activamente mantenidos** de DeepSeek Harness de [PerryLink](https://github.com/PerryLink): el registro tiene **42**, de los cuales **5** están congelados y **3** retirados; cada uno conserva su fila abajo, con el motivo en la columna Estado. Si este te ayuda, probablemente los demás también:
 
 | Plugin | En una línea | Estado |
 |---|---|---|
@@ -274,7 +274,7 @@ Este proyecto es uno de los **33 plugins activamente mantenidos** de DeepSeek Ha
 | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | LSP diagnostics, formatting, completion, code actions and rename over language servers | |
 | **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | PII masking middleware: anonymize at the model boundary, restore at the display layer | |
 | **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors | |
-| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | 🧊 CONGELADO — ver el README del repositorio |
+| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | |
 | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | OpenTelemetry and Langfuse observability exporter for DeepSeek Harness. | |
 | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | Claude Code outputStyles-equivalent runtime style switching | |
 | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | Claude Code-style declarative allow/deny/ask permission rules with audit | |

package/README-hi.md

@@ -56,7 +56,7 @@ content counts as stated in the README (What you get)
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (`5badb15009`, master का सबसे नया tag, 2026-10-03); npm `latest` = `0.2.0-rc.2`, `alpha` = `0.2.1-alpha.1`। 2026-10-06 को उसी checkout के विरुद्ध पुनः सत्यापित (gate chain + profile install smoke)। नॉलेज बेस, आधिकारिक-docs मिरर और [guide/migration-0.2.md](guide/migration-0.2.md) इसी बेसलाइन पर हैं। |
+| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.2` (`d743267388641bc76f17c45ce8b4c231aed1d32c`, master का सबसे नया tag **और** HEAD, 2026-10-09); npm `latest` = `0.2.0-rc.2`, `alpha` = `0.2.1-alpha.2`। 2026-10-06 को उसी checkout के विरुद्ध पुनः सत्यापित (gate chain + profile install smoke)। नॉलेज बेस, आधिकारिक-docs मिरर और [guide/migration-0.2.md](guide/migration-0.2.md) इसी बेसलाइन पर हैं। |
 | Node | `^22.19.0 || >=24.0.0` (DeepSeek Harness रनटाइम) |
 | Platforms | सभी (सादा ESM बंडल; कोई नेटिव कोड नहीं, कोई नेटवर्क नहीं) |
 | Model | कोई भी (कोई मॉडल अंतःक्रिया नहीं) |
@@ -246,7 +246,7 @@ pwsh -File scripts/verify-kit.ps1   # महत्वपूर्ण पथ +
 
 ## PerryLink DSH Plugin Family
 
-यह प्रोजेक्ट [PerryLink](https://github.com/PerryLink) के DeepSeek Harness प्लगइन परिवार का हिस्सा है — **33 सक्रिय रूप से अनुरक्षित**, कुल सूची **42** है जिसमें **6 फ़्रोज़न** और **3 सेवानिवृत्त** हैं; हर एक की पंक्ति नीचे बनी रहती है, कारण “स्थिति” कॉलम में है। अगर यह उपयोगी लगे, तो अन्य भी मददगार होंगे:
+यह प्रोजेक्ट [PerryLink](https://github.com/PerryLink) के DeepSeek Harness प्लगइन परिवार का हिस्सा है — **34 सक्रिय रूप से अनुरक्षित**, कुल सूची **42** है जिसमें **5 फ़्रोज़न** और **3 सेवानिवृत्त** हैं; हर एक की पंक्ति नीचे बनी रहती है, कारण “स्थिति” कॉलम में है। अगर यह उपयोगी लगे, तो अन्य भी मददगार होंगे:
 
 | Plugin | एक पंक्ति में | स्थिति |
 |---|---|---|
@@ -274,7 +274,7 @@ pwsh -File scripts/verify-kit.ps1   # महत्वपूर्ण पथ +
 | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | LSP diagnostics, formatting, completion, code actions and rename over language servers | |
 | **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | PII masking middleware: anonymize at the model boundary, restore at the display layer | |
 | **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors | |
-| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | 🧊 फ़्रोज़न — रिपॉज़िटरी README देखें |
+| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | |
 | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | OpenTelemetry and Langfuse observability exporter for DeepSeek Harness. | |
 | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | Claude Code outputStyles-equivalent runtime style switching | |
 | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | Claude Code-style declarative allow/deny/ask permission rules with audit | |

package/README-pt.md

@@ -56,7 +56,7 @@ content counts as stated in the README (What you get)
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (`5badb15009`, o tag mais novo do master, 2026-10-03); npm `latest` = `0.2.0-rc.2`, `alpha` = `0.2.1-alpha.1`. Re-verificado em 2026-10-06 contra esse checkout (cadeia de gates + smoke de instalação de perfil). A base de conhecimento, o espelho de docs oficiais e [guide/migration-0.2.md](guide/migration-0.2.md) usam essa linha de base. |
+| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.2` (`d743267388641bc76f17c45ce8b4c231aed1d32c`, a tag mais nova do master **e** HEAD, 2026-10-09); npm `latest` = `0.2.0-rc.2`, `alpha` = `0.2.1-alpha.2`. Re-verificado em 2026-10-06 contra esse checkout (cadeia de gates + smoke de instalação de perfil). A base de conhecimento, o espelho de docs oficiais e [guide/migration-0.2.md](guide/migration-0.2.md) usam essa linha de base. |
 | Node | `^22.19.0 || >=24.0.0` (runtime do DeepSeek Harness) |
 | Platforms | Todas (bundle ESM puro; sem código nativo, sem rede) |
 | Model | Qualquer (sem interação com o modelo) |
@@ -246,7 +246,7 @@ pwsh -File scripts/verify-kit.ps1   # caminhos críticos + varredura de links (+
 
 ## PerryLink DSH Plugin Family
 
-Este projeto é um dos **33 plugins ativamente mantidos** do DeepSeek Harness da [PerryLink](https://github.com/PerryLink): o registro tem **42**, dos quais **6** estão congelados e **3** aposentados; cada um mantém sua linha abaixo, com o motivo na coluna Status. Se este ajudou você, provavelmente os outros também ajudarão:
+Este projeto é um dos **34 plugins ativamente mantidos** do DeepSeek Harness da [PerryLink](https://github.com/PerryLink): o registro tem **42**, dos quais **5** estão congelados e **3** aposentados; cada um mantém sua linha abaixo, com o motivo na coluna Status. Se este ajudou você, provavelmente os outros também ajudarão:
 
 | Plugin | Em uma linha | Status |
 |---|---|---|
@@ -274,7 +274,7 @@ Este projeto é um dos **33 plugins ativamente mantidos** do DeepSeek Harness da
 | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | LSP diagnostics, formatting, completion, code actions and rename over language servers | |
 | **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | PII masking middleware: anonymize at the model boundary, restore at the display layer | |
 | **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors | |
-| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | 🧊 CONGELADO — ver o README do repositório |
+| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | |
 | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | OpenTelemetry and Langfuse observability exporter for DeepSeek Harness. | |
 | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | Claude Code outputStyles-equivalent runtime style switching | |
 | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | Claude Code-style declarative allow/deny/ask permission rules with audit | |

package/README-zh.md

@@ -58,7 +58,7 @@ content counts as stated in the README (What you get)
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1`（`5badb15009`，master 最新 tag，2026-10-03）；npm `latest`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.1`。已于 2026-10-06 对照该 checkout 重核（完整门禁链 + profile 安装冒烟）。知识库、官方文档副本与 [guide/migration-0.2.md](guide/migration-0.2.md) 均以该基线为准。 |
+| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.2`（`d743267388641bc76f17c45ce8b4c231aed1d32c`，master 最新 tag **且** = master HEAD，2026-10-09）；npm `latest`=`next`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.2`。**不存在稳定版**——全部 31 个 npm 版本与 26 个 GitHub Release 都是 prerelease。官方文档副本与 [guide/migration-0.2.md](guide/migration-0.2.md) 钉在上一版 `dsh-v0.2.1-alpha.1`（`5badb15009`，2026-10-03）；此后新增的 20 份破坏性变更指南收录于 [guide/version-matrix.md](guide/version-matrix.md) §3。 |
 | Node | `^22.19.0 || >=24.0.0`（DeepSeek Harness 运行时） |
 | Platforms | 全部（纯 ESM bundle；无原生代码、无网络） |
 | Model | 任意（无模型交互） |
@@ -68,6 +68,7 @@ content counts as stated in the README (What you get)
 `dsh-plugin-guide` 是 DSH 插件开发知识库加 CLI 工具链，打包为一个可安装 bundle。知识库注册为 `dsh-plugin-guide` agent 技能（在每个会话目录可见，按需加载工作流步骤、官方文档与社区深读）；`dsh-plugin-dev` CLI 在其之上提供三个机械层。
 
 - **插件契约与红线** —— effect/disposer、waterfall `next()`、模型可见 ⟺ 已记录、Schemastery 配置。
+- **版本适配** —— [guide/version-matrix.md](guide/version-matrix.md)：五个"最新"的区别、子包 `latest` 冻结陷阱、四个破坏性变更断层、peer 区间怎么选、会话格式 V0→V4 谱系，以及 `0.2.1-alpha.2` 落的 19 条破坏性变更。
 - **官方文档档案** —— 官方仓库文档（英 + 中）逐字副本，在最近核验快照处与上游逐字节一致。
 - **Cordis 入门** —— 五个概念与机制时间线（repository-plugin 0809 引入、0811 移除；两条安装通道）。
 - **20+ 个实战踩坑** —— 附根因 + 修法（cordis 双副本、tsconfig 三件套、多帧 zstd 会话、Windows junction、过期 npm `latest`…）。
@@ -81,6 +82,7 @@ content counts as stated in the README (What you get)
 | `SKILL.md` | `dsh-plugin-guide` agent 技能：红线 + 按任务类型的开发路径 |
 | `package.json` · `cordis.patch.yml` · `index.js` | 可安装 DSH bundle：`dsh.bundle.patch` 清单 + 注册技能的入口 |
 | `guide/plugin-dev-guide.md` | 完整开发指南（10 章） |
+| `guide/version-matrix.md` | **版本适配矩阵**：五个"最新"的区别、子包 `latest` 冻结、破坏性变更断层、peer 区间选择、会话格式谱系、`0.2.1-alpha.2` 的 19 条变更 |
 | `guide/quick-reference.md` | 一页速查表（5 语言） |
 | `guide/links.md` | 精选 URL 索引：官方开发文档（站点 ↔ 本地副本）+ 社区文档链接 |
 | `guide/when-to-retire-a-plugin.md` | 插件退役与冻结：一次组合审计的判据与实测数据（中英双语） |
@@ -248,7 +250,7 @@ pwsh -File scripts/verify-kit.ps1   # 关键路径 + 链接扫描（加 -Checkou
 
 ## PerryLink DSH Plugin Family
 
-本项目是 [PerryLink](https://github.com/PerryLink) 维护的 DeepSeek Harness 插件家族成员：**33 个活跃维护**，名册共 **42** 个，其中 **6 个已冻结**、**3 个已退役**——每一个都在下表保留自己的行，原因见「状态」列。如果它能帮到你，其他的也会：
+本项目是 [PerryLink](https://github.com/PerryLink) 维护的 DeepSeek Harness 插件家族成员：**34 个活跃维护**，名册共 **42** 个，其中 **5 个已冻结**、**3 个已退役**——每一个都在下表保留自己的行，原因见「状态」列。如果它能帮到你，其他的也会：
 
 | Plugin | 一句话 | 状态 |
 |---|---|---|
@@ -276,7 +278,7 @@ pwsh -File scripts/verify-kit.ps1   # 关键路径 + 链接扫描（加 -Checkou
 | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | LSP diagnostics, formatting, completion, code actions and rename over language servers | |
 | **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | PII masking middleware: anonymize at the model boundary, restore at the display layer | |
 | **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors | |
-| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | 🧊 已冻结 — 见仓库 README |
+| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | |
 | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | OpenTelemetry and Langfuse observability exporter for DeepSeek Harness. | |
 | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | Claude Code outputStyles-equivalent runtime style switching | |
 | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | Claude Code-style declarative allow/deny/ask permission rules with audit | |

package/README.md

@@ -60,7 +60,7 @@ content counts as stated in the README (What you get)
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (`5badb15009`, the newest master tag, 2026-10-03); npm `latest` = `0.2.0-rc.2`, `alpha` = `0.2.1-alpha.1`. Re-verified 2026-10-06 against that checkout (gate chain + profile install smoke). The knowledge base, the official-docs mirror and `guide/migration-0.2.md` all carry this baseline. |
+| 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. |
 | 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) |
@@ -71,6 +71,7 @@ content counts as stated in the README (What you get)
 
 - **Plugin contract & hard rules** — effects/disposers, waterfall `next()`, host-owned session events, `MessageSourceMap`, the weakest-mechanism ordering, Schemastery config, UI and performance rules.
 - **Official docs archive** — a verbatim copy of the official repo docs (EN + ZH), byte-identical to upstream at the last verified snapshot, including the pages that never reach the documentation site.
+- **Version adaptivity** — [guide/version-matrix.md](guide/version-matrix.md): the five different "latest" values, the frozen sub-package `latest` tags, the four breaking-change seams, the canonical peer range and how to pick one, the session-format lineage V0→V4, and the 19 breaking changes that landed in `0.2.1-alpha.2`.
 - **Migration guide** — [guide/migration-0.2.md](guide/migration-0.2.md): every breaking change from `0.1.6-alpha.2` to `0.2.1-alpha.1` (session format V4, the settings rebuild, invariant removal, `readBytes`, new slots, retired `plugin` message source), each with its official source and a 12-item checklist.
 - **Official in-repo skill, distilled** — [references/official-plugin-dev-skill.md](references/official-plugin-dev-skill.md): the harness's own `cordis-plugin-development` workflow, prohibitions, display-metadata checklist, practices, and UI/performance rules.
 - **Cordis primer** — the five concepts and the mechanism timeline (repository-plugin introduced 0809, removed 0811; the two install channels).
@@ -86,6 +87,7 @@ content counts as stated in the README (What you get)
 | `SKILL.md` | The `dsh-plugin-guide` agent skill: hard rules + task-based development paths |
 | `package.json` · `cordis.patch.yml` · `index.js` · `locale/` · `icon.svg` | The installable DSH bundle: `dsh.bundle.patch` manifest, entry point that registers the skill, and the display metadata Plugin Manager reads |
 | `guide/plugin-dev-guide.md` | The complete development guide (10 chapters) |
+| `guide/version-matrix.md` | **Version adaptivity matrix**: the five "latest" values, frozen sub-package `latest` tags, breaking-change seams, peer-range selection, session-format lineage, and the 19 changes in `0.2.1-alpha.2` |
 | `guide/migration-0.2.md` | Breaking-change migration guide for the 0.2 generation |
 | `guide/unfixed-issues.md` | Source-verified bug index + fixed-on-master list + design-vs-bug table |
 | `guide/quick-reference.md` | One-page cheat sheet (5 languages) |
@@ -257,7 +259,7 @@ pwsh -File scripts/verify-kit.ps1   # critical paths + link scan (+ docs drift w
 
 ## PerryLink DSH Plugin Family
 
-This project is one of the **33 actively maintained** DeepSeek Harness plugins from [PerryLink](https://github.com/PerryLink) — the roster is **42**, of which **6** are frozen and **3** retired; every one keeps its row below, with the reason in the Status column. If this one helps you, the others likely will too:
+This project is one of the **34 actively maintained** DeepSeek Harness plugins from [PerryLink](https://github.com/PerryLink) — the roster is **42**, of which **5** are frozen and **3** retired; every one keeps its row below, with the reason in the Status column. If this one helps you, the others likely will too:
 
 | Plugin | One-liner | Status |
 |---|---|---|
@@ -281,7 +283,7 @@ This project is one of the **33 actively maintained** DeepSeek Harness plugins f
 | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | LSP diagnostics, formatting, completion, code actions and rename over language servers | |
 | **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | PII masking middleware: anonymize at the model boundary, restore at the display layer | |
 | **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors | |
-| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | 🧊 FROZEN — see the repo README |
+| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | |
 | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | OpenTelemetry and Langfuse observability exporter for DeepSeek Harness. | |
 | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | Claude Code outputStyles-equivalent runtime style switching | |
 | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | Claude Code-style declarative allow/deny/ask permission rules with audit | |

package/SKILL.md

@@ -19,9 +19,10 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 
 ## 开发前置（第一步必做）
 
-0. **先认版本**：`dsh --version`。`0.1.7-alpha.1`（2026-09-22）起包含本世代全部破坏性变更（会话格式 V4、settings 重写、`readBytes`、Messages-only 适配器）；npm `latest`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.1`，master 最新 tag 是 `dsh-v0.2.1-alpha.1`——**这三个"最新"不是同一个东西**。目标宿主不是最新线时，**先读 `guide/migration-0.2.md`** 按条目对照。
+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 条新破坏性变更。
 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`。
 3. 确认目标扩展点：读 `references/official-docs/docs/architecture.md` 的「Where new behavior goes」表与 `references/official-docs/docs/cookbook/extension-cookbook.md` 的 feature→mechanism 表——**新行为必须挂到已文档化扩展点，不得改 agent-loop**；**用最弱的够用机制**（restrict < guard < waterfall 改写 < system-prompt/assemble）。
 4. 要写 UI / 要让 agent 自己装插件时，读 `references/official-plugin-dev-skill.md`（官方自带技能的要点与硬性规定）。
 
@@ -41,7 +42,7 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 - 可替换能力按三层接缝设计：Service Definition / Provider / Consumer；不提前拆。
 - 打包：bundle 清单 `"dsh":{"bundle":{"patch":"..."}}`（`patch` **可为有序数组**，每个文件的相对路径按各自目录解析）；覆盖按 `id` 整行替换 config（上游删行后 override **静默失效**，升级后跑 `--dump-config` 查 `patch: entry not found`）；`!!js`（双感叹号）；git 安装需要 `prepare` 脚本与用户侧 `allowBuilds`，发布 npm/tarball 免构建许可。
 - **交付必须补展示元数据**：`locale/*.json` 的 `meta.title`/`meta.description` + 导出的 `./icon`（≤256 KiB、realpath 后必须在包内）；子路径插件**不读** `package.json`。
-- **共享实例的 dsh 包只放 peerDependencies + devDependencies**，绝不放 dependencies（profile 内副本会静默遮蔽运行时版本，核心服务注册失败）。DSH **不校验** peer 范围，兼容性靠运行时探测。
+- **共享实例的 dsh 包只放 peerDependencies + devDependencies**，绝不放 dependencies（profile 内副本会静默遮蔽运行时版本，核心服务注册失败）。⚠️ **peer 范围会被安装期强制**（早期版本写成"DSH 不校验"，**已更正**）：`dsh plugin add` 拿运行时版本比对声明的 `@deepseek-ai/dsh-*` 范围，不匹配即**拒绝安装**；`engines.dsh` 才是纯声明、零强制。范围只能表达"能不能装"，**表达不了某个 API 在不在**——仍要配运行时探测。区间选择见 `guide/version-matrix.md` §4。
 - **UI 插件**：只渲染 slot 里的 React 组件（禁止 iframe 托管页面）；样式只用 `--dsw-alias-*` 主题 token；不 `require` 任何 Harness Client 包（抛错组件会把整个 slot 搞白）；`dsh.client.inject` **必须是静态数组**；不在组件外写 DOM、不往 `document.body` 追加。
 - **性能**：per-session 状态放 `ctx.sessionProjections`（纯同步 apply、忽略即同引用、纯 JSON + `stateVersion`）；等持久事件（`turn/end`/`assistant/message`/`tool/result`），实时 token 读 `agent/assistant-stream`；**不轮询 `agent/status`**。
 - **禁止**：在会话运行期间改 profile 的 `cordis.patch.yml`（HMR 会重载，实测丢光 preset 工具、杀掉在途 turn、最坏永久废掉 `sessionController`）；手写 profile 的 `package.json`；在 profile 目录里跑 pnpm。
@@ -57,7 +58,7 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 - **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。
 - **插件配置表单**：`docs/subsystems/settings.md`（已改名 "Plugin Configuration Forms"）+ `docs/cookbook/adding-a-settings-card.md`（已重写）。
 - **打包/发布**：`docs/user/develop/basic/publish.md`（bundle/profile、层顺序、多 patch 数组、peer 解析、git 安装坑）。
-- **升级/迁移**：`guide/migration-0.2.md`（本库综述）→ `docs/upgrade-guide/**`（官方逐版本迁移指南）+ `docs/persistence-changes/**`（持久化类型变更记录）+ `docs/session-format-status.md`（会话格式版本权威）。
+- **升级/迁移**：`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`。
 - **官方自带插件开发技能（0.2 世代新增，先读）**：`references/official-plugin-dev-skill.md`（主流程 + 六份分面参考要点 + 模板定位）；上游在 `packages/preset/agent-preset/skills/cordis-plugin-development/**`。它规定的官方路径是：工作区写 bundle → `plugin_manager` `install_bundle`（绝对目录）→ `cordis_inspect_query` 核对，**禁止**手写 profile 的 `package.json`/`cordis.patch.yml`、禁止在 profile 目录跑 pnpm。
 - **参考社区实现与实测坑**：`references/community-ecosystem.md`、`references/community-repo-deep-dive.md`（首批 15 个开发仓库深读）、`downloads/community-repos/`（**114 个仓库完整源码副本**，需先跑 `scripts/download-community-repos.ps1` 生成）。社区已确认的机制变化（repository-plugin 0811 移除、bundle vs 纯 cordis 双通道）与实测坑清单在 `guide/plugin-dev-guide.md` §7，源码级问题索引在 `guide/unfixed-issues.md`（含本世代新核实的 T1–T11）。官方 Discussions 全量归档（**2026-10-06 刷新**，含 #1629 官方插件脚手架 RFC）与 npm 全家桶元数据分别在 `downloads/github/harness/discussions/` 与 `downloads/npm/`；中英文社区文章 HTML 快照在 `downloads/web/community-articles/`。

package/dist/dsh-plugin-dev.js

@@ -146,10 +146,19 @@ function isDir(path) {
 * 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`).
+* 0.2.x harness (`installation rejected: ... is incompatible with dsh <runtime>`).
 */
 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";
+/**
+* The DSH release this scaffold was last verified against, single-sourced here
+* and substituted into template prose through the `{{dshBaseline}}` placeholder.
+*
+* Keep it in step with `guide/version-matrix.md` §1 and the root README
+* compatibility table. It is deliberately a *prerelease*: DSH has no stable
+* line (every published version and GitHub release carries `-alpha.N`/`-rc.N`),
+* so a scaffold that claimed a stable baseline would be lying.
+*/
+const DSH_BASELINE = "0.2.1-alpha.2";
 /** Resolve the templates root: env override first, then candidate walks. */
 function resolveTemplatesRoot() {
 	const env = process.env.DSH_PLUGIN_DEV_TEMPLATES;
@@ -175,7 +184,7 @@ function walkFiles(dir, base = "") {
 }
 /** Substitute placeholders in template text. */
 function renderTemplate(text, context) {
-	return text.replaceAll("{{pkgName}}", context.pkgName).replaceAll("{{name}}", context.name).replaceAll("{{version}}", context.version).replaceAll("{{year}}", context.year).replaceAll("{{dshPeerRange}}", DSH_PEER_RANGE);
+	return text.replaceAll("{{pkgName}}", context.pkgName).replaceAll("{{name}}", context.name).replaceAll("{{version}}", context.version).replaceAll("{{year}}", context.year).replaceAll("{{dshPeerRange}}", DSH_PEER_RANGE).replaceAll("{{dshBaseline}}", DSH_BASELINE);
 }
 /** Render every file of a language template. */
 function renderScaffold(lang, context) {
@@ -1626,8 +1635,8 @@ async function initGit(targetDir) {
 * `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 VERIFY_BASE_SPEC = "@deepseek-ai/dsh-base@0.2.1-alpha.2";
+const VERIFY_HEADLESS_SPEC = "@deepseek-ai/dsh-headless@0.2.1-alpha.2";
 const PROFILE_WORKSPACE = `# scratch profile allowlist (mirrors the repo's compat workflow)
 packages:
   - .
@@ -1817,7 +1826,7 @@ 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.2.1-alpha.1 (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.2 (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");
@@ -1955,8 +1964,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.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",
+					base: flagString(flags, "base", "@deepseek-ai/dsh-base@0.2.1-alpha.2") ?? "@deepseek-ai/dsh-base@0.2.1-alpha.2",
+					headless: flagString(flags, "headless", "@deepseek-ai/dsh-headless@0.2.1-alpha.2") ?? "@deepseek-ai/dsh-headless@0.2.1-alpha.2",
 					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/family-toolchain.md

@@ -0,0 +1,260 @@
+# 家族工具链路由（family-toolchain.md）
+
+> **这份文件回答**：我的问题该找哪个工具？哪个文档是这项事实的**权威所有者**？
+> 以及 `dsh-plugin-dev check` 的 16 项检查和 `dsh-plugin-doctor` 的 33 项检查是什么关系。
+>
+> **原则**：**一个事实只有一个所有者。** 本知识库只负责"认知 + 索引"，
+> 机械检查交给工具；发现重复时**链接**而不是**复述**。
+>
+> **测量时间**：2026-10-13。
+
+---
+
+## 1. 路由表：问题 → 所有者 → 可引用产物
+
+| 你的问题 | 权威所有者 | 可引用产物 | 命令 |
+|---|---|---|---|
+| 这个插件包结构对不对？ | `dsh-plugin-doctor` | `SPEC.md`（规范）R0–R8 | `npx @perrylink/dsh-plugin-doctor --only R` |
+| 我的 Cordis 用法有没有踩契约？ | `dsh-plugin-doctor` | `SPEC.md` §4.2b，K1–K14 | `… --only K` |
+| 装了能不能起来？ | `dsh-plugin-doctor` D 组 / `dsh-test-drive` | D0–D3/D9；test-drive 的四态记录 | `… --only D` |
+| 我在各个目录里被收录对了吗？ | `dsh-plugin-doctor` CC 组 | CC1–CC5 | `… --only CC` |
+| 我的插件质量几分？ | `dsh-score` | 五维评分 + 排行榜 JSON/MD | `dsh-score <repo\|pkg>` |
+| 怎么从旧世代升上来？ | `dsh-plugin-upgrade` | 走廊卡（`legAB` 20 seams / `legC` E1–E5） | `dsh-plugin-upgrade-scan` |
+| 共享代码怎么写？ | `@perrylink/dsh-plugin-kit` | `data/peer-range.json`、seam/gate 契约、新插件骨架 | — |
+| 社区认证是什么等级？ | `dsh-plugin-certification` + `dsh-cert-mcp` | 五维 A–E、等级 A–D、安全否决 | MCP：`get_certification` |
+| 目标宿主这一版有什么？ | **本知识库** | [`version-matrix.md`](version-matrix.md) | `dsh --version` |
+| 该改哪一行？ | **本知识库** | [`migration-0.2.md`](migration-0.2.md) | — |
+| 官方怎么规定的？ | **本知识库镜像** | `references/official-docs/` | — |
+
+---
+
+## 2. `dsh-plugin-doctor`：33 项检查全表
+
+规范来源是 **`SPEC.md`**（spec `v1`，checkset 字符串
+`R0-R8+K1-K14+D0-D3,D9+CC1-CC5/3`），ID 空间**已冻结**（SPEC §3.3）。
+共 **33** 项 = 9 (R) + 14 (K) + 5 (D) + 5 (CC)。
+
+> ⚠️ **不要引用 doctor 的 README 核对检查 ID。** README 在 5 处写 `K1–K9` 和"16 checks"，
+> 而规范 `SPEC.md` 定义的是 **K1–K14** 和 **21 项规范门禁**——README 在 K10–K14 落地时没更新。
+> README 内部还自相矛盾（43 / 41 / 37 仓 vs `data/verified-repos.json` 的 40 条）。
+
+### 2.1 裁定词表（SPEC §2，规范，五种）
+
+| 裁定 | 含义 |
+|---|---|
+| `pass` | 已评估且成立 |
+| `warn` | 已评估、看似违规，**启发式**，需人工复核，**单独不足以定罪** |
+| `fail` | 已评估且违规 → 计入失败 |
+| `error` | **检查本身无法完成** → 计入失败 |
+| `skip` | **未评估** —— **绝不能渲染成 pass** |
+
+正交分类：`critical`（目前仅 `R1`）与 `category` ∈
+{`plugin-defect`, `policy`, `not-applicable`, `environment`, `infrastructure`, `unsupported-host`, `unstable`}。
+**后四类永远不是插件缺陷**；`policy` 表示这是"家族约定而规范并不共享"（R5、R8）。
+
+**降级规则**（SPEC §3.2，规范）：被请求的组里**每一项都 `skip`**，则该组"未被评估"，
+不得报告成功；零检查执行、或组名匹配不到任何东西，同样不得报告成功。
+规范里记了理由：**曾经一个写坏的组名让 35 个仓库的 CI 门禁全绿，而实际什么都没查。**
+
+**K 组覆盖模式**（SPEC §3.4，规范披露）：`src`（带 `src/` → 完整预期覆盖）·
+`lib-fallback`（无 `src/`，退到 `main` 所在目录 → 真实覆盖但**不等价**，K3–K7 可能少报）·
+`none`（都不存在 → 降级）。
+
+### 2.2 R 组 —— 静态 · 包结构（R0–R8）
+
+| ID | 要求 | 裁定 | critical |
+|---|---|---|---|
+| `R0` | 基础清单字段 `name`/`version`/`license`(SPDX)/`type`；仓内有 `README.md` + `LICENSE` | warn · pass | 否 |
+| `R1` | **激活门 `dsh.bundle.patch`** 声明为非空字符串 | fail · pass | **是——唯一 critical** |
+| `R2` | tarball 完整性：`npm pack --dry-run --json --ignore-scripts` 成功；文件表含声明的入口**与** patch 文件且都非空；tarball 名 = name+version | fail · pass · skip | 否 |
+| `R3` | `cordis.patch.yml` 结构（启发式）：存在、解析为顶层 YAML **数组**；空数组合法；非空必须含 `- insert:` 与 ≥1 个 `id:`；每个 `name:` 等于或命名空间在包名之下 | skip · fail · pass | 否 |
+| `R4` | 入口契约：`main`/`exports` 入口存在且同时导出 `apply` 与 `name`；`inject` 是字符串字面量数组 | fail · warn · pass · skip | 否 |
+| `R5` | 依赖策略：① 任何位置不许裸 `cordis`/`schemastery`；② 导入的 `@deepseek-ai/cordis` 必须被声明；③ 它必须在 `peerDependencies` **和** `devDependencies`，**绝不** `dependencies`；④ `@deepseek-ai/dsh` 不得是直接 `dependencies` | fail · pass · skip | 否（`policy`） |
+| `R6` | `engines.node` 兼容 `^22.19.0 \|\| >=24.0.0`（只声明 Node 23 会失败） | fail · warn · pass | 否 |
+| `R7` | `files` 白名单已声明且覆盖入口 + patch；需要构建时入口不得指向源码 | fail · pass | 否 |
+| `R8` | 不得有指向已被取代的预发布线的陈旧 peer 范围（`0.1.0-rc.*`、`0.1.1-rc.*`、`0.1.2-alpha.*`、`0.1.3-alpha.*`），也不得有开顶 `>=` 范围 | skip · fail · warn · pass | 否（`policy`；"报告**陈旧**，不是**损坏**"） |
+
+**规范门禁**（SPEC §1）：`R0, R1, R3, R5, R6, R7, R8, K1–K14` = **21 项**，
+故意排除 R2 和 R4（它们读的是**构建产物**）。
+
+### 2.3 K 组 —— 静态 · Cordis 契约扫描（K1–K14）
+
+K1–K9 回答"这个插件自身正确吗"；**K10–K14 回答"它会不会干扰别的插件，或被别的插件悄悄吃掉"**。
+全部为启发式；没有发现源码文件时一律 `skip`。
+
+| ID | 含义 | 裁定 |
+|---|---|---|
+| `K1` | 每个 `ctx.<service>` 访问要么是 Context 内建、要么在 `inject` 声明、要么经 `ctx.get(name)` | skip · warn · pass |
+| `K2` | **活数据序列化红线** —— 绝不 `JSON.stringify(ctx…)`、`structuredClone(ctx…)`、`{...ctx…}` | skip · **fail** · pass |
+| `K3` | 定时器/全局监听被 `ctx.effect`（或 `ctx.on`）包裹，或显式自清理 | skip · warn · pass |
+| `K4` | 定义 `Schema` 的文件里不得引入箭头函数 | skip · warn · pass |
+| `K5` | `apply` 返回形态（v4 Effect 契约）：disposer 函数、`null`、`undefined`、`Promise<disposer>`、或（异步）可迭代；async `apply` 合法但必须返回 `Promise<disposer>` | skip · warn · pass |
+| `K6` | 每个注入的服务名要么是已知宿主接缝、要么带命名空间（含 `.`）、要么是自己 `provide` 的 | skip · warn · pass |
+| `K7` | 无 v3 遗留 API：`ctx.using/scope/runtime/lifecycle/collect/accept/decline/alias/off/fork`、`ctx.config`、`ctx.start()/stop()`、v3 的 `inject: {required, optional}` | skip · **fail**（硬名单）· warn（软名单）· pass |
+| `K8` | `export const Config` 必须是 Standard Schema 校验器，不是普通对象字面量 | skip · **fail** · pass |
+| `K9` | 对象插件不得设 `name: 'apply'`（框架会把它重置为 `undefined`） | skip · warn · pass |
+| `K10` | 用 `ctx.on(<waterfall 事件>, …)` 注册的监听器必须引用 `next` | skip · warn · pass |
+| `K11` | 注册的工具名不得与宿主内建或保留字 `run_code` 冲突，也不得用 `tools.data.delete(def.name)` + 重新注册的遮蔽写法 | skip · warn · pass |
+| `K12` | 传给 `super(ctx, '<name>')` / `ctx.provide('<name>')` 的键不得等于宿主接缝名 | skip · warn · pass |
+| `K13` | `cordis.patch.yml` 不得带顶层（非 `insert`）且 `id` 属于宿主的行（按 id 定位的 patch **整行替换 config，不做深合并**） | skip · warn · pass |
+| `K14` | **跨仓注入点冲突** —— 任何自有名字（服务键、工具名、命令名、patch `insert` 行 id）都不得与同工作区的兄弟插件仓重复 | skip · warn · pass |
+
+**K14 有规范的"守卫感知豁免"**（SPEC §4.2b）：在 `package.json` 的
+`dsh-plugin-doctor.crossPlugin.exempt` 或旁挂 `dsh-plugin-doctor.yml` 里声明
+`{kind, name, peer?, guard?}` 列表，`kind` ∈ {`service`, `tool`, `command`, `patch insert id`}；
+被豁免的冲突算 `pass`。工作区里少于两个插件仓时降级为 `skip`——
+所以随包发布的 CI workflow（不传 `--workspace`）不会因此挂构建。
+
+K10/K11/K13 的参照数据取自上游 `docs/event-producer-consumer.md` 的 `@mode` 列、
+工具目录各节，以及基线 DSH `0.2.0-rc.2` 的 `packages/bundle/base/cordis.patch.yml` 顶层 id。
+
+### 2.4 D 组 —— 动态 · 沙箱冒烟（D0–D3, D9）
+
+| ID | 要求 | 裁定 |
+|---|---|---|
+| `D0` | `npm pack --ignore-scripts` 成功；tarball 写进**沙箱**，不是被测仓库 | fail · pass |
+| `D1` | 宿主从 tarball 安装：`dsh plugin --profile headless add <tarball>`（带 `--ignore-scripts`）把包名写进 `dsh.profile.bundles` | skip · fail · pass |
+| `D2` | `dsh --profile headless --dump-config` 输出层标记 `# == <package name>` | skip · fail · pass |
+| `D3` | **无密钥 headless 冒烟（`MISSING_CREDENTIAL` 判据）**：无凭据时以**退出码 1 + `dsh: MISSING_CREDENTIAL`** 结束（有凭据环境下退出 0 也算 pass）。明确致命：`NO_ADAPTER`、`ERR_MODULE_NOT_FOUND`、`SyntaxError`、`TypeError`、`ReferenceError`、`Cannot find module` | skip · fail · pass |
+| `D9` | **沙箱隔离** —— 沙箱被隔离而非删除；运行打印隔离路径；删除是单独显式步骤 | pass · fail |
+
+D1 里"不是插件缺陷"的情形：缺 `pnpm`/`npm`（`infrastructure`）、宿主版本装不上（`unsupported-host`）、
+pnpm `ignored-builds` 阻断（`environment`，报为 `skip`）。
+
+### 2.5 CC 组 —— 生态 · 目录收录（CC1–CC5）
+
+渠道数据缺失时一律 `skip`，**永不判失败**。
+
+| ID | 要求 | 裁定 |
+|---|---|---|
+| `CC1` | 认证注册表 spec v1：若已收录，条目需带 `grade`、`snapshot` 和五维（`manifest`、`buildHygiene`、`supplyChain`、`releaseIntegrity`、`installSmoke`）的 `evidence`，无 `veto`，且 `installSmoke ≠ install-fail` | skip · warn · pass |
+| `CC2` | `adp-list` 条目：`url`/`name`/`category` 齐备；`category` 在 **23 值枚举**内；`url` 与仓库一致；`description.en` 单行；`tarball` 若存在须是 GitHub Release 上的 `https` `.tgz` | skip · fail · pass |
+| `CC3` | `dsh-catalog` 条目：`npm`/`repo`/`displayName`/`categories`/`summary` 齐备；`repo` 一致；`categories` 非空数组；`summary` ≤1000 字符、不含安装命令文本、且未被截断（须以标点结尾） | skip · fail · pass |
+| `CC4` | `dshWorkshop` 清单：若声明，`lifecycle.activation` 必须是**五个枚举值**之一 | skip · fail · pass |
+| `CC5` | **家族三重门——规范明说"这不是生态标准"**：Apache-2.0 许可、五语 README、三种 seam 角色，由 `dsh-plugin-kit` 校验 CLI 检查。非 PerryLink 工作区报 `skip`（`not-applicable`） | skip · fail · pass |
+
+> **CC4 的五个值**（doctor SPEC 断言，但**只有 doctor 的 `SURVEY.md` §1.5 列出了它们**）：
+> `immediate`、`hot-reload`、`restart-plugin`、`restart-profile`、`restart-host`；
+> `restartRequired` 判据为 `/^restart-/`。
+
+### 2.6 退出码契约
+
+| 码 | 含义 |
+|---|---|
+| `0` | 无 fail/error，且每个被请求的组**真的跑过** |
+| `1` | 存在 fail/error（插件缺陷） |
+| `2` | 用法错误 / 未知组 / 未知选项 |
+| `3` | 基础设施错误 |
+| `4` | 宿主版本不支持，**不是插件裁定** |
+| `5` | 结果不稳定，步骤超时或被杀 |
+| `6` | **降级（degraded）**——被请求的组从未真正运行 |
+
+`--allow-degraded` 把 6 降为 0，但 JSON 里 `degraded` 字段仍非空。
+**两道防假绿**：`--only` 组名匹配不到 → 立即 `2`；被请求的组全部 `skip` → `6`。
+
+**组别名**：`R` = R0–R8，`K` = K1–K9 *(README)* / **K1–K14** *(SPEC，以此为准)*，
+`D` = D0–D3/D9，`CC` = CC1–CC5。**建议用 ASCII 别名**——
+一个被双重错误编码的 CJK 组名匹配不到任何东西（这正是 35 仓假绿的成因）。
+
+---
+
+## 3. 六项检查族的交叉对照
+
+| 工具 | 检查项 | 层级 | 与本库的关系 |
+|---|---|---|---|
+| `dsh-plugin-dev check`（**本库**） | **16** 项 | 静态 | 每项经 `src/cli/skill-sections.ts` 链回本知识库章节 |
+| `dsh-plugin-doctor` | **33** 项（规范门禁 21） | 静态 + 动态 + 生态 | 超集；R8 与我们的 `manifest-peers` 重叠但**更严**（查开顶区间与陈旧线） |
+| `omdsh-dev/dsh-plugin-check` | **33** 项（README 只列 26） | 静态 | 独立实现，基线停在 0.1.5-rc.1 |
+| `dsh-session-health` | 11 项检测 ID | 静态 | 会话文件层面 |
+| `dsh-security-audit` | 6 个 action | 静态 | 四态诚实模型（skipped/error 永不记为 pass） |
+| `dsh-cert-mcp` / certification | 5 维（A–E） | 生态 | 认证等级 A–D + 安全否决 |
+
+### 3.1 本库 `dsh-plugin-dev check` 的 16 项 ID
+
+`patch-valid` · `patch-ids-unique` · `manifest-bundle-patch` · `manifest-main` ·
+`manifest-peers` · `manifest-engines` · `manifest-files` · `manifest-package-manager` ·
+`display-meta` · `readme-five-langs` · `readme-consistency` ·
+`redline-persona-role` · `redline-waterfall-next` · `redline-no-hardcoded-tunables` ·
+`redline-effect-registration` · `redline-async-apply-registration`
+
+### 3.2 与 doctor 的对应关系（谁更严就用谁）
+
+| 本库检查 | doctor 对应 | 说明 |
+|---|---|---|
+| `patch-valid` | `R3` | doctor 额外要求 `name:` 命名空间在包名之下 |
+| `patch-ids-unique` | `K13` | doctor 从"重复"扩展到"是否占用宿主 id" |
+| `manifest-bundle-patch` | `R1` | **R1 是唯一 critical**，我们的是普通 fail |
+| `manifest-main` | `R4` | doctor 还查导出是否含 `apply` + `name` |
+| `manifest-peers` | `R5` + `R8` | **doctor 更严**：查裸 `cordis`、查 `dependencies` 误置、查陈旧线与开顶区间 |
+| `manifest-engines` | `R6` | — |
+| `manifest-files` | `R7` | — |
+| `manifest-package-manager` | — | 本库独有 |
+| `display-meta` | — | 本库独有（doctor 无展示元数据检查） |
+| `readme-five-langs` | `CC5`（仅家族内） | doctor 只在 PerryLink 工作区查 |
+| `readme-consistency` | — | 本库独有 |
+| `redline-persona-role` | — | 本库独有 |
+| `redline-waterfall-next` | `K10` | 重叠 |
+| `redline-effect-registration` | `K3` + `K5` | doctor 拆成两项 |
+| `redline-async-apply-registration` | `K5` 部分 | ⚠️ **我们是家族内该缺陷的唯一检测器**——`dsh-plugin-upgrade` 的 `legC` W0 卡明确点名"guide async-apply lint"作为 E2 的预防门。doctor 只查返回形态 |
+| `redline-no-hardcoded-tunables` | `K8` 部分 | doctor 查 `Config` 是否 Standard Schema |
+
+> **结论**：**我们的 16 项是 doctor 33 项的子集，但有 5 项 doctor 没有**
+> （`manifest-package-manager`、`display-meta`、`readme-consistency`、
+> `redline-persona-role`、`redline-async-apply-registration`）。
+> 两者**不是替代关系**：本库的检查**每一项都链回可读章节**，doctor 的检查**有裁定语义与退出码契约**。
+> 严肃发布请**两个都跑**。
+
+---
+
+## 4. 规范事实：只认一个所有者
+
+| 事实 | 所有者 | 值 |
+|---|---|---|
+| canonical peer 区间 | `dsh-plugin-kit` → `data/peer-range.json` | 六子句（见 [version-matrix.md](version-matrix.md) §4.1） |
+| 家族花名册 | `dsh-plugin-kit` → `data/repos.json` | **95 条**（94 插件 + 1 基建）；活跃 87 / 冻结 5 / 退役 3 |
+| 家族检查 ID 空间 | `dsh-plugin-doctor` → `SPEC.md` | 33 项，已冻结 |
+| 认证等级定义 | `dsh-plugin-certification` → README（即规范） | 五维 A–E，等级 A–D |
+| 认证注册表内容 | 同上 → `data/certified.json` | 截至 2026-10-13：**仅 1 条**（`dsh-auto-review`，A 级，快照 2026-09-07） |
+| 已核验仓名单 | `dsh-plugin-doctor` → `data/verified-repos.json` | **40 条** |
+| 升级走廊与 seam | `dsh-plugin-upgrade` | `legAB` 20 seams；`legC` E1–E5 |
+| DSH 版本谱系与 peer 区间选择 | **本知识库** | [`version-matrix.md`](version-matrix.md) |
+
+> ⚠️ **花名册计数存在五个互相冲突的说法**，引用前先看日期：
+> `data/repos.json`（2026-10-12）95 条 · certification README 94/86 · doctor README 42/34 ·
+> doctor 自己的表 45 行 · `dsh-catalog` README 自相矛盾（开头 96 / 计数节 42）·
+> `dsh-kit` README "87 活跃 + 5 冻结 = 92"。
+> **以 `data/repos.json` 为准**；本库 `guide/when-to-retire-a-plugin.md` 的
+> "44 仓 / 7 冻结"是 **2026-10-05 那次审计的快照**，测的是不同时点，**不要直接换算**。
+
+---
+
+## 5. 本知识库在家族里的位置
+
+```
+                        认知层（读）                    机械层（跑）
+                  ┌──────────────────────┐      ┌──────────────────────────┐
+   官方契约 ──────┤  dsh-plugin-guide    │      │  dsh-plugin-doctor       │ 33 项，有裁定语义
+   + 版本谱系     │  （本库）             │      │  dsh-test-drive          │ 隔离冒烟
+   + 迁移叙事     │  guide/ + references/ │      │  dsh-score               │ 五维评分
+   + 踩坑档案     │  + dsh-plugin-dev    │      │  dsh-cert-mcp            │ 认证查询
+                  │    check（16 项）     │      │  dsh-plugin-upgrade      │ 走廊扫描
+                  └──────────────────────┘      └──────────────────────────┘
+                            ↑                                  ↑
+                       回答"为什么/该改哪"                回答"过没过/几分"
+```
+
+**分工一句话**：本库负责**认知**（为什么、该改哪一行、这一版有什么），
+工具链负责**判定**（过没过、几分、能不能装）。**两者都链到本库章节**——
+`dsh-plugin-dev check` 经 `src/cli/skill-sections.ts`，
+`dsh-plugin-upgrade` 的 `legC` 卡直接点名本库的 async-apply lint。
+
+---
+
+## 6. 未核事项
+
+- `dsh-plugin-doctor` 的 `--dsh` 默认值：README 兼容性单元格写 peer 下界 `0.1.2-rc.1`，
+  用法注释却写 npm latest——**两处冲突**。
+- SPEC checkset 字符串里的 `/3` 含义未确认。
+- CC2 的 23 值 `category` 枚举**家族内无人发布完整列表**（doctor 的 `adp-list` 可导出）。
+- `data/verified.json`（区别于 `verified-repos.json`）当前内容未读。
+- 本表**未执行任何家族工具**；所有行为描述均为**文档化行为**，非实测行为。

package/guide/links.md

@@ -44,7 +44,7 @@
 
 | 主题 | 本地副本 | GitHub 直链 |
 |---|---|---|
-| 会话格式版本状态（**版本权威**） | `docs/session-format-status.md`（含 `latestFinalizedVersion: 4` / `latestReleasedVersion: 3` 记录） | [blob](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/session-format-status.md) |
+| 会话格式版本状态（**版本权威**） | `docs/session-format-status.md`（**版本权威**；镜像基线已更新为 `latestReleasedVersion: 4` / `evidenceTag: dsh-v0.2.0-rc.2`） | [blob](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/session-format-status.md) |
 | 逐版本迁移指南（**无 index、无入链**，6 篇） | `docs/upgrade-guide/v0.1.7-rc.2/**`、`docs/upgrade-guide/v0.2.0-rc.2/**`（schedule-optional-bundle、transcript-view-legacy-normal、account-sign-in-errors、remove-runtime-invariants、schedule-bundle-retired、subpath-plugin-display-manifest） | [目录](https://github.com/deepseek-ai/deepseek-harness/tree/master/docs/upgrade-guide) |
 | 持久化类型变更记录（含 V4 声明） | `docs/persistence-changes/**`（`2026-09-16-session-format-v4.md`、`finalized/v4.json`、`historical-formats/v3.md`…） | [目录](https://github.com/deepseek-ai/deepseek-harness/tree/master/docs/persistence-changes) |
 | 圆角规范 | `docs/ui-radius.md` | [blob](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/ui-radius.md) |
@@ -77,7 +77,8 @@
 | [omdsh-dev/plugin-template](https://github.com/omdsh-dev/plugin-template) | 生产级独立插件模板：src 四文件结构 + 7 个开发 skill + 自包含 prepare + 契约文档 |
 | [omdsh-dev/dsh-plugin-dev](https://github.com/omdsh-dev/dsh-plugin-dev) | 踩坑档案：20 个实测坑 + 环境基线 |
 | [Opr4Mp3r/deepseek-harness-plugin-from-scratch](https://github.com/Opr4Mp3r/deepseek-harness-plugin-from-scratch) | 代码审计式渐进教程：17 反模式 + 交付检查单 |
-| [vlln/plugin-registry](https://github.com/vlln/plugin-registry) | 插件注册中心 + make-dsh-plugin skill + 机制时间线（repository 0809→0811） |
+| [vlln/dsh-skills](https://github.com/vlln/dsh-skills) | ✅ **现行**（`plugin-registry` 于 2026-10-03 归档后的继任者）：`make-dsh-plugin` 开发引导 skill + 0.1.6→0.2.0 改名症状表 + 实测踩坑（`gotchas.md`） |
+| ~~[vlln/plugin-registry](https://github.com/vlln/plugin-registry)~~ | ⚠️ **已归档（2026-10-03）**，冻结在 0.1.5 基线。仍可引其 repository-plugin 0809→0811 机制时间线，但**不要再当作活项目** |
 | [whyihaveyou/dsh-suite](https://github.com/whyihaveyou/dsh-suite) | 双语插件目录 + `npm create dsh-plugin` 脚手架 + 每日兼容性 CI |
 | [omdsh-dev/dsh-plugin-check](https://github.com/omdsh-dev/dsh-plugin-check) | 插件健康检查：清单协议 / patch 格式 / 构建陷阱 |
 | [omdsh-dev/dsh-plugin-skills](https://github.com/omdsh-dev/dsh-plugin-skills) | agent 会话内搭建/测试插件的 skill 集 |