dsh-primer 0.4.5 → 0.4.7

package/data/standards.json

@@ -2,7 +2,7 @@
   "schema": "dsh-plugin-guide-standards/1",
   "version": "1.0.0",
   "nonOfficial": true,
-  "updatedAt": "2026-11-01",
+  "updatedAt": "2026-11-14",
   "localized": {
     "en": "guide/standards.md",
     "zh-CN": "guide/standards.zh-CN.md"
@@ -10,16 +10,19 @@
   "canonical": {
     "repo": "PerryLink/dsh-standards",
     "version": "1.0.0-rc.1",
-    "status": "draft",
+    "status": "published",
     "clauses": [
       "31-DSH-ENTRY入门规范.md",
       "32-DSH-FLOW顺畅规范.md",
       "33-DSH-BOOST加速实践.md",
       "34-三层分级模型-GB-GBT-GBZ类比.md"
     ],
-    "auditStatus": "available in the private standards repository; not bundled with this guide",
+    "auditStatus": "available — the checkers ship in the public dsh-standards package (>=1.6.10; baseline 1.6.12) and are no longer private or planned",
     "entryChecker": "40-checker/bin/dsh-plugin-verify.mjs",
-    "private": true
+    "private": false,
+    "packageName": "dsh-standards",
+    "packageVersion": "1.6.12",
+    "packageUrl": "https://www.npmjs.com/package/dsh-standards"
   },
   "disclaimer": "Not an official DeepSeek standard, not a certification, not a security audit, and not a legal GB/GB-T/GB-Z instrument. The GB analogy is a communication aid only. Certification grades A-D are orthogonal to the three levels.",
   "axes": {
@@ -271,21 +274,24 @@
   "tools": {
     "audit": {
       "path": "40-checker/scripts/level-audit.mjs",
-      "url": "40-checker/scripts/level-audit.mjs",
-      "status": "planned",
-      "command": "node 40-checker/scripts/level-audit.mjs <plugin-dir>",
-      "note": "Not bundled with this guide; run only if the file exists in your checkout."
+      "url": "https://www.npmjs.com/package/dsh-standards",
+      "status": "available",
+      "command": "dsh-levels <plugin-dir> --no-runtime --format json   # bin/dsh-levels.mjs shipped by dsh-standards",
+      "note": "Ships in the public npm package dsh-standards (>=1.6.10; baseline 1.6.12). Paths are relative to that package root, not to this guide.",
+      "package": "dsh-standards@1.6.12"
     },
     "entryChecker": {
       "path": "40-checker/bin/dsh-plugin-verify.mjs",
-      "url": "40-checker/bin/dsh-plugin-verify.mjs",
-      "command": "node 40-checker/bin/dsh-plugin-verify.mjs <plugin-dir> --scope entry --entry-claim static"
+      "url": "https://www.npmjs.com/package/dsh-standards",
+      "command": "node 40-checker/bin/dsh-plugin-verify.mjs <plugin-dir> --scope entry --entry-claim static",
+      "package": "dsh-standards@1.6.12",
+      "note": "Ships in the public npm package dsh-standards (>=1.6.10; baseline 1.6.12); path relative to that package root."
     },
     "localStatic": {
       "command": "dsh-plugin-dev check --json",
       "note": "16 static checks (a subset of dsh-plugin-doctor's 33); not a level audit."
     },
-    "private": true
+    "private": false
   },
   "certification": {
     "orthogonal": true,

package/dist/dsh-plugin-dev.js

@@ -171,7 +171,7 @@ function isDir(path) {
 * range that stops at 0.1.x makes every scaffolded plugin uninstallable on a
 * 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";
+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 || >=0.2.2-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.
@@ -181,7 +181,7 @@ const DSH_PEER_RANGE = ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6
 * 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";
+const DSH_BASELINE = "0.2.2-rc.3";
 /** Resolve the templates root: env override first, then candidate walks. */
 function resolveTemplatesRoot() {
 	const env = process.env.DSH_PLUGIN_DEV_TEMPLATES;
@@ -1849,8 +1849,8 @@ function runSeams(index, options) {
 * `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-rc.2";
-const VERIFY_HEADLESS_SPEC = "@deepseek-ai/dsh-headless@0.2.1-rc.2";
+const VERIFY_BASE_SPEC = "@deepseek-ai/dsh-base@0.2.2-rc.3";
+const VERIFY_HEADLESS_SPEC = "@deepseek-ai/dsh-headless@0.2.2-rc.3";
 const PROFILE_WORKSPACE = `# scratch profile allowlist (mirrors the repo's compat workflow)
 packages:
   - .
@@ -2040,7 +2040,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-rc.2 (older builds such as the rc.6 line do not satisfy the compat pin)");
+		base.push("ensure the dsh CLI is @deepseek-ai/dsh@0.2.2-rc.3 (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");
@@ -2217,8 +2217,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-rc.2") ?? "@deepseek-ai/dsh-base@0.2.1-rc.2",
-					headless: flagString(flags, "headless", "@deepseek-ai/dsh-headless@0.2.1-rc.2") ?? "@deepseek-ai/dsh-headless@0.2.1-rc.2",
+					base: flagString(flags, "base", "@deepseek-ai/dsh-base@0.2.2-rc.3") ?? "@deepseek-ai/dsh-base@0.2.2-rc.3",
+					headless: flagString(flags, "headless", "@deepseek-ai/dsh-headless@0.2.2-rc.3") ?? "@deepseek-ai/dsh-headless@0.2.2-rc.3",
 					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/links.md

@@ -45,12 +45,12 @@
 | 主题 | 本地副本 | GitHub 直链 |
 |---|---|---|
 | 会话格式版本状态（**版本权威**） | `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) |
+| 逐版本迁移指南（**无 index、无入链**；镜像 tag `dsh-v0.2.2-rc.3` 内 12 个版本目录，0.2.2 线 46 条） | `docs/upgrade-guide/v0.1.7-rc.2/**`、`v0.2.0-rc.2/**`、**`v0.2.2-alpha.2/**`（22 条）、`v0.2.2-alpha.3/**`（5 条）、`v0.2.2-rc.1/**`（19 条）** | [目录（rc.3 tag）](https://github.com/deepseek-ai/deepseek-harness/tree/dsh-v0.2.2-rc.3/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) |
 | Web 样式 | `docs/web-styling.md` | [blob](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/web-styling.md) |
 | 模块图 / 依赖目录 / 持久化 schema | `docs/module-graph.md`、`docs/dependency-catalog.json`、`docs/persistence-schema.json` | [docs 目录](https://github.com/deepseek-ai/deepseek-harness/tree/master/docs) |
-| **官方自带插件开发技能**（preset 内，最该读的一份） | 不在 `docs/` 下：`packages/preset/agent-preset/skills/cordis-plugin-development/**`；本库要点摘录见 [../references/official-plugin-dev-skill.md](../references/official-plugin-dev-skill.md) | [目录](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/preset/agent-preset/skills) |
+| **官方自带插件开发技能**（preset 内，最该读的一份） | 不在 `docs/` 下：rc.3 起是**单个 `dsh-doc` 技能**（`packages/preset/agent-preset/skills/dsh-doc/**`，17 份 references + 2 套模板）；本库要点摘录见 [../references/official-plugin-dev-skill.md](../references/official-plugin-dev-skill.md) | [目录（rc.3 tag）](https://github.com/deepseek-ai/deepseek-harness/tree/dsh-v0.2.2-rc.3/packages/preset/agent-preset/skills) |
 
 ## 3. 官方仓库与直链（GitHub，master 分支）
 

package/guide/migration-0.2.md

@@ -1,10 +1,12 @@
 # 迁移到 0.2 世代（migration-0.2.md）
 
 > **适用对象**：所有针对 DeepSeek Harness `0.1.6-alpha.2` 及更早版本开发的第三方插件（bundle / 纯 cordis 插件 / UI 插件 / MCP 配置包）。
-> **基线**：本文件对照 `d743267388641bc76f17c45ce8b4c231aed1d32c`（tag `dsh-v0.2.1-alpha.2`，2026-10-09，master HEAD）核验；区间起点为 `ddefc45fbc7f8e46dd73185e68295696d1297887`（tag `dsh-v0.1.6-alpha.2`，2026-09-17）。
+> **基线 1（0.1.6→0.2.1 线）**：本文件对照 `d743267388641bc76f17c45ce8b4c231aed1d32c`（tag `dsh-v0.2.1-alpha.2`，2026-10-09）核验；区间起点为 `ddefc45fbc7f8e46dd73185e68295696d1297887`（tag `dsh-v0.1.6-alpha.2`，2026-09-17）。
+> **基线 2（当前线）**：官方文档镜像已钉到发布 tag `dsh-v0.2.2-rc.3`（`38a6a5c965aa99ab525161efb7cc5cf1fe62fced`，2026-11-13）；rc.3 包内 `docs/upgrade-guide` 只到 `v0.2.2-rc.1`。
 > **覆盖范围**：§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`）**。
-> 两段跨度都已有稳定 ID，可被扫描器引用（`dsh-plugin-upgrade` 的走廊目前只到 `legC`）。
+> **§13 覆盖 `0.2.1-alpha.1` → `0.2.1-alpha.2`（19 个 seam，`L1`–`L19`）**；
+> **§14 覆盖 rc.3 包内 0.2.2 线的 46 个 seam（`K1`–`K46`）**，并单列 `v0.2.2-rc.2` 的 13 条**下一版**指南（不属于 rc.3）。
+> 三段跨度都已有稳定 ID，可被扫描器引用（`dsh-plugin-upgrade` 的走廊目前只到 `legC`）。
 > **权威优先级**：官方 `docs/upgrade-guide/**`（原文副本 `references/official-docs/docs/upgrade-guide/`）> 本文件 > 社区文章。官方每一条"next release removes X"都对应本文件的一节。
 > 事实核实方式：源码 `path:line` + 提交号，全部可在 `D:\deepseek-harness`（或你的 checkout）复核；无法核实的项已标注 `UNVERIFIED`。
 
@@ -18,12 +20,13 @@
 
 | 问题 | 答案（**2026-10-09 复核**；完整谱系见 [version-matrix.md](version-matrix.md)） |
 |---|---|
-| master 最新 tag | `dsh-v0.2.1-alpha.2`（2026-10-09，`d743267388641bc76f17c45ce8b4c231aed1d32c`；**= master HEAD**） |
-| npm `latest` dist-tag | `0.2.0-rc.2`（**不是** master 最新 tag） |
-| npm `alpha` / `next` | `alpha`=`0.2.1-alpha.2`、`next`=`0.2.0-rc.2` |
-| 是否存在稳定版 | **否**。全部 31 个 npm 版本都是 `-alpha.N`/`-rc.N`，全部 26 个 GitHub Release 都是 `prerelease: true` |
+| master 最新 tag | `dsh-v0.2.2-rc.3`（2026-11-13，`38a6a5c965aa99ab525161efb7cc5cf1fe62fced`）——本机 checkout 的 master 已合并 rc.3 发布 |
+| npm `latest` dist-tag | `0.2.2-rc.1`（**不是**最新 tag） |
+| npm `next` / `alpha` | `next`=`0.2.2-rc.3`、`alpha`=`0.2.2-alpha.3` |
+| 是否存在稳定版 | **否**。全部 44 个 npm 版本都是 `-alpha.N`/`-rc.N`，全部 39 个 GitHub Release 都是 `prerelease: true` |
+| rc.3 包内的 0.2.2 线指南 | **46 条**：22 条 authored 于 `v0.2.2-alpha.2`（落 alpha.3）、5 条 `v0.2.2-alpha.3`（落 rc.1）、19 条 `v0.2.2-rc.1`（落 rc.2）——见 §14 |
 | 区间内发布线（9 个） | `0.1.6-alpha.2`(09-17) → `0.1.7-alpha.1`(09-22) → `0.1.5-rc.3`(09-22) → `0.1.7-alpha.2`(09-22) → `0.1.7-rc.1`(09-23) → `0.1.7-rc.2`(09-24) → `0.2.0-rc.1`(09-28) → `0.2.0-rc.2`(09-29) → `0.2.1-alpha.1`(10-03) |
-| Node 门槛 | `^22.19.0 \|\| >=24.0.0`；跟随 dsh 0.2.2-alpha.3 的包可用 `>=24.9.0`（无 `.nvmrc`/`.node-version` 文件） |
+| Node 门槛 | **`>=24.9.0`**（rc.3 宿主 `package.json`）；0.2.1-alpha.2 时代为 `^22.19.0 \|\| >=24.0.0`（无 `.nvmrc`/`.node-version` 文件） |
 | `dsh.version` 字段 | **不存在**。DSH 的包清单只有 `dsh.bundle` / `dsh.profile` / `dsh.client` 三组键 |
 | 官方发布说明在哪 | 仓库里**没有 `CHANGELOG.md`**、也没有 `docs/persistence-changes/releases/*` 新条目，所以逐版本说明只在 GitHub **Releases** 的 body 里（`gh release view <tag>` 或 Releases API）。本文件的每一条都对照过 tag `dsh-v0.1.7-alpha.1` / `dsh-v0.2.0-rc.2` / `dsh-v0.2.1-alpha.1` 的发布说明 |
 
@@ -33,7 +36,7 @@
 
 **npm 陷阱（最贵的一条）**：库包（`dsh-tools`、`dsh-base`、`dsh-headless`、`dsh-session-persistence-jsonl`、`dsh-session`、`dsh-settings`、`dsh-workflow` …）的 `latest` 至今钉在 **`0.0.1-rc.1`**。写 `"@deepseek-ai/dsh-session": "latest"` 会装到远古版本；必须写死版本或钉 `next`/`alpha`。唯一的例外是 CLI 包 `@deepseek-ai/dsh`（`latest`=`0.2.0-rc.2`）。
 
-**跨线 peer 范围**：`^0.1.x` 与 `^0.2.x` 互不覆盖，要同时支持两条线必须写两侧范围。⚠️ **peer 范围会被安装期强制**（本节早期版本写成"DSH 不校验范围"，已更正）：`dsh plugin add` 会拿运行时的版本去比插件声明的 peer 范围，不匹配就**拒绝安装**并把声明的范围原样打印出来。跨线支持因此必须**在范围里同时列出两侧的 prerelease 元组**（每个元组一个 clause），否则 0.2.x 宿主装不上——详见 [plugin-dev-guide.md](plugin-dev-guide.md) §7.3 的 `dsh-plugin` 段。范围之外仍要配**运行时特性探测**，因为范围只能表达"能不能装"，表达不了"某个 API 在不在"。
+**跨线 peer 范围**：`^0.1.x` 与 `^0.2.x` 互不覆盖，要同时支持两条线必须写两侧范围。⚠️ **兼容性门禁是强制的，且 `engines.dsh` 优先**（本节早期版本写成"DSH 不校验范围"，已更正）：清单**有 `engines.dsh`** 时该范围**单独决定**、忽略 `@deepseek-ai/dsh*` peers；**没有**时才回退到 peer 规则。`dsh plugin add` 会拿运行时的版本去比生效范围，不匹配就**拒绝安装**并把范围原样打印出来（官方语义：`references/official-docs/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md`）。跨线支持因此必须**在范围里同时列出两侧的 prerelease 元组**（每个元组一个 clause），否则 0.2.x 宿主装不上——详见 [plugin-dev-guide.md](plugin-dev-guide.md) §7.3 的 `dsh-plugin` 段。范围之外仍要配**运行时特性探测**，因为范围只能表达"能不能装"，表达不了"某个 API 在不在"。
 
 ## 2. 会话格式 V3 → V4（影响最深，涉及历史日志）
 
@@ -88,7 +91,7 @@
 
 - `dsh.bundle.patch` 现在接受**有序数组**：`{ "patch": ["./base.patch.yml", "./web.patch.yml"] }`，按序作为同一层应用，且每个文件里的相对插件路径**相对该文件所在目录**解析。校验失败信息：`dsh.bundle.patch must be a file path or a list of file paths`。
 - 层顺序未变：`dsh.profile.bundles` 顺序 → profile 自己的 `cordis.patch.yml` → `$DSH_HOME/cordis.patch.yml` → 各 `--patch`（argv 顺序）。**按 id 覆盖时整段 `config` 被替换，不做深合并。**
-- 包清单还可以声明 `dsh.manifestVersion`（格式标识，当前 `1`，与 npm 版本、会话格式版本无关）与 `engines.dsh`（作者声明的兼容范围，**当前安装器/加载器都不强制**——真正会被强制的是 `@deepseek-ai/dsh-*` 的 **peerDependencies**，安装期即拒绝不匹配者，见 [plugin-dev-guide.md](plugin-dev-guide.md) §7.3）。类型定义见 `@deepseek-ai/dsh-package-manifest`。
+- 包清单还可以声明 `dsh.manifestVersion`（格式标识，当前 `1`，与 npm 版本、会话格式版本无关）与 `engines.dsh`（**运行时兼容门禁**：声明了就**单独决定**安装/启动是否放行，并**忽略** `@deepseek-ai/dsh*` peer 范围；只有**缺失**时才回退 peers。语义自 `0.2.1-alpha.4` 起生效、rc.3 仍如此，官方原文见 `references/official-docs/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md`）。判定用 `includePrerelease: true`，所以 0.2.2 线要写 `>=0.2.2-0 <0.3.0` 这类带预发布下界的范围；`workspace:` 在 `engines.dsh` 中不合法。类型定义见 `@deepseek-ai/dsh-package-manifest`。
 - 展示元数据契约（Plugin Manager / Settings 在**不激活插件**的前提下读取）：包根读 `package.json` 的 `name`/`description`/`icon`，或导出 `./locale/*.json` 的 `meta.title`/`meta.description` 与 `./icon`；图标支持 SVG/PNG/JPEG/WebP，**≤ 256 KiB 且必须落在包内**（绝对路径、URL、指向包外的 symlink 都被拒）。子路径插件**永远不读** `<subpath>/package.json`——标题/描述走 `locale/*.json` 的 `meta.*`，图片走导出的 `<subpath>/icon`。
 - `dsh.client` 键**未变**：`platform`（web）、`inject`（仅排序，不是 cordis 服务注入）、`immediately`（一阶段预取）、`external`（基线与注入边之外的精确模块请求）。但客户端半侧只挂在**说明符恰为裸包名**的那一行上：把一个包拆成多行的组合包，其 UI 只随根行启停。
 
@@ -216,7 +219,8 @@ DSH 自带的 preset 里有一整套**官方插件开发技能**，这是本世
 > 本节给该跨度**稳定 ID（`L1`–`L19`）**、**症状**、**修法**与**官方出处**。
 >
 > **适用判定**：`dsh --version` 落在 `0.2.1-alpha.2`（或更新）时，**逐条核对**；
-> 停在 `0.2.0-rc.2` 及更早的**与本节无关**。
+> 停在 `0.2.0-rc.2` 及更早的**与本节无关**。落在 `0.2.2-alpha.3` 及更新（当前 rc.3）时，
+> **本节的 19 条与 §14 的 46 条都要核对**——0.2.2 线没有推翻本节，只有新增。
 > 官方出处全部已随镜像落地：`references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/<item>/guide.md`。
 >
 > ⚠️ **目录名陷阱**：`v0.2.1-alpha.1/` 是**变更被引入时仓库的版本号**，描述的是
@@ -261,9 +265,96 @@ DSH 自带的 preset 里有一整套**官方插件开发技能**，这是本世
 
 ---
 
-## 14. 已知分歧与未核实项（诚实标注）
+## 14. 新走廊：rc.3 包内的 `0.2.2` 线（46 个 seam，`K1`–`K46`）
 
-1. ✅ **已解决（2026-10-13）**：上游 `docs/session-format-status.md` 已是 `latestReleasedVersion: 4` / `evidenceTag: dsh-v0.2.0-rc.2`，与代码和 npm 一致；本项目 `references/official-docs/` 镜像**已重同步**到 `d743267388641bc76f17c45ce8b4c231aed1d32c`（`dsh-v0.2.1-alpha.2`，2026-10-13），该矛盾在本库内部也一并消失。
+> **本节解决 0.2.2 线的缺口**：rc.3 发布包的 `docs/upgrade-guide` 只到 `v0.2.2-rc.1`（22+5+19=46 条），
+> 但本文件此前只覆盖到 0.2.1 线。本节把 46 条整理成可引用 seam（`K1`–`K46`）、带症状与修法，并标注每条
+> 是否**静态可扫**；数据同步落在 `data/seams/index.json`（`seams` 的 K 记录 + `unreleased` 的 13 条）。
+>
+> **口径（与 §2/§13 相同）**：官方 `docs/upgrade-guide/v<X>/` 的目录名 `X` 是**变更被写下的版本**，
+> 描述的是**从 X 升到下一个 release** 的行为；表里 `landed` 列才是**变更落地**的版本。
+> 因此 `K1`–`K22` 落 `0.2.2-alpha.3`、`K23`–`K27` 落 `0.2.2-rc.1`、`K28`–`K46` 落 `0.2.2-rc.2`，
+> **全部都在 rc.3 发布包的快照范围内**（镜像已钉 `dsh-v0.2.2-rc.3` / `38a6a5c9…`）。
+>
+> **不要混淆下一版**：`v0.2.2-rc.2/` 的 13 条只存在于 rc.3 tag **之后**的 master，**不属于 rc.3**，
+> 单列在本节末尾与 `data/seams/index.json` 的 `unreleased` 中。
+
+| ID | 官方项 | authored 于 | landed | 标题 | 破坏/移除面 | 修法 | 静态可判 |
+|---|---|---|---|---|---|---|---|
+| **K1** | `context-menu-target` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Context menu types and icons | unprefixed context-menu action types and hooks；unkeyed icon components | Use the prefixed context-menu types and hooks and register keyed icon components. | 是（静态可扫） |
+| **K2** | `cordis-loader-entry-trees` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Loader entry tree reports and Include persistence | Loader entry-tree mutation reports without commit(change) | Report entry-tree mutations through commit(change); Include persists them through a journal. | 是（静态可扫） |
+| **K3** | `css-anchored-menus` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | CSS-anchored menus | JavaScript panel positioning；Menu rectangle callbacks | Position menus with CSS anchors instead of JavaScript panel positioning and rectangle callbacks. | 是（静态可扫） |
+| **K4** | `cua-source-dev-helper` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Source-built Computer Use helper identity | source-built CUA helper bundle identity | Grant the source-built helper its separate macOS permission. | 否（运行时/部署面） |
+| **K5** | `desktop-stable-channel` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Desktop stable channel name | Desktop update channel named latest | Subscribe Desktop updates to the renamed stable channel. | 否（运行时/部署面） |
+| **K6** | `forge-git-permissions` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Forge Git query permissions and content conversion | Forge Git queries not tied to Session permissions；configured diff helpers during Git queries | Let Forge Git queries run under Session permissions; remove configured diff helpers. | 否（运行时/部署面） |
+| **K7** | `forge-worktree-entry` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | One plugin entry for change requests and worktrees | standalone Git worktrees card on the Plugins page | Use the Change requests and worktrees entry on the Plugins page. | 否（运行时/部署面） |
+| **K8** | `fs-observation-policy-default-off` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Filesystem mutations no longer require a prior read by default | fs-observation-policy row enabled by default；apply_patch absent from dsh-base and the Web standard preset | Re-enable the fs-observation-policy row if read-before-write is required; account for apply_patch in the base and standard presets. | 否（运行时/部署面） |
+| **K9** | `llm-error-builtin-codes` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | `new LlmError` accepts only built-in failure codes | new LlmError with non-builtin failure codes | Construct built-in LlmError codes directly; route other cases through LlmError.fromFailure. | 是（静态可扫） |
+| **K10** | `llm-request-purpose-declarations` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Declare auxiliary LLM request purposes | shared fixed union of auxiliary LLM request purposes | Declare auxiliary request purposes with producer-owned type declarations. | 是（静态可扫） |
+| **K11** | `pi-ai-request-image-count` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | pi-ai request image count | all retained history images kept per pi-ai request | Expect history-image offloading after 50 retained images on pi-ai routes. | 否（运行时/部署面） |
+| **K12** | `projection-event-frames` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Projection frames list every key one event changed | one-key-per-frame live projection frames | Read frames that list every key one committed event changed. | 是（静态可扫） |
+| **K13** | `projection-released-checkpoint` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Released projection units stay in checkpoints | released projection unit omitted from session checkpoints | Expect a released projection unit to keep its last checkpoint row. | 否（运行时/部署面） |
+| **K14** | `projection-snapshot-scope` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Projection snapshot scope | registry cached snapshot read；context pressure and breakdown in Session list summaries | Compute only the units a snapshot returns; stop using the cached registry read and the Session-list pressure fields. | 是（静态可扫） |
+| **K15** | `retained-ptc-timeout` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Retained PTC timeout recovery | immediate process termination on retained PTC timeout | Expect cooperative stop first and process termination only when acknowledgement fails. | 否（运行时/部署面） |
+| **K16** | `schedule-agent-tools` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Schedule tools manage every Host task by RRULE and target | schedule_update tool；schedule_delete tool | Use schedule_create / schedule_list / schedule_view / schedule_edit against every Host task. | 是（静态可扫） |
+| **K17** | `schedule-remote-host-tasks` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Schedule uses one Host-wide management API | client-side Host task data layout | Use the single Host-wide schedule management API and its typed timing records. | 是（静态可扫） |
+| **K18** | `sdk-run-commands` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | SDK run accepts native commands | SDK run results before native command handling | Handle recognized native commands and await RunResult after the input completes. | 是（静态可扫） |
+| **K19** | `session-header-menu` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Session Header menus and export dialogs | custom Web compositions without Session context menus；export dialogs closed by Session switches | Provide Session context menus in custom Web compositions; expect export dialogs to stay visible across Session switches. | 否（运行时/部署面） |
+| **K20** | `subagent-explicit-reasoning` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Subagent reasoning overrides require an explicit route | reasoning overrides without an explicit provider and model | Pass an explicit provider and model route; omit effort to inherit the model default. | 是（静态可扫） |
+| **K21** | `web-search-credential-modes` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | DeepSeek web search and fetch follow the DeepSeek model route | shared web-search baseURL / apiKeyEnv / apiKey fields | Derive web search and fetch endpoints from the DeepSeek model route and use per-capability fields. | 是（静态可扫） |
+| **K22** | `web-search-default-provider` | 0.2.2-alpha.2 | **0.2.2-alpha.3** | Search defaults to the DeepSeek Search API; Exa and Perplexity are removed | legacy Messages search default；@deepseek-ai/dsh-web-search-exa；@deepseek-ai/dsh-web-search-perplexity | Rely on the DeepSeek Search API default and remove the Exa/Perplexity packages. | 是（静态可扫） |
+| **K23** | `chat-process-activity-context` | 0.2.2-alpha.3 | **0.2.2-rc.1** | Chat `ProcessActivity` adds `context` | ProcessActivity without a context category；older RunningProcessActivity shape | Handle the context category and the current RunningProcessActivity shape. | 是（静态可扫） |
+| **K24** | `office-kit-package` | 0.2.2-alpha.3 | **0.2.2-rc.1** | `@deepseek-ai/dsh-office-kit` replaces `@deepseek-ai/dsh-office-to-pdf` | @deepseek-ai/dsh-office-to-pdf；office-to-pdf service, Remote methods, exported types and config row | Move to @deepseek-ai/dsh-office-kit and its renamed service, Remote methods, types and row. | 是（静态可扫） |
+| **K25** | `office-operation-tools` | 0.2.2-alpha.3 | **0.2.2-rc.1** | Office operation skills are replaced by Office tools | office-render / office-recalculate / office-export-pdf skills；skill-office node and cli keys；two Office CLI environment variables | Use the skill-activated Office tools instead of the removed skills and CLI keys. | 是（静态可扫） |
+| **K26** | `office-skill-resources` | 0.2.2-alpha.3 | **0.2.2-rc.1** | Office skills load from the packaged assets | DSH_BUNDLED_OFFICE_SKILLS；office-skills/ resource directories | Load Office skills from the skill-office package assets; drop the environment variable and resource dirs. | 是（静态可扫） |
+| **K27** | `subagent-names` | 0.2.2-alpha.3 | **0.2.2-rc.1** | Subagent tools address agents by name | Subagent control and Team task tools addressed by id；previous list_agents row shape；subagent catalog payload version 2 | Address agents by name and handle the new list_agents rows and catalog payload version 3. | 是（静态可扫） |
+| **K28** | `account-notification-fields` | 0.2.2-rc.1 | **0.2.2-rc.2** | Update account notification consumers | bonus-specific account notification methods；notification requests outside the Harness domain | Use the generic account notification APIs and Harness-domain notification requests. | 是（静态可扫） |
+| **K29** | `account-remote-provider` | 0.2.2-rc.1 | **0.2.2-rc.2** | Account service and Remote imports | abstract account composition；Remote imports from the abstract account package | Compose the concrete deepseek-account service and import its Remote types. | 是（静态可扫） |
+| **K30** | `archive-worktrees` | 0.2.2-rc.1 | **0.2.2-rc.2** | Worktree cleanup on archive | archiving a Session left its worktree untouched | Expect archiving to remove a clean worktree while keeping the branch. | 否（运行时/部署面） |
+| **K31** | `attachment-error-codes` | 0.2.2-rc.1 | **0.2.2-rc.2** | Attachment failures keep their codes | AttachmentError not extending HarnessError；attachment failures recorded as UNKNOWN | Treat AttachmentError as a HarnessError subclass and read the preserved attachment codes. | 是（静态可扫） |
+| **K32** | `cua-ax-read-limits` | 0.2.2-rc.1 | **0.2.2-rc.2** | macOS AX tree read limits | fixed macOS AX traversal budgets | Pass per-read overrides and expect the larger default AX node budget. | 是（静态可扫） |
+| **K33** | `cua-hover-ax-only` | 0.2.2-rc.1 | **0.2.2-rc.2** | macOS hover keeps the system pointer in place by default | mouseMove that moves the system pointer | Expect macOS mouseMove to require AX alternate UI and return HOVER_UNAVAILABLE instead of moving the cursor. | 否（运行时/部署面） |
+| **K34** | `cua-native-platform` | 0.2.2-rc.1 | **0.2.2-rc.2** | Native CUA application and window API | global native CUA window input API；numeric element ids | Use scoped window input, string element IDs and platform capabilities. | 是（静态可扫） |
+| **K35** | `dsh-doc-skill` | 0.2.2-rc.1 | **0.2.2-rc.2** | `dsh-doc` replaces the Creator mode skills | cordis-plugin-development skill；editing-cordis-compositions skill；cordis-composition-reference skill；agent-experience skill；packages/preset/agent-preset/skills/cordis-plugin-development/** | Load the single dsh-doc skill; its references and templates now live under skills/dsh-doc/. | 是（静态可扫） |
+| **K36** | `forge-change-request-overview` | 0.2.2-rc.1 | **0.2.2-rc.2** | Forge snapshots carry the change request overview, and actions report unknown outcomes | ChangeRequestSnapshot without overview fields；ChangeRequestCheck without rerun；ForgeActionFailure without unknown | Populate the required overview and rerun fields and handle the unknown action outcome. | 是（静态可扫） |
+| **K37** | `forge-pinned-diff` | 0.2.2-rc.1 | **0.2.2-rc.2** | Forge diffs read one head commit | ForgeProvider.diff without a head commit；ForgeFailure without stale；ChangeRequestSnapshot without threadsTruncated | Pass the head commit to ctx.forge.diff / ForgeProvider.diff and handle stale plus threadsTruncated. | 是（静态可扫） |
+| **K38** | `forge-review-reads` | 0.2.2-rc.1 | **0.2.2-rc.2** | Forge failures report unsupported reads | review reads that silently succeed without provider support | Handle ForgeFailure code unsupported returned by ctx.forge.readReview. | 是（静态可扫） |
+| **K39** | `plugin-update-method` | 0.2.2-rc.1 | **0.2.2-rc.2** | `BundleInfo.update` replaces `BundleInfo.updatable` | BundleInfo.updatable | Read BundleInfo.update (registry \| git \| undefined) and handle ManagementError code unexpected-package. | 是（静态可扫） |
+| **K40** | `runtime-context-reminders` | 0.2.2-rc.1 | **0.2.2-rc.2** | Runtime-context reminder records | runtime-context log text without reminder framing；clear markers without empty-section records | Read the reminder framing and empty-snapshot-section clear markers in runtime-context log text. | 否（运行时/部署面） |
+| **K41** | `session-append-overloads` | 0.2.2-rc.1 | **0.2.2-rc.2** | Update replacements for `Session.append` | a replacement Session.append that implements only one overload | Implement both the single-event and array overloads when replacing Session.append. | 是（静态可扫） |
+| **K42** | `subagent-interrupt-default` | 0.2.2-rc.1 | **0.2.2-rc.2** | Built-in configurations disable agent interruption | interrupt_agent enabled by default for subagents and Team mode | Re-enable interrupt_agent explicitly in built-in configurations if interruption is required. | 否（运行时/部署面） |
+| **K43** | `terminal-backend-cleanup-error` | 0.2.2-rc.1 | **0.2.2-rc.2** | `TerminalBackendCleanupError` extends `TerminalError` | TerminalBackendCleanupError extending AggregateError | Extend TerminalError and carry the CLEANUP_FAILED code. | 是（静态可扫） |
+| **K44** | `terminal-bundle-sidebar-backend` | 0.2.2-rc.1 | **0.2.2-rc.2** | Persistent terminals open in the Web sidebar | optional-terminal-bash row；optional-terminal-pwsh row | Target optional-terminal-panel rows; Agent terminals now open in the Web sidebar. | 是（静态可扫） |
+| **K45** | `web-search-billing` | 0.2.2-rc.1 | **0.2.2-rc.2** | DeepSeek web search and fetch choose their credential by billing | provider authentication fields on DeepSeek Search/Fetch | Use per-capability billing and ordered credential sources for DeepSeek Search and Fetch. | 是（静态可扫） |
+| **K46** | `window-drag-regions` | 0.2.2-rc.1 | **0.2.2-rc.2** | Explicit window regions for custom Client overlays | global macOS no-drag exclusions for custom overlays | Declare explicit window regions for custom Client overlays. | 否（运行时/部署面） |
+
+**下一版（`v0.2.2-rc.2`，**不是** rc.3）的 13 条指南**（master-only，镜像里没有，别当 rc.3 变更）：
+
+| ID | 官方项 | 说明 |
+|---|---|---|
+| U1 | `guide.md` | Client module metadata |
+| U2 | `guide.md` | Token Provider and route admission migration |
+| U3 | `guide.md` | `ctx[Context.root]` replaces `ctx.root`, and service intercept metadata is renamed |
+| U4 | `guide.md` | CUA gives Agents without a preset `cua_run_code` |
+| U5 | `guide.md` | macOS Computer Use provider name |
+| U6 | `guide.md` | macOS CUA isolates unavailable AX branches |
+| U7 | `guide.md` | DeepSeek image upload timeout |
+| U8 | `guide.md` | Experimental plugin failures carry error codes |
+| U9 | `guide.md` | Update removed package subpath imports |
+| U10 | `guide.md` | Python PTC removal |
+| U11 | `guide.md` | Session status moves to `@deepseek-ai/dsh-client-ui-session-status` and completion reminders follow Host reading records |
+| U12 | `guide.md` | Shared search filter replaces rankByName and searchMode |
+| U13 | `guide.md` | Shell and read_image failures use consolidated error codes |
+
+> 这 13 条描述的是 rc.3 之后的下一次升级（其中 `cordis-root-and-intercept-metadata` 对应 Cordis 上游 rc.12，
+> rc.3 的 vendor 仍是上游 rc.11）。下一次审计以它们为输入，同时先核对目标发布包是否已包含它们。
+
+---
+
+## 15. 已知分歧与未核实项（诚实标注）
+
+1. ✅ **已解决（2026-11-14）**：上游 `docs/session-format-status.md` 已是 `latestReleasedVersion: 4` / `evidenceTag: dsh-v0.2.0-rc.2`，与代码和 npm 一致；本项目 `references/official-docs/` 镜像已重同步到**发布 tag** `dsh-v0.2.2-rc.3`（`38a6a5c965aa99ab525161efb7cc5cf1fe62fced`，709 md / 352 zh，2026-11-14），并通过 `scripts/check-facts.mjs` 校验 pin 与计数。
+   ⚠️ **历史更正**：0.4.5 曾把 master 同步 commit `e8f7b93…` 标成 `dsh-v0.2.2-rc.2`。它不是 rc.2 tag（rc.2 tag = `ddac9676…`），也多带了 4 个只在 master 的 `v0.2.2-rc.1` 指南（717/356）；该错误已随本次重同步修正。
 2. `UNVERIFIED`：未解包已发布的 npm tarball 逐字节确认产物与 tag 一致。
 3. `UNVERIFIED`：仓库内无 `CHANGELOG.md`、无 `docs/persistence-changes/releases/*` 新条目，因此**没有官方逐版本 release notes 可引**；tag 对应的提交主题是唯一线索。
 4. `ctx.agent` 在两个基线都**不存在**（不是"被移除"）。
@@ -272,4 +363,4 @@ DSH 自带的 preset 里有一整套**官方插件开发技能**，这是本世
 
 ---
 
-*维护：官方每次发版后重跑 `pwsh -File scripts/sync-official-docs.ps1`，再按 `references/official-docs/docs/upgrade-guide/**` 与 `docs/persistence-changes/**` 增量更新本文件；行号与提交号引用 `references/official-docs/SNAPSHOT.md` 的基线。*
+*维护：官方每次发版后重跑 `pwsh -File scripts/sync-official-docs.ps1 -Ref dsh-v<X>`（钉发布 tag，不取 master HEAD；当前 tag 见 `references/official-docs/SNAPSHOT.md`），再按 `references/official-docs/docs/upgrade-guide/**` 与 `docs/persistence-changes/**` 增量更新本文件；行号与提交号引用 `references/official-docs/SNAPSHOT.md` 的基线。*

package/guide/plugin-dev-guide.md

@@ -76,7 +76,7 @@ export function apply(ctx: Context) {
 - **bundle（分发层）**：npm 包，`package.json` 声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`；patch 里是"插入/覆盖插件行"的 YAML 数组。**`patch` 也可以是有序数组**：`{ "patch": ["./base.patch.yml", "./web.patch.yml"] }`，按序作为同一层应用，且每个文件里的相对插件路径**相对该文件所在目录**解析（校验失败信息：`dsh.bundle.patch must be a file path or a list of file paths`）。
 - **profile（可运行组合）**：`$DSH_HOME/profiles/<name>/`，`package.json` 声明 `"dsh": { "profile": { "bundles": [...] } }`；由 `dsh plugin` / `plugin_manager` 维护，手写不允许。
 - **client（浏览器半侧）**：`package.json` 声明 `"dsh": { "client": { "platform": "web", "inject": [...], "immediately": true, "external": [...] } }` 并导出编译好的 `./client`。`inject` **只决定激活顺序**（不是 cordis 服务注入），`immediately` 标记一阶段预取，`external` 列出基线之外的精确模块请求。客户端半侧只挂在**说明符恰为裸包名**的那一行上。
-- 另有两个可选作者字段：`dsh.manifestVersion`（清单格式标识，当前 `1`，与 npm 版本、会话格式版本无关）与 `engines.dsh`（兼容范围声明，**当前安装器/加载器都不校验**；会被校验的是 `@deepseek-ai/dsh-*` 的 peerDependencies，见 §7.3）。类型定义来自 `@deepseek-ai/dsh-package-manifest`。
+- 另有两个可选作者字段：`dsh.manifestVersion`（清单格式标识，当前 `1`，与 npm 版本、会话格式版本无关）与 `engines.dsh`（**运行时兼容门禁**：清单里有它时它单独决定安装/启动是否放行，并忽略 `@deepseek-ai/dsh*` peer 范围；只有缺失时才回退到 peer 规则。判定用 `includePrerelease: true`，所以 0.2.2 线要写 `>=0.2.2-0 <0.3.0` 这类带预发布下界的范围；`workspace:` 在 `engines.dsh` 中不合法。见 §7.3 与官方 `docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md`）。类型定义来自 `@deepseek-ai/dsh-package-manifest`。
 
 bundle 最小结构：
 
@@ -491,8 +491,8 @@ Plugin Manager 与 Settings 会**在不激活插件的前提下**读展示信息
 - 图标导出为 `"./icon"`（包根插件也可在 `package.json` 顶层写 `icon`，它优先于 `./icon`）；支持 SVG/PNG/JPEG/WebP，**≤ 256 KiB**，realpath 后必须仍在包内；
 - `files` 必须包含 patch、locale、图标与**每个运行时文件**——但**本地目录安装是链接 checkout，`files` 不过滤链接目录**，要直接核对文件；
 - **子路径插件（`my-plugins/search`）不是包，永远不读 `package.json`**：标题/描述走 `my-plugins/search/locale/*.json` 的 `meta.*`，图片走导出的 `my-plugins/search/icon`。
-- 可选作者字段：`dsh.manifestVersion`（当前 `1`）与 `engines.dsh`（**当前不校验**，只作声明）。类型来自 `@deepseek-ai/dsh-package-manifest`。
-- **真正会被强制的是 peerDependencies**（见 §7.3）：`dsh plugin add` 会用运行时的版本比对插件声明的 `@deepseek-ai/dsh-*` 范围，不匹配即**拒绝安装**。
+- 可选作者字段：`dsh.manifestVersion`（当前 `1`）与 `engines.dsh`（**运行时兼容门禁**：声明了就单独决定、忽略 `@deepseek-ai/dsh*` peers；只有缺失时才回退 peers；`includePrerelease: true`，下界要带预发布；`workspace:` 不合法）。类型来自 `@deepseek-ai/dsh-package-manifest`。
+- **没有 `engines.dsh` 时才看 peerDependencies**（见 §7.3）：`dsh plugin add` 会用运行时的版本比对插件声明的 `@deepseek-ai/dsh-*` 范围，不匹配即**拒绝安装**。声明了 `engines.dsh` 的包要让该范围覆盖全部支持版本，否则 peers 不会再放宽或收窄它。
 
 ### 7.1 从 GitHub 安装的 build-script 坑
 
@@ -518,9 +518,9 @@ bundle 挂一个普通 provider 插件：`inject = ['cmdlineArgs']`，用 `@deep
 **身份与依赖（最致命）**
 - **cordis 双副本 / 双 Cordis 分裂**：插件构建时若从 `.pnpm` 副本解析 cordis，与 harness 的 vendored 副本是"两个模块"，`declare module` 增强合并不了 → 报 `Property 'tools' does not exist on type 'Context'`。构建期把 cordis 解析到 harness 的 `vendor/cordis`；npm 安装路径下 peer 必须与宿主同一身份——**scoped `@deepseek-ai/cordis` 与 unscoped `cordis` 混用同样分裂**（dsh-tools 的类型只增强 scoped 版本）。独立包把 cordis 设为 peerDependency（+ dev），版本对齐宿主。
 - **官方 `@deepseek-ai/*` 包曾未发布公共 npm**（rc 早期）：社区 bundle 的 `dependencies` 留空，靠 profile 的 pnpm 闭包 flat fallback（`$DSH_HOME/profiles/node_modules`）注入；声明了反而解析失败。rc.6 起公开包可用（from-scratch 教程锁 `0.1.0-rc.6`、cordis `4.0.1`），两条时间线的资料都要知道，按当时宿主版本取舍。
-- **npm `latest` 标签是过期版本**：库包（`dsh-tools`、`dsh-base`、`dsh-headless`、`dsh-session-persistence-jsonl`、`dsh-settings`、`dsh-workflow` …）的 `latest` **至今**钉在 `0.0.1-rc.1`，所以写 `"latest"` 会装到远古版本，必须写死版本或钉 `next`/`alpha`。**2026-10-06 复核**：`@deepseek-ai/dsh` `latest`=`next`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.1`；dsh-tools / dsh-base / dsh-headless / dsh-session-persistence-jsonl 的 `latest` 仍 `0.0.1-rc.1`、`next`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.1`；`@deepseek-ai/cordis` `latest`=4.0.4 并有新标签 `dsh-0-2-1-alpha-1`=4.0.5-alpha.1；`@deepseek-ai/schemastery` `latest`=3.18.4；`create-dsh-plugin` `latest`=0.2.3；dsh-core、dsh-sdk 仍 404。历史两次复核（2026-08-14 与 09-04）的数值保留在上一条记录里，可见"`latest` 陷阱"从 rc 早期持续到 0.2 世代。**无作用域 `dsh` 包是无关项目 node-dsh**（"A shell written in JavaScript"）——官方 CLI 包是 `@deepseek-ai/dsh`，别装错。
+- **npm `latest` 标签是过期版本**：库包（`dsh-tools`、`dsh-base`、`dsh-headless`、`dsh-session-persistence-jsonl`、`dsh-settings`、`dsh-workflow` …）的 `latest` **至今**钉在 `0.0.1-rc.1`，所以写 `"latest"` 会装到远古版本，必须写死版本或钉 `next`/`alpha`。**2026-11-14 复核**：`@deepseek-ai/dsh` `latest`=`0.2.2-rc.1`、`next`=`0.2.2-rc.3`、`alpha`=`0.2.2-alpha.3`；dsh-tools / dsh-base / dsh-headless / dsh-session-persistence-jsonl 的 `latest` 仍 `0.0.1-rc.1`、`next`=`0.2.2-rc.3`、`alpha`=`0.2.2-alpha.3`；`@deepseek-ai/cordis` `latest`=4.1.0（DSH 0.2.2-rc.3 vendor 的 wrapper；上游基线 4.0.0-rc.11）；`@deepseek-ai/schemastery` `latest`=3.18.4；`create-dsh-plugin` `latest`=0.2.3；dsh-core、dsh-sdk 仍 404。历史两次复核（2026-08-14 与 09-04）的数值保留在上一条记录里，可见"`latest` 陷阱"从 rc 早期持续到 0.2 世代。**无作用域 `dsh` 包是无关项目 node-dsh**（"A shell written in JavaScript"）——官方 CLI 包是 `@deepseek-ai/dsh`，别装错。
 - **profile 内安装的 `@deepseek-ai/*` 会静默遮蔽运行时自带版本**（解析优先级 `profile > runtime`）：把共享实例的 dsh 包写进 **dependencies** 是错的做法——pnpm 会把它装进 profile，盖掉宿主自带的版本，然后核心服务注册失败（实测 `settings service is absent: mount @deepseek-ai/dsh-settings with @deepseek-ai/dsh-config-editor`，桌面端每次崩溃）。**共享实例的 dsh 包只放 `peerDependencies` + `devDependencies`**；独立版本演进或纯工具型包才放 `dependencies`。
-- ⚠️ **peer 范围会被安装期强制**（本节早期版本写成"DSH 不校验 peer 版本范围"，**已更正**）：`dsh plugin add` 用运行时版本比对插件声明的 `@deepseek-ai/dsh-*` 范围，不匹配即**拒绝安装**，打印声明的范围并给出豁免命令。实测原文：
+- ⚠️ **兼容性门禁是强制的，且 `engines.dsh` 优先**（本节早期版本写成"DSH 不校验 peer 版本范围"，**已更正**）：清单**有 `engines.dsh`** 时该范围**单独决定**、`@deepseek-ai/dsh*` peers 被忽略；**没有**时才回退到 peer 规则。`dsh plugin add` 用运行时版本比对生效范围，不匹配即**拒绝安装**，打印范围并给出豁免命令。实测原文（peer 回退分支）：
 
   ```
   dsh: installation rejected: Plugin dsh-nurse-record-check@0.1.0 is incompatible with
@@ -605,7 +605,7 @@ bundle 挂一个普通 provider 插件：`inject = ['cmdlineArgs']`，用 `@deep
 
 ## 9.1 版本兼容与迁移（0.2 世代必读）
 
-- **先认版本**：`dsh --version`，然后读 [version-matrix.md](version-matrix.md)（版本适配矩阵：五个"最新"的区分、子包 `latest` 冻结陷阱、破坏性变更断层、peer 区间选择、会话格式谱系）。`0.1.7-alpha.1` 起包含本世代全部破坏性变更（会话格式 V4）。npm 上 `latest`=`next`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.2`，而 master 最新 tag 是 `dsh-v0.2.1-alpha.2`——**这四个"最新"不是同一个东西**；**不存在稳定版**（全部 31 个 npm 版本都是 prerelease）。
+- **先认版本**：`dsh --version`，然后读 [version-matrix.md](version-matrix.md)（版本适配矩阵：几个"最新"的区分、子包 `latest` 冻结陷阱、破坏性变更断层、peer/engines 区间选择、会话格式谱系）。`0.1.7-alpha.1` 起包含本世代全部破坏性变更（会话格式 V4）。npm 上 `latest`=`0.2.2-rc.1`、`next`=`0.2.2-rc.3`、`alpha`=`0.2.2-alpha.3`，最新 tag 是 `dsh-v0.2.2-rc.3`——**这几个"最新"不是同一个东西**；**不存在稳定版**（全部 44 个 npm 版本与 39 个 GitHub Release 都是 prerelease）。
 - **peer 范围要写全两侧的 prerelease 元组**（如 `>=0.1.2-rc.1 <0.2.0 || … || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0`）。⚠️ **这个范围会被安装期强制**，不是文档意图：`dsh plugin add` 用运行时版本比对它，不匹配就拒绝安装并打印你声明的范围。所以少一个 0.2.x clause，插件在 0.2.x 宿主上**根本装不上**（拦在安装期，不是运行期）。范围之外仍要靠运行时特性探测——范围只表达"能不能装"，表达不了"某个 API 在不在"。
 - **共享实例的 dsh 包只放 peer + dev**，绝不放 dependencies（否则 profile 内副本会遮蔽运行时版本）。
 - **升级后必做**：`dsh --profile <name> --dump-config` 看有没有 `patch: entry <id> not found`（上游删行/改名后，你的 override 会**静默失效**）；再跑一次真实能力。

package/guide/quick-reference.es.md

@@ -137,7 +137,7 @@ Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloque com
 3. **El mecanismo más débil que baste**: `ctx.tools.restrict()` (solo quita) < `ctx.tools.guard()` (solo deniega) < reescritura por waterfall (depende del orden) < `system-prompt/assemble` (reemplaza todo). Observa resultados finales en `tools/result`; usa `tools/post-execute` solo para transformar.
 4. Visible-para-el-modelo ⇔ registrado: una nueva entrada visible requiere un nuevo evento de sesión (`SessionEventMap`) — **lo añade el host**, no tú (ver regla 10).
 5. Nunca codifiques valores ajustables (prueba: ¿puede cambiarlos cordis.yml?); la mala configuración falla en voz alta. Los campos editables en vivo usan `Volatile<T>` + `loader/volatile-update` (el namespace del formulario es el id de la entrada del perfil).
-6. Paquetes de plugin independientes: cordis es peerDependency con la misma identidad del host (mezclar scoped `@deepseek-ai/cordis` y unscoped divide identidades); ESM; manifiesto `dsh.bundle` (`patch` puede ser una lista ordenada); instalaciones git necesitan `prepare` + `allowBuilds`; publica `lib/` o un tarball. Los paquetes dsh de instancia compartida van **solo en peerDependencies + devDependencies**, nunca en `dependencies` (una copia en el perfil ensombrece el runtime en silencio). ⚠️ Corregido: **los rangos de peers SÍ se aplican al instalar** — `dsh plugin add` compara la versión del runtime con el rango declarado de `@deepseek-ai/dsh-*` y rechaza la instalación; solo `engines.dsh` es declarativo y no se aplica. Un rango indica "se puede instalar", no "esta API existe": mantén la sonda en runtime (selección de rango: `version-matrix.md` §4).
+6. Paquetes de plugin independientes: cordis es peerDependency con la misma identidad del host (mezclar scoped `@deepseek-ai/cordis` y unscoped divide identidades); ESM; manifiesto `dsh.bundle` (`patch` puede ser una lista ordenada); instalaciones git necesitan `prepare` + `allowBuilds`; publica `lib/` o un tarball. Los paquetes dsh de instancia compartida van **solo en peerDependencies + devDependencies**, nunca en `dependencies` (una copia en el perfil ensombrece el runtime en silencio). ⚠️ Corregido: **la puerta de compatibilidad se aplica al instalar/arrancar y `engines.dsh` decide solo** — si el manifiesto declara `engines.dsh`, ese rango decide y los peers `@deepseek-ai/dsh*` se ignoran; los peers solo son el respaldo cuando falta (`includePrerelease: true`, así que el límite inferior debe incluir el prerelease, p. ej. `>=0.2.2-0`; `workspace:` no es válido en `engines.dsh`). Un rango dice "se puede instalar", no "esta API existe": mantén la sonda en runtime (selección de rango: `version-matrix.md` §4; regla oficial: `docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md`).
 7. Publica metadatos de presentación: `locale/*.json` con `meta.title`/`meta.description` y un `./icon` exportado (SVG/PNG/JPEG/WebP, ≤256 KiB, dentro del paquete). Los plugins de subruta **nunca** leen su propio `package.json`.
 8. Documentación bilingüe en pares; descripciones/prompts son comportamiento; cambios no triviales llevan Agent Note; ejecuta el conjunto mínimo de checks antes de empujar (dsh-pre-push-checks).
 9. Los ids opacos entre límites son branded (`Branded<B>` de `dsh-brand`), nunca `string` pelado.
@@ -154,7 +154,7 @@ Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloque com
 - Junctions de Windows con PowerShell `New-Item -ItemType Junction`; la letra de unidad de vitest en mayúscula `C:/`.
 - `DSH_PERMISSION_MODE=danger-full-access` es de alto riesgo (sin backend de sandbox en Windows, aprobaciones desactivadas); `DSH_*` en `~/.dsh/.env` rompe el arranque.
 - Los archivos de sesión son zstd multiframe: usa `scanZstdFrames`/`createZstdFrameDecoder` (`@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts`).
-- npm: `dsh` sin alcance es el proyecto ajeno node-dsh (un shell) — instala `@deepseek-ai/dsh` (latest=0.1.2-rc.1); `@deepseek-ai/dsh-tools` y `@deepseek-ai/dsh-session-persistence-jsonl` tienen `latest` obsoleto (0.0.1-rc.1), fija `next` (0.1.2-rc.1); `create-dsh-plugin` latest=0.2.1; dsh-core/dsh-sdk siguen sin publicarse (verificado 2026-09-04).
+- npm: `dsh` sin alcance es el proyecto ajeno node-dsh (un shell) — instala `@deepseek-ai/dsh` (`latest`=`0.2.2-rc.1`, `next`=`0.2.2-rc.3`, `alpha`=`0.2.2-alpha.3`); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` y `@deepseek-ai/dsh-session-persistence-jsonl` aún publican un `latest` obsoleto (0.0.1-rc.1), fija `next` (`0.2.2-rc.3`) o `alpha` (`0.2.2-alpha.3`); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.1.0 (el wrapper que vendoriza DSH 0.2.2-rc.3; base upstream 4.0.0-rc.11); dsh-core/dsh-sdk siguen sin publicarse (verificado 2026-11-14).
 - Haz `resolve()` en ambos lados antes de comparar rutas (trampa de barras invertidas de Windows).
 
 ## Enlaces de documentación
@@ -172,7 +172,7 @@ Documentación comunitaria de desarrollo — plantillas/tutoriales/errores, list
 
 ## Índice de fuentes clave
 
-- Documentación oficial textual: `references/official-docs/docs/**` (717 páginas, incluye 356 pares `.zh.md`; espejo en `dsh-v0.2.2-rc.2`)
+- Documentación oficial textual: `references/official-docs/docs/**` (709 páginas, incluye 352 pares `.zh.md`; espejo fijado en la etiqueta `dsh-v0.2.2-rc.3`, commit `38a6a5c9…`)
 - Restricciones raíz del repo: `references/official-docs/AGENTS.md`, `references/official-docs/packages/AGENTS.md`, `references/official-docs/vendor/README.md`; estado de sincronización en `references/official-docs/SNAPSHOT.md`
 - HTML del sitio: `downloads/web/site/**` (sitio completo EN+ZH) + `downloads/manifest.tsv`
 - Cordis upstream: `downloads/github/cordis/**` + investigación `references/upstream-cordis.md`
@@ -182,4 +182,4 @@ Documentación comunitaria de desarrollo — plantillas/tutoriales/errores, list
 - Comunidad/ecosistema: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
 - Todas las URLs de fuentes: `references/sources.md`
 - [Matriz de versiones](version-matrix.md) — los cuatro valores «latest», etiquetas `latest` congeladas, fallas de compatibilidad y selección de rango de peers.
-- [Lista de migración](migration-0.2.md) — §0–§12 cubren los cambios que rompen compatibilidad, **§13 los 19 seams de `0.2.1-alpha.2`**.
+- [Lista de migración](migration-0.2.md) — §0–§12 cubren todos los cambios incompatibles de `0.1.6-alpha.2` → `0.2.1-alpha.1`, §13 cubre `0.2.1-alpha.2` como 19 seams citables (`L1`–`L19`) y §14 cubre los 46 seams de la línea 0.2.2 incluidos en la etiqueta rc.3 (`K1`–`K46`) más los 13 de la próxima versión aparte.

package/guide/quick-reference.hi.md

@@ -137,7 +137,7 @@ Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(
 3. **जो सबसे कमज़ोर mechanism काम करे वही लें**: `ctx.tools.restrict()` (केवल हटाता है) < `ctx.tools.guard()` (केवल मना करता है) < waterfall rewrite (क्रम पर निर्भर) < `system-prompt/assemble` (सब बदल देता है)। अंतिम परिणाम `tools/result` पर देखें; बदलने के लिए ही `tools/post-execute` लें।
 4. मॉडल-दृश्य ⇔ लॉग: नई मॉडल-दृश्य इनपुट के लिए नया सत्र इवेंट चाहिए (`SessionEventMap`) — **होस्ट जोड़ता है**, आप नहीं (नियम 10 देखें)।
 5. समायोज्य मान कभी हार्डकोड न करें (कसौटी: क्या cordis.yml इसे बदल सकता है?); गलत कॉन्फ़िग ज़ोर से विफल हो। लाइव-संपादन योग्य फ़ील्ड `Volatile<T>` + `loader/volatile-update` से (फ़ॉर्म namespace = profile entry id)।
-6. स्वतंत्र प्लगइन पैकेज: cordis peerDependency है और होस्ट पहचान से मेल खाना चाहिए (scoped `@deepseek-ai/cordis` और unscoped मिलाना पहचान बाँट देता है); ESM; `dsh.bundle` मैनिफ़ेस्ट (`patch` क्रमबद्ध array हो सकता है); git इंस्टॉल को `prepare` + `allowBuilds` चाहिए; `lib/` या tarball प्रकाशित करें। साझा-इंस्टेंस वाले dsh पैकेज **केवल peerDependencies + devDependencies** में रखें, `dependencies` में कभी नहीं (profile की प्रति runtime को चुपचाप ढक देती है)। ⚠️ सुधार: **peer रेंज इंस्टॉल के समय लागू होती है** — `dsh plugin add` runtime संस्करण की तुलना घोषित `@deepseek-ai/dsh-*` रेंज से करता है और इंस्टॉल अस्वीकार कर देता है; केवल `engines.dsh` घोषणात्मक है और लागू नहीं होता। रेंज बताती है "इंस्टॉल हो सकता है", यह नहीं कि "यह API मौजूद है" — runtime probing रखें (रेंज चयन: `version-matrix.md` §4)।
+6. स्वतंत्र प्लगइन पैकेज: cordis peerDependency है और होस्ट पहचान से मेल खाना चाहिए (scoped `@deepseek-ai/cordis` और unscoped मिलाना पहचान बाँट देता है); ESM; `dsh.bundle` मैनिफ़ेस्ट (`patch` क्रमबद्ध array हो सकता है); git इंस्टॉल को `prepare` + `allowBuilds` चाहिए; `lib/` या tarball प्रकाशित करें। साझा-इंस्टेंस वाले dsh पैकेज **केवल peerDependencies + devDependencies** में रखें, `dependencies` में कभी नहीं (profile की प्रति runtime को चुपचाप ढक देती है)। ⚠️ सुधार: **संगतता द्वार इंस्टॉल/स्टार्टअप पर लागू होता है और `engines.dsh` अकेले निर्णय करता है** — यदि मैनिफ़ेस्ट में `engines.dsh` है तो वही रेंज निर्णय देती है और `@deepseek-ai/dsh*` peers अनदेखे रहते हैं; peers केवल तब fallback हैं जब वह अनुपस्थित हो (`includePrerelease: true`, इसलिए निचली सीमा में prerelease चाहिए, जैसे `>=0.2.2-0`; `engines.dsh` में `workspace:` अमान्य है)। रेंज बताती है "इंस्टॉल हो सकता है", यह नहीं कि "यह API मौजूद है" — runtime probing रखें (रेंज चयन: `version-matrix.md` §4; आधिकारिक नियम: `docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md`)।
 7. प्रदर्शन मेटाडेटा ज़रूर भेजें: `locale/*.json` में `meta.title`/`meta.description` और export किया हुआ `./icon` (SVG/PNG/JPEG/WebP, ≤256 KiB, पैकेज के भीतर)। subpath प्लगइन अपना `package.json` **कभी नहीं** पढ़ते।
 8. दस्तावेज़ द्विभाषी जोड़ों में; टूल विवरण/प्रॉम्प्ट ही व्यवहार हैं; गैर-तुच्छ बदलाव में Agent Note चाहिए; पुश से पहले न्यूनतम जाँच सेट चलाएँ (dsh-pre-push-checks)।
 9. सीमाओं के पार अपारदर्शी ids branded होते हैं (`Branded<B>` from `dsh-brand`), कभी भी नंगे `string` नहीं।
@@ -154,7 +154,7 @@ Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(
 - Windows junctions PowerShell `New-Item -ItemType Junction` से; vitest ड्राइव अक्षर बड़ा `C:/`।
 - `DSH_PERMISSION_MODE=danger-full-access` उच्च जोखिम है (Windows पर सैंडबॉक्स बैकएंड नहीं, अनुमोदन बंद); `~/.dsh/.env` में `DSH_*` स्टार्टअप तोड़ता है।
 - सत्र फ़ाइलें मल्टी-फ़्रेम 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.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 को सत्यापित)।
+- npm: बिना स्कोप वाला `dsh` असंबंधित node-dsh प्रोजेक्ट (एक shell) है — `@deepseek-ai/dsh` इंस्टॉल करें (`latest`=`0.2.2-rc.1`, `next`=`0.2.2-rc.3`, `alpha`=`0.2.2-alpha.3`); `@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.2-rc.3`) या `alpha` (`0.2.2-alpha.3`) पिन करें; `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.1.0 (DSH 0.2.2-rc.3 द्वारा vendor किया गया wrapper; upstream आधार 4.0.0-rc.11); dsh-core/dsh-sdk अभी भी अप्रकाशित (2026-11-14 को सत्यापित)।
 - पथ तुलना से पहले दोनों ओर `resolve()` करें (Windows बैकस्लैश जाल)।
 
 ## दस्तावेज़ लिंक
@@ -172,7 +172,7 @@ Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(
 
 ## मुख्य स्रोत सूची
 
-- आधिकारिक दस्तावेज़ हूबहू: `references/official-docs/docs/**` (717 पृष्ठ, 356 `.zh.md` जोड़े सहित; मिरर `dsh-v0.2.2-rc.2` पर)
+- आधिकारिक दस्तावेज़ हूबहू: `references/official-docs/docs/**` (709 पृष्ठ, 352 `.zh.md` जोड़े सहित; मिरर रिलीज़ टैग `dsh-v0.2.2-rc.3`, commit `38a6a5c9…` पर पिन)
 - रिपो-रूट बाधाएँ: `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/**` (EN+ZH पूर्ण साइट) + `downloads/manifest.tsv`
 - अपस्ट्रीम Cordis: `downloads/github/cordis/**` + शोध `references/upstream-cordis.md`
@@ -182,4 +182,4 @@ Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(
 - समुदाय/पारिस्थितिकी: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
 - सभी स्रोत URL: `references/sources.md`
 - [संस्करण मैट्रिक्स](version-matrix.md) — चार "latest" मान, जमे हुए `latest` टैग, संगतता-भंग बिंदु और peer रेंज का चयन।
-- [माइग्रेशन सूची](migration-0.2.md) — §0–§12 संगतता-भंग बदलाव, **§13 में `0.2.1-alpha.2` के 19 seams**।
+- [माइग्रेशन सूची](migration-0.2.md) — §0–§12 `0.1.6-alpha.2` → `0.2.1-alpha.1` के सभी असंगत बदलाव, §13 `0.2.1-alpha.2` के 19 उद्धरण-योग्य seam (`L1`–`L19`), और §14 rc.3 टैग में शामिल 0.2.2 लाइन के 46 seam (`K1`–`K46`) तथा अगली पीढ़ी के 13 अलग से।

package/guide/quick-reference.md

@@ -137,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). ⚠️ 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).
+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: **the compatibility gate is enforced at install/startup, and `engines.dsh` decides alone** — when the manifest declares `engines.dsh`, that range decides and `@deepseek-ai/dsh*` peers are ignored; peers are only the fallback when it is absent (`includePrerelease: true`, so the lower bound must carry the prerelease, e.g. `>=0.2.2-0`; `workspace:` is invalid in `engines.dsh`). A range says "can it install", not "does this API exist" — keep runtime probing (range selection: `version-matrix.md` §4; official rule: `docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md`).
 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`.
@@ -154,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.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).
+- npm: unscoped `dsh` is the unrelated node-dsh shell — install `@deepseek-ai/dsh` (`latest`=`0.2.2-rc.1`, `next`=`0.2.2-rc.3`, `alpha`=`0.2.2-alpha.3`); `@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.2-rc.3`) or `alpha` (`0.2.2-alpha.3`); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.1.0 (the wrapper DSH 0.2.2-rc.3 vendors; upstream baseline 4.0.0-rc.11); dsh-core/dsh-sdk still unpublished (verified 2026-11-14).
 - `resolve()` both sides before path comparisons (Windows backslash trap).
 
 ## Documentation links
@@ -172,8 +172,8 @@ Community dev docs — templates/tutorials/pitfalls, full list in [references/co
 
 ## Key source index
 
-- Official docs verbatim: `references/official-docs/docs/**` (717 md pages, all 356 `.zh.md` pairs included, mirror at `dsh-v0.2.2-rc.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
+- Official docs verbatim: `references/official-docs/docs/**` (709 md pages, all 352 `.zh.md` pairs included, mirror pinned to the release tag `dsh-v0.2.2-rc.3`, commit `38a6a5c9…`); 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`, §13 covers `0.2.1-alpha.1` → `0.2.1-alpha.2` as 19 citable seams (`L1`–`L19`), and §14 covers the 46 seams of the 0.2.2 line shipped in the rc.3 tag (`K1`–`K46`) plus the 13 next-version guides listed separately; 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

@@ -137,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). ⚠️ 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).
+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: **a porta de compatibilidade é aplicada na instalação/arranque e `engines.dsh` decide sozinho** — quando o manifesto declara `engines.dsh`, essa faixa decide e os peers `@deepseek-ai/dsh*` são ignorados; os peers só são o fallback quando ela falta (`includePrerelease: true`, então o limite inferior precisa incluir o prerelease, p. ex. `>=0.2.2-0`; `workspace:` é inválido em `engines.dsh`). Uma faixa diz "dá para instalar", não "esta API existe": mantenha a sondagem em runtime (escolha de faixa: `version-matrix.md` §4; regra oficial: `docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md`).
 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.
@@ -154,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.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).
+- npm: o `dsh` sem escopo é o projeto alheio node-dsh (um shell) — instale `@deepseek-ai/dsh` (`latest`=`0.2.2-rc.1`, `next`=`0.2.2-rc.3`, `alpha`=`0.2.2-alpha.3`); `@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.2-rc.3`) ou `alpha` (`0.2.2-alpha.3`); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.1.0 (o wrapper que o DSH 0.2.2-rc.3 vendoriza; base upstream 4.0.0-rc.11); dsh-core/dsh-sdk seguem não publicados (verificado em 2026-11-14).
 - Aplique `resolve()` nos dois lados antes de comparar caminhos (armadilha da barra invertida do Windows).
 
 ## Links de documentação
@@ -172,7 +172,7 @@ Documentação comunitária de desenvolvimento — modelos/tutoriais/armadilhas,
 
 ## Índice de fontes principais
 
-- Documentação oficial textual: `references/official-docs/docs/**` (717 páginas, inclui 356 pares `.zh.md`; espelho em `dsh-v0.2.2-rc.2`)
+- Documentação oficial textual: `references/official-docs/docs/**` (709 páginas, inclui 352 pares `.zh.md`; espelho fixado na tag `dsh-v0.2.2-rc.3`, commit `38a6a5c9…`)
 - Restrições da raiz do repo: `references/official-docs/AGENTS.md`, `references/official-docs/packages/AGENTS.md`, `references/official-docs/vendor/README.md`; estado de sincronização em `references/official-docs/SNAPSHOT.md`
 - HTML do site: `downloads/web/site/**` (site completo EN+ZH) + `downloads/manifest.tsv`
 - Cordis upstream: `downloads/github/cordis/**` + pesquisa `references/upstream-cordis.md`
@@ -182,4 +182,4 @@ Documentação comunitária de desenvolvimento — modelos/tutoriais/armadilhas,
 - Comunidade/ecossistema: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
 - Todas as URLs de fontes: `references/sources.md`
 - [Matriz de versões](version-matrix.md) — os quatro valores "latest", tags `latest` congeladas, falhas de compatibilidade e seleção de intervalo de peers.
-- [Lista de migração](migration-0.2.md) — §0–§12 cobrem as mudanças que quebram compatibilidade, **§13 os 19 seams de `0.2.1-alpha.2`**.
+- [Lista de migração](migration-0.2.md) — §0–§12 cobrem as mudanças incompatíveis de `0.1.6-alpha.2` → `0.2.1-alpha.1`, §13 cobre `0.2.1-alpha.2` como 19 seams citáveis (`L1`–`L19`) e §14 cobre os 46 seams da linha 0.2.2 incluídos na tag rc.3 (`K1`–`K46`) mais os 13 da próxima versão em separado.