SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Plugins dsh: como funcionam e como avaliá-los

Um plugin dsh executa código de terceiros dentro do seu agente, com as permissões dele. Veja o que pode acessar e como verificar o pacote antes da instalação.

O que é um plugin dsh e o que ele pode fazer?

Os plugins dsh são pacotes Node que o DeepSeek Harness carrega no seu próprio processo. Depois de carregado, um plugin executa código de terceiros com as permissões do seu agente, na máquina que o agente já consegue alcançar. A própria instalação é mais protegida do que isso. O pnpm bloqueia os scripts de compilação das dependências até que os aprove, e a referência da CLI diz para "Restart that Profile after adding, removing, or updating a Bundle", por isso um plugin adicionado com dsh plugin é carregado no reinício seguinte. Um plugin instalado na página Plugins da interface web pode ser aplicado imediatamente. Nada se interpõe entre um plugin carregado e o restante do harness. Por isso, antes de instalar um plugin, pergunte que recursos esse código pode aceder e como manter esse acesso reduzido.

dsh (DeepSeek Harness) é o harness de agentes open source da DeepSeek AI, criado sobre um framework de plugins chamado Cordis. Esse termo intermédio é importante, porque um harness de agentes é o programa que envolve o modelo e controla o ciclo de execução, as ferramentas e as permissões. Um plugin integra-se exatamente nesse nível. O README do projeto afirma que tudo é um plugin. O adaptador do modelo é um plugin. A interface web onde escreve também é um plugin. Tudo o que instalar de fora do projeto entra na mesma árvore, com o mesmo nível de confiança das partes fornecidas com ele. Se ainda não iniciou um, comece por o DeepSeek Harness num VPS e volte antes de lhe adicionar qualquer componente.

Em agosto de 2026, o AGENTS.md do repositório listava os pontos de extensão que um plugin podia alcançar, incluindo:

  • LLM (large language model): o fornecedor pago pela sua chave de API
  • Shell: a capacidade bash, com os fornecedores local e pwsh
  • Filesystem: acesso a ficheiros controlado por políticas
  • Web: fornecedores de pesquisa e obtenção de conteúdo
  • Subprocess: um fornecedor de árvores de processos
  • Workflow: threads de trabalho
  • Subagent: delegação para outros agentes
  • Settings and credentials: a configuração guardada e as variáveis de ambiente

Essa lista deixou entretanto o AGENTS.md. Em 17 de novembro de 2026, o docs/architecture.md do projeto nomeia os pontos de extensão de outra forma. Também adiciona backends de sandbox, terminais persistentes, tarefas em segundo plano, comandos humanos e sessões acionadas por webhooks às interfaces de modelo, ferramentas, shell, filesystem e subagent.

Um plugin também regista ferramentas em ctx.tools, e a documentação é explícita: o schema de uma ferramenta registada entra na composição do prompt. Essa segunda parte é a que muitas pessoas ignoram. Um plugin pode alterar as decisões do agente sem que o seu próprio código faça algo invulgar, porque a descrição fornecida passa a ser texto lido pelo modelo. O problema tem a mesma forma que a injeção de prompts contra agentes de programação, com uma diferença: esse texto chega quando instala o plugin e permanece até o remover.

Como o dsh encontra e carrega plugins?

Não existe um diretório global de plugins. Um dsh em execução é uma árvore de plugins composta no arranque a partir de camadas ordenadas, e o perfil é a unidade que guarda as suas escolhas. $DSH_HOME usa ~/.dsh por predefinição, e cada perfil fica em $DSH_HOME/profiles/<name>. Os perfis web e headless são criados na primeira utilização a partir dos templates fornecidos.

Um diretório de perfil contém dois ficheiros que determinam tudo:

  • package.json, com as dependências de plugins externos e um manifesto dsh.profile que contém a lista ordenada bundles
  • cordis.patch.yml, a sua própria camada de patches sobre esses bundles
ls ~/.dsh
ls ~/.dsh/profiles/web

