Como corrigir erros de instalação e versão do dsh

O que a instalação do DeepSeek Harness realmente é

A instalação do DeepSeek Harness consiste num comando: npx @deepseek-ai/dsh web. Não existe instalador nem serviço para configurar. A maioria dos problemas encontrados não está relacionada com a instalação. Está relacionada com a resolução da versão: qual build de @deepseek-ai/dsh o npx decidiu executar hoje e se a sua versão do Node.js consegue executá-lo.

Dois factos determinam tudo o que se segue. Primeiro, todas as versões de @deepseek-ai/dsh publicadas no npm até agora são release candidates, e a tag latest aponta para uma delas. Em 18 August 2026, essa versão é 0.1.0-rc.7, publicada em 17 August 2026. Segundo, o README do projeto informa que o harness está em developer preview, que o desenvolvimento é rápido e que haverá alterações incompatíveis. Uma flag que funcionou na semana passada pode desaparecer esta semana. Fixe uma versão antes de criar qualquer componente sobre ela.

Primeiro, alguns termos. dsh é a ferramenta de linha de comandos do DeepSeek Harness. Node.js é o runtime JavaScript de que ela precisa. npx é o executor de pacotes incluído no npm (node package manager) e obtém um pacote quando necessário, em vez de o instalar permanentemente.

Qual versão do Node.js o dsh exige?

O arquivo package.json na raiz do repositório declara "engines": {"node": "^22.19.0 || >=24.0.0"}, lido em 18 August 2026 na versão 0.1.0-rc.7. Portanto, use Node 22.19.0 ou mais recente dentro da linha 22, ou Node 24 ou posterior. Node 20 não é compatível.

Verifique a versão instalada antes de qualquer outra coisa.

node -v
npm -v

Esta é a parte que surpreende algumas pessoas. O pacote @deepseek-ai/dsh publicado não contém um campo engines próprio. Apenas a raiz do monorepo declara esse campo, e esse arquivo da raiz nunca é publicado no npm. Portanto, o npm não tem nada para verificar: não exibe nenhum aviso EBADENGINE e não recusa a instalação. No Node 20, a instalação parece funcionar, e a falha só ocorre mais tarde, quando o código carregado usa uma sintaxe ou uma API que o seu runtime não oferece. Não existe uma única mensagem de erro estável para pesquisar, porque a linha que falha primeiro depende do módulo carregado primeiro. Consulte node -v em vez de interpretar apenas o crash.

Se a versão do Node for antiga demais, o nvm (node version manager) é a correção menos invasiva num VPS, porque instala os arquivos no seu diretório pessoal e não altera o Node do sistema.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
exec $SHELL -l
nvm install 24
nvm use 24
node -v

node -v agora deve exibir uma versão que começa com v24.. Se o shell ainda informar a versão antiga, a função do nvm não foi carregada. Abra um novo shell de login e tente novamente. Node 24.19.0 é a versão LTS (long term support) ativa em August 2026 e é o melhor destino por um segundo motivo explicado abaixo.

Por que o npx executa uma versão diferente todos os dias?

npx @deepseek-ai/dsh web não especifica nenhuma versão, por isso o npx consulta o registo para descobrir para onde aponta a tag latest. Essa tag muda. Quando a DeepSeek publica 0.1.0-rc.8, o comando guardado nas suas notas começa a executar código diferente, sem pedir confirmação e sem apresentar um changelog.

Pode consultar cada componente variável a partir da linha de comandos.

npm view @deepseek-ai/dsh dist-tags
npm view @deepseek-ai/dsh versions --json
npm view @deepseek-ai/dsh time --json

dist-tags mostra para onde latest aponta neste momento. Em 18 August 2026, tanto latest como next apontavam para 0.1.0-rc.7, por isso não existe um canal stable separado para utilizar. A lista versions é mais interessante porque contém lacunas: 0.0.1-rc.1, 0.0.1-rc.2, 0.0.1-rc.5, 0.1.0-rc.2, 0.1.0-rc.3, 0.1.0-rc.6, 0.1.0-rc.7. Faltam números nessa sequência porque alguns release candidates nunca foram publicados. Tentar adivinhar o próximo -rc.N num script de deploy vai falhar. Leia a lista em vez de contar para cima.

