CH 23 · Publicar e Distribuir

Número de palavras~3.910 palavrasTempo~20 minPré-requisitosCH 17, CH 22NívelReproduzível

Objetivo do Capítulo

Percorrendo o PART 04, você aprendeu a instalar plugins e a escrever plugins — mas ainda está sentado na pasta do seu próprio workspace, como outras pessoas o obtêm? Este capítulo o transforma em uma distribuição "um comando para instalar": primeiro explica o mecanismo subjacente pelo qual outros instalam seu plugin (pacote bundle), depois dá três métodos de distribuição, e finalmente instala você mesmo antes de publicar para verificar, confirmando que não há problema antes de publicar.

Primeiro Esclareça: Como Outros Instalam Seu Plugin

O dsh não tem um mercado de plugins embutido; a instalação oficial passa uniformemente por dsh plugin --profile <nome> add <fonte>. As fontes são quatro tipos: nome de pacote npm / diretório local / tarball / GitHub Release (abordado sistematicamente no CH 17). Então o que você precisa fazer é transformar seu plugin em qualquer uma dessas quatro fontes.

E "um plugin que pode ser add por outros" tem um nome oficial no dsh — bundle (pacote). Não confunda os dois conceitos:

• bundle é o que você escreve e distribui. Seu package.json declara dsh.bundle, respondendo "o que este pacote contribui" — um arquivo de patch que insere ou sobrescreve linhas de plugin.
• profile é com o que o usuário inicia com dsh --profile <nome>. Seu package.json declara dsh.profile, respondendo "quais bundles, em que ordem, compõem esta configuração".

Nada é ambos. Você distribui o bundle, o usuário o instala com um profile e o executa.

Como Se Parece um Plugin Publicável

No diretório do seu plugin terminado, as três coisas mais importantes:

seu-plugin/
├── package.json       # Declare dsh.bundle (e dsh.client se tiver UI)
├── cordis.patch.yml   # A camada de patch aplicada quando instalado
└── lib/               # Artefatos de build — isto é o que outros realmente instalam

Esses campos no package.json, nenhum pode ser descuidado:

Campo	Descrição
name	Nome do pacote, corresponde ao plugin, lê bem
version	Versão semântica, major.minor.patch, comece em 0.0.1
description	Uma linha explicando o que o plugin faz, mostrada na lista de instalação
type	module (ESM)
main	Aponta para o artefato de build, por exemplo, lib/index.js
files	Apenas empacote o que você precisa enviar: lib, cordis.patch.yml, LICENSE, etc. lib ausente significa que outros vão falhar ao carregar após instalar
keywords	Palavras-chave de pesquisa, ["deepseek","harness","dsh","dsh-plugin",...] — dsh-plugin é o padrão para ser encontrado
license	Open source deve declarar, por exemplo, MIT
dsh.bundle	{"patch":"./cordis.patch.yml"} — declare que este é um pacote, auto-montado na instalação
dsh.client	Plugins com UI declaram injeção de cliente (o conjunto abordado no CH 22)

Três Métodos de Distribuição

Do leve para o pesado. O primeiro é puramente auto-teste local, não precisa de nenhuma conta; os dois últimos precisam de uma conta — GitHub precisa de uma conta GitHub, npm precisa de uma conta npm.

Método Um: Diretório Local / tarball — Auto-Teste Antes de Publicar

• Diretório local: dsh plugin --profile demo add ./seu-plugin, pnpm vincula diretamente esse diretório, adequado para testes rápidos durante o desenvolvimento.
• tarball: no diretório do plugin pnpm pack para fazer um .tgz, então dsh plugin --profile demo add ./seu-plugin-0.0.1.tgz.

Antes de publicar, sempre instale com tarball você mesmo primeiro — tarball é exatamente o mesmo que você vai enviar; se pode instalar e executar, então você pode considerar publicar. Auto-teste completo em três passos:

# Empacote no diretório do plugin
pnpm pack

# Instale em um profile temporário limpo
dsh plugin --profile test add ./seu-plugin-0.0.1.tgz

# Veja se entrou na árvore de configuração
dsh --profile test --dump-config

Se você vir a camada do seu plugin na saída de --dump-config, o pacote carregou com sucesso. Então dsh --profile test para iniciar, teste se os recursos do plugin funcionam normalmente, tudo normal então publique.

Dois detalhes para lembrar:

• Após uma mudança de membro de bundle, você deve reiniciar o profile para ter efeito — um profile em execução retém o conjunto de bundles que tinha na inicialização (o limite no CH 17), instale então reinicie antes de testar.
• Ordem de carregamento: lista de bundles do profile → cordis.patch.yml próprio do profile → $DSH_HOME/cordis.patch.yml → overlay --patch, linhas aplicadas depois vencem. Seu plugin pertence à primeira camada.

Você também pode fazer o dsh fazer isso para você: envie o seguinte a ele, e ele vai ler a documentação, empacotar, instalar um profile temporário, verificar; você apenas verifica.

Pack the plugin in my current workspace into a publishable form, and do a pre-publish self-test: first read the dsh official docs to understand how to pack and install plugins (bundle packages, the four sources of dsh plugin add), do it per the official spec; pack the plugin into a tarball, check whether the package.json metadata (version, description, files, keywords, license) is complete; install it into a temporary profile and verify it can load and the features work normally; finally tell me the verification result and the path of the packaged product, and explain what I still need to do to publish to npm.

Método Dois: GitHub — Outros Instalam com Uma URL