O arranque aplica as camadas por esta ordem. As camadas posteriores prevalecem:

  1. uma raiz vazia
  2. os bundles do perfil, pela ordem indicada no manifesto
  3. o cordis.patch.yml do perfil
  4. $DSH_HOME/cordis.patch.yml
  5. quaisquer overlays --patch <path> passados na linha de comandos

Duas flags mostram o resultado dessa composição sem iniciar nada:

dsh --profile web --dump-default-config
dsh --profile web --dump-config

--dump-default-config mostra apenas as camadas de bundles. --dump-config adiciona as camadas de patches do perfil e do diretório home, além de quaisquer overlays --patch. É, portanto, o mais próximo de um inventário fiável do que o próximo arranque vai carregar. Consulte-o antes de confiar numa máquina que herdou.

Tenha atenção a esses ficheiros de patches. A configuração não é apenas dados inertes neste caso, porque o formato permite valores etiquetados !!js no bloco config de um plugin. Um fragmento cordis.patch.yml copiado de uma publicação num fórum é código. Trate-o como trataria um script de shell proveniente da mesma fonte.

O que dsh plugin add executa realmente?

dsh plugin --profile <name> <args> encaminha os argumentos para o pnpm dentro do diretório desse perfil, por isso o pnpm tem de estar no PATH. Os verbos são os verbos do pnpm:

dsh plugin --profile web add '<package-or-git-spec>'
dsh plugin --profile web remove '<package-name>'
dsh plugin --profile web why '<package-name>'
dsh plugin --profile web update

O modelo de segurança da instalação de um plugin dsh é, portanto, o modelo de segurança da instalação de qualquer dependência ao estilo npm, com um passo adicional em que o resultado é carregado no seu agente. O pacote inclui a sua própria árvore de dependências, e todos os pacotes dessa árvore acabam no mesmo processo. Tudo o que se aplica a como os ataques à cadeia de fornecimento do npm chegam a um servidor aplica-se aqui sem alterações.

O pnpm 10 e versões posteriores não executam por predefinição os scripts de compilação de uma dependência, e a aprovação é feita por pacote através de pnpm approve-builds ou da definição allowBuilds. O pnpm 11 substituiu a definição antiga onlyBuiltDependencies por allowBuilds, por isso um guia ou uma configuração antiga que ainda use onlyBuiltDependencies não aprova nada numa versão atual do pnpm. Verifique qual é a versão do pnpm instalada:

pnpm --version

É nos plugins alojados num repositório Git que isto aparece primeiro. A referência da CLI indica que um plugin Git que inclua código-fonte é compilado durante a instalação através do seu script prepare. Por isso, o primeiro add falha com a indicação allowBuilds do pnpm. Copie a chave apresentada para pnpm-workspace.yaml no perfil e execute novamente. A aprovação dessa chave permite que a compilação do repositório seja executada com as permissões do seu utilizador. Os tarballs já compilados e os checkouts locais não precisam de autorização.

Vale a pena manter essa predefinição, mas ela também é o recurso de segurança mais sobrevalorizado deste ecossistema. Os scripts de compilação bloqueados impedem a execução de código durante a instalação. Não fazem nada contra o próprio plugin, porque o objetivo de um plugin é que o harness o importe e o invoque quando o perfil for reiniciado, ou assim que a instalação for aplicada quando usou a página Plugins da interface web. Um plugin não precisa de um hook postinstall. Ele foi autorizado a entrar.

O que ler antes de instalar um plugin do dsh

Transfira o tarball publicado e leia-o. Nada é executado quando descompacta um arquivo.

npm pack '<package-name>@<version>'
tar -tzf '<package-name>-<version>.tgz'
tar -xzf '<package-name>-<version>.tgz'
less package/package.json

Quatro campos nesse package.json fornecem a maior parte das informações de que precisa. Leia scripts para consultar as entradas preinstall, install e postinstall. Leia dependencies para identificar nomes que não reconhece ou nomes que diferem por apenas um carácter de outros que reconhece. Leia bin para verificar tudo o que o pacote pretende colocar no seu PATH. Leia main ou exports para localizar o ficheiro de entrada. Depois, abra esse ficheiro e siga a cadeia de execução.

