PerryLink/dsh-plugin-guide

Desenvolvimento de Plugins do DeepSeek Harness (dsh-plugin-guide)

Desenvolva plugins do DeepSeek Harness com base na documentação oficial. Esta habilidade é uma lista de verificação de fluxo de trabalho e restrições; todos os detalhes factuais devem referenciar o texto original da base de conhecimento, sem inventar a partir da memória. Todas as cláusulas "deve/não deve" vêm dos repositórios oficiais AGENTS.md, docs/ e do site de documentação; em caso de conflito, prevalece o texto oficial.

Localização da Base de Conhecimento (procure na ordem, use a primeira que existir)

Esta habilidade e a base de conhecimento são distribuídas no mesmo diretório (o diretório onde este SKILL.md está é a raiz da base de conhecimento); todos os caminhos são relativos. Se este arquivo for copiado sozinho sem guide/, references/, use os caminhos de fallback:

1. Mesmo diretório deste arquivo: ./guide/ (guia completo + tabela de referência rápida + índice de links de documentação), ./references/ (relatórios de pesquisa e cópias completas da documentação oficial references/official-docs/docs/), ./downloads/ (downloads originais, opcional)
2. Cópia principal local: D:\deepseek-harness\Project\Plugins\dsh-plugin-guide\ (caminho de exemplo; ajuste conforme a instalação local)
3. Checkout do repositório oficial: D:\deepseek-harness\ (docs/, vendor/cordis/, packages/, examples/)
4. Online: https://github.com/deepseek-ai/deepseek-harness , https://deepseek-harness.github.io/deepseek-harness/develop/basic/ , https://github.com/cordiverse/cordis

Os caminhos relativos abaixo consideram como padrão o item 1 acima (diretório onde este arquivo de habilidade está localizado).

Pré-requisitos de Desenvolvimento (obrigatório primeiro passo)

1. Se ainda não leu sobre conceitos do Cordis: leia references/official-docs/docs/cordis-primer.md (5 conceitos, 5 minutos); se quiser praticar, execute os tutoriais 01-07 em references/official-docs/docs/cordis-tutorial/ (podem ser executados sem chave de API).
2. Abra guide/quick-reference.md (consulta rápida de contratos) + guide/plugin-dev-guide.md (caminho completo). A correspondência de URLs oficiais/comunitárias está em guide/links.md.
3. Confirme os pontos de extensão alvo: leia a tabela "Where new behavior goes" em references/official-docs/docs/architecture.md e a tabela feature→mechanism em references/official-docs/docs/cookbook/extension-cookbook.md – novos comportamentos devem ser vinculados a pontos de extensão documentados; não é permitido modificar o agent-loop.

Contratos de Plugin Obrigatórios (linhas vermelhas oficiais, verifique uma a uma)

• Plugin = módulo exporta name + apply(ctx, config) (+ opcional inject: string[]); serviços dependentes são inicializados antes de apply; se um serviço dependente desaparecer, o plugin é desinstalado automaticamente e recarregado quando o serviço retornar.
• Registrar é produzir efeito: toda contribuição deve usar ctx.effect() / ctx.on() / serviço register() (que retorna um disposer); nunca use removeListener/clearInterval manualmente para finalizar.
• Listeners do tipo waterfall devem chamar next(); não chamar = curto-circuito intencional (semântica de interceptação). Consulte a tabela de referência rápida para as semânticas de emit/waterfall/parallel/serial/bail.
• Visível ao modelo ↔ Registrado: tudo que entra em uma requisição de modelo deve ser reconstruível a partir do log da sessão; qualquer nova entrada visível ao modelo deve adicionar um novo evento de sessão SessionEventMap.
• Eventos/serviços com tipo seguro usam declaration merging (declare module '@deepseek-ai/cordis'); eventos documentados com @mode.
• Configuração usa Schema<Config> do Schemastery (objetos simples são proibidos); configurações inválidas causam falha ruidosa em tempo de carregamento; não codifique parâmetros ajustáveis (critério: podem ser alterados no cordis.yml?).
• Ferramentas usam defineTool: execute retorna apenas valores JSON padrão declarados em output.schema; respeite exec.signal; conteúdo legível por humanos vai em output.render; o presenter do cartão UI é uma função pura (proibido I/O/relógio/aleatoriedade).
• Capacidades substituíveis seguem o design de três camadas: Service Definition / Provider / Consumer; não desacople prematuramente.
• Empacotamento: manifesto bundle "dsh":{"bundle":{"patch":"..."}}; substituições de configuração são feitas por linha inteira baseada em id; use !!js (dois pontos de exclamação); instalação via git requer script prepare e allowBuilds no lado do usuário; publicar via npm/tarball dispensa permissão de build.

Caminhos de Desenvolvimento por Tipo de Tarefa

(Os caminhos abaixo estão em references/official-docs/ como cópias completas da documentação oficial)

