dsh-plugin-guide 0.3.26 → 0.3.29

package/guide/quick-reference.md

@@ -53,7 +53,7 @@ Other forms: object `export default { name, inject, apply }`; class `class X ext
 
 Lifecycle: `PENDING → LOADING → ACTIVE` (apply throws → FAILED); `ACTIVE → UNLOADING → DISPOSED`. A required service disappearing unloads the plugin; it reloads when the service returns.
 
-## Event dispatch modes + bail
+## Event dispatch modes (five, including bail)
 
 | Mode | awaited | Order | Return value |
 |---|---|---|---|
@@ -61,6 +61,7 @@ Lifecycle: `PENDING → LOADING → ACTIVE` (apply throws → FAILED); `ACTIVE
 | waterfall | no | registration order | yes (**not calling next() short-circuits**) |
 | parallel | yes | parallel | none |
 | serial | yes | registration order | yes (first non-empty stops) |
+| bail | no | registration order | yes (first non-null/false/undefined short-circuits and stops the rest) |
 
 Typed events (declaration merging):
 
@@ -136,7 +137,7 @@ Chunk protocol: `block-start` → `text-delta*` → `block-end` (complete block)
 3. Weakest mechanism that suffices: `ctx.tools.restrict()` (remove only) < `ctx.tools.guard()` (deny only) < waterfall rewrite (order-dependent) < `system-prompt/assemble` (replaces everything). Observe final outcomes on `tools/result`; use `tools/post-execute` only to transform.
 4. Model-visible ⇔ logged: new model-visible input requires a new session event (`SessionEventMap`) — added by the host, never by appending a new `type` yourself (see rule 8).
 5. Never hardcode tunables (test: can cordis.yml change it?); misconfiguration fails loud. Live-editable user fields use `Volatile<T>` + `loader/volatile-update` (the form namespace is the profile entry id).
-6. Standalone plugin packages: cordis is a peerDependency matching the host identity (mixing scoped `@deepseek-ai/cordis` and unscoped splits identities); ESM; `dsh.bundle` manifest (`patch` may be an ordered array); git installs need `prepare` + `allowBuilds`; ship `lib/` or a tarball. Shared-instance dsh packages go in **peerDependencies + devDependencies only** — never `dependencies` (a profile copy silently shadows the runtime, and DSH does not validate peer ranges).
+6. Standalone plugin packages: cordis is a peerDependency matching the host identity (mixing scoped `@deepseek-ai/cordis` and unscoped splits identities); ESM; `dsh.bundle` manifest (`patch` may be an ordered array); git installs need `prepare` + `allowBuilds`; ship `lib/` or a tarball. Shared-instance dsh packages go in **peerDependencies + devDependencies only** — never `dependencies` (a profile copy silently shadows the runtime). ⚠️ Corrected: **peer ranges ARE enforced at install time** — `dsh plugin add` compares the runtime version against the declared `@deepseek-ai/dsh-*` range and refuses the install; only `engines.dsh` is declarative and unenforced. A range says "can it install", not "does this API exist" — keep runtime probing (range selection: `version-matrix.md` §4).
 7. Ship display metadata: `locale/*.json` `meta.title`/`meta.description` plus an exported `./icon` (SVG/PNG/JPEG/WebP, ≤256 KiB, inside the package). Subpath plugins never read their own `package.json`.
 8. Bilingual docs in pairs; tool descriptions/prompts are behavior; non-trivial changes need an Agent Note; run the minimal check set before pushing (dsh-pre-push-checks).
 9. Opaque cross-boundary ids are branded (`Branded<B>` from `dsh-brand`), never bare `string`.
@@ -153,7 +154,7 @@ Chunk protocol: `block-start` → `text-delta*` → `block-end` (complete block)
 - Windows junctions via PowerShell `New-Item -ItemType Junction`; vitest drive letter must be uppercase `C:/`.
 - `DSH_PERMISSION_MODE=danger-full-access` is high-risk (no sandbox backend on Windows, approvals disabled); `DSH_*` vars in `~/.dsh/.env` break startup.
 - Session files are multi-frame zstd: use `scanZstdFrames`/`createZstdFrameDecoder` (`@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts`).
-- npm: unscoped `dsh` is the unrelated node-dsh shell — install `@deepseek-ai/dsh` (`latest`=`next`=0.2.0-rc.2, `alpha`=0.2.1-alpha.1); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` and `@deepseek-ai/dsh-session-persistence-jsonl` still ship a stale `latest` (0.0.1-rc.1), so pin `next` (0.2.0-rc.2) or `alpha` (0.2.1-alpha.1); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.0.4 with a new `dsh-0-2-1-alpha-1` tag at 4.0.5-alpha.1; dsh-core/dsh-sdk still unpublished (verified 2026-10-06).
+- npm: unscoped `dsh` is the unrelated node-dsh shell — install `@deepseek-ai/dsh` (`latest`=`next`=0.2.0-rc.2, `alpha`=0.2.1-alpha.2); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` and `@deepseek-ai/dsh-session-persistence-jsonl` still ship a stale `latest` (0.0.1-rc.1), so pin `next` (0.2.0-rc.2) or `alpha` (0.2.1-alpha.1); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.0.4 with a new `dsh-0-2-1-alpha-1` tag at 4.0.5-alpha.1; dsh-core/dsh-sdk still unpublished (verified 2026-10-06).
 - `resolve()` both sides before path comparisons (Windows backslash trap).
 
 ## Documentation links