Por que o npx continua a executar uma versão antiga?

Esta é a reclamação oposta, e ambas são válidas, dependendo de qual npm está a executar.

O npx mantém o seu próprio diretório de pacotes, separado da cache de tarballs, numa pasta chamada _npx dentro da cache do npm. Mostre o caminho e examine-o.

npm config get cache
ls "$(npm config get cache)/_npx"

Durante anos, o npx reutilizou o que encontrava nesse local para um nome de pacote simples e nunca consultou novamente o registry. O npm 11.2.0 alterou esse comportamento. Quando a especificação é um nome simples ou um intervalo de versões, o npx obtém agora o manifesto e reutiliza a cópia em cache apenas quando o tarball resolvido corresponde ao que o registry acabou de devolver.

O comportamento depende da versão do Node, porque o Node inclui uma versão específica do npm:

• O Node 20.20.2 inclui o npm 10.8.2.
• O Node 22.19.0 inclui o npm 10.9.3.
• O Node 22.23.2, a versão 22 mais recente, inclui o npm 10.9.8.
• O Node 24.19.0 inclui o npm 11.17.0.

Assim, toda a linha Node 22, oficialmente suportada pelo harness, inclui uma versão do npm anterior à 11.2.0. No Node 22, um npx @deepseek-ai/dsh web simples continuará a executar a release candidate que ficou em cache há semanas. O mesmo comando no Node 24 volta a resolver o pacote em cada execução. O mesmo comando produz dois comportamentos, sem que nenhum deles mostre um aviso. Peça à ferramenta para indicar a versão:

npx @deepseek-ai/dsh --version

Limpar a cache do npx

No npm 11.2.0 e posteriores, existem subcomandos específicos.

npm cache npx ls
npm cache npx rm --force

Sem --force, o npm recusa-se a apagar tudo e mostra Please use --force to remove entire npx cache. Use npm cache npx ls primeiro quando quiser remover uma entrada pela chave, em vez de remover todas.

No npm 10, esses subcomandos não existem. Nesse caso, elimine o diretório manualmente.

rm -rf "$(npm config get cache)/_npx"

npm cache clean --force não ajuda neste caso. Este comando limpa _cacache, o armazenamento de tarballs, mas deixa _npx intacto. Essa separação explica por que razão o npm adicionou posteriormente os subcomandos npm cache npx. Limpar _npx também não causa perda permanente: este diretório contém pacotes descarregados, enquanto o estado do harness fica em $DSH_HOME/profiles/<name> e não é afetado.

Como fixar um release candidate exato?

Indique a string completa da versão, incluindo a parte -rc.N.

npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

--yes é importante num script, porque o npx, caso contrário, mostra um prompt antes de instalar um pacote que ainda não encontrou e fica à espera de uma resposta que nunca chega.

Uma versão exata também é o caminho mais rápido. O npx baseia o diretório da cache na especificação introduzida e, quando a versão é exata, compara-a com o ID do pacote já instalado nesse diretório e executa-o sem fazer qualquer nova consulta ao registry. No npm 11.2.0 e posteriores, usar apenas o nome implica obter o manifest em cada arranque.

Uma instalação global fixa a versão da mesma forma e fornece um comando curto.

npm install -g @deepseek-ai/dsh@0.1.0-rc.7
dsh --version

Nenhuma versão correspondente encontrada para @deepseek-ai/dsh@^0.1.0

Um intervalo com caret ou til não corresponde a este pacote. npm install -g @deepseek-ai/dsh@^0.1.0 responde com o código de erro ETARGET e a linha No matching version found for @deepseek-ai/dsh@^0.1.0. O registry está a funcionar corretamente. Esta é uma regra do semver: um intervalo de versões não corresponde a uma versão prerelease, a menos que o próprio intervalo indique uma prerelease. Todas as builds publicadas deste pacote são -rc.N, que é uma prerelease, por isso ^0.1.0 não corresponde a nada. Escreva a versão exata.