Em seguida, leia o código que será efetivamente carregado. Um plugin que anuncia uma ferramenta de notificações não tem motivo para ler ~/.ssh, contactar um host que nunca ouviu mencionar ou iniciar uma shell. Se o pacote distribuir apenas JavaScript empacotado ou minificado e não existir código-fonte correspondente num repositório público, essa é a sua resposta. Prefira plugins cujo código-fonte possa ler e prefira os mais pequenos.

Também pode consultar o registry sem instalar nada:

pnpm view '<package-name>' dependencies
pnpm view '<package-name>' versions

Um pacote publicado na semana passada, com uma versão, sem o campo de repositório e com um nome que imita algo popular, é o truque mais antigo de qualquer registry. Verificar transferências com checksums é a prática complementar: saiba exatamente o que transferiu antes de o deixar executar.

Fixe a versão e mantenha o lockfile

Um intervalo de versão flutuante significa que o código dentro do processo do seu agente pode mudar em qualquer instalação ou atualização sem que você decida nada. Fixe-o.

dsh plugin --profile web add --save-exact '<package-name>@<version>'

A posição das flags varia entre as versões do pnpm, portanto verifique o resultado em vez de confiar no comando. Abra o package.json do perfil posteriormente e confirme se a dependência aparece como uma versão simples, sem nenhum ^ ou ~ na frente. Esse arquivo decide o que é instalado.

Em seguida, mantenha o lockfile, que fixa toda a árvore transitiva em vez de apenas o nome de nível superior:

find ~/.dsh -maxdepth 3 -name 'pnpm-lock.yaml'

Copie-o para um local onde você faça backups, juntamente com o package.json do perfil. Esses dois arquivos reconstroem a mesma árvore em uma nova máquina. Execute dsh plugin --profile web update apenas quando decidir alterar versões, nunca como uma limpeza de rotina, e leia o diff do lockfile logo após.

Para um plugin instalado a partir do git em vez de um registro, fixe o commit em vez da branch. Uma especificação no formato github:owner/repo#<full commit sha> garante uma árvore fixa. Um nome de branch entrega o que aquela branch contiver na próxima vez que o pnpm a resolver, o que é uma decisão que você delegou a outra pessoa. O próprio harness exige a mesma disciplina, pois o lançamento latest do npm é um release candidate e uma instalação sem versão fixa pode ser resolvida para uma versão diferente a qualquer momento, que é de onde vêm a maioria dos erros de instalação e versão do dsh.

O mercado de plugins e o valor real de uma lista selecionada

O dsh tem um marketplace que é instalado como um plugin. Isso revela algo sobre a arquitetura:

dsh plugin --profile web add dshmarket

Depois de reiniciar, ele aparece como um separador na página Plugins, ao lado de Installed, no dsh 0.2.1 e posteriores. Em hosts mais antigos, use Settings e depois Plugin Market. O README é claro quanto às limitações. As instalações estão limitadas às fontes listadas num registo selecionado, e qualquer outra fonte é rejeitada. Os scripts de compilação estão bloqueados por predefinição, e ativar um exige aprovação por pacote. Os plugins de terminal são sinalizados antes de serem adicionados a um perfil web. A frase mais importante é que a inclusão na lista não constitui uma recomendação, porque os plugins são código de terceiros. O mesmo README diz que a maioria dos plugins instalados através deste mecanismo fica ativa depois de atualizar a página, sem reiniciar. Assim, uma instalação com um clique pode estar em execução dentro do seu agente poucos segundos depois.

