dsh-plugin-guide 0.3.21 → 0.3.23

package/guide/quick-reference.hi.md

@@ -131,14 +131,20 @@ Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(
 
 ## कठोर नियम (उल्लंघन = गेट विफलता / गलत व्यवहार)
 
-1. हर पंजीकरण `ctx.effect()` / `ctx.on()` / सेवा के `register()` से हो (disposer लौटाता है)।
-2. waterfall श्रोताओं को `next()` बुलाना ही होगा; न बुलाना जानबूझकर शॉर्ट-सर्किट है।
-3. मॉडल-दृश्य ⇔ लॉग: नई मॉडल-दृश्य इनपुट के लिए नया सत्र इवेंट चाहिए (`SessionEventMap`)।
-4. समायोज्य मान कभी हार्डकोड न करें (कसौटी: क्या cordis.yml इसे बदल सकता है?); गलत कॉन्फ़िग ज़ोर से विफल हो।
-5. स्वतंत्र प्लगइन पैकेज: cordis peerDependency है और होस्ट पहचान से मेल खाना चाहिए (scoped `@deepseek-ai/cordis` और unscoped मिलाना पहचान बाँट देता है); ESM; `dsh.bundle` मैनिफ़ेस्ट; git इंस्टॉल को `prepare` + `allowBuilds` चाहिए; `lib/` या tarball प्रकाशित करें।
-6. दस्तावेज़ द्विभाषी जोड़ों में; टूल विवरण/प्रॉम्प्ट ही व्यवहार हैं; गैर-तुच्छ बदलाव में Agent Note चाहिए; पुश से पहले न्यूनतम जाँच सेट चलाएँ (dsh-pre-push-checks)।
-7. सीमाओं के पार अपारदर्शी ids branded होते हैं (`Branded<B>` from `dsh-brand`), कभी भी नंगे `string` नहीं।
-8. `SessionEventMap` सदस्य required-on-read हैं: 0.1.2-alpha.1 में `ignorable` लिफ़ाफ़ा हट गया है (पठन विफल-बंद है — जो build किसी इवेंट प्रकार को नहीं जानता वह log अस्वीकार करता है), और plugins के अपने इवेंट के append एक अनुकूली द्वार से चलते हैं जो बिना-लिफ़ाफ़े वाले hosts पर लिखना रोक देता है; केवल संरचनात्मक प्रारूप बदलाव ही `SESSION_FORMAT_VERSION` bump करते हैं। `SessionEvent` पर switch दस्तावेज़ित `default` में गिरता है — `assertNever` नहीं (merge-extensible union)।
+1. हर पंजीकरण `ctx.effect()` / `ctx.on()` / सेवा के `register()` से हो (disposer लौटाता है)। किसी अन्य context पर पंजीकरण (जैसे `agent.ctx`) के **दो मालिक** होते हैं — उसका disposer अपने effect में भी रखें।
+2. waterfall श्रोताओं को `next()` बुलाना ही होगा; न बुलाना जानबूझकर शॉर्ट-सर्किट है। `agent/pre-step` निर्णय बदलते समय उसे **spread** करें (`{ ...decision, messages }`) ताकि `startsRequestSeries` जैसे फ़ील्ड न खोएँ।
+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 को चुपचाप ढक देती है, और DSH peer रेंज **सत्यापित नहीं** करता)।
+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` नहीं।
+10. **किसी नए `type` के साथ session event कभी न जोड़ें**: `SessionEventMap` सदस्य required-on-read हैं — जो build किसी प्रकार को नहीं जानता वह पूरा log अस्वीकार कर देता है, जब तक उस event पर envelope का `ignorable: true` चिह्न न हो, और चल रहा `Session.append()` वह चिह्न लिख नहीं सकता (उसका तीसरा argument केवल surface events के लिए `SurfaceIntent` है)। अपनी state मौजूदा events से निकालें, या plugin का डेटा inspection से मिली storage service में रखें। केवल संरचनात्मक प्रारूप बदलाव ही `SESSION_FORMAT_VERSION` bump करते हैं (अब `4`; V3→V4 माइग्रेशन tool परिणामों को tool-role संदेशों में उठाता है और संदेश `source` को producer के `source.kind` पर ले जाता है)। `SessionEvent` पर switch अब भी दस्तावेज़ित `default` में गिरता है — `assertNever` नहीं (merge-extensible union)।
+11. `agent.inject()` का `source` अब सेवानिवृत्त `{ kind: 'plugin', plugin: '<name>' }` wrapper **स्वीकार नहीं करता** — पहले `MessageSourceMap` से अपना kind declare करें। `inject` agent को जगाता नहीं (`followup()`/`steer()` जगाते हैं)।
+12. **सत्र चलते समय profile का `cordis.patch.yml` कभी न लिखें** (HMR उसे reload करता है: जीवित सत्रों से tools गायब हो जाते हैं, चल रहे turn मर जाते हैं, और `session-controller` दोबारा बनाने पर वह पूरी प्रक्रिया restart तक मृत रह सकता है)। profile का `package.json` हाथ से न लिखें, profile डायरेक्टरी में pnpm न चलाएँ।
+13. UI प्लगइन: React को slot में render करें (iframe में सर्व किया पेज कभी नहीं); styling केवल `--dsw-alias-*` theme tokens से; Harness Client पैकेज को `require` कभी न करें (throw करता component पूरा slot खाली कर देता है); `dsh.client.inject` **स्थिर array** होना चाहिए।
+14. प्रदर्शन: per-session state `ctx.sessionProjections` में रखें (शुद्ध synchronous `apply`, अनदेखा करने पर वही reference, शुद्ध JSON + `stateVersion`); durable events की प्रतीक्षा करें (`turn/end`, `assistant/message`, `tool/result`) और live tokens `agent/assistant-stream` से render करें; `agent/status` को कभी poll न करें।
 
 ## समुदाय की त्वरित समस्या-सूची (विवरण: गाइड §7.3 / community-repo-deep-dive.md)
 
@@ -147,7 +153,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=0.1.2-rc.1); `@deepseek-ai/dsh-tools` और `@deepseek-ai/dsh-session-persistence-jsonl` का `latest` पुराना है (0.0.1-rc.1), `next` (0.1.2-rc.1) पिन करें; `create-dsh-plugin` latest=0.2.1; dsh-core/dsh-sdk अभी भी अप्रकाशित (2026-09-04 को सत्यापित)।
+- npm: बिना स्कोप वाला `dsh` असंबंधित node-dsh प्रोजेक्ट (एक shell) है — `@deepseek-ai/dsh` इंस्टॉल करें (`latest`=`next`=0.2.0-rc.2, `alpha`=0.2.1-alpha.1); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` और `@deepseek-ai/dsh-session-persistence-jsonl` का `latest` अब भी पुराना है (0.0.1-rc.1), इसलिए `next` (0.2.0-rc.2) या `alpha` (0.2.1-alpha.1) पिन करें; `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.0.4 और नया टैग `dsh-0-2-1-alpha-1`=4.0.5-alpha.1; dsh-core/dsh-sdk अभी भी अप्रकाशित (2026-10-06 को सत्यापित)।
 - पथ तुलना से पहले दोनों ओर `resolve()` करें (Windows बैकस्लैश जाल)।
 
 ## दस्तावेज़ लिंक

package/guide/quick-reference.md

@@ -131,14 +131,20 @@ Chunk protocol: `block-start` → `text-delta*` → `block-end` (complete block)
 
 ## Hard rules (violations = gate failures / wrong behavior)
 
-1. Every registration goes through `ctx.effect()` / `ctx.on()` / a service `register()` (returns a disposer).
-2. Waterfall listeners must call `next()`; not calling it short-circuits by design.
-3. Model-visible ⇔ logged: new model-visible input requires a new session event (`SessionEventMap`).
-4. Never hardcode tunables (test: can cordis.yml change it?); misconfiguration fails loud.
-5. Standalone plugin packages: cordis is a peerDependency matching the host identity (mixing scoped `@deepseek-ai/cordis` and unscoped splits identities); ESM; `dsh.bundle` manifest; git installs need `prepare` + `allowBuilds`; ship `lib/` or a tarball.
-6. 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).
-7. Opaque cross-boundary ids are branded (`Branded<B>` from `dsh-brand`), never bare `string`.
-8. `SessionEventMap` members are required-on-read: the `ignorable` envelope is gone on 0.1.2-alpha.1 (reads fail closed — a build that does not know an event type refuses the log), and plugin appends of custom events ride an adaptive gate that stops writing on envelope-less hosts; only structural format changes bump `SESSION_FORMAT_VERSION`. 0.1.2-rc.1 retains the `ignorable?: true` field for stored-log read compatibility only — its `Session.append` third argument is a `SurfaceIntent` for surface events and still cannot stamp the marker, so the gate keeps skipping custom-event appends there (no behavior change). Switch over `SessionEvent` falls through a documented `default` — no `assertNever` (merge-extensible union).
+1. Every registration goes through `ctx.effect()` / `ctx.on()` / a service `register()` (returns a disposer). A registration on another context (e.g. `agent.ctx`) has two owners — keep its disposer in your own effect too.
+2. Waterfall listeners must call `next()`; not calling it short-circuits by design. When rewriting an `agent/pre-step` decision, **spread it** (`{ ...decision, messages }`) so fields like `startsRequestSeries` survive.
+3. Weakest mechanism that suffices: `ctx.tools.restrict()` (remove only) < `ctx.tools.guard()` (deny only) < waterfall rewrite (order-dependent) < `system-prompt/assemble` (replaces everything). Observe final outcomes on `tools/result`; use `tools/post-execute` only to transform.
+4. Model-visible ⇔ logged: new model-visible input requires a new session event (`SessionEventMap`) — added by the host, never by appending a new `type` yourself (see rule 8).
+5. Never hardcode tunables (test: can cordis.yml change it?); misconfiguration fails loud. Live-editable user fields use `Volatile<T>` + `loader/volatile-update` (the form namespace is the profile entry id).
+6. Standalone plugin packages: cordis is a peerDependency matching the host identity (mixing scoped `@deepseek-ai/cordis` and unscoped splits identities); ESM; `dsh.bundle` manifest (`patch` may be an ordered array); git installs need `prepare` + `allowBuilds`; ship `lib/` or a tarball. Shared-instance dsh packages go in **peerDependencies + devDependencies only** — never `dependencies` (a profile copy silently shadows the runtime, and DSH does not validate peer ranges).
+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`.
+10. **Never append a session event with a new `type`.** `SessionEventMap` members are required-on-read: a reader that does not know a type refuses the whole log unless the event carries the envelope's `ignorable: true` marker, and live `Session.append()` cannot set that marker (its third argument is a `SurfaceIntent` for surface events only). Derive your state from existing events, or keep plugin-owned data in a storage service found through inspection. Only structural format changes bump `SESSION_FORMAT_VERSION` (currently `4`; the V3→V4 migration lifts tool results into tool-role messages and moves message sources to producer-owned `source.kind`). Switch over `SessionEvent` still falls through a documented `default` — no `assertNever` (merge-extensible union).
+11. `agent.inject()`'s `source` no longer accepts the retired `{ kind: 'plugin', plugin: '<name>' }` wrapper — declare your own kind through `MessageSourceMap` first. `inject` does not wake the agent (`followup()`/`steer()` do).
+12. Never write a profile `cordis.patch.yml` while sessions run (HMR reloads it: tools vanish from live sessions, in-flight turns die, and a rebuild of `session-controller` can kill it until a full restart). Never hand-write a profile `package.json`; never run pnpm inside the profile directory.
+13. UI plugins: render React in a slot (never an iframe-hosted page); style with `--dsw-alias-*` theme tokens only; never `require` a Harness Client package (a throwing component blanks the slot); `dsh.client.inject` must be a **static array**.
+14. Performance: keep per-session state in `ctx.sessionProjections` (pure synchronous `apply`, same reference when ignored, plain JSON + `stateVersion`); wait on durable events (`turn/end`, `assistant/message`, `tool/result`) and render live tokens from `agent/assistant-stream`; never poll `agent/status`.
 
 ## Community pitfalls quick list (details: guide §7.3 / community-repo-deep-dive.md)
 
