dsh-primer 0.4.4 → 0.4.6

package/README.pt.md

@@ -0,0 +1,493 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-primer-hero-en-dark.webp">
+  <img src="docs/assets/dsh-primer-hero-en-light.webp" width="100%" alt="dsh-primer: pergunte primeiro a versão do host — a base de conhecimento carrega como skill de agente sob demanda; só name + description ficam no catálogo, o corpo do SKILL.md carrega ao ser acionado e guide/ e references/ são lidos apenas quando citados; além do CLI dsh-plugin-dev new / check / verify">
+</picture>
+
+# dsh-primer
+
+**Pergunte primeiro a qual versão você está mirando: faça o agente construir contra a linha do host, não contra uma API lembrada.**
+
+A base de conhecimento de desenvolvimento de plugins para o DeepSeek Harness: espelho literal da documentação oficial, matriz de compatibilidade de versões, seams de migração e armadilhas testadas, instalada como skill de agente sob demanda; além do CLI `dsh-plugin-dev new / check / verify`.
+
+[Instalar](#instalação-em-três-passos) · [Configuração](#configuração) · [FAQ](#faq) · [简体中文](README.md) · [English](README.en.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-3366CC?style=flat-square&labelColor=2B3245)](LICENSE)
+[![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.2.1%20%3C0.3.0-4B67B4?style=flat-square&labelColor=2B3245)](#compatibilidade)
+[![npm](https://img.shields.io/npm/v/dsh-primer?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-primer)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-primer/verify.yml?branch=main&label=CI&style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-primer/actions/workflows/verify.yml)
+[![Node](https://img.shields.io/badge/node-%3E%3D24.9-339933?style=flat-square&labelColor=2B3245)](#compatibilidade)
+
+[![Stars](https://img.shields.io/github/stars/PerryLink/dsh-primer?style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-primer/stargazers)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-primer?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-primer)
+[![dshfind](https://dshfind.com/api/badge/PerryLink/dsh-primer?metric=downloads)](https://dshfind.com/plugins/PerryLink/dsh-primer?ref=badge)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-primer/badge)](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-primer)
+[![DSH Market](https://img.shields.io/badge/DSH_Market-listed-4B67B4?style=flat-square&labelColor=2B3245)](https://dsh.market/)
+
+```sh
+dsh plugin --profile <name> add dsh-primer
+```
+
+</div>
+
+<sub>Plugin da comunidade, sem afiliação com a DeepSeek. Repositório canônico: <https://github.com/PerryLink/dsh-primer>.</sub>
+
+## O que é
+
+O `dsh-primer` empacota tudo o que o desenvolvimento de plugins do DSH precisa num único bundle instalável: uma base de conhecimento registrada como a skill de agente `dsh-primer` (visível no catálogo de toda sessão, carregando sob demanda os passos de trabalho, a documentação oficial e as leituras da comunidade) e o CLI `dsh-plugin-dev`, sem dependências em tempo de execução, que acrescenta três camadas mecânicas sobre esse conhecimento.
+
+Mantido pela comunidade, **não** é um produto oficial da DeepSeek. O DeepSeek Harness está em prévia para desenvolvedores e continua publicando mudanças incompatíveis; em caso de dúvida, a documentação oficial em `references/official-docs/` é a fonte da verdade.
+
+Por que não basta ler a documentação oficial? Porque ela é escrita para quem já sabe qual página abrir, e o DSH publica um prerelease a cada 1,7–2,8 dias com mudanças incompatíveis. Este plugin cobre as três lacunas que mais custam tempo:
+
+| Lacuna | O que este plugin acrescenta |
+|---|---|
+| **"Contra qual DSH eu estou desenvolvendo?"** | Uma [matriz de versões](guide/version-matrix.md): os cinco valores que se chamam "latest", as tags `latest` congeladas dos subpacotes, os seams de mudança incompatível e como escolher um intervalo de `peerDependencies`. **Não existe linha estável.** |
+| **"O que esta versão quebra?"** | Um [guia de migração](guide/migration-0.2.md) que organiza `0.1.6-alpha.2` → `0.2.2-rc.3` como seams citáveis (§0–§13 cobrem a linha 0.1.6→0.2.1; §14 são os 46 seams `K1`–`K46` da linha 0.2.2 publicados no rc.3), cada um com sintoma *e* correção e sua fonte oficial, incluindo um risco de perda de dados e uma mudança que faz os prompts falharem antes de a requisição ao modelo ser montada. |
+| **"Meu plugin está realmente correto?"** | Um [CLI sem dependências](SKILL.md) (`dsh-plugin-dev new / check / verify`) mais um [espelho literal offline](references/official-docs/) da documentação oficial, para que o agente cite a página exata em vez de adivinhar. |
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-primer-flow-v5-dark.svg">
+  <img src="docs/assets/dsh-primer-flow-v5-light.svg" width="100%" alt="Estrutura de dois canais do dsh-primer: um bundle somente leitura alimenta uma camada cognitiva (registro da skill → uma entrada de catálogo → páginas sob demanda) e uma camada mecânica (new / check / verify / seams); os dois canais convergem num mesmo veredicto">
+</picture>
+
+## Instalação em três passos
+
+1. **Instalar** (um de três canais):
+
+   ```sh
+   # canal npm (versões publicadas: comece por aqui)
+   dsh plugin --profile web add dsh-primer
+   # canal git (main mais recente): dist/ não está no repositório, o pnpm precisa permitir o build prepare deste pacote
+   dsh plugin --profile web add github:PerryLink/dsh-primer#<sha>
+   # canal tarball: após pnpm pack neste repositório
+   dsh plugin --profile web add ./dsh-primer-<version>.tgz
+   ```
+
+2. **Reiniciar e confirmar que a linha foi montada**:
+
+   ```sh
+   dsh --profile web --dump-config | grep -A3 'id: dsh-primer'
+   ```
+
+   ```text
+   - id: dsh-primer
+     name: dsh-primer
+   ```
+
+   O catálogo de skills da sessão deve listar `dsh-primer`; o corpo da skill é o `SKILL.md` do pacote, e suas referências relativas são resolvidas por um `resourceBase` de diretório para `guide/` e `references/`.
+
+3. **Prove em 60 segundos** (ou peça ao agente: *"Use a skill dsh-primer para construir um plugin de …"*):
+
+   ```sh
+   npx dsh-primer new hello-plugin                  # gera um repositório de plugin TS
+   cd hello-plugin && npx dsh-primer check --json   # 16 verificações estáticas
+   npx dsh-primer verify                            # empacotamento + smoke em perfil limpo
+   ```
+
+**Desinstalar**: `dsh plugin --profile web remove dsh-primer` (ou apague a linha do patch do perfil). O registro é um efeito do Cordis, então desinstalar desfaz tudo sem resíduos.
+
+> Para a primeira instalação use o canal npm. O canal git traz o código-fonte e `dist/` não está no repositório, então o pnpm precisa executar o build `prepare` deste pacote, o que exige permitir o pacote em `allowBuilds` do perfil. É um custo documentado das instalações git, não um defeito, mas proporciona uma péssima primeira experiência.
+
+<details>
+<summary>Instalar pelo mercado do DSH Desktop</summary>
+
+Todos os plugins da PerryLink podem ser navegados no mercado embutido do DSH Desktop: **Mercado → Fontes → adicionar fonte → colar** `https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json` **→ selecionar**. A instalação continua passando pela verificação de identidade npm do mercado e pela sua confirmação. No canal da loja 1024: `npm i -g dsh1024` e depois `dsh1024 plugin --profile web add dsh-primer`.
+
+</details>
+
+## Capacidades principais
+
+O `dsh-primer` é a base de conhecimento de desenvolvimento de plugins do DSH mais uma cadeia de ferramentas CLI, empacotada como um único bundle instalável. A base registra-se como a skill de agente `dsh-primer` (visível no catálogo de toda sessão, carregando sob demanda os passos de trabalho, a documentação oficial e as leituras da comunidade); o CLI `dsh-plugin-dev` acrescenta três camadas mecânicas em cima.
+
+- **Contrato de plugin e regras duras** — effects/disposers, listeners waterfall que precisam chamar `next()`, eventos de sessão de propriedade do host, visível-para-o-modelo ⟺ registrado, configuração Schemastery, regras de UI e desempenho.
+- **Espelho literal da documentação oficial** — `references/official-docs/`: cópia byte a byte dos documentos do repositório oficial (EN + ZH), idêntica ao upstream no último snapshot verificado, incluindo as páginas que nunca chegam ao site de documentação.
+- **Matriz de adaptação de versões** — [guide/version-matrix.md](guide/version-matrix.md): os cinco valores "latest", as tags `latest` congeladas dos subpacotes, os quatro seams de mudança incompatível, como escolher o intervalo peer, a linhagem do formato de sessão V0→V4 as 19 mudanças incompatíveis de `0.2.1-alpha.2` e os 46 seams da linha 0.2.2 publicados no rc.3 (`K1`–`K46`, ver migração §14).
+- **Guia de migração** — [guide/migration-0.2.md](guide/migration-0.2.md): cada mudança incompatível de `0.1.6-alpha.2` a `0.2.1-alpha.1` (formato de sessão V4, reconstrução de settings, remoção de invariantes, `readBytes`, slots novos, a fonte de mensagem `plugin` aposentada), cada uma com sua fonte oficial e uma lista de 12 verificações.
+- **Primer do Cordis e a skill oficial, destilada** — os cinco conceitos do Cordis e a linha do tempo de mecanismos; [references/official-plugin-dev-skill.md](references/official-plugin-dev-skill.md) destila as proibições de `cordis-plugin-development`, a lista de metadados de apresentação e as regras de UI/desempenho.
+- **Índice de bugs verificados** — [guide/unfixed-issues.md](guide/unfixed-issues.md): 22 não corrigidos + 11 recém-verificados, cada um com `path:line`, contorno e commit de correção, mais uma tabela projeto-vs-bug e uma seção explícita de "não reproduzível".
+- **Mais de 30 armadilhas reais** com causa raiz e correção (cópias duplas do cordis, o trio de tsconfig, sessões zstd multiframe, junctions do Windows, `latest` desatualizado no npm, instalações `file:` carregando uma cópia, gravações de patch em tempo real…).
+- **Leituras da comunidade** — 114 repositórios da comunidade arquivados (15 analisados a fundo), mais um índice de fontes em que cada fato liga à sua origem.
+- **Cadeia de ferramentas CLI** — `dsh-plugin-dev new / check / verify`: andaime, verificação estática (incluindo metadados de apresentação e manifestos multi-patch) e verificação de empacotamento de plugins DSH; cada verificação liga à seção da skill que aplica.
+- **Roteamento da cadeia de ferramentas da família e decisão de escopo do espelho** — [guide/family-toolchain.md](guide/family-toolchain.md) diz qual ferramenta responde a cada pergunta, com a tabela completa de 33 verificações do `dsh-plugin-doctor` cruzada com as 16 deste repositório; [references/mirror-scope-decision.md](references/mirror-scope-decision.md) registra por que "apagar o conteúdo sem referências para economizar 80% do tamanho" não sobreviveu à remedição.
+- **Níveis de adoção (não oficiais)** — [guide/standards.md](guide/standards.md): o modelo DSH-ENTRY / DSH-FLOW / DSH-BOOST, a tabela profundidade × evidência, o que cada nível **não** afirma e como subir. A comparação GB / GB-T / GB-Z é apenas uma analogia; as notas de certificação A–D são ortogonais.
+
+### Superfícies
+
+| Superfície | Tipo | Notas |
+|---|---|---|
+| `dsh-primer` | skill | Registrada via `ctx.skills`; carrega `SKILL.md` + `./guide/` + `./references/` sob demanda |
+| `dsh-plugin-dev` | bin (CLI) | Subcomandos `new` / `check` / `verify`; não é uma linha de plugin DSH |
+
+## Mapa da base de conhecimento
+
+| Caminho | O que é |
+|---|---|
+| `SKILL.md` | A skill de agente `dsh-primer`: regras duras + caminhos de desenvolvimento por tipo de tarefa |
+| `package.json` · `cordis.patch.yml` · `index.js` · `locale/` · `icon.svg` | O bundle DSH instalável: manifesto `dsh.bundle.patch`, entrada que registra a skill e metadados de apresentação lidos pelo Plugin Manager |
+| `guide/plugin-dev-guide.md` | O guia de desenvolvimento completo (10 capítulos) |
+| `guide/version-matrix.md` | Matriz de adaptação de versões: os cinco "latest", tags `latest` congeladas, seams de mudança incompatível, escolha de intervalo peer, linhagem do formato de sessão, as 19 mudanças de `0.2.1-alpha.2` mais as 46 da linha 0.2.2 |
+| `guide/migration-0.2.md` | Guia de migração de mudanças incompatíveis da geração 0.2 (§0–§12 até `0.2.1-alpha.1`, §13 com os 19 seams de `0.2.1-alpha.2`, §14 com os 46 seams (`K1`–`K46`) publicados no rc.3 e os 13 da próxima versão em separado) |
+| `guide/unfixed-issues.md` | Índice de bugs verificado em fontes + lista corrigida no master + tabela projeto-vs-bug |
+| `guide/quick-reference.md` | Folha de consulta de uma página (5 idiomas) |
+| `guide/links.md` | Índice de URLs curado: documentação oficial de desenvolvimento (site ↔ cópias locais) + links da comunidade + páginas só do repositório |
+| `guide/when-to-retire-a-plugin.md` | Aposentar e congelar plugins: os critérios e os dados medidos de uma auditoria de portfólio (EN + ZH) |
+| `guide/choosing-a-plugin.md` | Escolher plugin: quem lidera cada superfície de capacidade, com os números medidos e as ressalvas de verificação (EN + ZH) |
+| `guide/family-toolchain.md` | Roteamento da cadeia de ferramentas da família: pergunta → dono → artefato citável; a tabela completa de 33 verificações do `dsh-plugin-doctor` cruzada com as 16 deste repositório |
+| `guide/standards.md` | Níveis de adoção (não oficiais): o modelo DSH-ENTRY / DSH-FLOW / DSH-BOOST e a tabela de dois eixos (EN + ZH) |
+| `references/official-docs/` | Cópia literal dos documentos do repositório oficial (EN + ZH); o selo de atualidade fica em `SNAPSHOT.md` |
+| `references/official-plugin-dev-skill.md` | Skill oficial de desenvolvimento de plugins, destilada |
+| `references/mirror-scope-decision.md` | Registro da decisão de escopo do espelho: por que ele não é cortado por "zero referências" (com um script de medição reexecutável) |
+| `references/*.md` | Relatórios de pesquisa: documentos do repositório, site, Cordis, o paper, ecossistema da comunidade, arquivo de 114 repositórios (15 analisados a fundo) |
+| `scripts/` | Scripts de download idempotentes + verificador de integridade + gerador de snapshot de tópicos + o gerador de imagens deste README |
+| `bin/` · `src/cli/` · `dist/` | O CLI `dsh-plugin-dev`: andaime, verificador, validador (TypeScript, empacotado com tsdown) |
+| `templates/` | Esqueletos de andaime TS + JS: modelo de contrato, Config, tests, `cordis.patch.yml`, metadados de locale, ícone, READMEs em cinco idiomas |
+| `downloads/` | Snapshots brutos — gerados por `scripts/`, não versionados |
+| `data/` | `facts.json` (o único lar dos números autoafirmados), `seams/index.json` (índice de seams consultável), `standards.json` |
+
+## Cadeia de ferramentas CLI
+
+O bundle inclui o CLI `dsh-plugin-dev`, sem dependências em tempo de execução (`bin/` → `dist/dsh-plugin-dev.js` empacotado com tsdown). Cada verificação cita a seção da skill que aplica, então um agente pode continuar auditando à mão.
+
+```sh
+dsh-plugin-dev new <name> [--lang ts|js] [--dir <path>] [--force] [--git]
+dsh-plugin-dev check [--cwd <dir>] [--json] [--strict]
+dsh-plugin-dev verify [--cwd <dir>] [--dsh <bin>] [--pnpm <bin>]
+dsh-plugin-dev seams <query> | --since <version>   # esta API existe no meu host alvo?
+```
+
+| Subcomando | O que faz |
+|---|---|
+| `new <name>` | Gera um repositório de plugin TS ou JS: modelo de contrato `src/index.ts`, Config do Schemastery, tests, tsdown/vitest, `cordis.patch.yml` comentado e READMEs em cinco idiomas. Idempotente; recusa destinos não vazios sem `--force`. |
+| `check` | Verificações estáticas: validade do `cordis.patch.yml`, metadados do `package.json` (ponteiro `dsh.bundle.patch`, peer deps, engines, lista de arquivos), consistência dos cinco READMEs e padrões de linha vermelha. Emite JSON consumível por CI. |
+| `verify` | `pnpm pack` e depois instala/inicia/desinstala o bundle num perfil `DSH_HOME` limpo em mkdtemp (alinhado com `verify:self-contained`). Falhas mostram a cauda do log e sugestões. |
+
+### Roteiro upstream
+
+O `dsh-plugin-dev` é candidato upstream do CLI oficial de desenvolvimento de plugins (item planejado C12): o andaime, o verificador e o validador são as camadas mecânicas, enquanto `SKILL.md` + `guide/` continuam sendo a camada cognitiva.
+
+## Exemplos
+
+Estes são os pontos de entrada reais do plugin; instale uma vez e chame um.
+
+### Exemplo detalhado
+
+**Comando**
+
+```sh
+dsh-plugin-dev seams L3
+```
+
+**Saída**
+
+```text
+1 seam(s):
+
+L3  webRuntime service replaced by webStartup
+    kind        service-renamed
+    lands in    0.2.1-alpha.2
+    confidence  documented
+    official    docs/upgrade-guide/v0.2.1-alpha.1/web-listener-trust-config/guide.md
+    removed     service webRuntime; row web-runtime; ctx.webRuntime.lanAddresses; wildcard --host
+    instead     webStartup (row web-startup), concrete host literals
+    detectable  yes — inspect: src/**/*.ts, cordis.patch.yml
+```
+
+*Observed from `src/cli/commands/seams.ts:54; data/seams/index.json:66`*
+
+### Ramo de falha
+
+**Entrada**
+
+```text
+node bin/dsh-plugin-dev.js seams no-such-seam-xyz
+```
+
+**Saída**
+
+```text
+no seam or capability matches "no-such-seam-xyz". This is an absence of evidence in the knowledge base, not evidence that the API is absent from your target host — check references/official-docs/ before concluding either way.
+```
+
+*Observed from `src/cli/lib/seams.ts:122-130; src/cli/commands/seams.ts:87-92; tests/seams.test.ts:88-90`*
+
+### Exemplos curtos
+
+`dsh-plugin-dev check --json` · `dsh-plugin-dev seams L3`
+
+## Configuração
+
+O bundle da skill não expõe nenhum `Config` do Schemastery: registra a base de conhecimento como skill de agente sem chaves ajustáveis, e o `cordis.patch.yml` apenas insere a própria linha. Tudo o que é ajustável fica no CLI `dsh-plugin-dev` e é lido de uma flag ou de uma variável de ambiente `DSH_PLUGIN_DEV_*`.
+
+| Chave | Flag | Ambiente | Padrão |
+|---|---|---|---|
+| `DSH_PLUGIN_DEV_TEMPLATES` | — | `DSH_PLUGIN_DEV_TEMPLATES` | `<package>/templates` |
+| `--dsh` | `--dsh` | `DSH_PLUGIN_DEV_DSH` | `dsh` |
+| `--pnpm` | `--pnpm` | `DSH_PLUGIN_DEV_PNPM` | `pnpm` |
+| `--timeout` | `--timeout` | `DSH_PLUGIN_DEV_TIMEOUT` | `300000` ms |
+| `--smoke-timeout` | `--smoke-timeout` | `DSH_PLUGIN_DEV_SMOKE_TIMEOUT` | `120000` ms |
+
+Para desativar: apague a linha do patch do perfil, ou execute `dsh plugin --profile web remove dsh-primer`.
+
+<details>
+<summary>Arquivo de patch completo (cordis.patch.yml, 9 linhas)</summary>
+
+```yaml
+# dsh-primer bundle layer: register the packaged knowledge base as an agent skill.
+# This file is the `dsh.bundle.patch` layer (see package.json#dsh.bundle.patch).
+# Layer semantics: a YAML array of row verbs; `insert` adds plugin rows to the
+# composed config. Later layers override a row by `id` (whole-config replacement).
+- insert:
+    # `id`: stable row identifier used by later layers to override this row.
+    - id: dsh-primer
+      # `name`: the module the loader imports; resolves to this package's entry (package.json#main → index.js).
+      name: dsh-primer
+```
+
+</details>
+
+## FAQ
+
+<details>
+<summary>A base de conhecimento vai me servir documentação desatualizada sem avisar?</summary>
+
+Não. O espelho fixa seu commit de origem, tag, hora de sincronização e número de páginas em `references/official-docs/SNAPSHOT.md`; `.github/workflows/docs-drift.yml` compara toda semana a ponta do `master` upstream com esse commit e abre uma issue nomeando os arquivos alterados quando há deriva. A atualização continua sendo uma ação humana (`scripts/sync-official-docs.ps1`). `data/facts.json` é o único lar dos números que este projeto afirma sobre si mesmo, e `check:facts` recusa a prosa que não concorda com ele.
+
+</details>
+
+<details>
+<summary>Instalá-lo muda meu perfil ou outros plugins?</summary>
+
+Não. O patch do bundle apenas `insert` a própria linha (`id: dsh-primer`) e nunca sobrescreve o `config` de uma linha embutida. Em `apply()` o plugin registra somente uma skill via `ctx.skills`, envolvida em `ctx.effect()`, então parar ou recarregar a quente desfaz tudo. Ele não registra ferramentas, comandos, chaves de slot de cliente nem prefixos `webServer`, e não escuta nenhum evento sensível à ordem como `agent/pre-step`.
+
+</details>
+
+<details>
+<summary>Ele faz requisições de rede ou chama um modelo?</summary>
+
+Não. Em tempo de execução ele só lê o próprio `guide/` e `references/` empacotados: sem requisições de rede, sem gravações e sem chamadas ao modelo; `package.json#dshWorkshop.permissions` declara apenas `filesystem:read`. A única rede é você executando `scripts/download-*.ps1` para gerar os snapshots brutos em `downloads/`.
+
+</details>
+
+<details>
+<summary>Como os cinco READMEs e os números da base se mantêm sincronizados?</summary>
+
+Quatro portões rodam na CI: `check:readmes` compara a estrutura de seções e as chaves de configuração entre os cinco idiomas, `check:parity` compara o número de blocos por seção, `check:facts` valida os números autoafirmados contra `data/facts.json`, e `check:ps1-bom` mantém o BOM UTF-8 dos scripts PowerShell. `scripts/verify-kit.ps1` acrescenta uma varredura de caminhos críticos e links relativos.
+
+</details>
+
+## Limites de segurança
+
+- **Base de conhecimento somente leitura.** O bundle só lê seus próprios arquivos; nunca escreve, nunca acessa a rede e nunca invoca um modelo.
+- **A documentação oficial são cópias literais.** `references/official-docs/` nunca é editado aqui; reporte os problemas ao upstream e ressincronize apenas com `scripts/sync-official-docs.ps1`.
+- **Limites de distribuição.** O conteúdo de terceiros empacotado mantém sua licença upstream; veja [NOTICE.md](NOTICE.md) (por exemplo `downloads/` é apenas local e `awesome-dsh-plugins` não deve ser redistribuído).
+
+## Permissões e dados
+
+- **Permissões**: `package.json#dshWorkshop.permissions` declara apenas `filesystem:read`; `apply()` lê o `SKILL.md` empacotado, e as referências relativas do corpo da skill são resolvidas por um `resourceBase` de diretório para `guide/` e `references/` do pacote.
+- **Dados**: somente leitura — não escreve no workspace nem fora do perfil; não inclui telemetria e não envia dados à PerryLink. A retenção das sessões e logs do host permanece sob controle do host.
+
+## Limitações conhecidas
+
+- **A documentação oficial é um snapshot.** Ressincronize com `scripts/sync-official-docs.ps1` quando o upstream se mover; o selo de atualidade e o hash do commit ficam em `references/official-docs/SNAPSHOT.md`.
+- **`downloads/` é gerado, não versionado.** Os snapshots brutos (arquivos de repositórios da comunidade, Discussions, artigos) precisam ser gerados com `scripts/download-*.ps1` antes de usar.
+- **O conteúdo de `awesome-dsh-plugins` é apenas local.** Seu upstream declara uma restrição de uso interno, então ele não é redistribuído com o repositório.
+
+## Interoperabilidade com outros plugins DSH
+
+Este plugin **não** interfere em outros plugins:
+
+- **Sua única dependência é o serviço `skills`.** Registra uma skill via `ctx.skills`, não importa nenhuma implementação do host e não fornece nenhuma chave de serviço.
+- **Sem colisão de ferramentas ou comandos.** Não registra ferramentas nem comandos, então não ocupa nenhum nome nu.
+- **Sem colisão de slots ou de rotas HTTP.** Não registra chaves de slot de cliente nem qualquer prefixo `webServer`.
+- **Sem colisão de camadas de patch.** O patch do bundle apenas `insert` a própria linha e nunca sobrescreve o `config` de uma linha embutida.
+- **Sem listeners de eventos compartilhados.** Não escuta nenhum evento sensível à ordem, então não há cadeia waterfall que possa curto-circuitar.
+- **O registro é um efeito.** `ctx.effect(() => ctx.skills.register(...))` fornece tudo e parar ou recarregar a quente desfaz.
+
+## Compatibilidade
+
+| Superfície | Estado |
+|---|---|
+| Harness | `engines.dsh` = `>=0.2.1-0 <0.3.0 \|\| >=0.2.2-0 <0.3.0`. Linha atual do host: npm `latest` = `0.2.2-rc.1`, `next` = `0.2.2-rc.3`, `alpha` = `0.2.2-alpha.3`, tag mais recente = `dsh-v0.2.2-rc.3`; **não existe linha estável** — as 44 versões do npm e as 39 releases do GitHub são prereleases. O espelho da documentação oficial está fixado na tag `dsh-v0.2.2-rc.3` (`38a6a5c9…`, sincronizado em 2026-11-14, 709 páginas md / 352 pares EN-ZH). |
+| Node | `>=24.9.0` |
+| Plataformas | Onde o DSH rodar (bundle ESM puro; sem código nativo, sem rede) |
+| Modelo | Qualquer (sem interação com modelos: o host injeta o corpo da skill no contexto) |
+
+## Canais de publicação
+
+Todos os canais resolvem a partir deste repositório ou do npm, então uma tag chega a todos:
+
+| Canal | Fonte da verdade | Como atualiza |
+|---|---|---|
+| npm (`dsh-primer`) | o `package.json` deste repositório | `.github/workflows/release.yml` com uma tag `v*`: portão `verify-kit` → verificação da seção do CHANGELOG → `npm publish --provenance` (pulado quando a versão já existe) |
+| GitHub Release | a mesma tag | o mesmo workflow a cria de forma idempotente a partir da tag |
+| Selos de descoberta (versão npm, dshfind, OpenSSF, DSH Market) | consultas ao vivo | não há nada a publicar: leem o npm/o registry em cada render |
+| DSH Desktop Market / dsh1024 | npm | o mercado instala o pacote npm, então uma versão publicada é instalável na hora; sem envio por versão |
+
+## Ecossistema e qualidade
+
+- [Página do pacote npm](https://www.npmjs.com/package/dsh-primer) (versões publicadas e downloads)
+- [Página do plugin no dshfind](https://dshfind.com/plugins/PerryLink/dsh-primer) (instalações e ranking)
+- [Relatório OpenSSF Scorecard](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-primer) (impulsionado por [.github/workflows/scorecard.yml](.github/workflows/scorecard.yml))
+- [Relatório de verificação do dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor#verified-徽章) (o cruzamento com as 16 verificações deste repositório está em [guide/family-toolchain.md](guide/family-toolchain.md))
+- [DSH Market](https://dsh.market/) (listado)
+- **Canal da loja 1024**: `npm i -g dsh1024` e depois `dsh1024 plugin --profile web add dsh-primer` (conta para o ranking de instalações do [deepseek1024.com](https://deepseek1024.com))
+- [Site de documentação](https://perrylink.github.io/dsh-primer/): cada capítulo em sua própria página, mais um [llms.txt](https://perrylink.github.io/dsh-primer/llms.txt) legível por máquina
+
+## Manter a base atualizada
+
+```sh
+pwsh -File scripts/sync-official-docs.ps1                     # cópia literal da documentação a partir de um checkout local
+pwsh -File scripts/download-sources.ps1                       # site/documentação oficial, Cordis, paper
+pwsh -File scripts/download-community-repos.ps1               # repositórios da comunidade (tarballs do codeload)
+pwsh -File scripts/download-community-articles.ps1            # artigos zh/en/HN da comunidade
+pwsh -File scripts/archive-discussions.ps1                    # Discussions oficiais (precisa de $env:GH_TOKEN)
+pwsh -File scripts/gen-topic-snapshot.ps1 -OutDir <dir>       # censo do tópico dsh-plugin
+pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>        # caminhos críticos + varredura de links + deriva de docs
+```
+
+## Desenvolvimento
+
+O bundle da skill (`index.js`) é ESM puro sem etapa de build; o CLI `dsh-plugin-dev` é TypeScript construído pelo tsdown. Portões:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run typecheck && pnpm run typecheck:ci
+pnpm test
+pnpm run build
+pnpm run verify:artifacts        # autoverificação + smoke de andaime (sem rede)
+pnpm run verify:self-contained   # empacotamento + smoke de instalação/início/desinstalação em perfil limpo
+pnpm run check:readmes           # os cinco READMEs compartilham estrutura de seções e chaves
+pnpm run check:parity            # os cinco READMEs têm os mesmos blocos por seção
+pnpm run check:facts             # os números autoafirmados coincidem com data/facts.json
+pnpm run check:ps1-bom           # os scripts PowerShell mantêm o BOM UTF-8
+pnpm pack
+pwsh -File scripts/verify-kit.ps1   # caminhos críticos + varredura de links (+ deriva de docs com -Checkout <checkout>)
+```
+
+As imagens do README são geradas por [`scripts/gen-readme-assets.py`](scripts/gen-readme-assets.py) (Pillow para o hero, SVG escrito à mão para o diagrama); é idempotente e reescreve `docs/assets/dsh-primer-hero-{zh,en}-{light,dark}.webp` e `docs/assets/dsh-primer-flow-v5-{light,dark}.svg`.
+
+Tópicos: `dsh`, `deepseek-harness`, `dsh-plugin`, `cordis`, `agent-skill`, `plugin-development`, `knowledge-base`, `cli`, `scaffold`, `checker`
+
+## Família e agradecimentos
+
+Este projeto faz parte da família de plugins do DeepSeek Harness da [PerryLink](https://github.com/PerryLink) (todos Apache-2.0). Se este plugin ajudar você, **dê uma estrela**: nada é liberado por isso, mas faz a próxima pessoa encontrá-lo antes.
+
+- [@PerryLink](https://github.com/PerryLink) — criador e mantenedor: conteúdo da base de conhecimento, a transformação em bundle instalável, envios ao ecossistema e engenharia de comunidade.
+- [@Yisa-yi](https://github.com/Yisa-yi) — **product manager**. Participou de todo o arco de design: a decisão de entregá-lo como bundle instalável que registra uma skill de agente sob demanda, a arquitetura de informação do guia de 10 capítulos, a regra de "cada fato liga à sua origem" e a separação entre a camada cognitiva (`SKILL.md` + `guide/`) e a camada mecânica (`dsh-plugin-dev new / check / verify`). Também definiu o padrão de evidência de `guide/unfixed-issues.md` e os critérios de congelamento/aposentadoria de `guide/when-to-retire-a-plugin.md`.
+- A manutenção diária conta com a ajuda de agentes do DeepSeek Harness (eles não têm conta no GitHub e são listados aqui por transparência, não como contribuidores).
+
+<details>
+<summary>Expandir todos os plugins</summary>
+
+| Plugin | Status |
+|---|---|
+| **[dsh-aqua-input-check](https://github.com/PerryLink/dsh-aqua-input-check)** |  |
+| **[dsh-archive-check](https://github.com/PerryLink/dsh-archive-check)** |  |
+| **[dsh-auto-review](https://github.com/PerryLink/dsh-auto-review)** |  |
+| **[dsh-autotier](https://github.com/PerryLink/dsh-autotier)** | 🧊 CONGELADO — ver o README do repo |
+| **[dsh-bid-ca-precheck](https://github.com/PerryLink/dsh-bid-ca-precheck)** |  |
+| **[dsh-bid-qual-check](https://github.com/PerryLink/dsh-bid-qual-check)** |  |
+| **[dsh-cert-mcp](https://github.com/PerryLink/dsh-cert-mcp)** | 🧊 CONGELADO — ver o README do repo |
+| **[dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind)** |  |
+| **[dsh-click](https://github.com/PerryLink/dsh-click)** |  |
+| **[dsh-composer-history](https://github.com/PerryLink/dsh-composer-history)** |  |
+| **[dsh-contract-stance](https://github.com/PerryLink/dsh-contract-stance)** |  |
+| **[dsh-customs-doc-check](https://github.com/PerryLink/dsh-customs-doc-check)** |  |
+| **[dsh-data-quality](https://github.com/PerryLink/dsh-data-quality)** | 🧊 CONGELADO — ver o README do repo |
+| **[dsh-demurrage-ledger](https://github.com/PerryLink/dsh-demurrage-ledger)** |  |
+| **[dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck)** |  |
+| **[dsh-drill-script-check](https://github.com/PerryLink/dsh-drill-script-check)** |  |
+| **[dsh-eia-guide-check](https://github.com/PerryLink/dsh-eia-guide-check)** |  |
+| **[dsh-emergency-plan](https://github.com/PerryLink/dsh-emergency-plan)** |  |
+| **[dsh-essay-rubric-check](https://github.com/PerryLink/dsh-essay-rubric-check)** |  |
+| **[dsh-evidence-check](https://github.com/PerryLink/dsh-evidence-check)** |  |
+| **[dsh-export-ctl-check](https://github.com/PerryLink/dsh-export-ctl-check)** |  |
+| **[dsh-fast](https://github.com/PerryLink/dsh-fast)** |  |
+| **[dsh-fmea-table-check](https://github.com/PerryLink/dsh-fmea-table-check)** |  |
+| **[dsh-forecast-penalty](https://github.com/PerryLink/dsh-forecast-penalty)** |  |
+| **[dsh-fund-research](https://github.com/PerryLink/dsh-fund-research)** |  |
+| **[dsh-github](https://github.com/PerryLink/dsh-github)** |  |
+| **[dsh-gongwen-flow-check](https://github.com/PerryLink/dsh-gongwen-flow-check)** |  |
+| **[dsh-gongwen-word-check](https://github.com/PerryLink/dsh-gongwen-word-check)** |  |
+| **[dsh-guard-plan-qc](https://github.com/PerryLink/dsh-guard-plan-qc)** |  |
+| **[dsh-hazchem-check](https://github.com/PerryLink/dsh-hazchem-check)** |  |
+| **[dsh-hazplan-check](https://github.com/PerryLink/dsh-hazplan-check)** |  |
+| **[dsh-hidden-risk-map](https://github.com/PerryLink/dsh-hidden-risk-map)** |  |
+| **[dsh-hs-classify](https://github.com/PerryLink/dsh-hs-classify)** |  |
+| **[dsh-icd-rule-check](https://github.com/PerryLink/dsh-icd-rule-check)** |  |
+| **[dsh-industry-research](https://github.com/PerryLink/dsh-industry-research)** |  |
+| **[dsh-lawcite-adapter](https://github.com/PerryLink/dsh-lawcite-adapter)** |  |
+| **[dsh-laya](https://github.com/PerryLink/dsh-laya)** |  |
+| **[dsh-lc-doc-check](https://github.com/PerryLink/dsh-lc-doc-check)** |  |
+| **[dsh-learning-gap-check](https://github.com/PerryLink/dsh-learning-gap-check)** |  |
+| **[dsh-library](https://github.com/PerryLink/dsh-library)** |  |
+| **[dsh-local-ai](https://github.com/PerryLink/dsh-local-ai)** |  |
+| **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** |  |
+| **[dsh-mask](https://github.com/PerryLink/dsh-mask)** |  |
+| **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** |  |
+| **[dsh-medrec-qc](https://github.com/PerryLink/dsh-medrec-qc)** |  |
+| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | 🧊 CONGELADO — ver o README do repo |
+| **[dsh-nsfc-form-check](https://github.com/PerryLink/dsh-nsfc-form-check)** |  |
+| **[dsh-nurse-record-check](https://github.com/PerryLink/dsh-nurse-record-check)** |  |
+| **[dsh-observe](https://github.com/PerryLink/dsh-observe)** |  |
+| **[dsh-origin-rvc-check](https://github.com/PerryLink/dsh-origin-rvc-check)** |  |
+| **[dsh-ota-review-check](https://github.com/PerryLink/dsh-ota-review-check)** |  |
+| **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** |  |
+| **[dsh-paper-doc-adapter](https://github.com/PerryLink/dsh-paper-doc-adapter)** |  |
+| **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** |  |
+| **[dsh-permit-report-check](https://github.com/PerryLink/dsh-permit-report-check)** |  |
+| **[dsh-pipeline-check](https://github.com/PerryLink/dsh-pipeline-check)** |  |
+| **[dsh-pleading-draft](https://github.com/PerryLink/dsh-pleading-draft)** |  |
+| **[dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor)** | 🚫 APOSENTADO (repo arquivado) |
+| **[dsh-primer](https://github.com/PerryLink/dsh-primer)** |  |
+| **[dsh-plugin-kit](https://github.com/PerryLink/dsh-plugin-kit)** | 🚫 APOSENTADO (repo arquivado) |
+| **[dsh-plugin-upgrade](https://github.com/PerryLink/dsh-plugin-upgrade)** | 🚫 APOSENTADO (repo arquivado) |
+| **[dsh-policy-brief-draft](https://github.com/PerryLink/dsh-policy-brief-draft)** |  |
+| **[dsh-power-loss-split](https://github.com/PerryLink/dsh-power-loss-split)** |  |
+| **[dsh-power-ticket-check](https://github.com/PerryLink/dsh-power-ticket-check)** |  |
+| **[dsh-ppap-check](https://github.com/PerryLink/dsh-ppap-check)** |  |
+| **[dsh-protest-deadline](https://github.com/PerryLink/dsh-protest-deadline)** |  |
+| **[dsh-railway-window](https://github.com/PerryLink/dsh-railway-window)** |  |
+| **[dsh-repair-order-qc](https://github.com/PerryLink/dsh-repair-order-qc)** |  |
+| **[dsh-research-report](https://github.com/PerryLink/dsh-research-report)** |  |
+| **[dsh-review-reply-check](https://github.com/PerryLink/dsh-review-reply-check)** |  |
+| **[dsh-rulefile-check](https://github.com/PerryLink/dsh-rulefile-check)** |  |
+| **[dsh-safety-brief-check](https://github.com/PerryLink/dsh-safety-brief-check)** |  |
+| **[dsh-score](https://github.com/PerryLink/dsh-score)** | 🧊 CONGELADO — ver o README do repo |
+| **[dsh-session-sync](https://github.com/PerryLink/dsh-session-sync)** |  |
+| **[dsh-site-log-check](https://github.com/PerryLink/dsh-site-log-check)** |  |
+| **[dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security)** |  |
+| **[dsh-soe-decision-check](https://github.com/PerryLink/dsh-soe-decision-check)** |  |
+| **[dsh-soilwater-check](https://github.com/PerryLink/dsh-soilwater-check)** |  |
+| **[dsh-sop-sync-check](https://github.com/PerryLink/dsh-sop-sync-check)** |  |
+| **[dsh-spc-gbt-adapter](https://github.com/PerryLink/dsh-spc-gbt-adapter)** |  |
+| **[dsh-talk](https://github.com/PerryLink/dsh-talk)** |  |
+| **[dsh-tender-extract](https://github.com/PerryLink/dsh-tender-extract)** |  |
+| **[dsh-tender-matrix](https://github.com/PerryLink/dsh-tender-matrix)** |  |
+| **[dsh-test-drive](https://github.com/PerryLink/dsh-test-drive)** |  |
+| **[dsh-ticktick](https://github.com/PerryLink/dsh-ticktick)** | 🚫 APOSENTADO (repo arquivado) |
+| **[dsh-translate](https://github.com/PerryLink/dsh-translate)** |  |
+| **[dsh-warranty-calc](https://github.com/PerryLink/dsh-warranty-calc)** |  |
+| **[dsh-budget](https://github.com/PerryLink/dsh-budget)** | 🧊 CONGELADO — ver o README do repo |
+| **[dsh-claude-move](https://github.com/PerryLink/dsh-claude-move)** | 🧊 CONGELADO — ver o README do repo |
+| **[dsh-defend](https://github.com/PerryLink/dsh-defend)** | 🧊 CONGELADO — ver o README do repo |
+| **[dsh-draw](https://github.com/PerryLink/dsh-draw)** | 🧊 CONGELADO — ver o README do repo |
+| **[dsh-reach](https://github.com/PerryLink/dsh-reach)** | 🧊 CONGELADO — ver o README do repo |
+| **[dsh-background-agents](https://github.com/PerryLink/dsh-background-agents)** | 🚫 APOSENTADO (repo arquivado) |
+| **[dsh-session-pin](https://github.com/PerryLink/dsh-session-pin)** | 🚫 APOSENTADO (repo arquivado) |
+| **[dsh-team-rooms](https://github.com/PerryLink/dsh-team-rooms)** | 🚫 APOSENTADO (repo arquivado) |
+
+</details>
+
+## Licença
+
+[LICENSE](LICENSE) (Apache License 2.0) © 2026 dsh-primer contributors — nosso próprio texto (`SKILL.md`, `guide/`, `references/`, `scripts/`, este README) é Apache-2.0; o conteúdo de terceiros empacotado está documentado em [NOTICE.md](NOTICE.md).
+
+<p align="center"><sub>Apache-2.0 · Plugin da comunidade, sem afiliação com a DeepSeek.</sub></p>
+
+## Cadeia de ferramentas e upstream (fatos, 2026-11)
+
+- Este repositório é a skill / CLI de desenvolvimento legada; as verificações atuais ficam em `dsh-standards`, o guia em `dsh-plugin-guide` e o gerador em `dsh-plugin-start`.
+- Upstream: `dsh-plugin-hub` main inclui uma verificação de metadados npm ciente da versão ([`4f3a560`](https://github.com/dshplugin/dsh-plugin-hub/commit/4f3a560), 2026-11-09); o escopo é apenas metadados npm na instalação; não executa ENTRY nem constitui aval.

package/SKILL.md

@@ -24,9 +24,11 @@ description: Use when developing, reviewing, packaging, debugging, or answering
    |---|---|---|
    | `< 0.1.7-alpha.1` | 旧基线 | 本世代破坏性变更**全部适用** → `guide/migration-0.2.md` §0–§12 逐条改 |
    | `0.1.7-alpha.1` – `0.2.1-alpha.1` | 中间线 | 会话格式 V4 已生效；§13 的 19 条**不适用** |
-   | `0.2.1-alpha.2` 或更新 | 最新线 | §13 的 19 条**适用** → `guide/version-matrix.md` §3 |
-   | **npm `latest`（= `0.2.0-rc.2`）** | **默认安装拿到的就是这一版** | ⚠️ 它**早于** master 一版：§13 不适用，但 `version-matrix.md` §1.1 的"不存在稳定版"警告适用 |
-   **四个"最新"不是同一个东西**：npm `latest`=`next`=`0.2.0-rc.2`、npm `alpha`=`0.2.1-alpha.2`、master 最新 tag = `dsh-v0.2.1-alpha.2`。**不存在稳定版**（全部 31 个 npm 版本都是 prerelease）。完整谱系、子包 `latest` 冻结陷阱与 peer 区间选择见 `guide/version-matrix.md`。
+   | `0.2.1-alpha.2` – `0.2.2-alpha.2` | 0.2.1 尾线 | §13 的 19 条**适用**；`§14` 的 0.2.2 线（`K1`–`K46`）尚未落地 |
+   | `0.2.2-alpha.3` – `0.2.2-rc.1` | 0.2.2 线中段 | `K1`–`K22` 已落地（alpha.3）、`K23`–`K27` 已落地（rc.1）；`K28`–`K46` 尚未 |
+   | `0.2.2-rc.2` 或更新（当前 `0.2.2-rc.3`） | **当前线** | §13 + §14 全部 **46 条**（`K1`–`K46`）适用；`v0.2.2-rc.2` 的 13 条指南是**下一版**内容，**不适用** |
+   | **npm `latest`（= `0.2.2-rc.1`）** | **默认安装拿到的就是这一版** | 它**早于**最新 tag 两个发布：`K28`–`K46` 尚未落地，其余同 0.2.2 线 |
+   **几个"最新"不是同一个东西**：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`（2026-11-13）。**不存在稳定版**（全部 44 个 npm 版本与 39 个 GitHub Release 都是 prerelease）。完整谱系、子包 `latest` 冻结陷阱与 peer/engines 区间选择见 `guide/version-matrix.md`。
 1. 若未读过 Cordis 概念：读 `references/official-docs/docs/cordis-primer.md`（5 个概念，5 分钟）；需要动手跟练时跑 `references/official-docs/docs/cordis-tutorial/` 01-07（无 API key 可跑）。
 2. 打开 `guide/quick-reference.md`（契约速查）+ `guide/plugin-dev-guide.md`（完整路径）。官方/社区文档 URL 对照见 `guide/links.md`。排查官方运行时行为/未修复 bug 时查 `guide/unfixed-issues.md`（master 基线源码核实的问题清单 + 已修复提交号 + 设计行为对照 + 本世代新核实的 T1–T11）。决定一个插件**该不该继续维护**（官方已进内核 / 第三方采用度显著更高）时查 `guide/when-to-retire-a-plugin.md`（判据 + 实测倍数表）；判断某个能力面谁领先时查 `guide/choosing-a-plugin.md`。
 2b. **要判断"该改哪一行 / 该找哪个工具"时**，读 `guide/family-toolchain.md`（家族工具链路由：问题→所有者→可引用产物；`dsh-plugin-doctor` 33 项检查全表与裁定语义；本库 16 项检查与 doctor 的交叉对照）。发布流水线（多插件组合的持续可安装/可发布/可升级）见 `guide/release-engineering.md`。
@@ -50,7 +52,7 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 - 可替换能力按三层接缝设计：Service Definition / Provider / Consumer；不提前拆。
 - 打包：bundle 清单 `"dsh":{"bundle":{"patch":"..."}}`（`patch` **可为有序数组**，每个文件的相对路径按各自目录解析）；覆盖按 `id` 整行替换 config（上游删行后 override **静默失效**，升级后跑 `--dump-config` 查 `patch: entry not found`）；`!!js`（双感叹号）；git 安装需要 `prepare` 脚本与用户侧 `allowBuilds`，发布 npm/tarball 免构建许可。
 - **交付必须补展示元数据**：`locale/*.json` 的 `meta.title`/`meta.description` + 导出的 `./icon`（≤256 KiB、realpath 后必须在包内）；子路径插件**不读** `package.json`。
-- **共享实例的 dsh 包只放 peerDependencies + devDependencies**，绝不放 dependencies（profile 内副本会静默遮蔽运行时版本，核心服务注册失败）。⚠️ **peer 范围会被安装期强制**（早期版本写成"DSH 不校验"，**已更正**）：`dsh plugin add` 拿运行时版本比对声明的 `@deepseek-ai/dsh-*` 范围，不匹配即**拒绝安装**；`engines.dsh` 才是纯声明、零强制。范围只能表达"能不能装"，**表达不了某个 API 在不在**——仍要配运行时探测。区间选择见 `guide/version-matrix.md` §4。
+- **共享实例的 dsh 包只放 peerDependencies + devDependencies**，绝不放 dependencies（profile 内副本会静默遮蔽运行时版本，核心服务注册失败）。⚠️ **兼容性门禁在安装/启动时强制**（早期版本写成"DSH 不校验 peer"，**已更正**）：**清单里有 `engines.dsh` 时，它单独决定结果并忽略 `@deepseek-ai/dsh*` peers**；只有**没有** `engines.dsh` 时才回退到 peer 范围。判定用 `includePrerelease: true`，所以下界要带预发布（`>=0.2.2-0 <0.3.0`）；`workspace:` 在 `engines.dsh` 里不合法；声明了 `engines.dsh` 就必须让它覆盖全部支持版本。范围只能表达"能不能装"，**表达不了某个 API 在不在**——仍要配运行时探测。区间选择见 `guide/version-matrix.md` §4，官方语义见 `references/official-docs/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md`。
 - **UI 插件**：只渲染 slot 里的 React 组件（禁止 iframe 托管页面）；样式只用 `--dsw-alias-*` 主题 token；不 `require` 任何 Harness Client 包（抛错组件会把整个 slot 搞白）；`dsh.client.inject` **必须是静态数组**；不在组件外写 DOM、不往 `document.body` 追加。
 - **性能**：per-session 状态放 `ctx.sessionProjections`（纯同步 apply、忽略即同引用、纯 JSON + `stateVersion`）；等持久事件（`turn/end`/`assistant/message`/`tool/result`），实时 token 读 `agent/assistant-stream`；**不轮询 `agent/status`**。
 - **禁止**：在会话运行期间改 profile 的 `cordis.patch.yml`（HMR 会重载，实测丢光 preset 工具、杀掉在途 turn、最坏永久废掉 `sessionController`）；手写 profile 的 `package.json`；在 profile 目录里跑 pnpm。
@@ -69,7 +71,7 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 - **权限 / 审批 / 沙箱**：`docs/subsystems/approval.md`（审批流与 `ask` 决策）+ `docs/subsystems/permission-presets.md`（预设档位）+ `docs/subsystems/sandbox.md`（进程约束及其已知边界：Windows ACL 部分强制）。需要拦截工具调用时读 `docs/cookbook/extension-cookbook.md` 的 permission-gate 范例。
 - **上下文 / 压缩 / 性能**：`docs/subsystems/compaction.md`（压缩缝与阈值语义）+ `docs/subsystems/spill.md`（溢出存储：只负责存储，无保留策略、无检索 API）；`ctx` 自身的 API 面见 `docs/cordis-api/context.md`（**没有** subsystems 版的 context 页）。per-session 派生状态用 `ctx.sessionProjections`（见 §4.8 第 5 条）。
 - **打包/发布**：`docs/user/develop/basic/publish.md`（bundle/profile、层顺序、多 patch 数组、peer 解析、git 安装坑）。
-- **升级/迁移**：`guide/version-matrix.md`（**版本适配矩阵：先读这个**——五个"最新"、子包 `latest` 冻结、破坏性变更断层、peer 区间选择、会话格式 V0→V4）→ `guide/migration-0.2.md`（本库综述，0.1.6→0.2.1-alpha.1）→ `docs/upgrade-guide/**`（官方逐版本迁移指南）+ `docs/persistence-changes/**`（持久化类型变更记录）+ `docs/session-format-status.md`（会话格式版本权威）。⚠️ **目标宿主是 `0.2.1-alpha.2` 或更新时**：`version-matrix.md` §3 列了该版落的 **19 条破坏性变更**（`webRuntime`→`webStartup`、`mode: both` 被拒、`backgroundMode`/`run_in_background` 移除、`{{cwd}}` 移除、`BundleInfo` 新增必填字段、`dsh plugin --profile` 位置强制等），`migration-0.2.md` **尚未并入**。
+- **升级/迁移**：`guide/version-matrix.md`（**版本适配矩阵：先读这个**——几个"最新"、子包 `latest` 冻结、破坏性变更断层、peer/engines 区间选择、会话格式 V0→V4）→ `guide/migration-0.2.md`（本库综述，0.1.6→0.2.1 线 + §14 的 0.2.2 线）→ `docs/upgrade-guide/**`（官方逐版本迁移指南）+ `docs/persistence-changes/**`（持久化类型变更记录）+ `docs/session-format-status.md`（会话格式版本权威）。⚠️ **目标宿主落在 `0.2.2-rc.2` 或更新（当前 rc.3）时**：`version-matrix.md` §3 的 19 条（0.2.1-alpha.2 线）**与** `migration-0.2.md` §14 的 46 条（0.2.2 线，`K1`–`K46`）都适用——后者含 `engines.dsh` 门禁语义、`dsh-doc-skill`、`plugin-update-method`（`BundleInfo.updatable`→`update`）、`Session.append` 双 overload、`window-drag-regions`、`attachment-error-codes` 等。镜像里**没有** `v0.2.2-rc.2` 目录：那 13 条属下一版，别当 rc.3 变更。
 - **查服务/事件精确签名**：**优先用会话内 inspection**（`cordis_inspect_list` / `cordis_inspect_query`：Service / Event / Config / Tool / Slots / Theme），其次 `docs/subsystems/*.md` 生成式 Cordis API 区 + `docs/cordis-api/*`；**不要自造第二份静态清单**。站点 URL ↔ 本地副本对照见 `guide/links.md`，社区链接完整清单见 `references/community-ecosystem.md`。
 - **官方自带插件开发技能（0.2 世代新增，先读）**：`references/official-plugin-dev-skill.md`（主流程 + 六份分面参考要点 + 模板定位）；上游在 `packages/preset/agent-preset/skills/cordis-plugin-development/**`。它规定的官方路径是：工作区写 bundle → `plugin_manager` `install_bundle`（绝对目录）→ `cordis_inspect_query` 核对，**禁止**手写 profile 的 `package.json`/`cordis.patch.yml`、禁止在 profile 目录跑 pnpm。
 - **参考社区实现与实测坑**：`references/community-ecosystem.md`、`references/community-repo-deep-dive.md`（首批 15 个开发仓库深读）、`downloads/community-repos/`（**114 个仓库完整源码副本**，需先跑 `scripts/download-community-repos.ps1` 生成）。社区已确认的机制变化（repository-plugin 0811 移除、bundle vs 纯 cordis 双通道）与实测坑清单在 `guide/plugin-dev-guide.md` §7，源码级问题索引在 `guide/unfixed-issues.md`（含本世代新核实的 T1–T11）。官方 Discussions 全量归档（**2026-10-06 刷新**，含 #1629 官方插件脚手架 RFC）与 npm 全家桶元数据分别在 `downloads/github/harness/discussions/` 与 `downloads/npm/`；中英文社区文章 HTML 快照在 `downloads/web/community-articles/`。
@@ -85,9 +87,9 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 
 ## 知识库维护（需要时）
 
-- 同步官方文档副本：`pwsh -File ./scripts/sync-official-docs.ps1 [-Checkout <deepseek-harness checkout>]`——只同步 git 已跟踪文件（未跟踪草稿与未推送提交不会进来），并刷新 `references/official-docs/SNAPSHOT.md`；README 的"最后核验"日期与提交号引用 SNAPSHOT.md，不要手改。漂移校验：`pwsh -File ./scripts/check-docs-drift.ps1 -Checkout <checkout>`（快速）或 `pwsh -File ./scripts/verify-kit.ps1 -Checkout <checkout>`（全量）。
+- 同步官方文档副本：`pwsh -File ./scripts/sync-official-docs.ps1 [-Checkout <deepseek-harness checkout>] [-Ref <tag|sha>]`——用 `-Ref` 钉**发布 tag**（当前 = `dsh-v0.2.2-rc.3` / `38a6a5c9…`，709 篇 md / 352 对中英），不钉 master HEAD；只同步 git 已跟踪文件（未跟踪草稿与未推送提交不会进来），并刷新 `references/official-docs/SNAPSHOT.md`；README 的"最后核验"日期与提交号引用 SNAPSHOT.md，不要手改。新鲜度校验（无 checkout）：`node ./scripts/check-docs-drift.mjs`（比较最新 release tag 与 SNAPSHOT 的 Source ref；**不要**用旧的 branch-tip 探针，tag 钉住时它必然报 drift）。有 checkout 时用 `pwsh -File ./scripts/verify-kit.ps1 -Checkout <checkout>` 做逐文件哈希对比。
 - 刷新线上资料：`pwsh -File ./scripts/download-sources.ps1`；刷新社区仓库：`pwsh -File ./scripts/download-community-repos.ps1`；刷新社区文章快照：`pwsh -File ./scripts/download-community-articles.ps1`（三个脚本幂等，产出进 `./downloads/`）。刷新官方 Discussions 归档：`$env:GH_TOKEN=<token>; pwsh -File ./scripts/archive-discussions.ps1`（list.json + 精选线程评论，防缩水保护；**2026-10-06 期：list=5000、精选 1648**）。**注意 REST 分页天花板**：`/discussions` 列表最多翻到 5000 条，而仓库实际 total_count≈8850（GraphQL 口径）——需要更全的历史时按 GraphQL `UPDATED_AT DESC` 补抓。话题清单计数重核：`pwsh -File ./scripts/gen-topic-snapshot.ps1 -OutDir <dir> -MaxPages 10`。
-- **维护节奏建议**：官方 3 周内发了 9 个 prerelease，所以"最后核验"日期要跟 tag 走；每次官方发版后按 `references/official-docs/docs/upgrade-guide/**`（**无 index、无入链**，必须主动看）+ `docs/persistence-changes/**` + GitHub Releases 说明三处增量更新 `guide/migration-0.2.md` 与 `guide/unfixed-issues.md`。
+- **维护节奏建议**：0.2.2 线在 17 天内发了 5 个 prerelease（2026-10-27 `alpha.2` → 11-13 `rc.3`），所以"最后核验"日期要跟 tag 走；每次官方发版后按 `references/official-docs/docs/upgrade-guide/**`（**无 index、无入链**，必须主动看）+ `docs/persistence-changes/**` + GitHub Releases 说明三处增量更新 `guide/migration-0.2.md` 与 `guide/unfixed-issues.md`。
 - 安装/刷新 agent 技能副本：`pwsh -File ./scripts/install-skill.ps1 -Target <skill目录>`（跳过 downloads/ 与 .github/，逐字节校验）。
 - 冲突裁决：与官方文档冲突时以 `references/official-docs/`（官方仓库原文）为准；官方文档与**代码**冲突时以代码/产物为准并**明确标注分歧**（本轮已发现一例：`session-format-status.md` 的发布记录落后于代码与 npm）。
 
@@ -103,9 +105,9 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 - `new <name>`：参数化脚手架，生成 TS 或 JS 插件仓库骨架（`src/index.ts` 契约模板、Schemastery Config、tests、tsdown/vitest、注释齐全的 `cordis.patch.yml`、五语 README），模板与 `references/official-docs` 同步更新。标志：`--lang <ts|js>`、`--dir <path>`、`--force`、`--git`。
 - `check [--json] [--strict] [--cwd <dir>]`：静态检查（`cordis.patch.yml` 合法性、`package.json` 元数据（`dsh.bundle.patch` 指向/peer 依赖/engines/files 白名单）、五语 README 一致性、工程红线模式），输出 CI 可消费的结构化 JSON；每个检查项在输出里引用本知识库对应章节（skill 联动），agent 可继续人工审计。**这 16 项是同族 `dsh-plugin-doctor` 33 项的子集**（逐项对照见 `guide/family-toolchain.md` §3）；发布前建议两个都跑。
 - `verify [--cwd <dir>] [--base <spec>] [--headless <spec>] [--profile <name>]`：`pnpm pack` 后装入干净临时 `DSH_HOME` profile 做安装+启动+卸载冒烟（对齐官方 verify:self-contained）；失败给出日志尾部与建议。
-- `seams <query>` / `seams --since <version>`：**回答"这个 API 在我目标宿主里存不存在"**，而不是让你去翻 429 页镜像。`query` 可以是 seam id（`L3`）、能力 id（`A20`）、版本号或任意词。`--since 0.2.0-rc.2` 列出**在该版本之后落地**的所有破坏性变更，并标出哪些**静态检查看不到**。
+- `seams <query>` / `seams --since <version>`：**回答"这个 API 在我目标宿主里存不存在"**，而不是让你去翻 709 页镜像。`query` 可以是 seam id（`L3` / `K12`）、能力 id（`A20`）、版本号或任意词。`--since 0.2.0-rc.2` 列出**在该版本之后落地**的所有破坏性变更，并标出哪些**静态检查看不到**。
   - **第三态是强制的**：知识库没有依据时**退出码 3 并明确说"这是知识库没有依据，不等于该 API 不存在"**——绝不把"不知道"渲染成"没有"。
-  - 数据源 `data/seams/index.json`：19 条 `L` 走廊 seam + 6 条机制 seam + 22 个能力区，每条带 `confidence`（`documented`/`inferred`/`unknown`）与官方出处；**其中 9 条标 `detectable: false` 并写明原因**（数据丢失、运行时状态、部署相关行为），任何消费者都不得把它们算作通过。
+  - 数据源 `data/seams/index.json`：19 条 `L` 走廊 seam（0.2.1 线）+ 7 条机制 seam + **46 条 `K` seam（0.2.2 线，rc.3 包内）** + 22 个能力区；另用 `unreleased` 单列 `v0.2.2-rc.2` 的 13 条下一版指南。每条带 `confidence`（`documented`/`inferred`/`unknown`）与官方出处；**其中 23 条标 `detectable: false` 并写明原因**（数据丢失、运行时状态、部署相关行为），任何消费者都不得把它们算作通过。
 
 四个子命令均可逆/幂等；网络/子进程尊重超时与 AbortSignal；只清理自己 mkdtemp 的目录。CLI 零运行时依赖，构建产物经 tsdown 打包为单文件 `dist/dsh-plugin-dev.js`。