Corrigir erros de versão no DeepSeek Harness
A build mais recente do DeepSeek Harness ainda é preliminar. Fixe uma versão exata do dsh, limpe o cache do npx e confirme qual npm está em uso.
O que é realmente a instalação do DeepSeek Harness
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 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á-la. Quando inicia, o binding predefinido é localhost; --host e --port substituem as definições do listener, e o endereço apresentado usa --public-url quando este está configurado. O binding predefinido e a razão pela qual a Web UI responde apenas em 127.0.0.1:3080 são um problema separado dos problemas abordados nesta página.
Dois factos determinam tudo o que se segue. Primeiro, todas as versões de @deepseek-ai/dsh publicadas no npm até 27 October 2026 eram versões preliminares. A maioria são release candidates (-rc.N), e desde 30 August 2026 também existem builds alpha (-alpha.N). A tag latest aponta para uma release candidate. Em 6 November 2026, essa versão é 0.2.2-rc.1. Segundo, o README do projeto indica que o harness está em developer preview, que está a evoluir rapidamente e que terá alterações incompatíveis. Uma flag que funcionou na semana passada pode desaparecer esta semana. Fixe uma versão antes de criar qualquer componente com base nela.
Primeiro, alguns termos. dsh é a ferramenta de linha de comandos do DeepSeek Harness. Node.js é o runtime JavaScript de que necessita. npx é o package runner incluído no npm (node package manager) e obtém um pacote a pedido, em vez de o instalar permanentemente. Se a palavra harness estiver a ser usada com um significado desconhecido nessa frase, um agent harness é o programa que envolve o modelo, mantendo o ciclo, 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.
Qual versão do Node.js o dsh exige?
Em 10 October 2026, quando o repositório estava na versão 0.2.1-alpha.2, o seu package.json raiz declarava "engines": {"node": "^22.19.0 || >=24.0.0"}. Esse já não é o requisito. Em 27 October 2026, com o repositório na versão 0.2.1-rc.3, o package.json raiz declara "engines": {"node": ">=24.9.0"}, e o código-fonte do próprio CLI, package.json, agora declara o mesmo. Uma nota de decisão do projeto, datada de 15 October 2026, afirma que as instalações do Node 22 devem ser atualizadas e que o Node 24.0 também não é suficiente, porque os pontos de entrada dependem de import.meta.main, que o 24.0 não possui. Portanto, é necessário usar o Node 24.9.0 ou mais recente. O Node 20 e o Node 22 estão excluídos, assim como qualquer versão do Node 24 anterior à 24.9.0. Quando verificados em 27 October 2026, as tags de lançamento de 0.2.1-rc.2, depois a build indicada por latest e 0.2.1-rc.3 ainda continham o intervalo antigo, portanto o novo requisito mínimo foi definido depois delas. Planeje usar a 24.9.0, porque esse é o intervalo declarado atualmente pelo projeto.
Verifique primeiro o que você tem instalado.
node -v
npm -vEsta é a parte que costuma surpreender. Em 27 October 2026, o pacote publicado @deepseek-ai/dsh ainda não tinha um campo engines próprio em nenhuma das suas 38 versões até 0.2.1-rc.4. A raiz do monorepo declara esse campo, mas o ficheiro da raiz nunca é publicado no npm. O código-fonte do CLI, package.json, ganhou esse campo num commit datado de 15 October 2026, mas nenhuma das builds publicadas verificadas em 27 October o continha. Portanto, essas builds não forneciam ao npm nenhum requisito específico do dsh sobre a versão do Node para verificar. Em 6 November 2026, o pacote publicado 0.2.2-rc.1 declara "engines": {"node": ">=24.9.0"}. O npm trata engines como informativo, a menos que você defina engine-strict. Com a configuração padrão, espere no máximo um aviso. Num Node não suportado, a instalação parece ter funcionado, e a falha surge mais tarde, quando o código carregado utiliza sintaxe ou uma API que o seu runtime não possui. Não existe uma única mensagem de erro estável para pesquisar, porque a linha que falha primeiro depende do módulo carregado primeiro. Leia node -v em vez de interpretar apenas o crash.
Se o seu Node for demasiado antigo, o nvm (node version manager) é a correção menos invasiva num VPS, porque instala tudo no seu diretório pessoal e deixa o Node do sistema intacto.
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 -vnode -v deve agora mostrar uma versão que começa com v24.. Se o shell ainda mostrar a versão antiga, execute which node. Um caminho fora de ~/.nvm normalmente tem uma de duas causas. A função do shell do nvm não foi carregada; nesse caso, abra um novo shell de login e tente novamente. Ou uma linha do perfil do shell altera PATH depois das linhas que carregam o nvm e coloca outro Node à frente; nesse caso, mova essa linha para antes das linhas do nvm. O Node 24 era a linha LTS (long term support) ativa em 10 October 2026 e passou para manutenção em 20 October 2026. A versão mais recente em 29 October 2026 é a 24.22.2, bem acima do requisito mínimo 24.9.0. O Node 26, que o intervalo de >=24.9.0 também permite, entrou em LTS ativa em 28 October 2026 com a versão 26.13.0. Qualquer uma das duas versões atende ao requisito mínimo, e ambas incluem versões do npm com a correção do range-cache descrita abaixo. Os binários oficiais do Node 26 para Linux também exigem libatomic, que pode ser necessário instalar separadamente na sua distribuição.
Por que o npx executa uma versão diferente todos os dias?
npx @deepseek-ai/dsh web não especifica nenhuma versão. A menos que o projeto no diretório atual já tenha @deepseek-ai/dsh instalado. Nesse caso, o npx executa essa cópia. Caso contrário, o npx consulta o registro para saber para onde a tag latest aponta. Essa tag muda, e muda com frequência. 0.1.0-rc.8 foi lançada em 19 August 2026, dois dias depois de 0.1.0-rc.7. Em 10 October 2026, latest apontava para 0.2.0-rc.2 e, em 27 October 2026, apontava para 0.2.1-rc.2. Cada vez que ela muda, o comando registrado nas suas anotações começa a executar um código diferente, sem aviso e sem um changelog apresentado ao utilizador.
Pode inspecionar cada parte variável pela linha de comandos.
npm view @deepseek-ai/dsh dist-tags
npm view @deepseek-ai/dsh versions --json
npm view @deepseek-ai/dsh time --jsondist-tags mostra para onde latest aponta atualmente. Em 10 October 2026, tanto latest como next apontavam para 0.2.0-rc.2, e uma terceira tag, alpha, apontava para 0.2.1-alpha.2, publicada no dia anterior. Em 27 October 2026, latest apontava para 0.2.1-rc.2, next apontava para 0.2.1-rc.4, publicada no dia anterior, e alpha apontava para 0.2.1-alpha.5. Em 6 November 2026, latest aponta para 0.2.2-rc.1. Em 4 November 2026, next apontava para 0.2.1-rc.5 e alpha apontava para 0.2.2-alpha.3. A tag latest ainda seleciona uma versão de pré-lançamento. A lista versions é mais interessante porque contém lacunas. Em 10 October 2026, ela continha 31 versões, de 0.0.1-rc.1 a 0.2.1-alpha.2. Em 27 October 2026, continha 38, todas ainda versões de pré-lançamento. 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 compilações alpha começam em 0.1.2-alpha.2 e 0.1.3-alpha.2, e não existe nenhum 0.1.4. Faltam números na lista publicada, e compilaçõ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 simplesmente incrementar os números.
Por que o npx continua executando uma versão antiga?
Esta é a reclamação oposta, e ambas são válidas, dependendo da especificação do pacote, da instalação local e de qual npm você está executando.
O npx mantém o seu próprio diretório de pacotes, separado do cache de tarballs, numa pasta chamada _npx dentro do cache do npm. Mostre o caminho e examine-o.
npm config get cache
ls "$(npm config get cache)/_npx"O npm 10.9.3 já consulta o registry para obter o nome simples de um pacote fora de uma instalação de projeto. O npm 11.2.0 alterou as verificações de validade do cache para intervalos de versões. Quando a especificação é apenas um nome e o pacote ainda não está instalado no projeto atual, o npx obtém o manifesto com preferOnline: true e reutiliza a cópia em cache em _npx somente quando o tarball resolvido corresponde ao que o registry retornou. Um nome simples ainda corresponde à versão instalada no projeto atual, sem consultar o registry. Para um intervalo de versões, o npm 10.9.3 aceita uma versão correspondente em cache; o npm 11.2.0 e versões mais recentes verificam se o intervalo resolve para algo mais recente.
O comportamento depende do npm que você realmente executa. A menos que tenha atualizado o npm separadamente com npm install -g npm, esse é o npm incluído na sua versão do Node:
- 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.4, a versão mais recente da linha 22 em 27 October 2026, inclui o npm 10.9.9.
- O Node 24.9.0, a versão mínima atual do harness, inclui o npm 11.6.0.
- O Node 24.19.0 inclui o npm 11.17.0.
- O Node 24.22.2, a versão mais recente da linha 24 em 29 October 2026, inclui o npm 11.19.1.
- O Node 26.13.0, a versão mais recente da linha 26 em 29 October 2026, inclui o npm 11.20.0.
Portanto, toda a linha Node 22 inclui um npm anterior ao 11.2.0. O harness ofereceu suporte ao Node 22 até meados de October 2026 e já não oferece, mas um servidor que executou o dsh antes disso ainda pode estar nessa versão. O npm 10.9.3 incluído no Node 22.19.0 já verifica novamente um npx @deepseek-ai/dsh web simples no registry fora de uma instalação de projeto. Portanto, uma entrada _npx antiga, por si só, não explica um candidato a lançamento antigo. Todas as versões do Node atualmente aceitas pelo harness, a partir da 24.9.0, incluem o npm 11.6.0 ou mais recente, que também contém a correção do cache de intervalos. Uma instalação do projeto ainda pode ter precedência. Pergunte à ferramenta qual instalação ela está usando:
npx @deepseek-ai/dsh --versionLimpando o cache do npx
No npm 11.2.0 e em versões mais recentes, existem subcomandos específicos.
npm cache npx ls
npm cache npx rm --forceSem --force, o npm se recusa a apagar tudo e exibe 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, exclua o diretório manualmente.
rm -rf "$(npm config get cache)/_npx"npm cache clean --force não ajuda neste caso. Ele limpa _cacache, o armazenamento de tarballs, e deixa _npx intacto. Essa separação é exatamente o motivo pelo qual o npm adicionou posteriormente os subcomandos npm cache npx. Limpar _npx também não causa nenhuma perda permanente: ele armazena os pacotes baixados, enquanto o estado do seu harness fica separado em $DSH_HOME, incluindo profiles/<name>, sessions, storages e .credentials.yaml, e não é afetado.
Como fixar um release candidate exato?
Informe a string completa da versão, incluindo a parte -rc.N.
npx --yes @deepseek-ai/dsh@0.1.0-rc.7 webOs exemplos desta página usam 0.1.0-rc.7. Substitua-a pela build que você testou. Em 27 October 2026, a tag latest apontava para 0.2.1-rc.2.
--yes aceita a confirmação de instalação de pacote do npx sem solicitar interação.
Uma versão exata fixa o pacote dsh, mas não garante uma inicialização offline. O npx usa a string de especificação informada como chave do diretório de cache e pode reutilizar uma versão exata já instalada nesse local. Porém, se não existir uma instalação local correspondente, a verificação anterior da árvore local busca o manifesto com preferOnline: true antes de inspecionar _npx. Uma versão exata correspondente instalada no projeto local evita essa consulta ao manifesto. Executar um nome simples fora de um projeto que instala dsh também inicia uma consulta ao manifesto, inclusive no npm 10.9.3.
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 --versionNenhuma versão correspondente encontrada para @deepseek-ai/dsh@^0.1.0
Em 27 October 2026, um intervalo simples com acento circunflexo ou til falhou para este pacote. npm install -g @deepseek-ai/dsh@^0.1.0 respondeu com o código de erro ETARGET e a linha No matching version found for @deepseek-ai/dsh@^0.1.0. O registro está funcionando corretamente. Esta é uma regra do semver: um intervalo de versões não corresponde a uma versão prerelease, a menos que um dos comparadores do próprio intervalo nomeie uma prerelease com os mesmos números de major, minor e patch. Todas as builds publicadas deste pacote até 27 October 2026 eram prereleases, -rc.N ou -alpha.N, e ^0.1.0 não nomeava nenhuma, portanto não correspondeu a nada. Informe a versão exata.
Essa regra funciona nos dois sentidos. Um intervalo simples nunca avança para um novo release candidate, mas um intervalo que nomeia uma prerelease pode avançar. ^0.1.0-rc.7 significa >=0.1.0-rc.7 <0.2.0-0, portanto aceita 0.1.0-rc.8 e também aceitaria uma versão final 0.1.0, enquanto 0.1.1-rc.1 fica de fora porque os números são diferentes. Esse é um estado parcialmente fixado entre uma versão exata e uma tag que muda, e ele altera o que é executado sem que você altere nada. Se você quer a build testada e nada mais, informe a versão exata.
Devo usar npx ou instalar o dsh globalmente?
Use o npx para uma primeira análise, pois o pacote permanece num diretório de cache que você já sabe como limpar. Use uma instalação global com versão fixa para qualquer coisa que precise continuar a funcionar após um reboot, como um agente de programação que você mantém a correr num VPS.
Os dois podem divergir numa máquina onde utilizou ambos, por isso compare-os.
which dsh
dsh --version
npx @deepseek-ai/dsh --versionwhich dsh não encontrar nada logo após uma instalação global bem-sucedida significa quase sempre que o diretório bin global do npm não está no seu PATH. Execute npm prefix -g para imprimir a raiz, e os binários estarão na pasta bin abaixo dela.
Uma nota de segurança. O npx obtém e executa código do registo sempre que resolve algo novo, o que num servidor é uma exposição real e não apenas teórica. Fixar a versão é parte da solução. O resto está em como os ataques à cadeia de suprimentos do npm chegam a um servidor.
O que uma versão de pré-visualização para desenvolvedores significa para a reprodutibilidade
0.1.0-rc.6 foi publicada em 13 August 2026 e 0.1.0-rc.7 em 17 August 2026. Foram quatro dias de diferença. O ritmo não abrandou desde então: foram publicadas mais 24 versões entre 19 August e 9 October 2026, incluindo 0.2.0-rc.1 em 28 September e 0.2.0-rc.2 no dia seguinte, e outras sete foram publicadas entre 14 e 26 October 2026, até 0.2.1-rc.4. Nesse ritmo, instruções escritas há um mês podem descrever uma linha de comandos que já não existe, e esta página também está sujeita a isso. Registe a data de cada afirmação sobre versões, incluindo nas suas próprias notas.
Dois hábitos tornam a pré-visualização administrável. Fixe a versão exata em cada comando e script, para que a reconstrução de um servidor selecione a mesma versão do dsh. Isso, por si só, não reproduz as dependências: o pacote 0.2.2-rc.1 publicado usa intervalos como js-yaml: ^4.3.2 e commander: ^15.0.0 e é distribuído sem um npm shrinkwrap. Para instalar as dependências de forma repetível, mantenha o dsh num projeto local com um package-lock.json versionado no repositório e reconstrua com npm ci. Depois, consulte a saída de ajuda da compilação fixada, em vez de qualquer guia.
npx @deepseek-ai/dsh@0.1.0-rc.7 --help
npx @deepseek-ai/dsh@0.1.0-rc.7 web --dump-configA 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 distribuídos na primeira utilização. O patch do perfil pode conter definições do modelo e do endpoint, mas as chaves de API guardadas ficam em $DSH_HOME/.credentials.yaml, enquanto as definições mantêm referências às credenciais. Portanto, uma versão fixada e uma configuração funcional são dois elementos separados que devem ser configurados corretamente. Patches ao nível do utilizador e da linha de comandos podem substituir as definições do perfil. Os bundles incluídos são resolvidos a partir da instalação do dsh que está 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. Ficam no diretório do perfil, e dsh plugin --profile <name> add <package> encaminha os respetivos 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á. Cada plugin adicionado é executado com as mesmas permissões do seu agent, por isso é importante verificar a que recursos um plugin pode aceder antes de o instalar. O próprio package.json do perfil declara esses plugins; preserve o seu pnpm-lock.yaml e use pnpm install --frozen-lockfile para reproduzir também as versões das respetivas dependências.
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 pergunta seguinte costuma estar relacionada com a rede, e não com as versões. É nesse ponto que entram aceder à interface Web do dsh num VPS remoto e o guia mais longo instalar o DeepSeek Harness num VPS.
Erros de argumentos que você verá de facto
Estes erros vêm do próprio analisador da CLI, e cada um identifica o problema exato. A redação manteve-se praticamente estável entre builds, mas não completamente. Por isso, as mensagens abaixo foram verificadas com 0.2.0-rc.2 em 6 October 2026.
erro: --profile <name> is required
Você executou npx @deepseek-ai/dsh sem subcomando e sem perfil. O comando sem argumentos inicia um perfil, portanto precisa de um nome. dsh web funciona sem --profile porque o analisador interpreta a primeira palavra isolada como o nome do perfil. Assim, inicia o perfil distribuído web automaticamente.
erro: --patch needs a path
--patch foi especificado sem nada depois dele. A opção pode ser repetida, e cada ocorrência recebe um caminho de ficheiro.
erro: --dump-config and --dump-default-config are mutually exclusive
Escolha uma das opções. Em 0.2.0-rc.2, o build latest identificado em 6 October 2026, a mensagem menciona uma terceira opção e apresenta-se 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, foi adicionado às outras duas. --dump-default-config imprime as camadas do bundle distribuído e não aceita --patch. --dump-config imprime a configuração composta de um perfil. As três opções evitam iniciar o harness, mas a recolha do schema importa módulos de plugins e pode invocar getters e builders lazy. Inspecione apenas plugins confiáveis e aplique um timeout externo nos scripts.
erro: plugin needs pnpm arguments to forward (e.g. add <package>)
dsh plugin --profile <name> foi especificado 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
Qual versão do Node.js o DeepSeek Harness exige?
Node.js 24.9.0 ou mais recente. Em 27 de outubro de 2026, com o repositório na versão 0.2.1-rc.3, a raiz continha package.json, que declara >=24.9.0. Em 10 de outubro de 2026, declarava ^22.19.0 || >=24.0.0, mas uma nota de decisão do projeto, datada de 15 de outubro de 2026, removeu o suporte ao Node 22 e elevou o requisito mínimo para acima de 24.0. O Node 20 e o Node 22 não funcionam. Uma versão do Node 24 anterior a 24.9.0 também não funciona. Em 27 de outubro de 2026, nenhuma build publicada no npm tinha um campo engines próprio. Por isso, o npm não podia avisar nem bloquear com base no requisito de Node do dsh, e o runtime incompatível falhava apenas mais tarde. O pacote publicado 0.2.2-rc.1, verificado em 6 de novembro de 2026, agora declara >=24.9.0 em engines.node. Por padrão, o npm avisa e recusa um runtime incompatível quando engine-strict está ativado. Consulte primeiro node -v. Todas as versões do Node que atendem ao requisito mínimo incluem o npm 11 ou mais recente, que contém a correção de cache de intervalos do npx introduzida no npm 11.2.0.
Como faço o npx usar o dsh mais recente em vez de uma versão em cache?
O npm 10.9.3 e as versões atuais do npm já consultam novamente o registro para um nome de pacote simples, exceto quando o diretório atual é um projeto com o dsh instalado. Nesse caso, o npx executa a cópia local. Use npx @deepseek-ai/dsh@latest --version para solicitar explicitamente a tag latest do registro. O npm 11.2.0 alterou as verificações de atualização para intervalos de versões, não para nomes simples. Limpe o cache do npx com npm cache npx rm --force no npm 11.2.0 ou mais recente. No npm 10, elimine o diretório com rm -rf "$(npm config get cache)/_npx". Depois, confirme com npx @deepseek-ai/dsh --version. Observe 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?
Em 27 de outubro de 2026, o npm retornou o código de erro ETARGET com a linha No matching version found for @deepseek-ai/dsh@^0.1.0.. Todas as builds publicadas nessa verificação eram versões preliminares, como 0.2.0-rc.2 ou 0.2.1-alpha.2. Um intervalo semver não corresponde a versões preliminares, a menos que o próprio intervalo especifique uma versão preliminar com os mesmos números de versão major, minor e patch. 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.
Devo instalar o dsh globalmente ou executá-lo através do npx?
O npx é adequado para uma primeira avaliação, porque o pacote permanece no diretório de cache. O harness também cria estado persistente do perfil. Uma instalação global fixada, como npm install -g @deepseek-ai/dsh@0.1.0-rc.7, é adequada para qualquer uso que precise continuar funcionando, porque a versão só muda quando você 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. O comando npm prefix -g mostra a raiz onde ele está instalado.
O DeepSeek Harness já é estável o suficiente para servir de base a um projeto?
Ainda não, segundo a própria descrição do projeto. O README informa que o projeto está em pré-visualização para desenvolvedores, passa por iterações rápidas e 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 agosto de 2026. As versões 0.2.0-rc.1 e 0.2.0-rc.2 foram publicadas com um dia de intervalo em setembro de 2026. As versões 0.2.1-rc.1 e 0.2.1-rc.2 foram publicadas no mesmo dia em outubro de 2026. O intervalo de versões Node suportado também mudou em outubro de 2026. Fixe uma versão exata e leia --help dessa build fixada, e não de um guia qualquer. Date as suas próprias notas para poder identificar quando ficaram desatualizadas.