O mais comum na comunidade: construa o artefato, faça upload dele para um GitHub Release, outros instalam com uma única URL. O DSH Skill & MCP Panel que instalamos no CH 12 foi distribuído desta forma.

Três passos:

1. Empacote: no diretório do plugin pnpm pack, obtenha seu-plugin-0.0.1.tgz.
2. Faça upload: envie o repositório para o GitHub, crie um Release na página do repositório (escreva um número de versão v0.0.1), faça upload do .tgz.
3. Dê o endereço de instalação: outros instalam com este endereço:

dsh plugin --profile web add https://github.com/seu-usuário/nome-do-repo/releases/download/v0.0.1/seu-plugin-0.0.1.tgz

O que é instalado é o artefato de build, sem necessidade de autorização allowBuilds, tão fácil quanto instalar do npm. Para fixar um endereço "sempre aponta para o mais recente", substitua download/v0.0.1/... por releases/latest/download/seu-plugin.tgz (não inclua número de versão no nome do arquivo).

Note: plugins indo por esta rota, lib/ geralmente não está no git — o repositório só tem código-fonte, faça build local antes de publicar, pnpm pack para tarball, então faça upload para o Release.

Avançado: GitHub Actions auto-build e publish

Empacotamento manual, criar Release e fazer upload de arquivos uma vez é bom, mas com muitas versões fica chato. Tenha o GitHub Actions fazendo isso para você: envie uma tag v0.0.1, Actions executa automaticamente build → pnpm pack → criar Release → fazer upload do tarball. De então em diante, basta enviar uma nova tag para uma nova versão, todo o resto é automático.

Um workflow típico vai em .github/workflows/release.yml do repositório: trigger é push: tags: ['v*'], passos em ordem: checkout do código, instalar Node, pnpm install, pnpm build, pnpm pack, use softprops/action-gh-release para criar um Release e fazer upload do .tgz gerado como anexo. Configure uma vez, e você não precisa fazer upload manual de arquivos para cada versão.

Você também pode fazer o dsh fazer a publicação para você

Empacotamento, enviar o repositório, criar o Release — essas tarefas repetitivas, apenas passe para o dsh. Envie isto na caixa de entrada da Web UI:

Publish the plugin in my current workspace to GitHub, release v0.0.1, use GitHub Actions for auto-build and publish per the dsh official spec, and finally tell me what address others can use to install.

Ele vai ler a documentação sozinho, executar comandos sozinho, lidar com git e Release sozinho. Você só precisa confirmar de acordo com a política de permissão quando ele fizer operações que cruzam limites como enviar o repositório e criar o Release, e finalmente verificar se o endereço de instalação está correto.

Método Três: Publicar no npm — Outros Apenas Digitam o Nome do Pacote

Publique o plugin no npm, e é o mais conciso para outros instalarem: dsh plugin --profile web add seu-plugin.

Quatro passos:

1. Registre-se e faça login no npm: registre uma conta no site do npm (grátis), então npm login (vai pedir nome de usuário, senha e email).
2. Faça build: garanta que lib/ é o artefato de build. Plugins de tipo source precisam fazer pnpm build antes de publicar — npm instala código pré-construído, publique sem construir, e outros obtêm um pacote vazio.
3. Publique: execute pnpm publish no diretório do plugin.
4. Verifique: mude para um profile limpo, dsh plugin --profile test add seu-plugin, confirme que pode instalar e executar.

Após Publicar: Marque o Tópico dsh-plugin

Independentemente do método, adicione dsh-plugin aos Tópicos do repositório GitHub — a equipe oficial explicitamente recomenda fazer isso, para que outros possam encontrar mais facilmente seu plugin. Lembre-se também de incluir dsh-plugin nos keywords do pacote npm, duplamente.

Armadilhas Comuns

Problema	O que está acontecendo	Como lidar
Instalado mas sem efeito	Mudança de membro de bundle não reiniciou	Reinicie o profile após instalar então teste
Outros falham ao carregar após instalar	files omitiu lib/, apenas source enviado	Adicione o diretório de artefato de build a files, reempacote
Número de versão duplicado	Mesma versão publish é permanentemente rejeitada pelo npm	Mude para uma versão diferente então publique
Nome de pacote tomado	Já existe no npm com o mesmo nome	Escolha um nome de pacote não relacionado
Instalado mas não ativado	Pacote não declarou dsh.bundle	Adicione "dsh":{"bundle":{...}}, caso contrário é apenas uma dependência regular e não é montado

O que você aprendeu neste capítulo

Você passa se conseguir completar os itens abaixo:

• [ ] Saiba que um bundle é "o que você distribui", um profile é "com o que o usuário inicia", e seus manifestos são diferentes
• [ ] Escreva um package.json correto para um plugin publicável: name / version / files / keywords / license / dsh.bundle, e dsh.client se tiver UI
• [ ] Conheça os cenários apropriados para os três métodos de distribuição: auto-teste local/tarball, GitHub Release tarball (instalação mainstream com um clique, suporta Actions auto-publish), npm publish
• [ ] Auto-teste antes de publicar: pnpm pack → add em profile temporário → confirmação com --dump-config → reiniciar para verificar
• [ ] Saiba que você pode fazer o dsh fazer o empacotamento, auto-teste e publicação para GitHub, sem necessidade de fazer passo a passo manualmente
• [ ] Saiba que após publicar, marque o repositório GitHub com o tópico dsh-plugin, e os keywords do pacote npm incluem dsh-plugin
• [ ] Pode evitar armadilhas comuns: files omitindo lib/, mudanças de bundle não reiniciadas, pacote não declarou dsh.bundle