Esta regra tem um efeito secundário útil. Como os intervalos não podem avançar para um novo release candidate, não há um estado parcialmente fixado para analisar. Está numa versão exata ou numa tag que pode mudar.

Devo usar npx ou instalar dsh globalmente?

Use npx para uma primeira avaliação, porque nada fica no sistema, exceto um diretório de cache que agora sabe como limpar. Use uma instalação global com versão fixada para tudo o que tiver de continuar a funcionar depois de um reboot, como um agente de programação que mantém em execução numa VPS.

Os dois podem apresentar resultados diferentes num servidor onde tenha usado ambos. Compare-os.

which dsh
dsh --version
npx @deepseek-ai/dsh --version

which dsh não encontrar nada logo depois de uma instalação global bem-sucedida quase sempre significa que o diretório global de binários do npm está ausente do seu PATH. Execute npm prefix -g para mostrar a raiz. Os binários ficam no diretório bin dentro dela.

Há uma questão de segurança. O npx transfere e executa código do registry sempre que resolve algo novo. Num servidor, isto é uma exposição real, não uma possibilidade teórica. Fixar a versão é parte da solução. O restante está explicado em como os ataques à cadeia de fornecimento do npm chegam a um servidor.

O que a developer preview significa para a reprodutibilidade

0.1.0-rc.6 foi publicado em 13 de agosto de 2026 e 0.1.0-rc.7 em 17 de agosto de 2026. Apenas quatro dias de diferença. A este ritmo, instruções escritas há um mês podem descrever uma linha de comandos que já não existe, incluindo esta página. Registe a data de cada afirmação sobre versões, incluindo nas suas próprias notas.

Dois hábitos tornam a preview utilizável. Fixe a versão exata em cada comando e script, para que reconstruir um servidor produza o mesmo harness. Depois, consulte a saída da ajuda da build fixada, em vez de usar um guia.

npx @deepseek-ai/dsh@0.1.0-rc.7 --help
npx @deepseek-ai/dsh@0.1.0-rc.7 web --dump-config

A segunda parte da reprodutibilidade é o perfil. dsh --profile <name> inicia o perfil armazenado em $DSH_HOME/profiles/<name>, e os perfis web e headless são criados a partir de templates fornecidos na primeira utilização. Esse diretório também é onde o harness lê a chave da API, o modelo e as definições do endpoint, pelo que uma versão fixada e uma configuração funcional são dois aspetos distintos a configurar corretamente. Os bundles incluídos são resolvidos a partir da instalação do dsh que está atualmente em execução. Isto significa que alterar a versão fixada também altera esses bundles. Os plugins externos funcionam de forma diferente. Ficam no diretório do perfil, e dsh plugin --profile <name> add <package> encaminha os argumentos para o pnpm para os instalar. Por isso, o pnpm tem de estar no seu PATH, e o dsh informa claramente quando não está. O package.json do próprio perfil é o que fixa esses plugins. Assim, uma fixação completa abrange dois ficheiros, não um.

Esta separação será familiar se já tiver mantido ferramentas Python em ambientes isolados num servidor: a ferramenta e os componentes que lhe adiciona são fixados em locais separados. Depois de o harness iniciar, a questão seguinte costuma ser a rede, não as versões. É nesse ponto que entram aceder à Web UI do dsh num VPS remoto e o guia mais longo em instalar o DeepSeek Harness num VPS.

Erros de argumentos que verá na prática

Estes erros vêm do próprio analisador da CLI. Por isso, são estáveis ao longo da linha de versões release candidate e cada um identifica o problema exato.

error: --profile <name> is required