@@ -171,8 +172,8 @@ Community dev docs — templates/tutorials/pitfalls, full list in [references/co
 
 ## Key source index
 
-- Official docs verbatim: `references/official-docs/docs/**` (369 md pages, all 182 `.zh.md` pairs included); the pages **not on the documentation site** (session-format-status, `upgrade-guide/**`, `persistence-changes/**`, ui-radius, web-styling, module-graph) are listed in [links.md](links.md) §2.1
-- Migration checklist: [migration-0.2.md](migration-0.2.md) (every breaking change from 0.1.6-alpha.2 → 0.2.1-alpha.1, with the official upgrade-guide source for each)
+- Official docs verbatim: `references/official-docs/docs/**` (429 md pages, all 212 `.zh.md` pairs included, mirror at `dsh-v0.2.1-alpha.2`); the pages **not on the documentation site** (session-format-status, `upgrade-guide/**`, `persistence-changes/**`, ui-radius, web-styling, module-graph) are listed in [links.md](links.md) §2.1
+- Migration checklist: [migration-0.2.md](migration-0.2.md) — §0–§12 cover every breaking change from `0.1.6-alpha.2` → `0.2.1-alpha.1`, and §13 covers `0.2.1-alpha.1` → `0.2.1-alpha.2` as 19 citable seams (`L1`–`L19`); each entry cites its official upgrade-guide source
 - The official in-repo plugin-development skill: [references/official-plugin-dev-skill.md](../references/official-plugin-dev-skill.md)
 - Repo-root constraints: `references/official-docs/AGENTS.md`, `references/official-docs/packages/AGENTS.md`, `references/official-docs/vendor/README.md`; sync state in `references/official-docs/SNAPSHOT.md`
 - Site crawl HTML: `downloads/web/site/**` (EN+ZH full site) + `downloads/manifest.tsv` (download ledger)

package/guide/quick-reference.pt.md

@@ -53,7 +53,7 @@ Outras formas: objeto `export default { name, inject, apply }`; classe `class X
 
 Ciclo de vida: `PENDING → LOADING → ACTIVE` (apply lança erro → FAILED); `ACTIVE → UNLOADING → DISPOSED`. Se um serviço necessário desaparece, o plugin descarrega; recarrega quando o serviço volta.
 
-## Modos de despacho de eventos + bail
+## Modos de despacho de eventos (cinco, incluindo bail)
 
 | Modo | await | Ordem | Valor de retorno |
 |---|---|---|---|
@@ -61,6 +61,7 @@ Ciclo de vida: `PENDING → LOADING → ACTIVE` (apply lança erro → FAILED);
 | waterfall | não | ordem de registro | sim (**não chamar `next()` causa curto-circuito**) |
 | parallel | sim | paralelo | nenhum |
 | serial | sim | ordem de registro | sim (o primeiro não vazio para) |
+| bail | não | ordem de registro | sim (o primeiro não null/false/undefined curto-circuita e PARA o resto) |
 
 Eventos tipados (declaration merging):
 
@@ -136,7 +137,7 @@ Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloco comp
 3. **O mecanismo mais fraco que basta**: `ctx.tools.restrict()` (só remove) < `ctx.tools.guard()` (só nega) < reescrita por waterfall (depende da ordem) < `system-prompt/assemble` (substitui tudo). Observe resultados finais em `tools/result`; use `tools/post-execute` só para transformar.
 4. Visível-para-o-modelo ⇔ registrado: nova entrada visível exige novo evento de sessão (`SessionEventMap`) — **adicionado pelo host**, não por você (ver regra 10).
 5. Nunca codifique valores ajustáveis (teste: o cordis.yml consegue mudá-los?); má configuração falha em voz alta. Campos editáveis ao vivo usam `Volatile<T>` + `loader/volatile-update` (o namespace do formulário é o id da entrada do perfil).
-6. Pacotes de plugin independentes: cordis é peerDependency com a mesma identidade do host (misturar scoped `@deepseek-ai/cordis` e unscoped divide identidades); ESM; manifesto `dsh.bundle` (`patch` pode ser uma lista ordenada); instalações git precisam de `prepare` + `allowBuilds`; publique `lib/` ou um tarball. Pacotes dsh de instância compartilhada ficam **só em peerDependencies + devDependencies**, nunca em `dependencies` (uma cópia no perfil sombreia o runtime em silêncio, e o DSH **não valida** faixas de peer).
+6. Pacotes de plugin independentes: cordis é peerDependency com a mesma identidade do host (misturar scoped `@deepseek-ai/cordis` e unscoped divide identidades); ESM; manifesto `dsh.bundle` (`patch` pode ser uma lista ordenada); instalações git precisam de `prepare` + `allowBuilds`; publique `lib/` ou um tarball. Pacotes dsh de instância compartilhada ficam **só em peerDependencies + devDependencies**, nunca em `dependencies` (uma cópia no perfil sombreia o runtime em silêncio). ⚠️ Corrigido: **faixas de peer SÃO aplicadas na instalação** — `dsh plugin add` compara a versão do runtime com a faixa declarada de `@deepseek-ai/dsh-*` e recusa a instalação; apenas `engines.dsh` é declarativo e não aplicado. Uma faixa diz "dá para instalar", não "esta API existe": mantenha a sondagem em runtime (escolha de faixa: `version-matrix.md` §4).
 7. Publique metadados de exibição: `locale/*.json` com `meta.title`/`meta.description` e um `./icon` exportado (SVG/PNG/JPEG/WebP, ≤256 KiB, dentro do pacote). Plugins de subcaminho **nunca** leem o próprio `package.json`.
 8. Documentação bilíngue em pares; descrições/prompts são comportamento; mudanças não triviais levam Agent Note; rode o conjunto mínimo de verificações antes de empurrar (dsh-pre-push-checks).
 9. IDs opacos entre limites são branded (`Branded<B>` de `dsh-brand`), nunca `string` crua.
@@ -153,7 +154,7 @@ Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloco comp
 - Junctions do Windows via PowerShell `New-Item -ItemType Junction`; letra de unidade do vitest em maiúscula `C:/`.
 - `DSH_PERMISSION_MODE=danger-full-access` é de alto risco (sem backend de sandbox no Windows, aprovações desativadas); `DSH_*` em `~/.dsh/.env` quebra a inicialização.
 - Arquivos de sessão são zstd multiframe: use `scanZstdFrames`/`createZstdFrameDecoder` (`@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts`).
-- npm: o `dsh` sem escopo é o projeto alheio node-dsh (um shell) — instale `@deepseek-ai/dsh` (`latest`=`next`=0.2.0-rc.2, `alpha`=0.2.1-alpha.1); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` e `@deepseek-ai/dsh-session-persistence-jsonl` ainda publicam um `latest` obsoleto (0.0.1-rc.1), fixe `next` (0.2.0-rc.2) ou `alpha` (0.2.1-alpha.1); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.0.4 com a nova tag `dsh-0-2-1-alpha-1` em 4.0.5-alpha.1; dsh-core/dsh-sdk seguem não publicados (verificado em 2026-10-06).
+- npm: o `dsh` sem escopo é o projeto alheio node-dsh (um shell) — instale `@deepseek-ai/dsh` (`latest`=`next`=0.2.0-rc.2, `alpha`=0.2.1-alpha.2); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` e `@deepseek-ai/dsh-session-persistence-jsonl` ainda publicam um `latest` obsoleto (0.0.1-rc.1), fixe `next` (0.2.0-rc.2) ou `alpha` (0.2.1-alpha.1); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.0.4 com a nova tag `dsh-0-2-1-alpha-1` em 4.0.5-alpha.1; dsh-core/dsh-sdk seguem não publicados (verificado em 2026-10-06).
 - Aplique `resolve()` nos dois lados antes de comparar caminhos (armadilha da barra invertida do Windows).
 
 ## Links de documentação

package/guide/quick-reference.zh-CN.md

@@ -52,7 +52,7 @@ export function apply(ctx: Context, config: Config) {
 
 生命周期：`PENDING → LOADING → ACTIVE`（apply 抛错 → FAILED）；`ACTIVE → UNLOADING → DISPOSED`。依赖服务消失 → 自动卸载，恢复 → 自动重载。
 
-## 事件派发四模式 + bail
+## 事件派发五模式（含 bail）
 
 | 模式 | await | 顺序 | 返回值 |
 |---|---|---|---|
@@ -60,6 +60,7 @@ export function apply(ctx: Context, config: Config) {
 | waterfall | 否 | 注册序 | 有（**不调 next() 即短路**） |
 | parallel | 是 | 并行 | 无 |
 | serial | 是 | 注册序 | 有（首个非空即止） |
+| bail | 否 | 注册序 | 有（首个非 null/false/undefined 即短路，**并停止后续监听器**） |
 
 类型声明（declaration merging）：
 
@@ -135,7 +136,7 @@ Chunk 协议：`block-start` → `text-delta*` → `block-end`（完整块）→
 3. **用最弱的够用机制**：`ctx.tools.restrict()`（只移除）< `ctx.tools.guard()`（只拒绝）< waterfall 改写（依赖顺序）< `system-prompt/assemble`（整段替换）。最终结果只看 `tools/result`；只有要变换结果才用 `tools/post-execute`。
 4. 模型可见 ⟺ 已记录：新模型可见输入必须新增会话事件（`SessionEventMap`）——**由宿主侧新增**，不是插件自己写（见第 10 条）。
 5. 不得硬编码可调参数（判断：cordis.yml 能否改）；misconfig fail loud。要暴露给用户的实时字段用 `Volatile<T>` + `loader/volatile-update`（表单命名空间=profile 条目 id）。
-6. 独立插件包：cordis 是 peerDependency（与宿主同身份：scoped `@deepseek-ai/cordis` 与 unscoped 混用会"双 Cordis 分裂"）；ESM；`dsh.bundle` 清单（`patch` **可为有序数组**）；git 安装配 `prepare` + `allowBuilds`；发布带 `lib/` 或 tarball。**共享实例的 dsh 包只放 peer + dev，绝不放 dependencies**（profile 内副本会静默遮蔽运行时；且 DSH **不校验** peer 范围）。
+6. 独立插件包：cordis 是 peerDependency（与宿主同身份：scoped `@deepseek-ai/cordis` 与 unscoped 混用会"双 Cordis 分裂"）；ESM；`dsh.bundle` 清单（`patch` **可为有序数组**）；git 安装配 `prepare` + `allowBuilds`；发布带 `lib/` 或 tarball。**共享实例的 dsh 包只放 peer + dev，绝不放 dependencies**（profile 内副本会静默遮蔽运行时）。⚠️ **已更正：peer 范围会被安装期强制**——`dsh plugin add` 拿运行时版本比对声明的 `@deepseek-ai/dsh-*` 范围，不匹配即**拒绝安装**；只有 `engines.dsh` 是纯声明、零强制。范围只能表达"能不能装"，**表达不了某个 API 在不在**——仍要配运行时探测（区间选择见 `version-matrix.md` §4）。
 7. 必须交展示元数据：`locale/*.json` 的 `meta.title`/`meta.description` + 导出的 `./icon`（SVG/PNG/JPEG/WebP，≤256 KiB，必须在包内）。子路径插件**不读**自己的 `package.json`。
 8. 文档双语成对；工具描述/提示词即行为；非平凡变更加 Agent Note；提交前跑最小检查集（dsh-pre-push-checks）。
 9. 跨边界 opaque id 用 branded（`Branded<B>` from `dsh-brand`），从不裸 `string`。
@@ -152,7 +153,7 @@ Chunk 协议：`block-start` → `text-delta*` → `block-end`（完整块）→
 - Windows junction 用 PowerShell `New-Item -ItemType Junction`；vitest 盘符大写 `C:/`。
 - `DSH_PERMISSION_MODE=danger-full-access` 高风险（Windows 无沙箱后端、禁用审批）；`DSH_*` 放 `~/.dsh/.env` 会报错。
 - 会话文件多帧 zstd：用 `scanZstdFrames`/`createZstdFrameDecoder`（`@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts`）。
-- npm：无作用域 `dsh` 是无关项目 node-dsh（shell）——官方包是 `@deepseek-ai/dsh`（`latest`=`next`=0.2.0-rc.2、`alpha`=0.2.1-alpha.1）；`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-headless`、`@deepseek-ai/dsh-session-persistence-jsonl` 的 `latest` 仍是过期版本（0.0.1-rc.1），要钉 `next`（0.2.0-rc.2）或 `alpha`（0.2.1-alpha.1）；`create-dsh-plugin` latest=0.2.3；`@deepseek-ai/cordis` latest=4.0.4，另有新标签 `dsh-0-2-1-alpha-1`=4.0.5-alpha.1；dsh-core/dsh-sdk 仍未发布（2026-10-06 复核）。
+- npm：无作用域 `dsh` 是无关项目 node-dsh（shell）——官方包是 `@deepseek-ai/dsh`（`latest`=`next`=0.2.0-rc.2、`alpha`=0.2.1-alpha.2）；`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-headless`、`@deepseek-ai/dsh-session-persistence-jsonl` 的 `latest` 仍是过期版本（0.0.1-rc.1），要钉 `next`（0.2.0-rc.2）或 `alpha`（0.2.1-alpha.1）；`create-dsh-plugin` latest=0.2.3；`@deepseek-ai/cordis` latest=4.0.4，另有新标签 `dsh-0-2-1-alpha-1`=4.0.5-alpha.1；dsh-core/dsh-sdk 仍未发布（2026-10-06 复核）。
 - 路径比较前两侧都 `resolve()`（Windows 反斜杠陷阱）。
 
 ## 文档链接
@@ -170,8 +171,8 @@ Chunk 协议：`block-start` → `text-delta*` → `block-end`（完整块）→
 
 ## 关键源索引
 
-- 本地官方文档全文：`references/official-docs/docs/**`（369 篇，含全部 182 个 `.zh.md`）；**没上文档站**的那些页（session-format-status、`upgrade-guide/**`、`persistence-changes/**`、ui-radius、web-styling、module-graph）见 [links.md](links.md) §2.1
-- 迁移清单：[migration-0.2.md](migration-0.2.md)（0.1.6-alpha.2 → 0.2.1-alpha.1 的全部破坏性变更，逐条附官方 upgrade-guide 出处）
+- 本地官方文档全文：`references/official-docs/docs/**`（429 篇，含全部 212 个 `.zh.md`；镜像基线 `dsh-v0.2.1-alpha.2`）；**没上文档站**的那些页（session-format-status、`upgrade-guide/**`、`persistence-changes/**`、ui-radius、web-styling、module-graph）见 [links.md](links.md) §2.1
+- 迁移清单：[migration-0.2.md](migration-0.2.md) —— §0–§12 覆盖 `0.1.6-alpha.2` → `0.2.1-alpha.1` 的全部破坏性变更，**§13 把 `0.2.1-alpha.1` → `0.2.1-alpha.2` 整理成 19 个可引用 seam（`L1`–`L19`）**；每条都附官方 upgrade-guide 出处
 - 官方自带插件开发技能：[references/official-plugin-dev-skill.md](../references/official-plugin-dev-skill.md)
 - 仓库根约束：`references/official-docs/AGENTS.md`、`references/official-docs/packages/AGENTS.md`、`references/official-docs/vendor/README.md`；同步状态见 `references/official-docs/SNAPSHOT.md`
 - 站点爬取 HTML：`downloads/web/site/**`（中英双语全站）+ `downloads/manifest.tsv`（下载清单）

package/guide/release-engineering.md

@@ -42,14 +42,16 @@ The pattern that admits all windows (one clause per prerelease tuple; each `-0`
 {
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.3.0"
+    "@deepseek-ai/dsh-tools": ">=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"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-tools": "0.1.7-rc.2"
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2"
   }
 }
 ```
 
+⚠️ **Do not write the open form `>=0.1.2-rc.1 <0.3.0`.** It looks like the widest safe range and is the opposite: it spans an entire breaking-change generation, so the gate admits a `0.2.x` host while your plugin still calls `0.1.x` APIs — an install-time pass followed by a runtime break. **Upper bounds must be cut per generation** (`<0.2.0` / `<0.3.0`), and the six-clause shape above is the canonical range recorded in `dsh-plugin-kit`'s `data/peer-range.json` (`canonicalRange`, updated 2026-09-26). `dsh-plugin-doctor`'s R8 flags the open form.
+
 A range is only as wide as its newest clause, and semver makes this easy to get wrong in a way that looks right: **a range admits a prerelease only if some comparator carries that same `[major, minor, patch]` tuple AND a prerelease.** So a band ending at `>=0.1.6-0 <0.2.0` admits `0.1.6-alpha.2` but *not* `0.1.7-alpha.2` — it reads as "everything up to 0.2" and behaves as "nothing after the 0.1.6 tuple". Adding the line's own clause is the whole fix; check it with `semver.satisfies('0.1.7-alpha.2', range)`, never by eye.
 
 Rules that follow:

package/guide/release-engineering.zh-CN.md

@@ -42,14 +42,16 @@
 {
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.3.0"
+    "@deepseek-ai/dsh-tools": ">=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"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-tools": "0.1.7-rc.2"
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2"
   }
 }
 ```
 
+⚠️ **不要写开区间 `>=0.1.2-rc.1 <0.3.0`。** 它看起来是最宽的"安全"范围，实际正相反：它横跨整整一代破坏性变更，门禁会放行 `0.2.x` 宿主，而你的插件还在调 `0.1.x` 的 API——**安装期放行、运行期炸**。**上界必须按世代切**（`<0.2.0` / `<0.3.0`）；上面这个六子句形态就是 `dsh-plugin-kit` 的 `data/peer-range.json`（`canonicalRange`，2026-09-26 更新）记录的规范区间，`dsh-plugin-doctor` 的 R8 会标记开区间写法。
+
 范围的宽度只等于它最新那条子句，而 semver 在这里很容易让人写错、且**看起来是对的**：**一个范围只有在某条比较符带着同一个 `[major, minor, patch]` tuple 且带预发布时，才接纳该预发布版本。** 所以一条止于 `>=0.1.6-0 <0.2.0` 的带子接纳 `0.1.6-alpha.2`，却**不**接纳 `0.1.7-alpha.2`——读起来像"0.2 之前全都要"，行为上却是"0.1.6 tuple 之后一概不要"。补上该线自己的子句就是全部修法；用 `semver.satisfies('0.1.7-alpha.2', range)` 去验，**不要用眼睛看**。
 
 由此得到的规则：

package/guide/unfixed-issues.md

@@ -8,6 +8,13 @@
 > - 复核基线 1：`0d1f50007f9bca3f52b06e1c3074fa14d5fb0720`（2026-09-15，0.1.6-alpha.1 世代；区间 666 提交）
 > - 复核基线 2：`ddefc45fbc7f8e46dd73185e68295696d1297887`（`dsh-v0.1.6-alpha.2`，2026-09-19；+882 提交）
 > - **复核基线 3：`5badb15009ae1756c3afe0ae0cef1faafc290ccc`（`dsh-v0.2.1-alpha.1`，2026-10-03；+2300 余提交 / 8763 改动文件）——2026-10-06 全表重核，逐条复核覆盖 #1–#32 与 S1–S7**：
+>
+> ⚠️ **阅读本表前必读的基线口径**：本文件全部 `path:line` 与"已修复提交号"**钉在复核基线 3（`5badb15`，2026-10-03）**。
+> 本库的官方文档镜像已在 **2026-10-13 重同步到 `d743267388641bc76f17c45ce8b4c231aed1d32c`（`dsh-v0.2.1-alpha.2`）**——
+> 也就是说**镜像比本表新一版**。二者不是矛盾，是两个不同用途的基线：
+> 镜像求"与上游逐字节一致"，本表求"每条结论有可复核的行号锚点"。
+> **在 `5badb15` 上复核行号**（`git -C <checkout> show 5badb15:<path>`），或用镜像里的路径但**预期行号可能已漂移**。
+> 下一轮全表重核的目标基线是 `d743267`；在重核完成前，请把"未修复"读作"**截至 2026-10-03 未修复**"。
 >   - **转入已修复 4 项**：#2（协议平面压平为 Messages-only，旧 chat-completions 半边删除；**后继形态 #8836 仍在**）、#5（`code`→`ptc` 迁移）、#10（pi-ai ^0.87.1 带上 `x-opencode-session`）、#22（压缩阈值改为 `min(window×ratio, window−reserved−headroom)`）、#29（telemetry 读取拍平 + 迁移产物强校验）——共 5 项，其中 #5 的修复**早于上一基线**，说明旧条目本身就过时。
 >   - **判为不可复现 1 项**：#4（read_image）移入 §2，保留记录但**不要再当 bug 传播**。
 >   - **部分修复 3 项**：#1（同级已接受、更窄仍抛）、#13（windowsHide 半侧已消失，自愈半侧仍在）、#19（`./invariant` 子路径已随 invariants 整体移除而消失，残留 devDependency `dsh-attachment` 引用）、S5（SKILL.md 半侧早已修好，仅剩生成文件/文档措辞残留）——共 4 项。

package/guide/version-matrix.md

@@ -0,0 +1,309 @@
+# DSH 版本适配矩阵（version-matrix.md）
+
+> **这份文件回答一个问题**：我的插件要跑在哪个 DSH 上，那个版本有什么、没有什么、
+> 哪一版开始行为变了。
+>
+> **测量时间**：2026-10-09（官方版本线）／2026-10-13（生态数字）。
+> **数据来源**：npm registry `@deepseek-ai/dsh`、GitHub REST API（tags/commits/releases）、
+> 官方 `docs/upgrade-guide/**`、官方 `docs/persistence-changes/**`。逐条可复现命令见 §7。
+>
+> **口径**：本文件只写**有出处**的数字。取不到的一律写 `未核`，不写推测值。
+> 官方说法与社区实测冲突时分别标注。
+
+---
+
+## 1. 先认版本：五个"最新"不是同一个东西
+
+这是插件作者**第一个**要做的判断。五个数可以不相等，而 peer 范围按线分叉：
+
+| # | 说法 | 值（2026-10-09） | 怎么查 | 性质 |
+|---|---|---|---|---|
+| 1 | npm `latest` | `0.2.0-rc.2` | `npm view @deepseek-ai/dsh dist-tags` | 默认装的就是这个 |
+| 2 | npm `next` | `0.2.0-rc.2` | 同上 | 与 latest 同值 |
+| 3 | npm `alpha` | `0.2.1-alpha.2` | 同上 | 最新发布 |
+| 4 | master 最新 tag | `dsh-v0.2.1-alpha.2` | GitHub `/tags` | 源码线的名字；**等于 master HEAD** |
+| 5 | **本机实际** | — | `dsh --version` | **唯一真正要紧的数** |
+
+### 1.1 没有"稳定版"这回事
+
+- **全部 31 个 npm 版本都带 `-alpha.N` / `-rc.N` 后缀；全部 26 个 GitHub Release 都是 `prerelease: true`。**
+- 所以 npm 的 `latest` 标签在这里**不代表稳定**——它只是"默认安装会拿到的那一个"。
+- 给作者的有效读法：**最新 = `0.2.1-alpha.2`（npm `alpha`）；默认安装 = `0.2.0-rc.2`（npm `latest`/`next`）**。
+- 官方 `CONTRIBUTING.md` 明确**不接受外部 PR**，`AGENTS.md` 声明 API 处于 pre-stable。
+  插件作者无法"等它稳定"，只能**钉版本 + 声明区间**。
+
+### 1.2 ★ 陷阱：子包的 `latest` 是冻住的
+
+主包 `@deepseek-ai/dsh` 每次发版都会重发全部子包到 `alpha`/`next`，但**每个子包的 `latest`
+标签停在它第一次被设置的那个版本，永不前进**。裸装子包会装到远古版本：
+
+| 包 | `latest`（冻住的值） | `next` | `alpha` |
+|---|---|---|---|
+| `@deepseek-ai/dsh` | `0.2.0-rc.2` | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-base` | **`0.0.1-rc.1`** | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-session` | **`0.0.1-rc.1`** | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-tools` | **`0.0.1-rc.1`** | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-subagent` | **`0.0.1-rc.1`** | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-home-paths` | `0.0.1-rc.3` | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-client-ui-primitives` | **`0.0.1-rc.1`** | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-agent` | `0.1.0-rc.6` | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-typert-protocol` | `0.1.0-rc.6` | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-package-manifest` | `0.1.3-alpha.2` | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-plugin-manager` | `0.1.6-alpha.2` | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-experimental-ptc-runtime-python` | `0.1.6-alpha.1` | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+| `@deepseek-ai/dsh-otel` | `0.2.0-rc.1` | `0.2.0-rc.2` | `0.2.1-alpha.2` |
+
+**结论三条**：
+
+1. 永远不要写 `"@deepseek-ai/dsh-tools": "latest"` 或裸 `pnpm add @deepseek-ai/dsh-session`。
+2. **不要依赖子包版本号判断宿主代次**——`dsh-agent` 的 `latest` 停在 `0.1.0-rc.6`，
+   而它可能正跟着 `0.2.1-alpha.2` 运行。判断代次只认 `dsh --version`。
+3. 共享实例的 dsh 包一律 `peerDependencies` + `devDependencies`（**绝不 `dependencies`**），
+   按 §4 选区间。
+
+---
+
+## 2. 破坏性变更断层（只列"哪一版开始不一样"）
+
+流水账在 §8；这里只列作者真正会撞上的断层。**官方 `docs/upgrade-guide/v<X>/` 的目录名
+`X` 是"变更被引入的版本"，描述的是从 X 升到**下一个** release 的变更**——
+原文措辞是 *"In vX, … was so; the next release no longer…"*。别把目录名当目标版本。
+
+| 断层 | 引入版本（目录名） | 落到哪一版 | 影响面 |
+|---|---|---|---|
+| **即插即拔基础设施** | `0.1.6-alpha.2` | 同版 | `dsh-hmr` / `dsh-plugin-manager` / `ui-plugin-manager` 三包一次性出现；新增 `ctx.hmr` / `ctx.pluginManager` / `ctx.profileContext` |
+| **peer 从"声明"变"运行时门禁"** | `0.1.7-rc.1` | 同版 | `plugin-compatibility.ts` 三文件首次出现；不匹配的行被直接 `disabled`，模块永不导入 |
+| **会话格式 V4 + 本世代破坏性变更** | `0.1.7-alpha.1` | 同版 | `SESSION_FORMAT_VERSION` 3→4、settings 重写、`readBytes`、Messages-only 适配器 |
+| **0.2.0 世代清理** | `0.2.0-rc.2` | 下一版 | 移除 runtime invariants、schedule bundle 退役、子路径插件不再读 `package.json`、新增 `no-response` 错误码 |
+| **0.2.1-alpha.2 大批变更** | `0.2.1-alpha.1` | `0.2.1-alpha.2` | **19 条**破坏性变更（见 §3） |
+
+> ⚠ **两个断层不属于同一层面，别混**：`0.1.6-alpha.2` 解决"能不能热插拔"，
+> `0.1.7-rc.1` 才解决"版本不匹配时会不会被拦"。`0.1.6-alpha.2` 上的
+> `dsh-plugin-manager` **没有** peer 预检。
+
+> ⚠ **`0.1.5-rc.3` 是时间线上的陷阱**：它在 `0.1.6-alpha.2` **之后**发布（2026-09-22），
+> 是给留在 0.1.5 线用户的**回补版本**，也是唯一**没有 GitHub Release** 的 tag。
+> 它的依赖写成精确版本、没有 `exports`、没有 `dsh-hmr`/`dsh-plugin-manager`。
+> **任何"按发布时间排序推断版本新旧"的脚本都会在这里出错——必须按 semver 比较。**
+
+---
+
+## 3. `0.2.1-alpha.1 → 0.2.1-alpha.2`：19 条破坏性变更
+
+如果你在 `0.2.0-rc.2` 或更早的线上，**这 19 条与你无关**；如果你跟的是 master/alpha 线，
+**逐条核对**。官方 release notes 也列了这 5 条为 "other changes"：Python PTC 沙箱、
+`both` 模式移除、`dshHome` 移除、子代理执行统一、Agent Team 直投收件箱。
+
+| # | 变更 | 破坏了什么 | 你要做什么 |
+|---|---|---|---|
+| 1 | `subagent-activations` | `backgroundMode`/`enableRunInBackground`/`run_in_background` 全部移除；`@deepseek-ai/dsh-subagent-in-process-driver` 包被删；`ctx.subagents.start()`→`startActivation()` | 删两个配置键与工具参数；宿主代码换 `startActivation({ …, delivery: 'caller' })`；自定义本地 provider 要实现 `prepareContinuable()` |
+| 2 | `tool-presentation-mode` | `mode` 只接受 `native`/`ptc`，**`both` 被拒绝**；含环境变量 `DSH_TOOLS_MODE=both` 与 `ctx.tools.presentAs('both')` | 改成 `native` 或 `ptc` |
+| 3 | `web-listener-trust-config` | **`webRuntime` 服务被移除**，改 `webStartup`（行 `web-startup`）；`ctx.webRuntime.lanAddresses` 没了；**通配 host（`0.0.0.0`/`::`）在加载期被拒** | `inject: [webRuntime]`→`[webStartup]`；`trustedHosts` 换服务；通配 host 换具体 IP 字面量 |
+| 4 | `working-directory` | 内置 `{{cwd}}` 提示变量被移除；`cwd` 配置从 ACP / DSH-SDK 子代理移除；**保留 `{{cwd}}` 的自定义模板在模型请求前就失败** | 删提示里的目录子句；`cwd` 改由子请求传或先调 `working_directory({ cd })` |
+| 5 | `session-title-provider-strategy` | `dsh-session-title-llm` 移除 3 个导出符号（`registerSessionTitleLlmProvider` / `generateSessionTitleWithLlm` / `SessionTitleLlmMessageSelector`）；`targetWords`/`targetCjkCharacters` 移到各 provider 自己的 Config | 改用 `ctx.sessionTitle.register({ id, automatic, generate })`，自己搭 system/input |
+| 6 | `session-title-adapters` | 标题请求改走 `ctx.llm.prepareCall()`；只挂 `llm/stream` 中间件的组合需另注册 adapter；自定义 adapter 的 `reasoning.efforts` **必须从低到高排** | 用 `ctx.llm.registerAdapter()` 注册标题路由 |
+| 7 | `ssh-helper-launch` | `dsh-ssh` 用单一 `launch` 键取代 `node`/`bootstrapPath`/`bootstrapHash`；**要求 SSH protocol 2**；`dsh-ptc-runtime-node` 的 `nodeExecutable`/`bootstrapPath`→`launch` | `launch: { kind: 'node-script' }` 或 `{ kind: 'executable' }`；helper 与 hash 必须同改 |
+| 8 | `team-direct-inbox` | Agent Teams 消息直投目标 inbox，独立 mailbox 消失；`send_message` 只返回 `{"sent":true}`；`maxPendingMessagesPerMember` 移除；**未投递的排队消息永不派发 = 数据丢失** | **升级前**让待发消息跑完；升级后必需的显式重发 |
+| 9 | `instruction-home-override` | `dsh-agent-instructions` 移除 `dshHome` 配置字段，改用 `@deepseek-ai/dsh-home-paths` 的 `resolveDshHome()`；**残留键被静默忽略** | 删 `dshHome`；改用进程环境变量 `DSH_HOME` |
+| 10 | `experimental-package-composition` | CLI 与 Python runtime 的安装依赖**不再包含 hook 桥**；安装与组合分离（装了不等于挂上）；只"启用"被删行的 patch 不会把它插回来 | 显式装 peer；选 bundle **先于**覆盖其行；用完整 `insert` 替代对已删行的 override |
+| 11 | `native-subagent-bundle-tools` | 选中 bundle 会**额外注册 Host 全局工具**（`tool-subagent-claude-code`/`-codex`），对最小预设也可见；**插件构造或严格校验 `BundleInfo` 必须补两个必填字段 `official`/`availability`**；`PluginPackageRef` 同理 | 补必填字段；删同名冗余 Host 行（会被遮蔽） |
+| 12 | `python-ptc-sandbox` | Python PTC runtime **要求 `sandbox` + `sandboxPolicy` 服务**；默认 `read-only`；受限运行会以 `sandbox-unavailable` 失败 | 挂 `dsh-sandbox-local` + `dsh-sandbox-policy`；设 `sandbox-policy` 行的 `mode`/`workspaceRoot` |
+| 13 | `python-optional-resources` | Python wheels **不再内置** Office sidecar 与 authoring 解释器；SDK 启动不再下载 | 用前显式 `download_office()` / `download_primary_runtime()`；离线部署预置 `DSH_RESOURCE_CACHE` |
+| 14 | `plugin-option-placement` | `dsh plugin` 只认**转发给 pnpm 的参数之前**的 `--profile`；**`dsh plugin add <pkg> --profile <name>` 现在直接失败** | 改成 `dsh plugin --profile <name> add <package>` |
+| 15 | `terminal-command-labels` | `TerminalBlockLabels`（`dsh-client-ui-primitives`）新增**必填** `commandLine(line: number): string` | 给每个 labels 对象补 `commandLine` |
+| 16 | `deepseek-model-discovery` | `deepseek-official` 路由**无 key 时返回空目录**，Desktop/Web 隐藏 DeepSeek 组 | 配 key 或用 `apiKeyEnv` 指定的环境变量；自定义消费方要处理空目录 |
+| 17 | `new-session-generations` | Web/Desktop 新建会话会**同时新建 Agent**，不再复用空会话 | 改过预设定义后用 New Session；要复用用 `openWorkspace`/`connectWorkspace` |
+| 18 | `mock-messages-events` | `dsh-llm-mock-server` 会在结构化 SSE 负载旁**同时发 Messages 事件名** | 消费具名事件，别只筛匿名消息 |
+| 19 | `desktop-test-auth-popup` | Desktop **测试**认证弹窗默认关闭 | 需要时设 `updates.allowTestAuthPopupWindow: true` 并完全重启 |
+
+另有一条**回填**在 `v0.2.0-rc.2/` 目录里、但我们基线之后才加入的：
+`bundled-python-tests`（打包的 NumPy/pandas **测试目录**被移除；要跑上游测试套件请另建
+Python 环境）。它放在旧目录属于例外——上游自己的规则是"版本号 bump 后旧目录冻结"。
+
+**出处**：每条对应
+`docs/upgrade-guide/v0.2.1-alpha.1/<item>/guide.md`（官方仓库 master）；
+发布说明 `releases/tag/dsh-v0.2.1-alpha.2`。
+
+---
+
+## 4. 我该声明什么 peer 区间
+
+两条硬事实：
+
+1. **peer 是运行时门禁，不是声明。** 从 `0.1.7-rc.1` 起，`app-boot/src/plugin-compatibility.ts`
+   在插件被 import **之前**校验 `peerDependencies` 里的 `@deepseek-ai/dsh` / `@deepseek-ai/dsh-*`；
+   不匹配的行被**直接置为 `disabled`**，模块永不导入。
+2. **门禁语义是 `includePrerelease: true`**（`plugin-compatibility.ts:77`），比裸 semver **宽松**。
+   `engines.dsh` 与 `dsh.manifestVersion` 则是**纯声明、零强制**——写了不生效。
+
+### 4.1 家族内当前使用的规范区间
+
+```
+>=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
+```
+
+这是 `dsh-plugin-kit` 的 `data/peer-range.json`（`canonicalRange`，2026-09-26 更新）所记录的
+规范值，六个子句按线枚举。**本仓库 `src/cli/templates.ts` 生成的区间与它逐字节一致**，
+是仓库内唯一副本。
+
+### 4.2 选区间的判断法
+
+| 你的插件用了什么 | 下界至少要到 |
+|---|---|
+| 只用 Cordis 基础能力（tools/events/services/effects） | `0.1.2-rc.1`（最早） |
+| 用了 `ctx.hmr` / `ctx.pluginManager` | `>=0.1.6-0` |
+| 依赖 peer 门禁本身、或 0.1.7 的 API | `>=0.1.7-0` |
+| 用了 0.2.0 世代接口（settings 重写后） | `>=0.2.0-0` |
+| 用了 §3 里任何一条新形态（如 `webStartup`、`BundleInfo.official`） | `>=0.2.1-0` |
+
+**不要**写开区间上界（如 `>=0.1.2-rc.1 <0.3.0`）：它跨过了整代破坏性变更，
+门禁放行但运行时会炸。**上界必须按世代切**（`<0.2.0` / `<0.3.0`）。
+
+---
+
+## 5. 会话格式（persistence）版本谱系
+
+插件若读写会话日志，必须认这个表。
+
+| 格式 | 首次写入的版本 | 规模（root/type） | 说明 |
+|---|---|---|---|
+| V0 | `0.1.2-rc.1` | 54 / 415 | 历史 **V0 参考快照**取自这个 tag |
+| **V1** | **从未发布** | — | 没有 tag 的 writer version 是 1（来源 PR #3349） |
+| V2 | `0.1.3-alpha.2` | 56 / 435 | — |
+| V3 | `0.1.5-alpha.1` | 60 / 467 | 源码 PR #4320 |
+| **V4** | `0.1.7-alpha.1` | 63 / 597 | 当前；`SESSION_FORMAT_VERSION` 3→4 的提交是 `c36a83ff…` |
+
+**官方权威记录**：`docs/session-format-status.md` 现在写
+`latestReleasedVersion: 4` / `evidenceTag: dsh-v0.2.0-rc.2`。
+（我们镜像快照早于该更正，曾把它记为"未解决的矛盾"——**以 live 为准**。）
+
+**三个读数陷阱**：
+
+1. **逐版本持久化档案冻结在 `0.1.5-rc.2`**（2026-09-12 采集，26 tag / 25 次转换）。
+   `0.1.6-alpha.1` 之后**没有任何持久化记录**。所以新版本的唯一官方历史是 **upgrade-guide**。
+2. **V4 之后仍有 `same-version` 记录**（不改格式号也能加类型）。基线后有
+   `2026-09-13-working-directory` 等 5 条，其中 `event:working-directory/change` 是
+   **required-on-read**——**旧构建拒绝打开含该事件的日志**。
+3. **多帧 zstd**：`session.jsonl.zstd` **每次写入追加一个 zstd frame**，
+   `zstdDecompressSync` 一次只解出第一帧（137 行会话可能只得到 1 行）。
+   必须按魔数 `28 B5 2F FD` 切分。
+
+---
+
+## 6. 能力 × 版本（22 个原生能力面）
+
+**这一节的"引入版本"是怎么算出来的**（决定了它能怎么用）：
+对每个能力面取"**首个包含该路径新增提交的 tag**"——`git log --diff-filter=A --reverse -- <path>`
+配 `git tag --contains`，再按 tag 创建时间取最早的一个。**这是包/路径层面的引入，不是 API 层面的精确引入**：
+一个能力面内部的某个具体函数、配置键、服务键可能比整面晚若干版本。
+**要精确到 API 就查 `references/official-docs/docs/subsystems/*.md` 与 `docs/capability-seams.md`**，
+不要拿这张表当 API 级答案。
+
+**口径警告（必须连带引用）**：本 checkout 里**最早的 tag 是 `dsh-v0.1.0-rc.7`（2026-08-17）**。
+更早的 `dsh-v0.0.1-rc.1` … `dsh-v0.1.0-rc.6` **只在 `docs/persistence-changes/releases/` 里有文档、没有 tag**。
+所以表里的 **`≤ rc.7` 意思是"在最老的 tag 上就已经存在"，不是"rc.7 引入"**——
+真正的引入时间只能靠首提交日期或 Agent Note 日期（表里给了）。
+
+| # | 能力面 | 引入版本 | 更细的时间锚（原文） |
+|---|---|---|---|
+| A1 | **Subagents** | **≤ `dsh-v0.1.0-rc.7`** | seam ≤ rc.7（note 2026-06-21）；continuable note 2026-07-28；控制工具首提交 2026-08-02 |
+| A2 | **Agent Teams**（实验） | **`dsh-v0.1.0-rc.8`** | note 2026-08-05；包首提交 2026-08-19 → `rc.8`；profile bundle 2026-09-04 → `0.1.3-alpha.1` |
+| A3 | **Workflow 编排** | **`dsh-v0.1.6-alpha.1`** | note/`tool-workflow` 2026-07-05、`tool-ralph` 2026-07-20（均 ≤ rc.7）；`workflow-ptc` 2026-09-13 → 本版 |
+| A4 | **后台作业**（jobs） | **≤ `dsh-v0.1.0-rc.7`** | 首提交 2026-08-13；整合 note 2026-09-03 |
+| A5 | **定时 / cron** | **`dsh-v0.2.1-alpha.1`** | `after` 2026-08-05、定频 + cron 2026-08-06（`31c0c6a9f6`）→ ≤ rc.7；**工具包改为 preset 作用域** 2026-09-24 → 本版 |
+| A6 | **目标追踪**（goal） | **≤ `dsh-v0.1.0-rc.7`** | 2026-07-19（三份 note） |
+| A7 | **Plan mode** | **≤ `dsh-v0.1.0-rc.7`** | 2026-07-22（note `2026-07-07-plan-mode`） |
+| A8 | **Todo** | **≤ `dsh-v0.1.0-rc.7`** | 2026-06-29 |
+| A9 | **LSP 导航** | **`dsh-v0.1.3-alpha.1`** | seam 2026-07-16；`lsp-stdio` 2026-08-13（≤ rc.7）；`tool-lsp` 2026-09-04 → 本版 |
+| A10 | **浏览器自动化** | **`dsh-v0.1.6-alpha.1`** | 2026-09-12/13（note 2026-09-12）；**seam 原生、provider 实验性** |
+| A11 | **Computer use** | **`dsh-v0.1.6-alpha.1`** | 2026-09-12；**seam 原生、provider 实验性** |
+| A12 | **MCP client** | **`dsh-v0.1.3-alpha.1`** | client note 2026-07-07；成组首 tag 2026-09-04 |
+| A13 | **可观测 / OpenTelemetry** | **`dsh-v0.2.0-rc.1`** | otel 包 2026-09-25 → 本版；product adapter 2026-09-21 → `0.1.7-alpha.2`；session adapter 2026-09-04 → `0.1.3-alpha.1` |
+| A14 | **交付物 / 文档 / 附件** | **`dsh-v0.1.6-alpha.2`** | deliverables 2026-09-14、office-to-pdf 2026-09-16 → 本版；attachment seam 2026-09-04 → `0.1.3-alpha.1` |
+| A15 | **会话存储 / 持久化检查点 / 搜索 / fork-resume-export** | **`dsh-v0.1.3-alpha.1`** | session/llm 2026-06-11；检查点策略 2026-08-09（≤ rc.7）；session-query-sqlite 等 2026-09-04 → 本版；**V4 格式 2026-09-16** |
+| A16 | **Web 访问**（search/fetch） | **`dsh-v0.1.3-alpha.1`** | seam note 2026-06-24；成组首 tag 2026-09-04 |
+| A17 | **出站 webhook** | **`dsh-v0.1.2-alpha.1`** | 成组 2026-08-23 → 本版；GitHub 适配器 2026-09-04 → `0.1.3-alpha.1` |
+| A18 | **终端 / SSH / shell** | **`dsh-v0.1.6-alpha.1`** | shell/terminal 2026-08-13（≤ rc.7）；**SSH 2026-09-12 → 本版**；终端权限 note 2026-09-16 |
+| A19 | **权限 / 审批 / 沙箱** | **`dsh-v0.1.3-alpha.1`** | sandbox/permission/user-approval/commands 2026-09-04 → 本版；Windows ACL note 2026-08-08、guards 2026-07-08（均 ≤ rc.7） |
+| A20 | **扩展点：skills / 动态插件 / hooks / presets** | **`dsh-v0.1.6-alpha.2`** | skill 2026-07-10、hooks 2026-07-01（≤ rc.7）；**plugin-manager 工具 2026-09-14 → 本版**；preset registry 2026-09-21 → `0.1.7-alpha.2`；cordis runners 2026-09-04 → `0.1.3-alpha.1` |
+| A21 | **上下文管理：compaction / spill / 观察策略** | **`dsh-v0.1.3-alpha.1`** | compaction seam 2026-06-18、成组 2026-08-13（≤ rc.7）；spill 成组 2026-09-04 → 本版；图片 offload 2026-09-08 → `0.1.6-alpha.1` |
+| A22 | **插件 / API 面：Remote 控制器 / Typert / SDK / ACP / bundle** | **`dsh-v0.1.2-alpha.1`** | acp 2026-06-16、sdk 2026-07-15、api/typert 2026-07-29–08-07（≤ rc.7）；sdk-minimal 2026-08-24 → 本版 |
+
+### 6.1 只在该特写表里的能力（§1–§5 未收）
+
+前几节只列了"会破坏插件"的项；下表补**新增即用得上**的接缝，出处同样是官方 `docs/`：
+
+| 接缝 / 机制 | 引入 | 出处 |
+|---|---|---|
+| `ctx.hmr`、`ctx.pluginManager`、`ctx.profileContext` | `0.1.6-alpha.2` | 三包同版首次出现（逐 tag `git cat-file -e` 验证） |
+| peer 兼容性运行时门禁 | `0.1.7-rc.1` | `plugin-compatibility.ts` 等三文件首次出现 |
+| 会话格式 V4 | `0.1.7-alpha.1` | `SESSION_FORMAT_VERSION` 提交 `c36a83ff…` |
+| `ctx.mcpResources`、`ctx.browserUse`、`ctx.computerUse`、`ctx.ssh`、`ctx.inspector`、`ctx.dynamicCordisRunner` + `ctx.cordisInspect` | `0.2.1-alpha.1` | 见 A10/A11/A12/A18/A20 行；归档调研与官方 `docs/capability-seams.md` |
+| 新 slot `conversation.input.permission`、`sidebar.right.tab.guide.entry` | `0.2.1-alpha.1` | 官方 slot 文档 |
+| `webStartup`（取代 `webRuntime`） | `0.2.1-alpha.2` | `upgrade-guide/v0.2.1-alpha.1/web-listener-trust-config` |
+| `BundleInfo.official` / `.availability`（**必填**） | `0.2.1-alpha.2` | `upgrade-guide/v0.2.1-alpha.1/native-subagent-bundle-tools` |
+| `working_directory` 工具、`create_worktree` | `0.2.1-alpha.2` 前 | live `docs/tool-catalog.md` |
+| `@deepseek-ai/dsh-invariants` | ≤`0.2.0-rc.2` 存在 → `0.2.1-alpha.1` **移除** | `upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants` |
+| `@deepseek-ai/dsh-experimental-schedule-bundle` | `0.2.0-rc.2` 退役 | `upgrade-guide/v0.2.0-rc.2/schedule-bundle-retired` |
+| 子路径插件读自己的 `package.json` 取展示文案 | ≤`0.2.0-rc.2` → `0.2.1-alpha.1` **不再读** | `upgrade-guide/v0.2.0-rc.2/subpath-plugin-display-manifest` |
+| `repository-plugin`（`.dsh-plugin`） | 2026-08-09 推出 → **08-11 移除** | 社区实测（`vlln/plugin-registry` 档案，**该仓 2026-10-03 已归档**） |
+
+> 22 面全表连同每面的**工具名、API 名、配置键与逐条出处行号**，来自一次
+> read-only 清点。**清点时 checkout 在 `dsh-v0.2.1-alpha.1` / `5badb15`；本库镜像现已同步到 `dsh-v0.2.1-alpha.2` / `d743267`**，
+> 本文只摘"引入版本"一列；**要完整清单请按上文口径重跑**，或读官方
+> `docs/subsystems/*.md` + `docs/capability-seams.md` + `docs/tool-catalog.md`。
+
+---
+
+## 7. 自检与复现
+
+```powershell
+# 五个"最新"里的前四个
+npm view @deepseek-ai/dsh dist-tags
+# { latest: '0.2.0-rc.2', next: '0.2.0-rc.2', alpha: '0.2.1-alpha.2' }
+
+# 子包 latest 是否冻结（换包名即可）
+npm view @deepseek-ai/dsh-tools dist-tags
+# { latest: '0.0.1-rc.1', next: '0.2.0-rc.2', alpha: '0.2.1-alpha.2' }
+
+# master 最新 tag 与 HEAD
+Invoke-RestMethod -Headers @{'User-Agent'='x'} `
+  https://api.github.com/repos/deepseek-ai/deepseek-harness/tags | Select-Object -First 3 name
+
+# 官方 upgrade-guide 目录（新断层会新增一个版本目录）
+Invoke-RestMethod -Headers @{'User-Agent'='x'} `
+  https://api.github.com/repos/deepseek-ai/deepseek-harness/contents/docs/upgrade-guide
+
+# 本机实际版本 —— 唯一真正要紧的那个
+dsh --version
+```
+
+**维护节奏**：官方 3 周内发过 9 个 prerelease。每次官方发版后按
+`docs/upgrade-guide/**`（**无 index、无入链，必须主动看**）+ `docs/persistence-changes/**`
++ GitHub Releases 三处增量更新本文件与 `guide/migration-0.2.md`。
+
+---
+
+## 8. 与 `guide/migration-0.2.md` 的分工
+
+| 文件 | 回答什么 | 形态 |
+|---|---|---|
+| **本文件** | 「哪个版本有/没有什么」「我该声明什么区间」 | **速查表 + 版本锚点** |
+| `guide/migration-0.2.md` | 「从 0.1.6 升到 0.2 世代要改什么」 | **迁移叙事 + 逐条清单** |
+
+两者双向互链。**冲突时官方原文优先**（`references/official-docs/`）；官方文档与代码冲突时
+以代码/产物为准，并**显式标注分歧**。
+
+---
+
+## 9. 未核事项（不要当成已知）
+
+- §6 的"引入版本"是**包/路径层面**的（首含该路径的 tag），**不是 API 层面**；面内某个具体
+  函数/配置键/服务键可能更晚。精确到 API 请查官方 `docs/subsystems/*.md` 与 `docs/capability-seams.md`。
+- §6 的 `≤ rc.7` 是**下限**不是引入点：本 checkout 最老的 tag 是 `dsh-v0.1.0-rc.7`，更早只有文档没有 tag。
+- `0.1.2-alpha.2` 首次出现 `dsh.configTrees`，`0.1.7-alpha.1` 又移除它——**中间是否还有变更未逐版核对**。
+- 子包 `latest` 冻结的**原因**未确认（值已实测，机制未证）。
+- `0.1.0-rc.3` / `-rc.4` 在持久化档案的 tag 清单里存在，但 live tag 列表与 npm 都没有——**原因未知**。
+- 24 个基线之前版本的 release note **正文**未逐条读取（正文存在，`0.1.7-rc.1` 有 19,003 字符）。
+  写权威的逐版本历史前必须读。
+- `dsh-v0.1.2-alpha.1`、`dsh-v0.1.3-alpha.1` 是 **GitHub-only** 版本（有 release，npm 上没有）。

package/guide/when-to-retire-a-plugin.md

@@ -29,7 +29,7 @@ One thing first: **this is not a purge, it is a self-audit.** The official proje
 | Disposition | Count | Packages | Meaning |
 |---|---|---|---|
 | 🪦 **Retired** | 3 | `dsh-background-agents`, `dsh-session-pin`, `dsh-team-rooms` | **Compatibility updates stop**: RETIRED banner at the top of the README, npm `deprecate` applied, GitHub repository archived (read-only) |
-| 🧊 **Frozen** | 7 | `dsh-budget`, `dsh-memento`, `dsh-draw`, `dsh-claude-move`, `dsh-reach`, `dsh-wechat`, `dsh-defend` | **No new features — but still working and not deprecated**; only genuine breakage gets fixed |
+| 🧊 **Frozen** | 6 | `dsh-budget`, `dsh-draw`, `dsh-claude-move`, `dsh-reach`, `dsh-wechat`, `dsh-defend` | **No new features — but still working and not deprecated**; only genuine breakage gets fixed |
 | ✅ **Reclassified** | 1 | `dsh-catalog` | First judged as a retirement; after review, kept: it is an internal family tool and does not compete with third-party catalogs. **Still maintained** |
 
 Two earlier corridor packages, `dsh-plugin-upgrade-015` (stopped at npm `0.1.1`) and `dsh-plugin-upgrade-016` (never published), are also retired; plugin upgrades continue through the single `dsh-plugin-upgrade` line.
@@ -100,10 +100,10 @@ This section is for users.
 | Status | Will the package be deleted or unpublished? | Will bugs still be fixed? | npm state | Repository state |
 |---|---|---|---|---|
 | 🪦 **Retired** (3) | No | **No** — including compatibility updates | `deprecate` applied | Archived, read-only |
-| 🧊 **Frozen** (7) | No | **Yes** — but only a minimal compatibility fix, and only when a breaking host change makes the package completely unusable | Normal, **not** deprecated | Normal, **not** archived |
+| 🧊 **Frozen** (6) | No | **Yes** — but only a minimal compatibility fix, and only when a breaking host change makes the package completely unusable | Normal, **not** deprecated | Normal, **not** archived |
 | Everything else | No | Yes | Normal | Normal |
 
-**If you have one installed, there is nothing you need to do.** The seven frozen packages install and run exactly as before: no interface changes, no versions pulled. The only thing that would require action is a host upgrade that actually breaks one — in that case, please open an issue and I will fix it. **If what you want is new features, please use the rivals named in the section 3 table.** Every one of them is significantly better adopted on its surface, and that is precisely why the package is frozen.
+**If you have one installed, there is nothing you need to do.** The frozen packages install and run exactly as before: no interface changes, no versions pulled. The only thing that would require action is a host upgrade that actually breaks one — in that case, please open an issue and I will fix it. **If what you want is new features, please use the rivals named in the section 3 table.** Every one of them is significantly better adopted on its surface, and that is precisely why the package was frozen.
 
 **Why not express this by deleting packages?** Because deleting them means the next person cannot find the package, and cannot find the reason it was retired either. So the family tables **keep every row and only add a status note**: retired and frozen repositories stay listed in every family table with a `🚫 RETIRED` / `🧊 FROZEN` status column, and their original descriptions are left untouched.
 
@@ -116,11 +116,11 @@ This section is for users.
 5. **Can a second signal corroborate your download count?** `dsh-budget` has 1,079 weekly downloads and **10 stars** — high downloads look like CI and mirror noise, while low stars look like real appeal. In the other direction, `dsh-auto-review` carries **10 open issues**, which is what real use and real bug reports look like. Download counts alone mislead.
 6. **Is "do I still use it" your criterion?** If you no longer use it, it should not be (my own Web profile runs the stock bundle set today). Replace it with two questions: **does anyone out there still need this, and is the maintenance cost still worth it?**
 7. **How far behind do you have to be?** There is no threshold. `dsh-fast` is 43× behind and stays as it is; `dsh-defend` is 14× behind and is frozen. The price of freezing is admitting you are no longer the best choice on that surface, so it is only worth paying for packages where further investment will not produce anything distinctive.
-8. **Is your decision written into the README?** A decision that lives only in your head, or only in an internal report, does not exist. Each of the seven frozen packages carries a `## Maintenance status: 🧊 FROZEN` section with the measured comparison table and a note on where the rival is stronger; each of the three retired packages carries a RETIRED banner at the top of its README. **At a minimum, users should be able to learn from the README why you stopped.**
+8. **Is your decision written into the README?** A decision that lives only in your head, or only in an internal report, does not exist. Each frozen package carries a `## Maintenance status: 🧊 FROZEN` section with the measured comparison table and a note on where the rival is stronger (six, each carrying a `status` of `frozen` in `dsh-plugin-kit/data/repos.json`); each of the three retired packages carries a RETIRED banner at the top of its README. **At a minimum, users should be able to learn from the README why you stopped.**
 
 ## 7. Statement of fact
 
-- **The family today**: the family tables list **44 plugin repositories** (45 rows in the tables that include `dsh-plugin-upgrade-015`), of which 🚫 **3 are retired** and 🧊 **7 are frozen**; the rest are maintained as active repositories. Licensing is predominantly Apache-2.0.
+- **The family today**: the family tables list **44 plugin repositories** (45 rows in the tables that include `dsh-plugin-upgrade-015`), of which 🚫 **3 are retired** and 🧊 **6 are frozen**; the rest are maintained as active repositories. Licensing is predominantly Apache-2.0.
 - **Where the repositories are**: https://github.com/PerryLink
 - **Measurement date**: 2026-10-05, from that self-audit — a full npm registry pull, live GitHub REST API measurements, and file-by-file evidence from the host source tree. **The conclusions are checkable**: each one points at a specific file or a specific API reading, and anything that could not was marked "unverified".
 

package/guide/when-to-retire-a-plugin.zh-CN.md

@@ -29,7 +29,7 @@
 | 档位 | 数量 | 包 | 含义 |
 |---|---|---|---|
 | 🪦 **退役** | 3 | `dsh-background-agents`、`dsh-session-pin`、`dsh-team-rooms` | **停止兼容性更新**：README 顶部 RETIRED 横幅、npm 已 `deprecate`、GitHub 仓已归档（只读） |
-| 🧊 **冻结** | 7 | `dsh-budget`、`dsh-memento`、`dsh-draw`、`dsh-claude-move`、`dsh-reach`、`dsh-wechat`、`dsh-defend` | **不发新功能；但仍然可用、没有废弃**，只有真实故障才修 |
+| 🧊 **冻结** | 6 | `dsh-budget`、`dsh-draw`、`dsh-claude-move`、`dsh-reach`、`dsh-wechat`、`dsh-defend` | **不发新功能；但仍然可用、没有废弃**，只有真实故障才修 |
 | ✅ **改判** | 1 | `dsh-catalog` | 原本判退役，复核后改判：它是家族内部工具，不与第三方目录竞争，**继续维护** |
 
 另有两支早期走廊线 `dsh-plugin-upgrade-015`（停在 npm `0.1.1`）与 `dsh-plugin-upgrade-016`（从未发布）已退役；插件升级由 `dsh-plugin-upgrade` 一条线独家继续。
@@ -100,10 +100,10 @@
 | 状态 | 会删包 / 撤版吗 | 还会修 bug 吗 | npm 状态 | 仓库状态 |
 |---|---|---|---|---|
 | 🪦 **退役**（3 个） | 不会 | **不会**（含兼容性更新） | 已 `deprecate` | 已归档，只读 |
-| 🧊 **冻结**（7 个） | 不会 | **会**——但只有当宿主破坏性变更让它完全不可用时，才做最小兼容修复 | 正常，**没有** deprecated | 正常，**未归档** |
+| 🧊 **冻结**（6 个） | 不会 | **会**——但只有当宿主破坏性变更让它完全不可用时，才做最小兼容修复 | 正常，**没有** deprecated | 正常，**未归档** |
 | 其余 | 不会 | 会 | 正常 | 正常 |
 
-**已安装的用户该怎么做：什么都不用做。** 冻结的 7 个照常安装、照常运行，接口不变、版本不撤。只有当某次宿主升级真的把它弄坏了才需要动作——那种情况请开 issue，我会修。**如果你要的是新功能，请去用第 3 节表里那些对手**——它们在各自赛道上的采用度都明显更高，这也是我冻结自己这几个包的原因。
+**已安装的用户该怎么做：什么都不用做。** 冻结的包照常安装、照常运行，接口不变、版本不撤。只有当某次宿主升级真的把它弄坏了才需要动作——那种情况请开 issue，我会修。**如果你要的是新功能，请去用第 3 节表里那些对手**——它们在各自赛道上的采用度都明显更高，这也是我冻结自己这几个包的原因。
 
 **为什么不用「删包」表达态度？** 因为删了之后，下一个人搜不到这个包，也看不到退役原因。所以家族表**行不删、只加状态备注**：退役与冻结的仓全部保留在每一张家族表里，用状态列标注 `🚫 已退役` / `🧊 已冻结`，描述原文照旧。
 
@@ -116,11 +116,11 @@
 5. **你的下载量能被第二个信号验证吗？** `dsh-budget` 周下载 1,079，star 只有 **10**——高下载更像 CI / 镜像噪声，低 star 才是真实吸引力。反过来 `dsh-auto-review` 有 **10 个 open issue**，那是真有人在用、在报障。单看下载量会骗人。
 6. **「我还在用吗」是不是你的判据？** 如果不用了，它不该当判据（我的 Web profile 现在就跑 stock 组合）。换成这两句：**对外是否还有人需要？维护成本是否还值？**
 7. **落后多少倍才该退？** 没有阈值。`dsh-fast` 落后 43× 留在现状，`dsh-defend` 落后 14× 被冻结。冻结要付的代价是「承认自己不再是这条赛道最好的选择」，所以只值得对「继续投入也不会产出独特东西」的包付这个代价。
-8. **你的决定写进 README 了吗？** 只写在脑子里、或只写在一份内部报告里，等于没写。冻结的 7 个各自有 `## Maintenance status: 🧊 FROZEN` 一节，含实测对比表与「对手强在哪」的说明；退役的 3 个 README 顶部有 RETIRED 横幅。**使用者至少应该能从 README 里知道你为什么不做了。**
+8. **你的决定写进 README 了吗？** 只写在脑子里、或只写在一份内部报告里，等于没写。冻结的包各自有 `## Maintenance status: 🧊 FROZEN` 一节，含实测对比表与「对手强在哪」的说明（6 个，各自在 `dsh-plugin-kit/data/repos.json` 里 `status` 为 `frozen`）；退役的 3 个 README 顶部有 RETIRED 横幅。**使用者至少应该能从 README 里知道你为什么不做了。**
 
 ## 7. 事实陈述
 
-- **家族现状**：家族表现在列 **44 个插件仓**（含 `dsh-plugin-upgrade-015` 的表为 45 行），其中 🚫 **已退役 3 个**、🧊 **已冻结 7 个**，其余按活跃仓维护。许可以 Apache-2.0 为主。
+- **家族现状**：家族表现在列 **44 个插件仓**（含 `dsh-plugin-upgrade-015` 的表为 45 行），其中 🚫 **已退役 3 个**、🧊 **已冻结 6 个**，其余按活跃仓维护。许可以 Apache-2.0 为主。
 - **仓库位置**：https://github.com/PerryLink
 - **数据采集时间**：2026-10-05。来源为那份自查报告——npm registry API 全量拉取、GitHub REST API 实测、宿主源码逐文件取证。**结论是可复核的**：每一条都能指到具体文件或具体 API 读数，指不到的一律标「未证实」。