dsh-primer 0.4.4 → 0.4.6

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/**` (215 पृष्ठ, `.zh.md` जोड़े सहित)
+- आधिकारिक दस्तावेज़ हूबहू: `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/**` (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
+- 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/**` (215 páginas, inclui pares `.zh.md`)
+- 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.

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

@@ -136,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 内副本会静默遮蔽运行时）。⚠️ **已更正：peer 范围会被安装期强制**——`dsh plugin add` 拿运行时版本比对声明的 `@deepseek-ai/dsh-*` 范围，不匹配即**拒绝安装**；只有 `engines.dsh` 是纯声明、零强制。范围只能表达"能不能装"，**表达不了某个 API 在不在**——仍要配运行时探测（区间选择见 `version-matrix.md` §4）。
+6. 独立插件包：cordis 是 peerDependency（与宿主同身份：scoped `@deepseek-ai/cordis` 与 unscoped 混用会"双 Cordis 分裂"）；ESM；`dsh.bundle` 清单（`patch` **可为有序数组**）；git 安装配 `prepare` + `allowBuilds`；发布带 `lib/` 或 tarball。**共享实例的 dsh 包只放 peer + dev，绝不放 dependencies**（profile 内副本会静默遮蔽运行时）。⚠️ **已更正：兼容性门禁在安装/启动期强制，且 `engines.dsh` 单独决定**——**有 `engines.dsh` 时该范围单独决定并忽略 `@deepseek-ai/dsh*` peers**，只有缺失时才回退到 peer 范围（`includePrerelease: true`，下界必须带预发布，如 `>=0.2.2-0`；`workspace:` 在 `engines.dsh` 中不合法）。范围只能表达"能不能装"，**表达不了某个 API 在不在**——仍要配运行时探测（区间选择见 `version-matrix.md` §4，官方语义见 `docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md`）。
 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`。
@@ -153,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.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 vendored 的 wrapper；上游基线 4.0.0-rc.11）；dsh-core/dsh-sdk 仍未发布（2026-11-14 复核）。
 - 路径比较前两侧都 `resolve()`（Windows 反斜杠陷阱）。
 
 ## 文档链接
@@ -171,8 +171,8 @@ Chunk 协议：`block-start` → `text-delta*` → `block-end`（完整块）→
 
 ## 关键源索引
 
-- 本地官方文档全文：`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-docs/docs/**`（709 篇，含全部 352 个 `.zh.md`；镜像钉在发布 tag `dsh-v0.2.2-rc.3`，commit `38a6a5c9…`）；**没上文档站**的那些页（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`）**，**§14 是 rc.3 包内 0.2.2 线的 46 个 seam（`K1`–`K46`）**，另单列下一版 13 条；每条都附官方 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/standards.md

@@ -70,7 +70,7 @@ G0–G2 and G4 pass in static inspection, which supports `recognized`; `runtime`
 
 **What it does not claim.** Security, UI correctness, production readiness, full feature correctness, official endorsement, or that the plugin will work on an untested DSH line.
 
-**How to self-check.** Record `dsh --version`, the host commit, and the artifact mtime. Run `dsh-plugin-dev check --json` for the 16 local static checks (a subset of `dsh-plugin-doctor`'s 33 — see [family-toolchain.md](family-toolchain.md)), then the standards repo's entry checker (commands below). For bundles, also run `dsh --profile <name> --dump-config` and look for `patch: entry <id> not found`, then boot and read the row states. Write the claim as `DSH-ENTRY: runtime (dsh 0.2.2-alpha.3, commit <sha>, 2026-11-04); Node >=24.9`.
+**How to self-check.** Record `dsh --version`, the host commit, and the artifact mtime. Run `dsh-plugin-dev check --json` for the 16 local static checks (a subset of `dsh-plugin-doctor`'s 33 — see [family-toolchain.md](family-toolchain.md)), then the standards repo's entry checker (commands below). For bundles, also run `dsh --profile <name> --dump-config` and look for `patch: entry <id> not found`, then boot and read the row states. Write the claim as `DSH-ENTRY: runtime (dsh 0.2.2-rc.3, commit <sha>, 2026-11-14); Node >=24.9`.
 
 ## DSH-FLOW: adoption experience
 

package/guide/standards.zh-CN.md

@@ -70,7 +70,7 @@ G0–G2 与 G4 在静态检查里通过，支持 `recognized`；`runtime` 需要
 
 **不声称什么。** 不声称安全、UI 正确、生产可用、功能完整、官方背书，也不声称在未测过的 DSH 线上可用。
 
-**怎么自检。** 记录 `dsh --version`、宿主 commit、产物 mtime。先跑 `dsh-plugin-dev check --json` 的 16 项本地静态检查（它是 `dsh-plugin-doctor` 33 项的子集，见 [family-toolchain.md](family-toolchain.md)）；再跑标准仓的 entry 检查器（命令见下）。bundle 还要跑 `dsh --profile <name> --dump-config`，确认没有 `patch: entry <id> not found`，然后真实 boot 并读行状态。声明写成 `DSH-ENTRY: runtime (dsh 0.2.1-rc.2, commit <sha>, 2026-11-01)`。
+**怎么自检。** 记录 `dsh --version`、宿主 commit、产物 mtime。先跑 `dsh-plugin-dev check --json` 的 16 项本地静态检查（它是 `dsh-plugin-doctor` 33 项的子集，见 [family-toolchain.md](family-toolchain.md)）；再跑标准仓的 entry 检查器（命令见下）。bundle 还要跑 `dsh --profile <name> --dump-config`，确认没有 `patch: entry <id> not found`，然后真实 boot 并读行状态。声明写成 `DSH-ENTRY: runtime (dsh 0.2.2-rc.3, commit <sha>, 2026-11-14); Node >=24.9`。
 
 ## DSH-FLOW：采用体验
 

package/guide/unfixed-issues.md

@@ -10,11 +10,11 @@
 > - **复核基线 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`）**——
-> 也就是说**镜像比本表新一版**。二者不是矛盾，是两个不同用途的基线：
+> 本库的官方文档镜像已在 **2026-11-14 按发布 tag 重同步到 `38a6a5c965aa99ab525161efb7cc5cf1fe62fced`（`dsh-v0.2.2-rc.3`）**——
+> 也就是说**镜像已远新于本表**。二者不是矛盾，是两个不同用途的基线：
 > 镜像求"与上游逐字节一致"，本表求"每条结论有可复核的行号锚点"。
 > **在 `5badb15` 上复核行号**（`git -C <checkout> show 5badb15:<path>`），或用镜像里的路径但**预期行号可能已漂移**。
-> 下一轮全表重核的目标基线是 `d743267`；在重核完成前，请把"未修复"读作"**截至 2026-10-03 未修复**"。
+> 下一轮全表重核的目标基线是 `38a6a5c9`（rc.3）；在重核完成前，请把"未修复"读作"**截至 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

@@ -3,9 +3,9 @@
 > **这份文件回答一个问题**：我的插件要跑在哪个 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。
+> **测量时间**：2026-11-14（官方版本线 = `0.2.2-rc.3`；镜像与计数同日重核）。
+> **数据来源**：npm registry `@deepseek-ai/dsh` 的 dist-tags 与版本清单、GitHub REST API（tags/releases）、
+> 官方 `docs/upgrade-guide/**`（镜像已钉发布 tag `dsh-v0.2.2-rc.3`）、官方 `docs/persistence-changes/**`。逐条可复现命令见 §7。
 >
 > **口径**：本文件只写**有出处**的数字。取不到的一律写 `未核`，不写推测值。
 > 官方说法与社区实测冲突时分别标注。
@@ -16,42 +16,44 @@
 
 这是插件作者**第一个**要做的判断。五个数可以不相等，而 peer 范围按线分叉：
 
-| # | 说法 | 值（2026-10-09） | 怎么查 | 性质 |
+| # | 说法 | 值（2026-11-14） | 怎么查 | 性质 |
 |---|---|---|---|---|
-| 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 | npm `latest` | `0.2.2-rc.1` | `npm view @deepseek-ai/dsh dist-tags` | 默认装的就是这个；**它已不是最新** |
+| 2 | npm `next` | `0.2.2-rc.3` | 同上 | 最新发布（本机 CLI 即此版本） |
+| 3 | npm `alpha` | `0.2.2-alpha.3` | 同上 | alpha 通道最新 |
+| 4 | 最新 tag | `dsh-v0.2.2-rc.3`（`38a6a5c9…`，2026-11-13） | GitHub `/tags`、`/releases` | 源码线的名字；master 已合并 rc.3 发布 |
+| 5 | **本机实际** | `0.2.2-rc.3`（本库核验机） | `dsh --version` | **唯一真正要紧的数** |
 
 ### 1.1 没有"稳定版"这回事
 
-- **全部 31 个 npm 版本都带 `-alpha.N` / `-rc.N` 后缀；全部 26 个 GitHub Release 都是 `prerelease: true`。**
+- **全部 44 个 npm 版本都带 `-alpha.N` / `-rc.N` 后缀；全部 39 个 GitHub Release 都是 `prerelease: true`。** 另有 40 个 tag，比 release 多 1 个——`dsh-v0.1.5-rc.3` 有 tag 无 release。
 - 所以 npm 的 `latest` 标签在这里**不代表稳定**——它只是"默认安装会拿到的那一个"。
-- 给作者的有效读法：**最新 = `0.2.1-alpha.2`（npm `alpha`）；默认安装 = `0.2.0-rc.2`（npm `latest`/`next`）**。
+- 给作者的有效读法（2026-11-14）：**默认安装 = `0.2.2-rc.1`（npm `latest`）；最新发布 = `0.2.2-rc.3`（npm `next`，也是最新 tag `dsh-v0.2.2-rc.3`）；alpha 通道 = `0.2.2-alpha.3`**。注意 `latest` 与 `next` **已不再相等**：`latest` 落后 `next` 两个 prerelease（`rc.1` vs `rc.3`），0.2.1 时代两者同值。
 - 官方 `CONTRIBUTING.md` 明确**不接受外部 PR**，`AGENTS.md` 声明 API 处于 pre-stable。
   插件作者无法"等它稳定"，只能**钉版本 + 声明区间**。
 
 ### 1.2 ★ 陷阱：子包的 `latest` 是冻住的
 
 主包 `@deepseek-ai/dsh` 每次发版都会重发全部子包到 `alpha`/`next`，但**每个子包的 `latest`
-标签停在它第一次被设置的那个版本，永不前进**。裸装子包会装到远古版本：
+标签停在它第一次被设置的那个版本，永不前进**。裸装子包会装到远古版本（2026-11-14 实测）：
 
 | 包 | `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` |
+| `@deepseek-ai/dsh` | `0.2.2-rc.1`（主包 latest 已前进，但仍**不是最新**） | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-base` | **`0.0.1-rc.1`** | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-session` | **`0.0.1-rc.1`** | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-tools` | **`0.0.1-rc.1`** | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-subagent` | **`0.0.1-rc.1`** | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-home-paths` | `0.0.1-rc.3` | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-client-ui-primitives` | **`0.0.1-rc.1`** | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-agent` | `0.1.0-rc.6` | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-typert-protocol` | `0.1.0-rc.6` | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-package-manifest` | `0.1.3-alpha.2` | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-plugin-manager` | `0.1.6-alpha.2` | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-experimental-ptc-runtime-python` | `0.1.6-alpha.1` | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+| `@deepseek-ai/dsh-otel` | `0.2.0-rc.1` | `0.2.2-rc.3` | `0.2.2-alpha.3` |
+
+**结论三条**（不变）：1) 子包 `latest` 继续冻在远古版本，绝不裸装；2) 判断宿主代次只认 `dsh --version`；3) 共享实例的 dsh 包只放 peer + dev，区间按 §4 选。
 
 **结论三条**：
 
@@ -72,10 +74,15 @@
 | 断层 | 引入版本（目录名） | 落到哪一版 | 影响面 |
 |---|---|---|---|
 | **即插即拔基础设施** | `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`，模块永不导入 |
+| **peer/`engines.dsh` 兼容性门禁** | `0.1.7-rc.1`（peer）→ `0.2.1-alpha.4`（engines 优先） | 同版 | 不匹配的行被直接 `disabled`，模块永不导入；**有 `engines.dsh` 时它单独决定并忽略 peers**，无它才回退 peers（见 §4） |
 | **会话格式 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.2.1-alpha.2 大批变更** | `0.2.1-alpha.1` | `0.2.1-alpha.2` | **19 条**破坏性变更（见 §3，`L1`–`L19`） |
+| **0.2.2-alpha.2 批次** | `0.2.2-alpha.2` | `0.2.2-alpha.3` | **22 条**（`K1`–`K22`：context menu 类型、CSS 锚定菜单、loader entry tree、projection/LLM/schedule/search 等） |
+| **0.2.2-alpha.3 批次** | `0.2.2-alpha.3` | `0.2.2-rc.1` | **5 条**（`K23`–`K27`：`office-kit` 替换 `office-to-pdf`、Office 工具化、subagent 按名寻址等） |
+| **0.2.2-rc.1 批次** | `0.2.2-rc.1` | `0.2.2-rc.2` | **19 条**（`K28`–`K46`：`dsh-doc-skill`、`plugin-update-method`、`session-append-overloads`、`window-drag-regions`、`attachment-error-codes` 等） |
+
+**rc.3 自身没有新增迁移指南**：rc.3 tag 的 `docs/upgrade-guide` 到 `v0.2.2-rc.1` 为止，上面三批合计 46 条就是 rc.3 发布包覆盖的全部 0.2.2 线变更（逐条 ID/症状/修法见 [migration-0.2.md](migration-0.2.md) §14）。rc.3 的发布内容只有**加性**实验能力（见 §6.1）。`v0.2.2-rc.2` 的 13 条指南只存在于 rc.3 **之后**的 master，**属于下一版，不要算进 rc.3**。
 
 > ⚠ **两个断层不属于同一层面，别混**：`0.1.6-alpha.2` 解决"能不能热插拔"，
 > `0.1.7-rc.1` 才解决"版本不匹配时会不会被拦"。`0.1.6-alpha.2` 上的
@@ -91,7 +98,8 @@
 ## 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 沙箱、
+**逐条核对**。本章是 0.2.1 线；rc.3（`0.2.2-rc.2` 及更新）用户还要看
+[migration-0.2.md](migration-0.2.md) §14 的 46 条 0.2.2 线 seam（`K1`–`K46`）。官方 release notes 也列了这 5 条为 "other changes"：Python PTC 沙箱、
 `both` 模式移除、`dshHome` 移除、子代理执行统一、Agent Team 直投收件箱。
 
 | # | 变更 | 破坏了什么 | 你要做什么 |
@@ -128,23 +136,30 @@ Python 环境）。它放在旧目录属于例外——上游自己的规则是"
 
 ## 4. 我该声明什么 peer 区间
 
-两条硬事实：
+三条硬事实（rc.3 语义）：
 
-1. **peer 是运行时门禁，不是声明。** 从 `0.1.7-rc.1` 起，`app-boot/src/plugin-compatibility.ts`
-   在插件被 import **之前**校验 `peerDependencies` 里的 `@deepseek-ai/dsh` / `@deepseek-ai/dsh-*`；
+1. **`engines.dsh` 是运行时门禁，且单独决定。** 从 `0.2.1-alpha.4` 起，`app-boot/src/plugin-compatibility.ts`
+   在插件被 import **之前**先读清单：**只要有 `engines.dsh`，就用该范围单独决定结果，并忽略 `@deepseek-ai/dsh*` 的 `peerDependencies`**；
    不匹配的行被**直接置为 `disabled`**，模块永不导入。
-2. **门禁语义是 `includePrerelease: true`**（`plugin-compatibility.ts:77`），比裸 semver **宽松**。
-   `engines.dsh` 与 `dsh.manifestVersion` 则是**纯声明、零强制**——写了不生效。
+2. **只有缺失 `engines.dsh` 时才回退到 peers。** 这时才校验 `peerDependencies` 里的 `@deepseek-ai/dsh` / `@deepseek-ai/dsh-*`（同一套 disabled 行为）。
+   声明了 `engines.dsh` 的包，peers 不再放宽或收窄它——所以 `engines.dsh` 必须覆盖**全部**支持版本。`workspace:` 只在 peer 中有效，出现在 `engines.dsh` 里即判不兼容。
+3. **门禁语义是 `includePrerelease: true`**（`plugin-compatibility.ts:52`），比裸 semver **宽松**。
+   所以 0.2.2 线要写 `>=0.2.2-0 <0.3.0` 这类带预发布下界的范围；`dsh.manifestVersion` 仍是纯声明，不参与门禁。
+   官方原文：`references/official-docs/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md`。
 
 ### 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
+>=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
 ```
 
-这是 `dsh-plugin-kit` 的 `data/peer-range.json`（`canonicalRange`，2026-09-26 更新）所记录的
-规范值，六个子句按线枚举。**本仓库 `src/cli/templates.ts` 生成的区间与它逐字节一致**，
-是仓库内唯一副本。
+这是 `dsh-plugin-kit` 的 `data/peer-range.json`（`canonicalRange`）所记录的规范区间；本库上次核该文件是
+2026-09-26 的六子句版本，本节按 0.2.2 线新增第七子句 `>=0.2.2-0 <0.3.0`（0.2.2 的预发布要求下界带 `-0`，
+否则严格 semver 下 `0.2.2-rc.3` 不落进范围）。**本仓库 `src/cli/templates.ts` 的 `DSH_PEER_RANGE` 与本节逐字节一致**，
+`package.json` 的 `engines.dsh` 与 `peerDependencies` 也同步含该子句。
+
+> ⚠️ **0.2.2 线优先把范围写进 `engines.dsh`**：写了它，peers 就完全不参与判定；`engines.dsh` 里不能用 `workspace:`。
+> 只有不发 `engines.dsh` 的包才靠 peers 兜底。
 
 ### 4.2 选区间的判断法
 
@@ -155,6 +170,7 @@ Python 环境）。它放在旧目录属于例外——上游自己的规则是"
 | 依赖 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.2.2 线（`engines.dsh` 门禁语义、`BundleInfo.update`、`dsh-doc`、Office kit、`Session.append` 双 overload、`window-drag-regions` 等，见 migration §14） | `>=0.2.2-0` |
 
 **不要**写开区间上界（如 `>=0.1.2-rc.1 <0.3.0`）：它跨过了整代破坏性变更，
 门禁放行但运行时会炸。**上界必须按世代切**（`<0.2.0` / `<0.3.0`）。
@@ -247,9 +263,11 @@ Python 环境）。它放在旧目录属于例外——上游自己的规则是"
 | `@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 已归档**） |
+| slot `sidebar.session.action`（hoc）+ `workspace.picker` SlotFactory / `workspace.picker.directoryFlow` | `0.2.2-rc.3` | rc.3 树：`ui-sidebar/.../contract/slots.ts`、`ui-workspace/.../contract/slots.ts`；**加性**，无迁移指南 |
+| 服务 seam `ctx.deepseekChatImport`（配置 `maxSessions`/`maxUploadBytes`/`maxEntryBytes`/`maxTitleBytes`）+ 实验 bundle `@deepseek-ai/dsh-deepseek-chat-import` | `0.2.2-rc.3` | `docs/capability-seams.md`、`docs/config-catalog.md`；**加性**，默认未装，无迁移指南 |
 
 > 22 面全表连同每面的**工具名、API 名、配置键与逐条出处行号**，来自一次
-> read-only 清点。**清点时 checkout 在 `dsh-v0.2.1-alpha.1` / `5badb15`；本库镜像现已同步到 `dsh-v0.2.1-alpha.2` / `d743267`**，
+> read-only 清点。**清点时 checkout 在 `dsh-v0.2.1-alpha.1` / `5badb15`；本库镜像现已同步到发布 tag `dsh-v0.2.2-rc.3` / `38a6a5c9`**，
 > 本文只摘"引入版本"一列；**要完整清单请按上文口径重跑**，或读官方
 > `docs/subsystems/*.md` + `docs/capability-seams.md` + `docs/tool-catalog.md`。
 
@@ -260,13 +278,18 @@ Python 环境）。它放在旧目录属于例外——上游自己的规则是"
 ```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: '0.2.2-rc.1', next: '0.2.2-rc.3', alpha: '0.2.2-alpha.3' }
 
 # 子包 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' }
+# { latest: '0.0.1-rc.1', next: '0.2.2-rc.3', alpha: '0.2.2-alpha.3' }
+
+# 版本/Release 计数（2026-11-14：44 / 39）
+npm view @deepseek-ai/dsh versions --json | ConvertFrom-Json | Measure-Object | Select-Object Count
+Invoke-RestMethod -Headers @{'User-Agent'='x'} `
+  'https://api.github.com/repos/deepseek-ai/deepseek-harness/releases?per_page=100' | Measure-Object | Select-Object Count
 
-# master 最新 tag 与 HEAD
+# 最新 tag 与 HEAD
 Invoke-RestMethod -Headers @{'User-Agent'='x'} `
   https://api.github.com/repos/deepseek-ai/deepseek-harness/tags | Select-Object -First 3 name
 
@@ -278,7 +301,7 @@ Invoke-RestMethod -Headers @{'User-Agent'='x'} `
 dsh --version
 ```
 
-**维护节奏**：官方 3 周内发过 9 个 prerelease。每次官方发版后按
+**维护节奏**：0.2.2 线在 17 天内发了 5 个 prerelease（2026-10-27 `alpha.2` → 11-03 `alpha.3` → 11-04 `rc.1` → 11-12 `rc.2` → 11-13 `rc.3`，npm 发布时刻）。每次官方发版后按
 `docs/upgrade-guide/**`（**无 index、无入链，必须主动看**）+ `docs/persistence-changes/**`
 + GitHub Releases 三处增量更新本文件与 `guide/migration-0.2.md`。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-primer",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "DSH plugin development as an on-demand agent skill: official docs mirror, version-compatibility matrix, migration seams, measured pitfalls, plus a scaffolder, checker and pack verifier CLI.",
   "type": "module",
   "main": "index.js",
@@ -78,21 +78,22 @@
     "verify:artifacts": "node scripts/verify-artifacts.mjs",
     "verify:self-contained": "pnpm run build && node dist/dsh-plugin-dev.js verify",
     "prepare": "tsdown",
-    "prepack": "tsdown"
+    "prepack": "tsdown",
+    "check:drift": "node scripts/check-docs-drift.mjs"
   },
   "dependencies": {},
   "devDependencies": {
-    "@deepseek-ai/dsh-attachment": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.2-rc.3",
     "@types/node": "^22.20.1",
     "@types/semver": "^7.8.0",
     "semver": "^7.8.5",
     "tsdown": "^0.23.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.7",
-    "@deepseek-ai/dsh-working-directory": "0.2.1-rc.2"
+    "@deepseek-ai/dsh-working-directory": "0.2.2-rc.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": ">=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"
+    "@deepseek-ai/dsh": ">=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"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh": {
@@ -121,7 +122,7 @@
   },
   "engines": {
     "node": ">=24.9.0",
-    "dsh": ">=0.2.1-0 <0.3.0"
+    "dsh": ">=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0"
   },
   "packageManager": "pnpm@11.7.0",
   "dshWorkshop": {
@@ -154,7 +155,12 @@
         "0.2.0-rc.2",
         "0.2.1-alpha.1",
         "0.2.1-alpha.2",
-        "0.2.1-rc.2"
+        "0.2.1-rc.2",
+        "0.2.2-alpha.2",
+        "0.2.2-alpha.3",
+        "0.2.2-rc.1",
+        "0.2.2-rc.2",
+        "0.2.2-rc.3"
       ]
     },
     "capability": {

package/references/official-docs/AGENTS.md

@@ -37,6 +37,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   compaction/           context compaction
   context/              request context
   subagent/             delegated agents
+  team/                 shared task coordination
   jobs/                 background jobs
   bundle/               profile bundles
   workflow/             workflow execution
@@ -81,7 +82,7 @@ Package groups: [packages/README.md](packages/README.md). [Experimental status](
 ## Commands
 
 ```sh
-pnpm install            # pnpm workspaces, node ^22.19 || >=24
+pnpm install            # pnpm workspaces, node >=24.9
 pnpm run clean           # remove build outputs and safe residue from deleted packages
 pnpm run test           # unit tests
 pnpm run test:coverage  # CI coverage gate: per-file 100% on packages/*/*/src