Uma lista selecionada eleva o nível mínimo de segurança. Mas não analisa o código por si, nem consegue dizer o que a próxima versão de um plugin fará depois de a conta do mantenedor mudar de mãos. Trate uma instalação com um clique como trataria curl | bash do mesmo autor. Vale a pena repetir outra linha desse README: um backup exportado pode conter credenciais da configuração do seu perfil. Nunca o anexe a um issue público nem a um site de paste. Se quiser uma lista inicial em vez de um método, plugins do dsh que vale a pena instalar é o artigo complementar deste.

O harness também tem agora a sua própria rota. Um plugin Custom experimental, que indexa bundles e é ativado na página Plugins, adiciona um separador Discover alimentado pelos ficheiros de índice que adicionar manualmente. O dsh não inclui nenhuma fonte de índice, e a documentação diz que os índices são conteúdo de terceiros. O dsh verifica o formato do ficheiro, mas não verifica as informações que um índice fornece sobre o título, o autor ou a fonte de um plugin.

Execute o dsh como seu próprio utilizador, não como root

A verificação reduz a frequência com que algo malicioso entra no sistema. O princípio do privilégio mínimo determina o que esse algo alcança quando entra. Num VPS, essa segunda parte é simples de configurar.

Crie uma conta unix dedicada para o harness com o seu próprio diretório home e nunca o execute como root:

sudo adduser --disabled-password --gecos "" dshrun
sudo -iu dshrun

Dentro dessa sessão, inicie o harness para que ele escreva os seus dados no diretório home dessa conta:

npx @deepseek-ai/dsh web

A interface web utiliza a porta http://127.0.0.1:3080 por predefinição. Mantenha-a assim. Se alguma vez clicou na ligação impressa a partir de outra máquina e não obteve resposta, o que o dsh significa quando imprime esse endereço explica o motivo. A composição web fornecida verifica os cabeçalhos Host e Origin e exige um navegador autenticado ou um API Peer para cada método Host RPC e stream WebSocket, e o dsh web recusa o --host 0.0.0.0. Os clientes da API autenticam-se através do /connect e recebem um cookie de API assinado. Trate esse login como uma segunda fechadura, não como uma razão para expor a porta 3080. Por trás dela existe um agente com acesso a uma shell, portanto, um token de sessão vazado ou um erro de login numa porta pública entrega a um estranho uma shell remota sem privilégios de root, mas com uma interface amigável. Aceda a partir do seu portátil através de um túnel SSH:

ssh -L 3080:127.0.0.1:3080 you@your-vps

Em seguida, confirme que nada está a escutar num endereço público:

ss -lnt | grep 3080

O endereço local deve indicar 127.0.0.1:3080. Se indicar 0.0.0.0:3080, algo diferente das predefinições do dsh web colocou-o lá, como uma composição diferente ou uma alteração de configuração, e essa composição gere a sua própria autenticação. A documentação do projeto afirma que o servidor web subjacente não traz autenticação ou política de Origin própria; portanto, até saber o que protege essa porta, assuma que a sua firewall é a única barreira entre um estranho e o seu agente, e mova-o de volta para o loopback. O raciocínio por trás de executar o Claude Code de forma segura num VPS aplica-se ao dsh sem alterações. Dê ao agente um diretório de trabalho que ele tenha permissão para destruir e mantenha fora dessa máquina tudo o que não possa reconstruir. Melhor ainda, trate a máquina como uma VM descartável para agentes de programação, pois reconstruir um VPS demora uma hora, enquanto auditar um demora uma semana.

Onde ficam as suas chaves e por que as permissões de ficheiros não são suficientes

O dsh mantém as chaves de API em $DSH_HOME/.credentials.yaml e os valores de ambiente em $DSH_HOME/.env, com as definições do modelo em cordis.patch.yml do perfil ativo. Quando este guia foi verificado pela primeira vez, em outubro de 2026, $DSH_HOME/settings.yaml de uma versão anterior foi importado uma vez e renomeado para settings.yaml.imported. Qual chave pertence a cada um desses ficheiros e o que é efetivamente enviado para fora da máquina em cada modo são questões abordadas em configurar as chaves de API, os modelos e os endpoints do dsh. É importante esclarecer isto antes de adicionar um plugin, porque cada chave configurada é mais um dado que um plugin pode ler. Restrinja o acesso aos dois ficheiros sensíveis:

chmod 600 ~/.dsh/.credentials.yaml ~/.dsh/.env
ls -l ~/.dsh

O modo 600 permite ao proprietário ler e escrever e não dá permissões a mais ninguém. É útil conhecer esta configuração nas duas notações (modos numéricos e simbólicos do chmod). Seja claro sobre o que ela oferece. Os modos dos ficheiros protegem esses ficheiros contra outras contas na máquina. Não oferecem proteção contra um plugin, porque o plugin é executado como o utilizador que é proprietário dos ficheiros, dentro do processo que os lê. Por isso, manter os segredos fora do alcance de um agente de IA significa não os colocar na máquina. Uma máquina com dsh deve conter apenas a chave do modelo de que precisa. As suas credenciais de cloud e as suas chaves de assinatura devem ficar noutro local.

Por que um plugin que lê a Web altera o modelo de ameaças

A camada Web fornece aos plugins mecanismos de pesquisa e obtenção de conteúdo. Um plugin que carrega uma página para a sua sessão está a carregar texto que um atacante pode escrever. Um prompt de modelo não separa instruções de dados. Por isso, uma página obtida pode conter uma linha dirigida ao seu agente, e um harness com acesso ao shell fica a um passo obediente de a executar.

O controlo já existe no harness. dsh-base, o primeiro bundle partilhado dos perfis web, headless, sdk e acp, inclui a sandbox e a política de aprovação (o perfil sdk-minimal deixa-a deliberadamente de fora). Use-o. Uma sessão que pode obter páginas não fidedignas deve exigir aprovação para qualquer operação que escreva ou execute algo, para que uma instrução obtida não se transforme numa ação por si só. Impedir ações do agente sem aprovação explica como decidir onde colocar esse limite. A relação também funciona nos dois sentidos, porque o seu próprio servidor é uma página que o agente de alguém vai obter. Esse é o caso de bloquear crawlers de IA no seu servidor.

Como verificar o que um plugin alterou?

Crie um snapshot antes da instalação, instale o plugin, crie outro snapshot e leia as diferenças.

dsh --profile web --dump-config > /tmp/dsh-before.txt
dsh plugin --profile web add '<package-name>@<version>'
dsh --profile web --dump-config > /tmp/dsh-after.txt
diff -u /tmp/dsh-before.txt /tmp/dsh-after.txt

O diff mostra quais entradas do plugin a instalação adicionou à árvore composta. Apenas um pacote que declare um patch de bundle entra na árvore. Uma dependência simples não adiciona nada ali, e dsh emite um aviso sobre isso uma vez. Se um plugin instalado para uma funcionalidade pequena adicionar várias entradas que você não consegue justificar, pare e leia o código-fonte antes de inicializá-lo. dsh plugin --profile web why <package-name> responde à outra pergunta: qual das suas dependências diretas puxou determinado pacote.

Os pacotes instalados ficam no próprio node_modules do perfil, em $DSH_HOME/profiles/<name>/node_modules. Assim, você também pode consultar a árvore no disco:

ls ~/.dsh/profiles/web/node_modules

Mantenha um segundo perfil no qual você nunca faça experiências. Se uma instalação quebrar o harness, inicializar dsh --profile <clean-name> informará em segundos se o plugin foi a causa.

Como removo um plugin do dsh?

dsh plugin --profile web remove '<package-name>'
dsh --profile web --dump-config > /tmp/dsh-after-removal.txt
diff -u /tmp/dsh-before.txt /tmp/dsh-after-removal.txt

Remover a dependência nem sempre remove a configuração. As entradas gravadas no cordis.patch.yml do perfil permanecem, porque esse ficheiro é seu e o harness não o reescreve por si. Abra o ficheiro e elimine qualquer bloco que identifique o pacote removido.

less ~/.dsh/profiles/web/cordis.patch.yml