• Nova ferramenta: docs/user/develop/basic/tool.md (tutorial) → docs/cookbook/adding-a-tool.md (contrato completo: validação de parâmetros, valores padrão, tarefas em segundo plano com ctx.jobs, hooks de estratégia, Code Mode, cartões UI) → implementação de referência packages/shell/tool-bash (checkout local).
• Novo serviço/capacidade: docs/user/develop/framework/service.md + docs/user/develop/practice/ (código completo de separação em três camadas).
• Interceptação/estratégia/hook: docs/cookbook/extension-cookbook.md (exemplo de permission-gate) + docs/event-producer-consumer.md (matriz completa de eventos).
• Novo provedor LLM: docs/user/develop/practice/llm-adapter.md (protocolo StreamChunk).
• UI/nós de sessão: docs/cookbook/adding-a-conversation-node.md + docs/subsystems/session.md, client-modules.md.
• Empacotamento/publicação: docs/user/develop/basic/publish.md (bundle/profile, ordem de camadas, armadilhas de instalação via git).
• Consultar assinatura exata de serviço/evento: área de API Cordis gerativa em docs/subsystems/*.md + docs/cordis-api/*; não crie uma segunda lista estática. A correspondência entre URLs do site e cópias locais está em guide/links.md; a lista completa de links da comunidade está em references/community-ecosystem.md.
• Implementações de referência da comunidade e armadilhas testadas: references/community-ecosystem.md, references/community-repo-deep-dive.md (análise aprofundada de 15 repositórios de desenvolvimento), downloads/community-repos/ (cópias completas do código-fonte, que devem ser geradas executando scripts/download-community-repos.ps1). Mudanças de mecanismo confirmadas pela comunidade (como a remoção do repository-plugin 0811, bundle vs. canal duplo puramente Cordis) e 20 armadilhas testadas (cópia dupla do Cordis, trio tsconfig, zstd multi-quadro, junction no Windows, etc.) estão em guide/plugin-dev-guide.md §7.

Validação (antes da entrega)

• Validação de carregamento: dsh --profile <nome> --dump-config verifique se a linha de patch entrou em vigor; log de inicialização sem FAILED.
• Validação de comportamento: teste real via Web UI ou dsh --profile headless "…"; o retorno da ferramenta/texto visível ao modelo é o comportamento; qualquer alteração requer novo teste.
• Alterações dentro do repositório exigem adicionalmente: verificação de tipo, testes do pacote alvo, snapshot sem chave (comportamento visível ao modelo/produto deve ter snapshot transcrito após montagem), documentação bilíngue aos pares, Agent Note (alterações não triviais no mesmo PR).
• Pacote de plugin independente: após pnpm pack, instale em um perfil limpo para verificar (incluindo artefatos de build em lib/).

Manutenção da Base de Conhecimento (quando necessário)

• Sincronizar cópia da documentação oficial: pwsh -File ./scripts/sync-official-docs.ps1 [-Checkout <checkout deepseek-harness>] – sincroniza apenas arquivos rastreados pelo git (rascunhos não rastreados e commits não enviados não são incluídos) e atualiza references/official-docs/SNAPSHOT.md; a data da "última verificação" e o hash do commit no README devem referenciar SNAPSHOT.md, não devem ser editados manualmente. Verificação de divergência: pwsh -File ./scripts/verify-kit.ps1 -Checkout <checkout>.
• Atualizar materiais online: pwsh -File ./scripts/download-sources.ps1; atualizar repositórios da comunidade: pwsh -File ./scripts/download-community-repos.ps1 (ambos os scripts são idempotentes, saída em ./downloads/). Recontagem de tópicos: pwsh -File ./scripts/gen-topic-snapshot.ps1 -OutDir <dir> -MaxPages 20 (GitHub Search API q=topic:dsh-plugin; limite de paginação 1000 itens; contagem única e total_count da API devem ser registrados em sources.md §D.2).
• Instalar/atualizar cópia da habilidade do agente: pwsh -File ./scripts/install-skill.ps1 -Target <diretório-da-habilidade> (pula downloads/ e .github/, verifica byte a byte).
• Resolução de conflitos: em caso de conflito com a documentação oficial, prevalece references/official-docs/ (texto original do repositório oficial).

Limites

• Esta habilidade é um "guia + restrições + índice de materiais", não uma execução mecânica de scripts/listas; APIs precisas devem ser consultadas na referência gerativa.
• Não é permitido modificar arquivos do repositório harness fora da base de conhecimento, a menos que o usuário solicite explicitamente; vendor/ e .agents/notes/archived/ são somente leitura.
• Antes de referenciar conteúdo de downloads/, confirme sua existência (este diretório não está no git; deve ser gerado pelos scripts acima); o arquivo awesome-dsh-plugins é apenas para referência local e não pode ser redistribuído com o repositório (seu upstream declara restrições de uso interno, veja NOTICE.md).