@@ -129,12 +130,13 @@ Real-API tests/demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and
 ## Conventions
 
 - Packages use `@deepseek-ai/dsh-<name>`; vendor is [rescoped](docs/rescope.md) and `private: true`. Harness packages declare `@deepseek-ai/cordis` in `peerDependencies`/`devDependencies`. Workspace dependency sections use DSH `workspace:*`, vendor/native `workspace:~` ([rules](.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md)).
-- ESM everywhere (`"type": "module"`). Use package names across packages and `.ts` in local relative imports. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only exports) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
-- **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
+- ESM everywhere (`"type": "module"`). Use package names across packages and `.ts` in local relative imports. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only exports) ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
+- **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer, directly or through its documented registration handle.
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`. Public service methods document parameters and non-void returns. `SessionEventMap` members are required-on-read unless the envelope carries `ignorable: true`. Bump `SESSION_FORMAT_VERSION` only when existing discriminators cannot prevent unsafe interpretation; same-version changes require safe reader behavior ([review](.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.md)).
 - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
+- **Session projections:** follow [dsh-session-projection](.agents/skills/dsh-session-projection/SKILL.md) when creating, extending, or reviewing one, or migrating a fold helper to one.
 - **Plugins, not loop changes**: new behavior goes on documented extension points; changing `agent-loop` requires updating docs/architecture.md.
 - **A capability seam comprises Service Definition / Service Provider / Consumer roles.** It is complete, never one role; split only when roles evolve independently ([glossary](docs/glossary.md#capability-seam)).
 - **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).
@@ -146,7 +148,7 @@ Real-API tests/demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and
 - **No new assertions to `unknown`** (`as unknown` or `<unknown>`). Preserve or reduce the exact legacy baseline; use typed values or validation for replacements ([rule](.agents/notes/implemented/process/2026-09-19-no-unknown-casts.md)).
 - **Source plane vs artifact plane, never mixed.** Static gates and tests resolve workspace imports through tsconfig `paths` to `src` and pass on a clean tree; gates consuming built `lib/` declare that dependency ([layout](docs/development.md#typescript-project-layout)).
 - **Keep compiler faces explicit.** A package with both Host and Client programs exposes face-specific leaf configs and a solution-only root; repo-wide programs seed a face config, never the root solution ([layout](docs/development.md#typescript-project-layout)).
-- **Error handling:** use typed, structured failures and localized, actionable reports. Define handling ownership, containment, and failure guarantees; stop dependent work and visibly report untrusted state or unknown outcomes. Follow [dsh-error-handling](.agents/skills/dsh-error-handling/SKILL.md).
+- **Error handling:** use typed, structured failures and localized, actionable reports. Coded errors and expected tool failures use `HarnessError`. Define handling ownership, containment, and failure guarantees; stop dependent work and visibly report untrusted state or unknown outcomes. Follow [dsh-error-handling](.agents/skills/dsh-error-handling/SKILL.md).
 - **An empty `catch` names the error** and why; keep its `try` to one statement.
 - **Keep comments local.** Do not restate code, expand unrelated comments, or explain distant behavior without local need ([rationale](.agents/skills/dsh-prose-standard/SKILL.md)).
 - **Ban `prove` + `nance`** ([rule](.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.md)).
@@ -154,13 +156,15 @@ Real-API tests/demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and
 - **Tests describe behavior, not correctness.** Change obsolete behavior with its tests; explain why in the PR.
 - **Create Agent Notes only for durable decision rationale;** mechanical/local edits are exempt, including local UI changes ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)).
 - **Official plugin artwork:** use [dsh-official-plugin-artwork](.agents/skills/dsh-official-plugin-artwork/SKILL.md) for official and official experimental plugin icons; obtain designer approval before landing new glyphs.
-- **Client UI copy is locale-owned.** Route product text through typed dictionaries and `t` or localized primitive props; `verify-client-ui-i18n` rejects hardcoded copy ([decision](.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md)).
+- **Client UI copy is locale-owned.** Route product text through typed dictionaries and `t` or localized primitive props; `verify-client-ui-i18n` rejects hardcoded copy ([decision](.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md)). English copy, including plugin titles, uses sentence case ([rule](.agents/skills/dsh-prose-standard/SKILL.md#required-coverage-by-prose-location)).
+- **UI changes:** use [dsh-client-ui-ux](.agents/skills/dsh-client-ui-ux/SKILL.md) as the design and review entry point; load its references only as needed.
 - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible change updates a keyless recorded-session snapshot; [snapshot ownership](snapshots/AGENTS.md) reserves the top-level tree for session-driven cases and keeps other expected output owner-local. Fixtures replay on macOS/Linux; fix fixtures, not normalizers.
 - **Design each tool's UI presentation up front.** Host presenters stay pure; Web cards derive from raw events and persisted result metadata ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for capability seams, lifecycle paths, and transcript output; include missing snapshot-harness support in the same change.
 - **Both SDKs project the loop.** Agent-loop, session-lifecycle, and `SessionEventMap` changes update the TypeScript and Python SDK expected outputs in the same PR; `pnpm run test` covers neither ([surfaces](docs/testing.md#when-a-snapshot-test-is-required)).
 - **Choose PR history deliberately.** Split independent changes and fix the introducing PR before propagation. Standalone/stack branches may merge-forward or rebase. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; preserve an in-progress merge-forward checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
 - **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md)).
+- **PR descriptions:** write and update every PR description with [dsh-pr-description](.agents/skills/dsh-pr-description/SKILL.md).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
 

package/references/official-docs/CLAUDE.md

@@ -1 +1 @@
-AGENTS.md
+AGENTS.md

package/references/official-docs/README.md

@@ -5,7 +5,7 @@
 
 | 内容 | 位置 | 来源（仓库内路径） |
 |---|---|---|
-| 官方 `docs/` 全文（215 篇 md，含全部 `.zh.md` 双语对） | [`docs/`](docs/) | `docs/` |
+| 官方 `docs/` 全文（709 篇 md，含 352 个 `.zh.md` 双语对） | [`docs/`](docs/) | `docs/` |
 | 仓库根开发红线 | [`AGENTS.md`](AGENTS.md) | `AGENTS.md` |
 | CLAUDE 入口（上游为 symlink，此处为其目标文本） | [`CLAUDE.md`](CLAUDE.md) | `CLAUDE.md` → `AGENTS.md` |
 | 基准测试说明 | [`BENCHMARK.md`](BENCHMARK.md) | `BENCHMARK.md` |
@@ -25,11 +25,16 @@
 ## 同步与校验
 
 ```sh
