AI-Scarlett/build-dsh-plugin

Build DSH Plugin

Use este workflow para transformar uma ideia de plugin DSH em um bundle padrão sem modificar ou sombrear o próprio Harness.

Normalize o resumo do usuário

Leia intake.md para cada nova solicitação de plugin. Aceite linguagem comum, o resumo mínimo em chinês ou o template JSON estruturado em plugin-brief.template.json.

Exija apenas três fatos semânticos antes da geração de código:

1. o problema atual do usuário;
2. o resultado esperado pelo usuário;
3. pelo menos um critério de aceitação observável.

Inferir nomes, IDs de pacotes, candidatos de arquitetura, classe de risco, estrutura de projeto, testes e padrões seguros. Não peça ao usuário para projetar Host APIs, entradas Cordis, esquemas, ferramentas de build ou estratégia de teste, a menos que ele tenha uma preferência.

Quando campos opcionais estiverem ausentes, padrão para geração de código apenas, Bundle DSH padrão, comportamento somente leitura, nenhuma mutação real de Profile, nenhum restart, nenhuma rede/processo/conta/dispositivo externo, nenhuma credencial, exposição local apenas, nenhuma publicação e aceitação E3 descartável. Construa Bundles DSH reutilizáveis com estrutura de pacote compatível com marketplace por padrão, mas não infira autorização para enviar ou alterar o DSH STORE. Declare cada padrão como uma suposição. Nenhuma publicação é um padrão de autorização, não uma proibição permanente: uma versão fixa, explicitamente autorizada, devidamente licenciada e internamente consistente pode ser distribuída a partir de um site ou proposta para um marketplace.

Faça apenas perguntas cujas respostas alterem materialmente o resultado do produto ou o limite de risco. A falta de problema, resultado ou aceitação bloqueia a geração. A falta de Profile alvo, escopo de mutação, proprietário de credencial, segurança LAN/Internet ou dispositivo/conta real bloqueia apenas a operação real correspondente; não bloqueia um scaffold de código seguro quando as interfaces podem permanecer abstratas.

Execute o normalizador determinístico quando um resumo JSON estiver disponível:

node scripts/normalize-brief.mjs /caminho/absoluto/para/plugin-brief.json
node scripts/normalize-brief.mjs /caminho/absoluto/para/plugin-brief.json --json

Se o status normalizado for READY ou READY_WITH_ASSUMPTIONS e o modo solicitado for build-source, prossiga através das Fases 0–6 sem outra rodada ampla de esclarecimento. Pare antes da liberação, mutação real de Profile, restart, credenciais, dispositivo ou exposição pública, a menos que separadamente autorizado e totalmente especificado.

Estabeleça o contrato

Comece somente leitura. Inspecione as instruções do repositório, a versão alvo do DSH, a documentação oficial do plugin, o Profile ativo apenas quando relevante e um exemplo de plugin padrão atual. Não assuma uma API ou contrato de pacote de um projeto mais antigo.

Sempre aplique estas regras:

• Construa um bundle DSH, não um aplicativo desktop ou um fork do DSH.
• Nunca modifique a árvore de código fonte do DSH ou qualquer pacote @deepseek-ai/*.
• Nunca desative, substitua ou sombreie o inventário oficial de plugins.
• Nunca chame APIs de mutação Loader/Fiber. Use serviços públicos do Host e composição de bundle.
• Use o DSH CLI oficial para alterações de pacote. Passe arrays de argumentos fixos; nunca construa strings de comando shell.
• Mantenha os testes em homes/profiles descartáveis. Nunca escreva testes contra o ~/.dsh real.
• Não exponha credenciais, arquivos completos do usuário, contexto injetado de sistema/plugin, raciocínio do modelo ou caminhos privados através de logs ou clientes.
• Mantenha planejamento, conclusão de código, liberação de pacote, instalação de Profile, aceitação de runtime e aceitação externa/dispositivo como estados separados.
• Mantenha prontidão do plugin, prontidão de candidato a catálogo, PR/CI do Registry, catálogo mesclado, visibilidade no marketplace público e instalação de Profile como estados separados.
• Mantenha saída canônica da Tool, renderização voltada para o modelo, intenção de cartão neutra ao provedor e renderização opcional do Client como contratos separados.

Leia boundaries.md antes da implementação ou instalação. Bloqueios rígidos nesse arquivo substituem qualquer pontuação. Leia card-contract.md antes de implementar uma Tool de modelo, presentCall, presentResult, presentationMeta ou um cartão Tool personalizado.

Explique cada decisão consequente

Não emita uma lista de regras sem sua lógica de decisão. Para cada decisão de arquitetura, permissão, mutação, liberação ou aceitação, registre:

1. Objetivo: a falha ou resultado que a decisão controla.
2. Racional: por que a mecânica do DSH ou o modelo de ameaça atual a exige.
3. Benefícios: o que se torna mais seguro, mais simples, mais compatível ou mais fácil de verificar.
4. Custos: carga de implementação, atrito de UX, custo de desempenho, perda de capacidade ou atraso operacional.
5. Aplicabilidade: as condições sob as quais a decisão é apropriada.
6. Alternativas: opções viáveis, por que foram rejeitadas e quando reconsiderá-las.
7. Procedimento: etapas concretas, responsável, entradas, saídas e comportamento de rollback.
8. Portão de evidência: a prova observável necessária para avançar e a condição que interrompe o trabalho.

Leia decision-guide.md ao planejar, revisar ou explicar um plugin. Use seus cartões de decisão em vez de copiar um padrão preferido sem análise.

Execute o workflow

Siga workflow.md para o processo completo de estágios com portões e artefatos necessários. Não pule um estágio apenas porque um plugin semelhante passou por ele anteriormente; versões do DSH, composição de Profile, dependências e serviços externos podem mudar.

1. Prove o ajuste ao Host

Identifique o Host alvo, a costura de extensão, o resultado solicitado do usuário, as mutações de estado, as dependências externas e a superfície de aceitação.

Pare e relate uma incompatibilidade de Host quando o projeto for direcionado ao Obsidian, VS Code, uma extensão de navegador, apenas MCP ou outro runtime sem um contrato de bundle DSH comprovado. Ofereça o Host compatível ou um adaptador deliberadamente escopado. Não desvie para um projeto adjacente.

Produza um registro de contrato de Host e uma comparação de arquitetura. Portão: compatível, adaptador-necessário ou incompatível; nunca deixe isso como prosa implícita.

2. Classifique o risco

Atribua uma classe de scorecard.md:

• R0: metadados/UI somente leitura.
• R1: ferramentas/serviços do Host ou estado de plugin de propriedade do usuário, sem gravações no ciclo de vida do Profile.
• R2: ponte para processo externo, rede, credenciais ou dispositivo.
• R3: ciclo de vida do Profile, restart, controle remoto ou gerenciamento amplo.

Use a classe mais alta quando estiver em dúvida. Registre não-objetivos e superfícies proibidas antes de codificar.

Produza um registro de risco que nomeie ativos, atores, limites de confiança, superfícies de gravação, impacto de falha, nível mínimo de evidência e o motivo para escolher a classe.

3. Selecione o padrão padrão

• Bundle somente Host: exponha um serviço/ferramenta Cordis público e contribua com uma ou mais linhas de patch exclusivas.
• Host + Client: mantenha o código do Browser separado; registre com window.__ModuleLoader__.load() e slots. O código do Browser não deve importar módulos Host/Node.
• Rota Web opcional: atrase o registro com ctx.inject(['webServer'], ...); perfis headless/sem Web ainda devem inicializar.
• Adaptador de Skill: monte arquivos Skill isolados; não instale silenciosamente o runtime externo, extensão ou credenciais.
• Ponte ApiProxy: adapte a superfície remota pública estreita com uma lista de permissões, ocultação, autenticação, análise limitada e segurança de transporte com falha fechada.
• Gerenciador de ciclo de vida: trate cada alteração de Profile como uma transação R3 e use o protocolo de mutação abaixo.
• Contrato de cartão Tool: prefira intenções de renderização presentCall/presentResult neutras ao provedor; use um cartão personalizado de Client Slot apenas para uma Tool de propriedade do plugin quando o vocabulário embutido inspecionado não puder expressar o resultado.

Crie um manifesto de bundle com dsh.bundle.patch, um cordis.patch.yml resolvível por pacote, IDs de entrada exclusivos, arquivos explícitos, versão, licença e contrato de build. Lembre-se de que camadas de patch posteriores substituem o config completo de uma linha; elas não fazem deep-merge.

Compare pelo menos dois padrões plausíveis quando a escolha afetar permissões, limites de processo, comportamento de instalação ou experiência do usuário. Registre benefícios e custos; não selecione uma arquitetura apenas porque um projeto anterior a usou.

4. Implemente privilégio mínimo

Use serviços públicos já fornecidos pela versão DSH inspecionada. Se a costura necessária estiver ausente, pare e proponha um adaptador ou mudança upstream em vez de corrigir o núcleo.

Prefira descoberta somente leitura e APIs de simulação/pré-visualização. Torne os recursos de gravação ativados separadamente. Valide esquemas e limites de tamanho antes da lógica de negócios. Rejeite perfis malformados, caminhos ambíguos, componentes oficiais desconhecidos, estado obsoleto, repetição, alterações concorrentes e evidências ausentes.

Para cada Tool de modelo, registre a saída canônica, o renderizador voltado para o modelo, o cartão pendente, o cartão concluído, os metadados de apresentação duráveis, os limites/ocultação, o fallback genérico e as evidências ao vivo/replay. Os apresentadores devem ser determinísticos e não realizar I/O, acesso a clock/aleatório, leituras de sessão ou trabalho extra que exija permissão. Nunca coloque credenciais, arquivos privados completos, raciocínio do modelo ou argumentos ilimitados em um cartão.

Para padrões de falha recorrentes, leia problem-playbook.md.

Produza uma matriz de permissões com cada fonte de dados/ação, lado proprietário, chamador permitido, ocultação, limite de tamanho/taxa, modo de falha e teste. Qualquer permissão sem um resultado do usuário e um teste é removida.

5. Aplique o protocolo de mutação

Para mutações de Profile/pacote/restart, crie um novo plano tipado para exatamente uma operação contendo:

1. operação e Profile alvo;
2. identidade imutável do pacote/fonte;
3. escopo exato do arquivo e hashes de pré-condição esperados;
4. argv do comando e diretório de trabalho;
5. localização do backup e procedimento de rollback;
6. pós-condição e verificações de saúde;
7. exatamente uma frase de confirmação;
8. expiração e identidade de uso único.

Mostre o plano e aguarde a confirmação exata por operação. Invalide-o em caso de incompatibilidade, expiração, alteração concorrente ou uso anterior. Faça backup antes de escrever, confirme atomicamente, execute verificações de saúde de configuração e runtime e reverta em caso de falha. Uma liberação de repositório nunca autoriza uma atualização de Profile local.

Trate o atrito de confirmação e a maquinaria de transação como custos explícitos. Aceite esses custos para R3 porque a alternativa é a corrupção silenciosa e difícil de recuperar do estado do usuário. Não imponha o protocolo de mutação em leituras puramente R0.

6. Suba a escada de evidências

Avance apenas com evidências atuais:

• E0: ideia ou plano.
• E1: revisão de estrutura/fonte estática.
• E2: testes automatizados de unidade/contrato/falha.
• E3: instalação em Profile descartável, --dump-config, inicialização e fumigação de API.
• E4: versão de Profile real confirmada separadamente, processo/porta, inventário/API oficial e leitura de UI visível.
• E5: aceitação externa/pública/dispositivo, mais evidências de recuperação de falha ou rollback.

Nunca infira um nível superior de um inferior. Capturas de tela da UI não provam rollback; HTTP 200 não prova UI visível; sucesso de instalação não prova saúde de restart; saída de simulador não prova um dispositivo real.

Para cartões Tool, E2 inclui testes de apresentador determinístico, replay malformado, ocultação, limite, truncamento e fallback genérico. E3 inclui paridade de replay ao vivo mais persistido em um runtime DSH isolado. O comportamento visível do cartão no Profile do usuário permanece E4.

Produza uma matriz de evidências por capacidade. Inclua evidências negativas e de recuperação, não apenas o caminho feliz. Uma pontuação classifica a prontidão; ela nunca concede autoridade ou substitui um portão duro.

7. Libere e instale separadamente

Antes da liberação do repositório, sincronize a versão do pacote, README, entrada do catálogo, âncora de instalação imutável, testes e metadados de fonte fixos. Para fontes Git, ou envie artefatos compilados ou declare um script prepare autocontido e divulgue pnpm allowBuilds; fixe um SHA de commit completo.

Execute verificações de repositório, verificação de fonte e simulação de empacotamento. Verifique o commit remoto e os ativos públicos após o merge. Então pare. Atualize um Profile real apenas sob um novo plano de mutação confirmado, reinicie-o através do mecanismo aprovado e leia de volta a versão resolvida e o estado do runtime.

Produza dois relatórios separados: evidências de liberação de repositório e evidências de aceitação de Profile/runtime. Quando o segundo relatório estiver ausente, declare Profile inalterado ou Profile não verificado.

8. Torne plugins reutilizáveis prontos para o DSH STORE

Leia marketplace.md sempre que construir um plugin DSH reutilizável de terceiros, avaliar um repositório existente para o DSH STORE ou preparar uma entrada de catálogo.

Não espere até o envio para descobrir incompatibilidade de listagem. Desde o primeiro scaffold, reserve IDs exclusivos de pacote/catálogo/entrada; declare repositório, versão, licença, dsh.bundle.patch seguro, Patch relativo ao pacote, arquivos de runtime/build, scripts de ciclo de vida, permissões, dependências e evidências de compatibilidade. No início de cada avaliação de STORE, execute node scripts/official-dsh-releases.mjs e use sua janela oficial das três últimas versões; não reutilize uma janela lembrada. O resolvedor segue o canal npm latest/alpha/beta/rc ativo mais alto, exclui versões apenas next e obsoletas e falha fechado em autoridade inválida. A janela observada em 2026-09-02 é 0.1.2-alpha.2, 0.1.2-alpha.3 e 0.1.2-alpha.4, mas é evidência em vez de uma constante permanente. Mantenha registros exatos de compatibility.dshReleases e compatibility.dshOperations correspondentes para instalar, iniciar, desinstalar e reverter em cada versão na janela resolvida. Chaves históricas podem permanecer, mas metadados desconhecidos permanecem desconhecidos em vez de serem adivinhados.

Mantenha a descoberta do STORE e a instalação confiável física e logicamente separadas. Um registro em registry/candidates.json é apenas de descoberta, não carrega nenhum contrato de pacote/instalação/permissão e deve normalizar para installable: false sem ações permitidas. Ele pode passar para registry/catalog.json apenas após uma revisão separada de fonte fixa, Bundle, licença, permissão, compatibilidade e evidência. Promoção, recomendação, patrocínio, estrelas ou pontuação...

[...truncado para tradução]