Executou npx @deepseek-ai/dsh sem subcomando e sem perfil. O comando sem argumentos inicia um perfil, por isso precisa de um nome. dsh web é o subcomando que não aceita --profile, porque inicia automaticamente o perfil web fornecido com o pacote.

error: --patch needs a path

--patch foi fornecido sem nada depois dele. A flag pode ser repetida, e cada ocorrência recebe um caminho de ficheiro.

error: --dump-config and --dump-default-config are mutually exclusive

Escolha uma das opções. --dump-default-config apresenta as camadas do pacote fornecido e não aceita --patch. --dump-config apresenta a configuração composta de um perfil. Ambas apresentam a informação e terminam sem iniciar o harness, o que as torna a forma segura de ver o que uma nova versão release candidate alterou.

error: plugin needs pnpm arguments to forward (e.g. add <package>)

dsh plugin --profile <name> foi fornecido sem argumentos para encaminhar. O subcomando inicializa o perfil quando este não existe e depois encaminha o restante da linha de comandos para pnpm. Por isso, precisa de argumentos como add @scope/dsh-plugin-example.

FAQ

De que versão do Node.js o DeepSeek Harness precisa?

O repositório declara ^22.19.0 || >=24.0.0 no seu package.json raiz, consultado em 18 August 2026 na versão 0.1.0-rc.7. Portanto, precisa de Node 22.19.0 ou posterior na linha 22, ou de Node 24 ou mais recente. Node 20 não funciona. O pacote npm publicado não tem um campo engines próprio. Por isso, o npm não apresenta avisos nem bloqueia a instalação, e a falha só aparece durante a execução. Verifique primeiro node -v. Node 24 é a melhor escolha, porque inclui npm 11, que corrige a reutilização de versões pelo npx.

Como forço o npx a usar a versão mais recente do dsh em vez de uma versão em cache?

No npm 11.2.0 e posteriores, npx @deepseek-ai/dsh já consulta novamente o registry em cada execução quando recebe apenas o nome de um pacote. No npm 10, incluído em todas as versões do Node 22, isso não acontece. Limpe a cache do npx com npm cache npx rm --force no npm 11 ou elimine a pasta com rm -rf "$(npm config get cache)/_npx" no npm 10. Depois, confirme com npx @deepseek-ai/dsh --version. Tenha em atenção que npm cache clean --force limpa um diretório diferente e não corrige este problema.

Por que a instalação de @deepseek-ai/dsh@^0.1.0 falha?

O npm devolve o código de erro ETARGET com a linha No matching version found for @deepseek-ai/dsh@^0.1.0. Todas as versões publicadas são versões de pré-lançamento, como 0.1.0-rc.7, e um intervalo semver não corresponde a versões de pré-lançamento, a menos que o próprio intervalo inclua uma. Instale a string de versão exata, incluindo o sufixo -rc.N. Execute npm view @deepseek-ai/dsh versions --json para ver que versões existem, porque a sequência tem lacunas nos pontos em que os release candidates não foram publicados.

Devo instalar o dsh globalmente ou executá-lo através do npx?

O npx é adequado para uma primeira avaliação, porque nada fica persistente além de um diretório de cache. Uma instalação global fixada, como npm install -g @deepseek-ai/dsh@0.1.0-rc.7, é adequada para algo que tenha de continuar a funcionar, porque a versão só muda quando a altera. Se o comando dsh não for encontrado depois de uma instalação global, o diretório binário global do npm está ausente do seu PATH, e npm prefix -g mostra a raiz sob a qual ele se encontra.

O DeepSeek Harness já é suficientemente estável para servir de base?

Ainda não, segundo a própria descrição do projeto. O README afirma que o projeto está em pré-visualização para programadores, evolui rapidamente e terá alterações incompatíveis. Os release candidates 0.1.0-rc.6 e 0.1.0-rc.7 foram publicados com quatro dias de intervalo em August 2026. Fixe uma versão exata e leia --help dessa versão fixada, em vez de o consultar num guia. Date as suas próprias notas, para conseguir determinar quando ficaram desatualizadas.