Plugins dsh: como funcionam e como avaliá-los

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

Os plugins dsh são pacotes Node que o DeepSeek Harness carrega no próprio processo. Instalar um plugin executa código de terceiros com as permissões do seu agente, na máquina que o agente já consegue alcançar. Nada separa um plugin carregado do restante do harness. Portanto, antes de instalar um plugin, a pergunta é o que esse código pode aceder e como limitar esse acesso.

dsh (DeepSeek Harness) é o harness de agentes de código aberto da DeepSeek AI, criado sobre um framework de plugins chamado Cordis. Essa palavra intermédia é 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. Qualquer componente instalado externamente ao projeto entra na mesma árvore, com o mesmo nível de confiança que os componentes fornecidos com ele. Se ainda não instalou um, comece por o DeepSeek Harness num VPS e volte aqui antes de adicionar qualquer componente.

Os pontos de extensão que um plugin pode alcançar estão listados no AGENTS.md do repositório. Em August 2026, incluem:

• LLM (large language model): o fornecedor pago pela sua API key
• 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 sua configuração guardada e as variáveis de ambiente

Um plugin também regista ferramentas em ctx.tools, e a documentação deixa claro que o schema de uma ferramenta registada é incluído na montagem do prompt. É esta segunda parte que costuma passar despercebida. Um plugin pode alterar aquilo que o seu agente decide fazer sem que o próprio código execute algo invulgar, porque a descrição que o plugin fornece passa a ser texto lido pelo modelo. O problema tem a mesma natureza de prompt injection contra agentes de programação, com uma diferença: este 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 a unidade que guarda as suas escolhas é um perfil. $DSH_HOME usa ~/.dsh por predefinição, e cada perfil fica em $DSH_HOME/profiles/<name>. Os perfis web e headless são criados automaticamente 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 correções sobre esses bundles

ls ~/.dsh
ls ~/.dsh/profiles/web

O arranque aplica as camadas nesta ordem, e 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> fornecidos 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 a árvore composta. --dump-config adiciona as camadas de perfil e de correções do utilizador, sendo o mais próximo de um inventário fiável do que o próximo arranque irá carregar. Consulte-o antes de confiar numa máquina que herdou.

Há um aviso sobre esses ficheiros de correções. A configuração não é apenas dados inertes neste caso, porque o formato permite valores identificados com !!js dentro do 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 da mesma origem.

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 mesmo modelo de segurança da instalação de qualquer dependência ao estilo do npm, com uma etapa 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 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 onlyBuiltDependencies ou pnpm approve-builds. Verifique qual versão do pnpm tem:

pnpm --version

Vale a pena manter essa predefinição, mas ela também é o recurso de segurança mais mal interpretado do 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 a finalidade de um plugin é o harness importá-lo e chamá-lo no arranque seguinte. Um plugin não precisa de um hook postinstall. Foi carregado de forma autorizada.

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ões flutuante significa que o código dentro do processo do seu agente pode mudar em qualquer instalação ou atualização sem que você tome essa decisão. Fixe a versão.

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

A posição das flags varia entre versões do pnpm. Por isso, verifique o resultado em vez de confiar no comando. Abra o package.json do perfil depois e confirme que a dependência aparece como uma versão simples, sem ^ ou ~ à sua frente. Esse ficheiro determina o que é instalado.

Depois, mantenha o lockfile, que fixa toda a árvore transitiva e não apenas o nome de nível superior:

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

Copie-o para um local incluído nos backups, juntamente com o package.json do perfil. Esses dois ficheiros reconstroem a mesma árvore num novo servidor. Execute dsh plugin --profile web update quando decidir alterar versões, nunca como limpeza de rotina, e leia o diff do lockfile depois.

Para um plugin instalado a partir do git e não de um registry, fixe o commit em vez da branch. Uma especificação no formato github:owner/repo#<full commit sha> fornece uma árvore fixa. O nome de uma branch fornece o conteúdo dessa branch na próxima vez que o pnpm a resolver. Nesse caso, essa decisão fica entregue a outra pessoa. O próprio harness exige a mesma disciplina, porque cada build publicado do dsh é um release candidate e uma instalação sem versão fixa pode resolver para outro em qualquer dia. É daí que provém a maioria dos erros de instalação e versão do dsh.

O mercado de plugins e o valor da curadoria

O dsh tem um mercado de plugins e é instalado como um plugin. Isso revela alguns aspetos da arquitetura:

dsh plugin --profile web add dshmarket

Depois de reiniciar, o mercado aparece em Settings e, em seguida, Plugin Market. O README explica claramente as limitações. As instalações estão limitadas às fontes listadas num registo com curadoria, e qualquer outra fonte é rejeitada. Os scripts de compilação estão bloqueados por predefinição, e ativá-los requer aprovação por pacote. Os plugins de terminal são sinalizados antes de serem incluídos num perfil web. A frase mais importante é que a listagem não constitui uma recomendação, porque os plugins são código de terceiros.

