Como publicar um plugin do DeepSeek Harness e ser encontrado pelo tópico dsh-plugin

Fala aí, beleza? O DeepSeek Harness carrega um lema que já entrega a arquitetura inteira: "Everything is a Plugin"

Ou seja, se você quer estender o bicho, você não abre um pull request: você escreve um plugin

Aí bate o problema real de quem escreve uma extensão: ninguém acha ela. O código tá lá, funcionando, resolvendo um problema seu e provavelmente de mais um monte de gente, e mesmo assim ele morre num repositório que ninguém visita

A boa notícia é que o projeto tem um mecanismo de descoberta declarado, e é bem menos burocrático do que parece: adicionar o tópico dsh-plugin ao repositório público do plugin no GitHub. É isso que o README oficial do deepseek-harness orienta, e é o que faz o teu plugin aparecer na listagem pública de github.com/topics/dsh-plugin

Um aviso antes de tu investir tempo nisso: o Harness está em developer preview e itera rápido, com aviso explícito de mudanças que quebram compatibilidade. Então escreve o plugin sabendo que vai ter que dar manutenção nele…

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Quando faz sentido publicar um plugin em vez de só usar o dsh

Nem todo hack local precisa virar pacote, beleza? Mas tem três cenários em que distribuir vale MUITO a pena

Você resolveu algo no seu cordis.yml local e outras pessoas têm o mesmo problema. É o caso mais óbvio e o mais comum: o plugin já existe, só falta empacotar e marcar o tópico

Você quer contribuir com o projeto. Aqui tem um detalhe que muita gente descobre tarde: a equipe oficial não aceita pull requests externos no momento. O CONTRIBUTING aponta outros caminhos de contribuição: reportar issues, participar das discussions, criar plugins da comunidade, escrever documentação e ajudar outros usuários

Traduzindo: o plugin da comunidade é o canal real de contribuição de código nesse projeto hoje

Você quer que o teu plugin vire peça de uma composição maior. E aqui entram dois conceitos que confundem no começo

Que é bundle? É um pacote npm que declara dsh.bundle no manifest, apontando pra um arquivo de patch que insere ou sobrescreve linhas de plugin. Pensa nele como um combo pronto de plugins

E profile? É um diretório que descreve uma composição executável, em $DSH_HOME/profiles/<name>, declarando dsh.profile no manifest com os bundles e a ordem deles

Se você já mexeu com plugins de skills no Claude Code, a ideia de empacotar capacidade em vez de colar configuração solta na mão vai soar bem familiar 🙂

O que você precisa antes de publicar o plugin

Lista curta, sem enrolação:

• A CLI oficial, distribuída no npm como o pacote @deepseek-ai/dsh
• Um projeto TypeScript, porque no Harness um plugin é um módulo TypeScript que exporta uma função apply, chamada pelo framework no carregamento com um objeto de contexto ctx (o tipo Context vem de @deepseek-ai/cordis)
• Conta no GitHub com repositório público, já que o tópico é o mecanismo de descoberta. Repositório privado com tópico não aparece pra ninguém
• Conta no npm, se a tua distribuição for por pacote publicado

Se você não quer começar do zero, existe um template de plugin mantido pela comunidade em dsh-plugin-template, de autoria do usuário bugmaker2. Deixando claro: esse template não tem vínculo com a DeepSeek, é iniciativa de comunidade mesmo

E a fonte da verdade continua sendo a documentação oficial em deepseek-harness.github.io/deepseek-harness, principalmente as seções /develop/basic/ e /develop/basic/publish. Como o projeto muda rápido, vale conferir lá antes de bater o martelo em qualquer detalhe

Passo a passo para publicar o plugin e marcar o tópico dsh-plugin

1. Escreva o plugin:

O esqueleto mínimo é bem enxuto, se liga:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin'

export function apply(ctx: Context) {
}

É só isso mesmo: um name exportado e a função apply

O erro comum deste passo: tratar apply como uma função qualquer do teu módulo. Ela é o ponto de entrada, quem chama é o framework, no momento do carregamento, passando o ctx. Toda a tua lógica de registro pendura ali dentro

2. Teste localmente pelo cordis.yml:

O carregamento em desenvolvimento é feito pelo arquivo cordis.yml, que funciona como um overlay listando entradas de plugin. Cada entrada tem um name que é um especificador de módulo: pode ser um caminho relativo ou o nome de um pacote npm

O erro comum deste passo: o caminho do plugin local precisa ser absoluto. Já vi gente perder a tarde jurando que o plugin estava quebrado, quando o problema era o caminho relativo que o loader não resolveu…

3. Escolha como vai distribuir:

São dois caminhos documentados, e os dois são válidos

O primeiro é publicar o plugin no npm, com a pasta lib/ construída na publicação. Aí o usuário instala assim:

dsh plugin add your-package

O segundo é gerar um tarball e instalar pelo caminho local:

pnpm pack
dsh plugin add ./hello-plugin-0.1.0.tgz

Vale saber o que acontece por baixo: o comando dsh plugin encaminha os argumentos pro pnpm dentro do diretório do profile, e aceita a forma dsh plugin --profile <name> <args...>

O erro comum deste passo: achar que o dsh plugin add é um gerenciador próprio e exótico. Se você conhece npm ou composer, a analogia é direta: é o pnpm rodando no diretório certo pra você

4. Publique o repositório e adicione o tópico dsh-plugin:

Esse é O passo da descoberta, e é o que a maioria pula

Com o repositório público no GitHub, adicione o tópico dsh-plugin a ele. É esse o mecanismo indicado pelo próprio projeto pra que o plugin seja encontrado

Depois confere a listagem em github.com/topics/dsh-plugin e vê se o teu repo aparece por lá

O erro comum deste passo: publicar o pacote no npm e considerar o trabalho feito. Pacote publicado não é plugin descobrível: quem procura extensão do Harness vai olhar o tópico

5. Escreva um README decente:

O tópico leva a pessoa até o teu repositório, o README decide se ela instala ou fecha a aba

Diz o que o plugin faz, como instalar e o que ele espera de configuração

E existem listas mantidas pela comunidade que agregam repositórios do tópico, como a 0xsline/awesome-deepseek-harness e a awesome-dsh-plugin. Nenhuma delas faz parte do projeto oficial, então trata como o que são: vitrines de comunidade, um empurrãozinho extra de visibilidade

Publicar cedo é o atalho de quem está começando

No vídeo lá do canal eu falo sobre uma dúvida clássica de quem tá começando: dá pra começar a carreira pelo backend ou tem que ser pelo frontend?

E a minha resposta é que não tem caminho certo nem errado aqui: os dois pontos de partida funcionam, cada um com o seu trade-off

Eu gosto do frontend porque o aprendizado dá um resultado visível mais rápido, e resultado visível motiva quem tá começando. Só que quem começa pelo backend ganha uma visão melhor do todo, porque já lida com banco de dados, regras de negócio e funcionalidades às vezes bem complexas na camada de tratamento de dados. O frontend, por começar preso a HTML, CSS e JavaScript, demora um pouco mais pra chegar nos assuntos avançados

Por que eu trago isso pra cá? Porque a lógica do "resultado visível" vale igual aqui

Um plugin publicado e marcado com o tópico é trabalho SEU, público, dentro de um projeto novo, onde a concorrência ainda é pequena. É portfólio de verdade, com código rodando na máquina de outra pessoa, não mais um repositório de exercício

E em ecossistema novo o custo de entrar é baixo. Quanto mais cedo, melhor 😀

Pra quem tá nessa decisão de por onde começar e de como montar um portfólio público, esse vídeo do canal entra bem aqui

Conclusão: marque o repositório e acompanhe as mudanças

Recapitulando o caminho: escreve o módulo TypeScript com export const name e export function apply(ctx: Context), testa local pelo cordis.yml (com caminho absoluto!), escolhe entre publicar no npm ou gerar o tarball com pnpm pack, e aí sim publica o repositório e adiciona o tópico dsh-plugin

Depois é acompanhar a documentação oficial, porque o projeto está em developer preview, itera rápido e avisa explicitamente que vai ter mudança quebrando compatibilidade

O repositório oficial é publicado sob licença MIT pela DeepSeek AI, o que ajuda bastante na hora de construir em cima. Se você quer entender melhor o que o open source garante nesse tipo de projeto (e o que ele não garante), esse papo rende

Marca o tópico no teu repo e bora ver o ecossistema crescer

até o próximo post!