Corrigir erros de instalação e versão do DeepSeek Harness

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 um instalador nem um serviço para configurar. A maior parte dos problemas encontrados não está relacionada com a instalação. Está relacionada com a resolução da versão: qual compilação de @deepseek-ai/dsh o npx decidiu executar nesse dia e se a sua versão do Node.js consegue executá-la. Quando arranca, o endereço apresentado está associado a localhost. O motivo pelo qual a Web UI responde apenas em 127.0.0.1:3080 é um problema separado dos problemas abordados nesta página.

Há dois factos que determinam tudo o que se segue. Primeiro, todas as versões de @deepseek-ai/dsh publicadas até agora no npm são versões preliminares. A maioria são release candidates (-rc.N) e, desde 30 August 2026, também existem compilações alpha (-alpha.N). A tag latest aponta para uma release candidate. Em 6 October 2026, essa versão é 0.2.0-rc.2, publicada em 29 September 2026. Segundo, o README do projeto informa que o harness está em developer preview, sofre alterações rápidas e terá mudanças incompatíveis. Uma flag que funcionou na semana passada pode desaparecer nesta semana. Fixe uma versão antes de criar qualquer componente baseado nela.

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. Se o termo harness tiver aqui um significado pouco familiar, um agent harness é o programa que envolve o modelo, mantendo o ciclo de execução, as ferramentas, as permissões e o estado da sessão. Por isso, um número de versão que não escolheu pode alterar o comportamento do seu agente.

De que versão do Node.js o dsh precisa?

A raiz do repositório package.json declara "engines": {"node": "^22.19.0 || >=24.0.0"}, com leitura em 6 de outubro de 2026, quando o repositório estava na versão 0.2.1-alpha.1. Portanto, é necessário usar Node 22.19.0 ou posterior dentro da linha 22, ou Node 24 ou posterior. O Node 20 não é compatível.

Verifique primeiro o que está instalado.

node -v
npm -v

Esta é a parte que costuma causar confusão. 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 ficheiro da raiz nunca é publicado no npm. Por isso, o npm não tem nada para verificar: não apresenta nenhum aviso EBADENGINE e não recusa a instalação. No Node 20, a instalação parece funcionar, mas a falha ocorre mais tarde, quando o código carregado utiliza sintaxe ou uma API que o runtime não suporta. Não existe uma mensagem de erro única e estável para pesquisar, porque a linha que falha primeiro depende do módulo carregado primeiro. Consulte node -v em vez de analisar apenas o crash.

Se a versão do Node for demasiado antiga, o nvm (gestor de versões do Node) é a correção menos invasiva num VPS, porque é instalado no 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 deve agora apresentar uma versão que começa por v24.. Se a shell continuar a apresentar a versão antiga, a função da shell do nvm não foi carregada. Abra uma nova shell de login e tente novamente. O Node 24 é a linha LTS ativa (suporte de longo prazo) em 6 de outubro de 2026, e a versão mais recente nessa data é a 24.21.0. É o alvo mais indicado 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 registry para obter o destino atual da tag latest. Essa tag muda, e muda com frequência. 0.1.0-rc.8 foi publicada em 19 August 2026, dois dias depois de 0.1.0-rc.7, e em 6 October 2026 latest já apontava para 0.2.0-rc.2. Sempre que a tag muda, o comando guardado nas suas notas passa a executar código diferente, sem confirmação e sem um changelog disponível.

Pode consultar todos os elementos variáveis 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 6 October 2026, latest e next apontavam para 0.2.0-rc.2, e uma terceira tag, alpha, apontava para 0.2.1-alpha.1. Nenhuma delas é um canal estável para utilizar. A lista versions é mais interessante porque tem lacunas. Em 6 October 2026, continha 30 versões, de 0.0.1-rc.1 a 0.2.1-alpha.1. A linha 0.0.1 salta de -rc.2 para -rc.5, a linha 0.1.0 salta de -rc.3 para -rc.6, as versões alpha começam em 0.1.2-alpha.2 e 0.1.3-alpha.2, e não existe qualquer 0.1.4. Faltam números porque algumas versões nunca foram publicadas, e as versões alpha e release candidates aparecem intercaladas na mesma lista. Tentar adivinhar o próximo -rc.N num script de deploy vai falhar. Leia a lista em vez de incrementar os números.

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