-# 同步（源固定为 checkout 的 origin/master，未跟踪/未推送内容不会进来）
-pwsh -File scripts/sync-official-docs.ps1 [-Checkout <deepseek-harness-checkout>]
+# 同步（默认取 checkout 的 origin/master；用 -Ref 钉一个发布 tag 得到可复现快照；未跟踪/未推送内容不会进来）
+pwsh -File scripts/sync-official-docs.ps1 [-Checkout <deepseek-harness-checkout>] [-Ref <tag|sha>]
 
-# 漂移校验（KB 与 checkout 的 git 已跟踪文件逐一哈希对比）
+# 漂移校验（有 checkout 时逐文件哈希对比）
 pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>
+
+# 新鲜度校验（无 checkout；比较"最新 release tag"与 SNAPSHOT 的 Source ref）
+node scripts/check-docs-drift.mjs
 ```
 
 同步范围只包含 git 已跟踪文件；checkout 里的本地草稿（未跟踪）与未推送提交的改动不会进入本目录。同步后 README 里的"最后核验"日期与提交号请引用 `SNAPSHOT.md`。
+
+**当前快照钉的是发布 tag，不是 master HEAD**：`references/official-docs` 对齐 `dsh-v0.2.2-rc.3`（`38a6a5c9…`，709 篇 md / 352 对中英），用 `-Ref dsh-v0.2.2-rc.3` 可复现。只在 tag 之后 master 才出现的文档（例如 `docs/upgrade-guide/v0.2.2-rc.2/**` 的 13 条指南）**不属于本快照**，属于下一版内容，别把它们算进 rc.3。