dsh-plugin-guide 0.3.27 → 0.3.30

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 is pinned to that same commit (429 md pages, re-synced 2026-10-13; see [references/official-docs/SNAPSHOT.md](references/official-docs/SNAPSHOT.md)). `guide/migration-0.2.md` covers `0.1.6-alpha.2` → `0.2.1-alpha.1` in §0–§12 and `0.2.1-alpha.1` → `0.2.1-alpha.2` as 19 citable seams in §13; the 20 breaking-change guides added since the previous baseline (19 under `v0.2.1-alpha.1` plus one backfilled into `v0.2.0-rc.2`) are all in the mirror. |
 | Node | `^22.19.0 || >=24.0.0` (DeepSeek Harness runtime) |
 | Platforms | All (plain ESM bundle; no native code, no network) |
 | Model | Any (no model interaction) |
@@ -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,17 @@ 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`，然后按下表决定读什么。**不要跳过这一步**——本库 17 篇文档里对当前宿主不适用的部分不会自己标注。
+   | 你的 `dsh --version` | 含义 | 读什么 |
+   |---|---|---|
+   | `< 0.1.7-alpha.1` | 旧基线 | 本世代破坏性变更**全部适用** → `guide/migration-0.2.md` §0–§12 逐条改 |
+   | `0.1.7-alpha.1` – `0.2.1-alpha.1` | 中间线 | 会话格式 V4 已生效；§13 的 19 条**不适用** |
+   | `0.2.1-alpha.2` 或更新 | 最新线 | §13 的 19 条**适用** → `guide/version-matrix.md` §3 |
+   | **npm `latest`（= `0.2.0-rc.2`）** | **默认安装拿到的就是这一版** | ⚠️ 它**早于** master 一版：§13 不适用，但 `version-matrix.md` §1.1 的"不存在稳定版"警告适用 |
+   **四个"最新"不是同一个东西**：npm `latest`=`next`=`0.2.0-rc.2`、npm `alpha`=`0.2.1-alpha.2`、master 最新 tag = `dsh-v0.2.1-alpha.2`。**不存在稳定版**（全部 31 个 npm 版本都是 prerelease）。完整谱系、子包 `latest` 冻结陷阱与 peer 区间选择见 `guide/version-matrix.md`。
 1. 若未读过 Cordis 概念：读 `references/official-docs/docs/cordis-primer.md`（5 个概念，5 分钟）；需要动手跟练时跑 `references/official-docs/docs/cordis-tutorial/` 01-07（无 API key 可跑）。
 2. 打开 `guide/quick-reference.md`（契约速查）+ `guide/plugin-dev-guide.md`（完整路径）。官方/社区文档 URL 对照见 `guide/links.md`。排查官方运行时行为/未修复 bug 时查 `guide/unfixed-issues.md`（master 基线源码核实的问题清单 + 已修复提交号 + 设计行为对照 + 本世代新核实的 T1–T11）。决定一个插件**该不该继续维护**（官方已进内核 / 第三方采用度显著更高）时查 `guide/when-to-retire-a-plugin.md`（判据 + 实测倍数表）；判断某个能力面谁领先时查 `guide/choosing-a-plugin.md`。
+2b. **要判断"该改哪一行 / 该找哪个工具"时**，读 `guide/family-toolchain.md`（家族工具链路由：问题→所有者→可引用产物；`dsh-plugin-doctor` 33 项检查全表与裁定语义；本库 16 项检查与 doctor 的交叉对照）。发布流水线（多插件组合的持续可安装/可发布/可升级）见 `guide/release-engineering.md`。
 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 +49,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。
@@ -54,10 +62,10 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 - **新服务/能力**：`docs/user/develop/framework/service.md` + `docs/user/develop/practice/`（三层拆分完整代码）。
 - **拦截/策略/hook**：`docs/cookbook/extension-cookbook.md`（permission-gate 范例）+ `docs/event-producer-consumer.md`（全事件矩阵）。
 - **新 LLM 提供商**：`docs/user/develop/practice/llm-adapter.md`（StreamChunk 协议）。
-- **UI 插件（Web）**：`references/official-plugin-dev-skill.md` §3.2 + `docs/subsystems/slots.md`、`sidebar-right.md`、`client-modules.md`、`web-client.md`、`ui-radius.md`；Chat 行业务节点用 `ctx.uiConversation.events.register()` + `conversation.chat.node` slot。
+- **UI 插件（Web）**：`references/official-plugin-dev-skill.md` §3.2 + `docs/subsystems/slots.md`、`sidebar-right.md`、`client-modules.md`、`web-client.md`、**`docs/ui-radius.md`**（注意 `ui-radius` 在 `docs/` 顶层，**不在** `docs/subsystems/` 下）；Chat 行业务节点用 `ctx.uiConversation.events.register()` + `conversation.chat.node` slot。
 - **插件配置表单**：`docs/subsystems/settings.md`（已改名 "Plugin Configuration Forms"）+ `docs/cookbook/adding-a-settings-card.md`（已重写）。
 - **打包/发布**：`docs/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/`。
@@ -81,11 +89,16 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 
 ## CLI 工具链（dsh-plugin-dev）
 
-本仓库随 bundle 附带零依赖 CLI `dsh-plugin-dev`，把机械检查自动化（知识库仍是认知层，CLI 是机械层）：
+本仓库随 bundle 附带零依赖 CLI `dsh-plugin-dev`，把机械检查自动化（知识库仍是认知层，CLI 是机械层）。
 
-- `dsh-plugin-dev new <name>`：参数化脚手架，生成 TS 或 JS 插件仓库骨架（`src/index.ts` 契约模板、Schemastery Config、tests、tsdown/vitest、注释齐全的 `cordis.patch.yml`、五语 README），模板与 `references/official-docs` 同步更新。
-- `dsh-plugin-dev check [--json] [--strict]`：静态检查（`cordis.patch.yml` 合法性、`package.json` 元数据（`dsh.bundle.patch` 指向/peer 依赖/engines/files 白名单）、五语 README 一致性、工程红线模式），输出 CI 可消费的结构化 JSON；每个检查项在输出里引用本知识库对应章节（skill 联动），agent 可继续人工审计。
-- `dsh-plugin-dev verify`：`pnpm pack` 后装入干净临时 `DSH_HOME` profile 做安装+启动+卸载冒烟（对齐官方 verify:self-contained）；失败给出日志尾部与建议。
+> ⚠️ **调用方式**：`dsh-plugin-dev` **通常不在 PATH 上**（bundle 安装只登记技能，不安装二进制）。
+> 用本 SKILL.md 所在目录下的入口调用：`node "<resourceBase>/bin/dsh-plugin-dev.js" <子命令>`。
+> bundle 安装的包已带 `dist/`；从源码副本用则先跑一次 `pnpm run build`。
+> 只有全局 `npm i -g dsh-plugin-guide` 之后才可以直接敲 `dsh-plugin-dev`。
+
+- `new <name>`：参数化脚手架，生成 TS 或 JS 插件仓库骨架（`src/index.ts` 契约模板、Schemastery Config、tests、tsdown/vitest、注释齐全的 `cordis.patch.yml`、五语 README），模板与 `references/official-docs` 同步更新。标志：`--lang <ts|js>`、`--dir <path>`、`--force`、`--git`。
+- `check [--json] [--strict] [--cwd <dir>]`：静态检查（`cordis.patch.yml` 合法性、`package.json` 元数据（`dsh.bundle.patch` 指向/peer 依赖/engines/files 白名单）、五语 README 一致性、工程红线模式），输出 CI 可消费的结构化 JSON；每个检查项在输出里引用本知识库对应章节（skill 联动），agent 可继续人工审计。**这 16 项是同族 `dsh-plugin-doctor` 33 项的子集**（逐项对照见 `guide/family-toolchain.md` §3）；发布前建议两个都跑。
+- `verify [--cwd <dir>] [--base <spec>] [--headless <spec>] [--profile <name>]`：`pnpm pack` 后装入干净临时 `DSH_HOME` profile 做安装+启动+卸载冒烟（对齐官方 verify:self-contained）；失败给出日志尾部与建议。
 
 三个子命令均可逆/幂等；网络/子进程尊重超时与 AbortSignal；只清理自己 mkdtemp 的目录。CLI 零运行时依赖，构建产物经 tsdown 打包为单文件 `dist/dsh-plugin-dev.js`。
 

package/dist/dsh-plugin-dev.js

@@ -9,14 +9,31 @@ const LONG_ALIASES = {
 	help: "help",
 	version: "version"
 };
+/** Raised for a malformed or unrecognised argument. */
+var UsageError = class extends Error {};
 /**
 * Parse an argv slice (without the node/script prefix) into positionals and flags.
+*
+* `allowed` is the set of long flag names the caller accepts (aliases included).
+* Passing it turns an unrecognised flag into a `UsageError` instead of a silently
+* ignored one: `dsh-plugin-dev check --stirct` used to parse the typo, check
+* nothing extra, and exit 0 — a gate that can be disabled by a spelling mistake
+* is worse than no gate, because CI stays green and everyone believes it ran.
+*
 * @param argv - process.argv.slice(2) style input.
+* @param allowed - optional allowlist of accepted long flag names.
 * @returns the parsed structure.
 */
-function parseArgs(argv) {
+function parseArgs(argv, allowed) {
 	const positionals = [];
 	const flags = {};
+	const permitted = allowed ? new Set(allowed) : void 0;
+	const assertAllowed = (key) => {
+		if (permitted && !permitted.has(key)) {
+			const known = [...permitted].sort().join(", ");
+			throw new UsageError(`unknown option "--${key}" (accepted: ${known})`);
+		}
+	};
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
 		if (arg === "--") {
@@ -27,10 +44,13 @@ function parseArgs(argv) {
 			const body = arg.slice(2);
 			const eq = body.indexOf("=");
 			if (eq >= 0) {
-				setFlag(flags, body.slice(0, eq), body.slice(eq + 1));
+				const key = body.slice(0, eq);
+				assertAllowed(LONG_ALIASES[key] ?? key);
+				setFlag(flags, key, body.slice(eq + 1));
 				continue;
 			}
 			const key = body;
+			assertAllowed(LONG_ALIASES[key] ?? key);
 			const next = argv[i + 1];
 			if (next !== void 0 && !next.startsWith("-")) {
 				setFlag(flags, key, next);
@@ -39,7 +59,10 @@ function parseArgs(argv) {
 			continue;
 		}
 		if (arg.startsWith("-") && arg.length > 1) {
-			for (const ch of arg.slice(1)) flags[ch] = true;
+			for (const ch of arg.slice(1)) {
+				assertAllowed(ch);
+				flags[ch] = true;
+			}
 			continue;
 		}
 		positionals.push(arg);
@@ -146,10 +169,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 +207,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) {
@@ -900,7 +932,8 @@ function checkManifestFiles(_root, pkg) {
 	const problems = [];
 	for (const patchFile of patchFiles) if (!files.includes(patchFile)) problems.push(`files whitelist is missing the patch file "${patchFile}"`);
 	if (main && !files.includes(main) && !files.some((f) => main.startsWith(`${f.replace(/\/$/, "")}/`))) problems.push(`files whitelist is missing the main entry "${main}"`);
-	if (!files.some((f) => f === "lib" || f === "dist")) problems.push("files whitelist has no built-artifact directory (`lib` or `dist`)");
+	const entryDir = main?.includes("/") ? main.slice(0, main.indexOf("/")) : void 0;
+	if (entryDir && (entryDir === "lib" || entryDir === "dist") && !files.includes(entryDir)) problems.push(`files whitelist has no built-artifact directory ("${entryDir}"), but main points into it`);
 	if (problems.length > 0) return {
 		id: "manifest-files",
 		severity: "error",
@@ -1095,14 +1128,26 @@ function checkReadmeConsistency(root) {
 		skillRef: ref
 	};
 }
-/** Body of SKILL.md after its YAML frontmatter, or undefined. */
+/**
+* Body of SKILL.md after its YAML frontmatter, or undefined when the file is
+* absent. Falls back to the whole text when there is no well-formed block.
+*
+* CRLF tolerance is load-bearing: without `.gitattributes`, a Windows checkout
+* (`core.autocrlf=true`) delivers CRLF while CI and the published tarball
+* deliver LF. An exact `startsWith('---\n')` guard therefore failed locally,
+* leaving the frontmatter in the "body" — so `redline-persona-role` judged the
+* `name:` line as the opening paragraph and emitted a false warning on every
+* local run while CI stayed green. Keep this in step with `index.js`.
+*/
 function skillBody(root) {
 	const text = readText(join(root, "SKILL.md"));
 	if (!text) return void 0;
-	if (!text.startsWith("---\n")) return text;
-	const end = text.indexOf("\n---", 4);
-	if (end < 0) return text;
-	return text.slice(end + 4).replace(/^\n+/, "");
+	const open = /^---\r?\n/.exec(text);
+	if (!open) return text;
+	const rest = text.slice(open[0].length);
+	const close = /\r?\n---[ \t]*(?:\r?\n|$)/.exec(rest);
+	if (!close) return text;
+	return rest.slice(close.index + close[0].length).replace(/^(?:[ \t]*\r?\n)+/, "");
 }
 function checkRedlinePersonaRole(root) {
 	const ref = skillRefFor("redline-persona-role");
@@ -1626,8 +1671,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 +1862,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");
@@ -1912,7 +1957,37 @@ function timeoutMs(flags, key, envKey, fallback) {
 * @param cwd - working directory (injectable for tests).
 */
 async function main(argv, cwd = process.cwd()) {
-	const { positionals, flags } = parseArgs(argv);
+	const KNOWN_FLAGS = [
+		"help",
+		"h",
+		"version",
+		"V",
+		"lang",
+		"dir",
+		"force",
+		"git",
+		"cwd",
+		"json",
+		"strict",
+		"dsh",
+		"pnpm",
+		"profile",
+		"base",
+		"headless",
+		"timeout",
+		"smoke-timeout"
+	];
+	let parsed;
+	try {
+		parsed = parseArgs(argv, KNOWN_FLAGS);
+	} catch (err) {
+		if (err instanceof UsageError) {
+			process.stderr.write(`dsh-plugin-dev: ${err.message}\n`);
+			return 2;
+		}
+		throw err;
+	}
+	const { positionals, flags } = parsed;
 	if (flagBool(flags, "version") || flags.V === true) {
 		process.stdout.write(`${readCliVersion()}\n`);
 		return 0;
@@ -1955,8 +2030,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)
 				});