Esta é a reclamação oposta. Ambas podem ser verdadeiras, dependendo da versão do npm que 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 consulte o conteúdo.

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

Durante anos, o npx reutilizou o que encontrava nesse diretório para um nome de pacote simples e nunca consultou novamente o registo. 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 só reutiliza a cópia em cache quando o tarball resolvido corresponde ao que o registo acabou de devolver.

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

• Node 20.20.2 inclui o npm 10.8.2.
• Node 22.19.0 inclui o npm 10.9.3.
• Node 22.23.3, a versão 22 mais recente em 6 de outubro de 2026, inclui o npm 10.9.9.
• Node 24.19.0 inclui o npm 11.17.0.
• Node 24.21.0, a versão 24 mais recente em 6 de outubro de 2026, inclui o npm 11.19.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 foi colocada em cache há semanas. O mesmo comando no Node 24 volta a resolver o pacote em cada execução. Um comando, dois comportamentos, e nenhum deles emite um aviso. Consulte a ferramenta:

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, apague o diretório manualmente.

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

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

Como fixar uma release candidate exata?

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

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

Os exemplos nesta página usam 0.1.0-rc.7. Substitua pelo build que testou efetivamente. Em 6 October 2026, a tag latest apontava para 0.2.0-rc.2.

--yes é importante num script, porque, caso contrário, o npx 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 de cache na especificação que introduziu e, para uma versão exata, compara-a com o ID do pacote já instalado nesse diretório e executa-o sem qualquer consulta ao registry. No npm 11.2.0 e posteriores, um nome sem versão implica obter o manifesto em cada arranque.

Uma instalação global fixa a versão da mesma forma e permite usar 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 tilde 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. 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 versões publicadas deste pacote são prereleases, -rc.N ou -alpha.N, pelo que ^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 uma nova release candidate, não existe um estado parcialmente fixado que seja necessário analisar. Ou 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 além de um diretório de cache que já sabe como limpar. Use uma instalação global com versão fixada para qualquer ferramenta que tenha de continuar a funcionar depois de um reboot, como um agente de programação que mantém em execução num VPS.

Os dois métodos podem produzir resultados diferentes num servidor onde ambos foram usados. Compare-os.

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

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

Uma observaçã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 apenas teórica. Fixar a versão é parte da solução. O restante está em como os ataques à cadeia de fornecimento do npm chegam a um servidor.

O que a prévia para desenvolvedores significa para a reprodutibilidade

0.1.0-rc.6 foi publicada em 13 de agosto de 2026 e 0.1.0-rc.7 em 17 de agosto de 2026. Foram quatro dias de diferença. O ritmo não diminuiu desde então: foram publicadas mais 23 versões entre 19 de agosto e 3 de outubro de 2026, incluindo 0.2.0-rc.1 em 28 de setembro e 0.2.0-rc.2 no dia seguinte. Nesse ritmo, instruções escritas há um mês podem descrever uma linha de comando que já não existe, e esta página também está sujeita a isso. Registre a data de cada afirmação sobre versões, incluindo as suas próprias notas.

Dois hábitos tornam a prévia administrável. Fixe a versão exata em cada comando e script, para que a reconstrução de um servidor produza o mesmo harness. Depois, leia a saída da ajuda da build fixada, e não de 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 dos templates incluídos na primeira utilização. Esse diretório também é onde o harness lê a chave de API, o modelo e as configurações do endpoint, portanto uma versão fixada e uma configuração funcional são dois pontos distintos que precisam de ser tratados corretamente. Os bundles incluídos são resolvidos a partir da instalação de dsh atualmente em execução, o que significa que alterar a versão fixada também altera esses bundles. Os plugins externos funcionam de forma diferente. Eles ficam no diretório do perfil, e dsh plugin --profile <name> add <package> encaminha os argumentos para pnpm para os instalar. Portanto, pnpm tem de estar no seu PATH, e dsh informa claramente quando isso não acontece. Cada plugin adicionado é executado com as mesmas permissões do seu agente. Por isso, vale a pena verificar o que um plugin pode alcançar antes de o instalar. O próprio package.json do perfil é que fixa esses plugins. Assim, uma fixação completa abrange dois ficheiros, e não um só.

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