@@ -147,7 +153,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=0.1.2-rc.1); `@deepseek-ai/dsh-tools` and `@deepseek-ai/dsh-session-persistence-jsonl` have stale `latest` (0.0.1-rc.1), pin `next` (0.1.2-rc.1); `create-dsh-plugin` latest=0.2.1; dsh-core/dsh-sdk still unpublished (verified 2026-09-04).
+- npm: unscoped `dsh` is the unrelated node-dsh shell — install `@deepseek-ai/dsh` (`latest`=`next`=0.2.0-rc.2, `alpha`=0.2.1-alpha.1); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` and `@deepseek-ai/dsh-session-persistence-jsonl` still ship a stale `latest` (0.0.1-rc.1), so pin `next` (0.2.0-rc.2) or `alpha` (0.2.1-alpha.1); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.0.4 with a new `dsh-0-2-1-alpha-1` tag at 4.0.5-alpha.1; dsh-core/dsh-sdk still unpublished (verified 2026-10-06).
 - `resolve()` both sides before path comparisons (Windows backslash trap).
 
 ## Documentation links
@@ -165,7 +171,9 @@ Community dev docs — templates/tutorials/pitfalls, full list in [references/co
 
 ## Key source index
 
-- Official docs verbatim: `references/official-docs/docs/**` (215 pages, all `.zh.md` pairs included)
+- Official docs verbatim: `references/official-docs/docs/**` (369 md pages, all 182 `.zh.md` pairs included); the pages **not on the documentation site** (session-format-status, `upgrade-guide/**`, `persistence-changes/**`, ui-radius, web-styling, module-graph) are listed in [links.md](links.md) §2.1
+- Migration checklist: [migration-0.2.md](migration-0.2.md) (every breaking change from 0.1.6-alpha.2 → 0.2.1-alpha.1, with the official upgrade-guide source for each)
+- 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)
 - Upstream Cordis: `downloads/github/cordis/**` + research `references/upstream-cordis.md`

package/guide/quick-reference.pt.md

@@ -131,14 +131,20 @@ Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloco comp
 
 ## Regras rígidas (violações = falhas de gate / comportamento errado)
 
-1. Todo registro passa por `ctx.effect()` / `ctx.on()` / o `register()` de um serviço (retorna disposer).
-2. Listeners de waterfall devem chamar `next()`; não chamar causa curto-circuito por design.
-3. Visível-para-o-modelo ⇔ registrado: nova entrada visível exige novo evento de sessão (`SessionEventMap`).
-4. Nunca codifique valores ajustáveis (teste: o cordis.yml consegue mudá-los?); má configuração falha em voz alta.
-5. 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`; instalações git precisam de `prepare` + `allowBuilds`; publique `lib/` ou um tarball.
-6. 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).
-7. IDs opacos entre limites são branded (`Branded<B>` de `dsh-brand`), nunca `string` crua.
-8. Membros de `SessionEventMap` são required-on-read: o envelope `ignorable` desaparece no 0.1.2-alpha.1 (a leitura falha fechada — um build que não conhece um tipo de evento recusa o log), e appends de eventos próprios de plugins cruzam uma porta adaptativa que para de gravar em hosts sem envelope; 0.1.2-rc.1 mantém o campo ignorable?: true apenas para compatibilidade de leitura de logs armazenados (seu Session.append ainda não consegue estampar o marcador), então a porta continua sem gravar (sem mudança de comportamento). Apenas mudanças de formato estrutural bumpam `SESSION_FORMAT_VERSION`. O switch sobre `SessionEvent` cai num `default` documentado — sem `assertNever` (união merge-extensible).
+1. Todo registro passa por `ctx.effect()` / `ctx.on()` / o `register()` de um serviço (retorna disposer). Um registro em outro contexto (ex.: `agent.ctx`) tem **dois donos**: guarde o disposer também no seu próprio effect.
+2. Listeners de waterfall devem chamar `next()`; não chamar causa curto-circuito por design. Ao reescrever uma decisão de `agent/pre-step`, **propague com spread** (`{ ...decision, messages }`) para não perder campos como `startsRequestSeries`.
+3. **O mecanismo mais fraco que basta**: `ctx.tools.restrict()` (só remove) < `ctx.tools.guard()` (só nega) < reescrita por waterfall (depende da ordem) < `system-prompt/assemble` (substitui tudo). Observe resultados finais em `tools/result`; use `tools/post-execute` só para transformar.
+4. Visível-para-o-modelo ⇔ registrado: nova entrada visível exige novo evento de sessão (`SessionEventMap`) — **adicionado pelo host**, não por você (ver regra 10).
+5. Nunca codifique valores ajustáveis (teste: o cordis.yml consegue mudá-los?); má configuração falha em voz alta. Campos editáveis ao vivo usam `Volatile<T>` + `loader/volatile-update` (o namespace do formulário é o id da entrada do perfil).
+6. Pacotes de plugin independentes: cordis é peerDependency com a mesma identidade do host (misturar scoped `@deepseek-ai/cordis` e unscoped divide identidades); ESM; manifesto `dsh.bundle` (`patch` pode ser uma lista ordenada); instalações git precisam de `prepare` + `allowBuilds`; publique `lib/` ou um tarball. Pacotes dsh de instância compartilhada ficam **só em peerDependencies + devDependencies**, nunca em `dependencies` (uma cópia no perfil sombreia o runtime em silêncio, e o DSH **não valida** faixas de peer).
+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.
+10. **Nunca acrescente um evento de sessão com um `type` novo**: membros de `SessionEventMap` são required-on-read — um build que não conhece um tipo recusa todo o log, a menos que o evento carregue a marca `ignorable: true` do envelope, e o `Session.append()` em execução não consegue gravar essa marca (seu terceiro argumento é um `SurfaceIntent` apenas para eventos de superfície). Derive o estado de eventos existentes ou guarde dados do plugin num serviço de storage localizado por inspection. Apenas mudanças de formato estrutural bumpam `SESSION_FORMAT_VERSION` (hoje `4`; a migração V3→V4 eleva resultados de tool a mensagens com papel tool e move os `source` de mensagem para o `source.kind` do produtor). O switch sobre `SessionEvent` continua caindo num `default` documentado — sem `assertNever` (união merge-extensible).
+11. O `source` de `agent.inject()` **não aceita mais** o wrapper retirado `{ kind: 'plugin', plugin: '<name>' }`: declare seu próprio kind via `MessageSourceMap` primeiro. `inject` não acorda o agente (`followup()`/`steer()` acordam).
+12. **Nunca escreva o `cordis.patch.yml` do perfil com sessões rodando** (o HMR recarrega: tools somem das sessões vivas, turnos em andamento morrem e reconstruir o `session-controller` pode deixá-lo morto até reiniciar o processo). Nunca escreva à mão o `package.json` do perfil nem rode pnpm dentro do diretório do perfil.
+13. Plugins de UI: renderize React num slot (nunca uma página servida em iframe); estilize **só** com tokens de tema `--dsw-alias-*`; nunca faça `require` de um pacote Client do Harness (um componente que lança deixa o slot em branco); `dsh.client.inject` deve ser um **array estático**.
+14. Desempenho: guarde o estado por sessão em `ctx.sessionProjections` (`apply` puro e síncrono, mesma referência quando ignora, JSON puro + `stateVersion`); espere eventos duráveis (`turn/end`, `assistant/message`, `tool/result`) e renderize tokens ao vivo de `agent/assistant-stream`; nunca faça polling de `agent/status`.
 
 ## Lista rápida de armadilhas da comunidade (detalhes: guia §7.3 / community-repo-deep-dive.md)
 
@@ -147,7 +153,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=0.1.2-rc.1); `@deepseek-ai/dsh-tools` e `@deepseek-ai/dsh-session-persistence-jsonl` têm `latest` obsoleto (0.0.1-rc.1), fixe `next` (0.1.2-rc.1); `create-dsh-plugin` latest=0.2.1; dsh-core/dsh-sdk seguem não publicados (verificado em 2026-09-04).
+- npm: o `dsh` sem escopo é o projeto alheio node-dsh (um shell) — instale `@deepseek-ai/dsh` (`latest`=`next`=0.2.0-rc.2, `alpha`=0.2.1-alpha.1); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` e `@deepseek-ai/dsh-session-persistence-jsonl` ainda publicam um `latest` obsoleto (0.0.1-rc.1), fixe `next` (0.2.0-rc.2) ou `alpha` (0.2.1-alpha.1); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.0.4 com a nova tag `dsh-0-2-1-alpha-1` em 4.0.5-alpha.1; dsh-core/dsh-sdk seguem não publicados (verificado em 2026-10-06).
 - Aplique `resolve()` nos dois lados antes de comparar caminhos (armadilha da barra invertida do Windows).
 
 ## Links de documentação

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

@@ -1,4 +1,4 @@
-# DeepSeek Harness  0.1.2-rc.1 恢复信封 ignorable?: true 字段但仅用于存量日志读取兼容（其 Session.append 仍无法盖章），门控行为不变。 插件开发速查表
+# DeepSeek Harness 插件开发速查表
 
 > 一页式速查。细节回到 [plugin-dev-guide.md](plugin-dev-guide.md) 与 [references](../references/)。
 
@@ -130,14 +130,20 @@ Chunk 协议：`block-start` → `text-delta*` → `block-end`（完整块）→
 
 ## 红线（违反=挂门禁/错误行为）
 
-1. 注册必须走 `ctx.effect()`/`ctx.on()`/服务 `register()`（返回 disposer）。
-2. waterfall 监听器必须调 `next()`；不调=故意短路。
-3. 模型可见 ⟺ 已记录：新模型可见输入必须新增会话事件（`SessionEventMap`）。
-4. 不得硬编码可调参数（判断：cordis.yml 能否改）；misconfig fail loud。
-5. 独立插件包：cordis 是 peerDependency（与宿主同身份：scoped `@deepseek-ai/cordis` 与 unscoped 混用会"双 Cordis 分裂"）；ESM；`dsh.bundle` 清单；git 安装配 `prepare` + `allowBuilds`；发布带 `lib/` 或 tarball。
-6. 文档双语成对；工具描述/提示词即行为；非平凡变更加 Agent Note；提交前跑最小检查集（dsh-pre-push-checks）。
-7. 跨边界 opaque id 用 branded（`Branded<B>` from `dsh-brand`），从不裸 `string`。
-8. `SessionEventMap` 成员默认 required-on-read：`ignorable` 信封在 0.1.2-alpha.1 已移除（读路径 fail-closed——不认识该事件类型的 build 一律拒绝日志），插件自定义事件的追加走自适应门、在无信封宿主上停写；只有结构格式变更才 bump `SESSION_FORMAT_VERSION`。对 `SessionEvent` 的 switch 落入文档化 `default`——**禁用 `assertNever`**（merge-extensible union）。
+1. 注册必须走 `ctx.effect()`/`ctx.on()`/服务 `register()`（返回 disposer）。注册在别的 ctx（如 `agent.ctx`）上的有**两个拥有者**——disposer 也要留在自己插件的 effect 里。
+2. waterfall 监听器必须调 `next()`；不调=故意短路。改写 `agent/pre-step` 决策要**展开**（`{ ...decision, messages }`），否则 `startsRequestSeries` 之类字段会丢。
+3. **用最弱的够用机制**：`ctx.tools.restrict()`（只移除）< `ctx.tools.guard()`（只拒绝）< waterfall 改写（依赖顺序）< `system-prompt/assemble`（整段替换）。最终结果只看 `tools/result`；只有要变换结果才用 `tools/post-execute`。
+4. 模型可见 ⟺ 已记录：新模型可见输入必须新增会话事件（`SessionEventMap`）——**由宿主侧新增**，不是插件自己写（见第 10 条）。
+5. 不得硬编码可调参数（判断：cordis.yml 能否改）；misconfig fail loud。要暴露给用户的实时字段用 `Volatile<T>` + `loader/volatile-update`（表单命名空间=profile 条目 id）。
+6. 独立插件包：cordis 是 peerDependency（与宿主同身份：scoped `@deepseek-ai/cordis` 与 unscoped 混用会"双 Cordis 分裂"）；ESM；`dsh.bundle` 清单（`patch` **可为有序数组**）；git 安装配 `prepare` + `allowBuilds`；发布带 `lib/` 或 tarball。**共享实例的 dsh 包只放 peer + dev，绝不放 dependencies**（profile 内副本会静默遮蔽运行时；且 DSH **不校验** peer 范围）。
+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`。
+10. **绝不要用新的 `type` 追加会话事件**：`SessionEventMap` 成员默认 required-on-read——不认识该事件类型的 build 会拒绝整份日志，除非该事件带上信封的 `ignorable: true` 标记；而运行时 `Session.append()` **无法**写这个标记（其第三参仅为 surface 事件的 `SurfaceIntent`）。插件状态要从既有事件推导，或用 inspection 找到的 storage 服务自持。只有结构格式变更才 bump `SESSION_FORMAT_VERSION`（当前 `4`；V3→V4 迁移把 tool 结果提升为 tool-role 消息、把消息 source 换成生产者自有的 `source.kind`）。对 `SessionEvent` 的 switch 仍落入文档化 `default`——**禁用 `assertNever`**（merge-extensible union）。
+11. `agent.inject()` 的 `source` **不再接受**退役的 `{ kind: 'plugin', plugin: '<name>' }` 包装——先用 `MessageSourceMap` 声明合并自己的 kind。`inject` 不唤醒 agent（要唤醒用 `followup()`/`steer()`）。
+12. **绝不在会话运行期间写 profile 的 `cordis.patch.yml`**（HMR 会重载：会话内工具会消失、在途 turn 被杀、最坏重建 `session-controller` 失败并永久失效，只能整进程重启）。不要手写 profile 的 `package.json`，不要在 profile 目录里跑 pnpm。
+13. UI 插件：只渲染 slot 里的 React 组件（禁止 iframe 托管页面）；样式只用 `--dsw-alias-*` 主题 token；不 `require` 任何 Harness Client 包（抛错组件会把 slot 搞白）；`dsh.client.inject` **必须是静态数组**。
+14. 性能：per-session 状态放 `ctx.sessionProjections`（纯同步 `apply`、忽略即同引用、纯 JSON + `stateVersion`）；等持久事件（`turn/end`/`assistant/message`/`tool/result`），实时 token 读 `agent/assistant-stream`；**不轮询 `agent/status`**。
 
 ## 社区实测坑速查（详见 guide §7.3 / community-repo-deep-dive.md）
 
@@ -146,7 +152,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=0.1.2-rc.1）；`@deepseek-ai/dsh-tools` 与 `@deepseek-ai/dsh-session-persistence-jsonl` 的 `latest` 是过期版本（0.0.1-rc.1），要钉 `next`（0.1.2-rc.1）；`create-dsh-plugin` latest=0.2.1；dsh-core/dsh-sdk 仍未发布（2026-09-04 复核）。
+- npm：无作用域 `dsh` 是无关项目 node-dsh（shell）——官方包是 `@deepseek-ai/dsh`（`latest`=`next`=0.2.0-rc.2、`alpha`=0.2.1-alpha.1）；`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-headless`、`@deepseek-ai/dsh-session-persistence-jsonl` 的 `latest` 仍是过期版本（0.0.1-rc.1），要钉 `next`（0.2.0-rc.2）或 `alpha`（0.2.1-alpha.1）；`create-dsh-plugin` latest=0.2.3；`@deepseek-ai/cordis` latest=4.0.4，另有新标签 `dsh-0-2-1-alpha-1`=4.0.5-alpha.1；dsh-core/dsh-sdk 仍未发布（2026-10-06 复核）。
 - 路径比较前两侧都 `resolve()`（Windows 反斜杠陷阱）。
 
 ## 文档链接
@@ -164,7 +170,9 @@ Chunk 协议：`block-start` → `text-delta*` → `block-end`（完整块）→
 
 ## 关键源索引
 
-- 本地官方文档全文：`references/official-docs/docs/**`（215 篇，含全部 `.zh.md`）
+- 本地官方文档全文：`references/official-docs/docs/**`（369 篇，含全部 182 个 `.zh.md`）；**没上文档站**的那些页（session-format-status、`upgrade-guide/**`、`persistence-changes/**`、ui-radius、web-styling、module-graph）见 [links.md](links.md) §2.1
+- 迁移清单：[migration-0.2.md](migration-0.2.md)（0.1.6-alpha.2 → 0.2.1-alpha.1 的全部破坏性变更，逐条附官方 upgrade-guide 出处）
+- 官方自带插件开发技能：[references/official-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`（下载清单）
 - 上游 Cordis：`downloads/github/cordis/**` + 调研 `references/upstream-cordis.md`

package/guide/release-engineering.md

@@ -41,8 +41,8 @@ The pattern that admits all windows (one clause per prerelease tuple; each `-0`
 ```jsonc
 {
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.3.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-tools": "0.1.7-rc.2"

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

@@ -41,8 +41,8 @@
 ```jsonc
 {
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.3.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-tools": "0.1.7-rc.2"