Depois, trate da parte que nenhum comando de desinstalação consegue corrigir. Se removeu um plugin porque deixou de confiar nele, tudo o que ele podia ler já foi lido. Faça a rotação da chave da API do DeepSeek na consola do fornecedor e rode também qualquer outro segredo que estivesse em $DSH_HOME. Em seguida, determine a que recursos no resto da rede o account Unix usado pelo plugin tinha acesso.

A versão curta

  • Leia o tarball publicado antes da instalação, começando em scripts e no ficheiro de entrada
  • Fixe a versão exata ou, no caso de uma especificação git, o commit exato, e mantenha o lockfile
  • Instale num único perfil e mantenha um perfil limpo que possa iniciar quando algo falhar
  • Compare --dump-config antes e depois de cada instalação
  • Execute o harness com o seu próprio utilizador Unix, em loopback, e aceda a ele através de SSH
  • Mantenha uma chave de API no sistema e faça a rotação no dia em que remover um plugin em que já não confia

Nada disto é motivo para evitar plugins. O modelo de plugins é a razão pela qual dsh é útil, e um harness que não possa estender será substituído. O motivo é saber o que instalou, de quem, em que versão, e executar tudo num local que possa reconstruir.

FAQ

Os plugins do dsh ficam isolados uns dos outros?

Não. Um plugin é carregado no processo do harness através de Cordis e pode aceder às interfaces de capacidade documentadas, incluindo shell, sistema de ficheiros, web, subprocesso, subagente e credenciais. dsh-base, o primeiro bundle partilhado de web, headless, sdk e acp, fornece o sandbox e a política de aprovação que controlam o que as ferramentas do agente podem fazer. É essa política que fornece a proteção. Não existe um limite de permissões por plugin. O modelo correto é considerar que instalar um plugin estende a sua confiança ao respetivo autor e a todos os pacotes da árvore de dependências.

Posso instalar um plugin do dsh sem executar os respetivos scripts de instalação?

O pnpm 10 e versões posteriores bloqueiam por predefinição os scripts de compilação das dependências, e dsh plugin ... add encaminha para o pnpm. Assim, numa versão atual do pnpm, a instalação não executa scripts de pacotes, a menos que aprove esse pacote. Confirme a versão com pnpm --version. Isto não torna seguro um plugin que não tenha sido analisado. O próprio código do plugin é executado quando o harness o carrega, no reinício seguinte do perfil após uma instalação com dsh plugin ou, muitas vezes, imediatamente depois de uma instalação a partir da página Plugins da web. Nenhuma restrição aplicada durante a instalação afeta esse comportamento.

Onde ficam realmente os plugins do dsh e a respetiva configuração?

$DSH_HOME usa ~/.dsh por predefinição. Os perfis ficam em $DSH_HOME/profiles/<name>. Cada um contém um package.json com as dependências dos seus plugins, o manifesto dsh.profile dos bundles ordenados e uma camada de patches cordis.patch.yml. Os pacotes instalados ficam no node_modules próprio de cada perfil, em $DSH_HOME/profiles/<name>/node_modules. As chaves ficam em $DSH_HOME/.credentials.yaml, os valores de ambiente em $DSH_HOME/.env e um $DSH_HOME/cordis.patch.yml ao nível do diretório home é aplicado a todos os perfis. Execute dsh --profile web --dump-config para ver o resultado composto sem iniciar o sistema.

É seguro instalar a partir do mercado de plugins do dsh?

O mercado limita as instalações a fontes de um registo selecionado e bloqueia os scripts de compilação, a menos que os aprove por pacote. Isto é uma melhoria real em relação a copiar um nome de pacote de uma janela de chat. O próprio README indica que a inclusão no registo não constitui uma recomendação, porque os plugins são código de terceiros escrito por outras pessoas. Leia o código-fonte e fixe a versão. Mantenha o harness numa conta de utilizador e, idealmente, numa máquina que possa perder sem consequências graves.

Este artigo foi útil?