Erros de argumentos que irá encontrar

Estes erros vêm do próprio analisador da CLI, e cada um identifica o problema exato. A redação manteve-se estável na maioria das builds, mas não em todas. Por isso, as mensagens abaixo foram verificadas com 0.2.0-rc.2 em 6 October 2026.

error: --profile <name> is required

Executou npx @deepseek-ai/dsh sem subcomando nem perfil. O comando sem argumentos inicia um perfil, por isso precisa de um nome. dsh web funciona sem --profile porque o analisador interpreta a primeira palavra isolada como o nome do perfil e inicia o perfil web fornecido com o pacote.

error: --patch needs a path

Foi passado --patch sem nada a seguir. A flag pode ser repetida, e cada ocorrência recebe o caminho de um ficheiro.

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

Escolha uma das opções. Em 0.2.0-rc.2, a build para a qual latest apontava em 6 October 2026, a mensagem identifica uma terceira flag e aparece como error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive, porque --dump-config-schema, que imprime o JSON Schema das entradas de perfil e dos patches, juntou-se às outras duas. --dump-default-config imprime as camadas do bundle fornecido com o pacote e não aceita --patch. --dump-config imprime a configuração composta de um perfil. Todas imprimem o resultado e terminam sem iniciar o harness, o que as torna a forma segura de verificar o que um novo release candidate alterou sem o seu conhecimento.

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

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

FAQ

Que versão do Node.js é necessária para o DeepSeek Harness?

O repositório declara ^22.19.0 || >=24.0.0 no seu package.json de raiz, consultado em 6 October 2026, quando o repositório estava na versão 0.2.1-alpha.1. Portanto, é necessária a versão 22.19.0 ou posterior da linha 22, ou a versão 24 ou posterior. O Node 20 não funciona. O pacote npm publicado não tem um campo engines próprio, por isso o npm não avisa nem bloqueia a instalação. A falha só aparece em tempo de execução. Verifique primeiro node -v. O Node 24 é a melhor escolha, porque inclui o npm 11, que corrige a reutilização de versões pelo npx.

Como faço o npx 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 volta a consultar o registro para obter o nome simples do pacote em cada execução. No npm 10, incluído em todas as versões do Node 22, isso não acontece. Limpe o 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. Note 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 preliminares, como 0.2.0-rc.2 ou 0.2.1-alpha.1, e um intervalo semver não corresponde a versões preliminares, a menos que o próprio intervalo identifique uma. Instale a string de versão exata, incluindo o sufixo. Execute npm view @deepseek-ai/dsh versions --json para ver quais versões existem, porque a sequência tem lacunas onde não foram publicadas versões.

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 precise 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 não está incluído no seu PATH, e npm prefix -g mostra a raiz sob a qual ele está localizado.

O DeepSeek Harness é suficientemente estável para servir de base a um projeto?

Ainda não, segundo a própria descrição do projeto. O README afirma que o projeto está em pré-visualização para desenvolvedores, que evolui rapidamente e que terá alterações incompatíveis. As release candidates 0.1.0-rc.6 e 0.1.0-rc.7 foram publicadas com quatro dias de intervalo em August 2026, e 0.2.0-rc.1 e 0.2.0-rc.2 com um dia de intervalo em September 2026. Fixe uma versão exata e leia --help nessa versão fixada, em vez de o ler num guia. Date as suas próprias notas, para conseguir identificar quando ficaram desatualizadas.