Uma lista com curadoria eleva o nível mínimo de segurança. Não analisa o código por si, nem pode dizer o que a próxima versão de um plugin fará depois de a conta do responsável pela manutenção mudar de mãos. Trate uma instalação com um clique da mesma forma que trataria curl | bash do mesmo autor. Vale a pena repetir outra linha desse README: uma cópia de segurança exportada pode conter credenciais do seu ficheiro de configuração do perfil. Nunca a anexe a um problema público nem a um site de colagem de texto. Se quiser uma lista inicial em vez de um método, plugins do dsh que vale a pena instalar é o artigo complementar deste.

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

A verificação reduz a frequência com que algo malicioso entra. O princípio do menor privilégio determina o que esse processo pode alcançar quando isso acontece. Num VPS, configurar essa segunda camada é simples.

Crie uma conta Unix exclusiva para o harness, com o seu próprio diretório pessoal, 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 crie o seu diretório pessoal nessa conta:

npx @deepseek-ai/dsh web

A interface web fica disponível em http://127.0.0.1:3080 por predefinição. Mantenha essa configuração. Se alguma vez clicou nessa ligação apresentada a partir de outra máquina e não recebeu resposta, o que o dsh quer dizer quando apresenta esse endereço explica o motivo. Qualquer sistema que alcance essa porta pode controlar um agente com acesso a uma shell. Por isso, publicar a porta 3080 equivale a publicar uma shell remota sem privilégios de root, com uma interface simples. Aceda a ela a partir do seu portátil através de um túnel SSH:

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

Depois, confirme que não existe nenhum processo a escutar num endereço público:

ss -lnt | grep 3080

O endereço local deve ser 127.0.0.1:3080. Se for 0.0.0.0:3080, a firewall é a única barreira entre um intruso e o seu agente. O raciocínio apresentado em executar o Claude Code com segurança num VPS aplica-se igualmente ao dsh. Dê ao agente um único diretório de trabalho que ele possa destruir e mantenha fora dessa máquina tudo o que não conseguir recriar. Melhor ainda, trate o sistema como uma VM descartável para agentes de programação, porque recriar um VPS demora uma hora, enquanto auditá-lo pode demorar 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 dos modelos em $DSH_HOME/settings.yaml e o histórico de sessões em $DSH_HOME/storages. A documentação configuração das chaves de API, dos modelos e dos endpoints do dsh explica qual chave deve ficar em cada ficheiro e o que é efetivamente enviado para fora do sistema em cada modo. Resolva isso antes de adicionar um plugin, porque cada chave que configura é mais um dado que um plugin pode ler. Restrinja as permissões dos 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 concede qualquer permissão aos restantes utilizadores. Isto é importante tanto na notação numérica como na simbólica (modos numéricos e simbólicos do chmod). Seja claro sobre o que esta proteção oferece. Os modos dos ficheiros protegem esses ficheiros contra outras contas no sistema. Não protegem contra um plugin, porque o plugin é executado pelo 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. Um sistema com dsh deve guardar apenas a chave do modelo de que necessita. 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 interface Web fornece aos plugins recursos 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 de cada perfil, fornece a sandbox e a política de aprovação. Use-o. Uma sessão que pode obter páginas não confiáveis deve exigir aprovação para qualquer operação que escreva ou execute algo. Assim, uma instrução obtida não se pode tornar uma ação por si só. Colocar as ações do agente atrás de aprovações explica como decidir onde colocar esse limite. A relação também funciona no sentido inverso, porque o seu próprio servidor é uma página que o agente de alguém vai obter. Esse é o contexto 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 compare 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. Se um plugin instalado para uma funcionalidade pequena adicionar várias entradas que não consegue justificar, pare e leia o código-fonte antes de o iniciar. dsh plugin --profile web why <package-name> responde à outra pergunta: qual das suas dependências diretas trouxe um determinado pacote.

Os pacotes instalados ficam em $DSH_HOME/profiles/node_modules. Também pode consultar a árvore no disco:

ls ~/.dsh/profiles/node_modules

Mantenha um segundo perfil que nunca utiliza para fazer experiências. Se uma instalação danificar o harness, iniciar dsh --profile <clean-name> permite confirmar 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 do Cordis e pode aceder às interfaces de capacidade documentadas, incluindo shell, sistema de ficheiros, web, subprocessos, subagentes e credenciais. dsh-base, o primeiro bundle de cada perfil, 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 é assumir que instalar um plugin estende a sua confiança ao autor e a todos os pacotes da respetiva árvore de dependências.

Posso instalar um plugin do dsh sem executar os 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 sem a aprovação desse pacote. Confirme a versão com pnpm --version. Isto não torna seguro um plugin que não tenha sido analisado. O código do próprio plugin é executado no arranque seguinte porque o harness o carrega deliberadamente. Nenhuma restrição aplicada durante a instalação altera esse comportamento.

Onde ficam efetivamente 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 perfil contém um package.json com as dependências dos respetivos plugins, o manifesto dsh.profile dos bundles ordenados e uma camada de correções cordis.patch.yml. Os pacotes instalados ficam em $DSH_HOME/profiles/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 pessoal é 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, exceto quando os aprova por pacote. Isto representa uma melhoria real em relação a colar um nome de pacote a partir de uma janela de chat. O próprio README indica que a listagem não constitui uma recomendação, porque os plugins são código de terceiros criado 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.