Correggere gli errori di installazione e versione di dsh

Che cos’è realmente l’installazione di DeepSeek Harness

L’installazione di DeepSeek Harness consiste in un solo comando: npx @deepseek-ai/dsh web. Non esiste un installer e non c’è alcun servizio da configurare. La maggior parte dei problemi riscontrati non riguarda affatto l’installazione. Riguarda la risoluzione della versione: quale build di @deepseek-ai/dsh ha deciso di eseguire npx oggi e se la versione di Node.js è in grado di eseguirla.

Due aspetti determinano tutto ciò che segue. Primo: tutte le versioni di @deepseek-ai/dsh pubblicate finora su npm sono release candidate e il tag latest punta a una di queste. Al 18 agosto 2026 si tratta di 0.1.0-rc.7, pubblicata il 17 agosto 2026. Secondo: il README del progetto indica che l’harness è in developer preview, viene aggiornato rapidamente e sarà soggetto a modifiche incompatibili. Un flag che funzionava la settimana scorsa potrebbe non essere più disponibile questa settimana. Fissa una versione prima di costruirci sopra qualsiasi componente.

Prima è utile chiarire alcuni termini. dsh è lo strumento a riga di comando di DeepSeek Harness. Node.js è il runtime JavaScript richiesto. npx è il package runner incluso in npm (node package manager) e scarica un pacchetto su richiesta invece di installarlo in modo permanente.

Quale versione di Node.js richiede dsh?

Il file root package.json del repository dichiara "engines": {"node": "^22.19.0 || >=24.0.0"}, letto il 18 agosto 2026 alla versione 0.1.0-rc.7. Sono quindi richiesti Node 22.19.0 o una versione più recente della linea 22, oppure Node 24 o superiore. Node 20 non è supportato.

Prima di procedere, verifica la versione installata.

node -v
npm -v

Questo è il punto che spesso sorprende. Il pacchetto @deepseek-ai/dsh pubblicato non contiene un proprio campo engines. Lo dichiara soltanto la root del monorepo, e quel file root non viene pubblicato su npm. npm non ha quindi nulla da verificare: non stampa alcun avviso EBADENGINE e non rifiuta l'installazione. Su Node 20 l'installazione sembra riuscita, ma l'errore si verifica in seguito, quando il codice caricato utilizza una sintassi o un'API non disponibili nel runtime. Non esiste una singola stringa di errore stabile da cercare, perché la prima riga a fallire dipende dal modulo caricato per primo. Leggi node -v invece di limitarti a leggere il crash.

Se la versione di Node è troppo vecchia, nvm (node version manager) è la correzione meno invasiva su un VPS, perché installa i file nella directory home dell'utente e lascia invariato Node di 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 dovrebbe ora stampare una versione che inizia con v24.. Se la shell continua a riportare la versione precedente, la funzione shell di nvm non è stata caricata. Apri quindi una nuova shell di login e riprova. Node 24.19.0 è la versione LTS (long term support) corrente ad agosto 2026 ed è l'obiettivo preferibile anche per un secondo motivo descritto più avanti.

Perché npx esegue ogni giorno una versione diversa?

npx @deepseek-ai/dsh web non specifica alcuna versione, quindi npx interroga il registry per sapere a quale versione punta il tag latest. Il tag cambia. Quando DeepSeek pubblica 0.1.0-rc.8, il comando annotato inizia a eseguire codice diverso, senza richiesta di conferma e senza un changelog immediatamente visibile.

È possibile controllare ogni elemento dalla riga di comando.

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

dist-tags mostra a cosa punta attualmente latest. Il 18 August 2026 sia latest sia next puntavano a 0.1.0-rc.7, quindi non esiste un canale stable separato a cui passare. L'elenco versions è più interessante, perché contiene dei buchi: 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. Nella sequenza mancano alcuni numeri perché determinati release candidate non sono mai stati pubblicati. Indovinare il -rc.N successivo in uno script di deploy causerà un errore; è quindi necessario leggere l'elenco invece di incrementare i numeri.

Perché npx continua a eseguire una versione precedente?

Questa è la lamentela opposta, e entrambe le situazioni sono possibili, in base alla versione di npm in uso.

npx mantiene una propria directory dei pacchetti, separata dalla cache dei tarball, in una cartella denominata _npx all'interno della cache di npm. Stampate il percorso e controllatelo.

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

Per anni npx ha riutilizzato ciò che trovava in quella directory per un nome di pacchetto semplice, senza interrogare nuovamente il registry. npm 11.2.0 ha modificato questo comportamento. Quando lo spec è un nome semplice o un intervallo di versioni, npx ora scarica il manifest e riutilizza la copia nella cache solo quando il tarball risolto corrisponde a quello appena restituito dal registry.

Il comportamento dipende dalla release di Node in uso, perché Node include una versione specifica di npm:

• Node 20.20.2 include npm 10.8.2.
• Node 22.19.0 include npm 10.9.3.
• Node 22.23.2, la release 22 più recente, include npm 10.9.8.
• Node 24.19.0 include npm 11.17.0.

Di conseguenza, l'intera linea Node 22, ufficialmente supportata dall'harness, include una versione di npm precedente a 11.2.0. Su Node 22, un npx @deepseek-ai/dsh web semplice continuerà a eseguire la release candidate memorizzata nella cache settimane prima. Lo stesso comando su Node 24 esegue nuovamente la risoluzione a ogni esecuzione. Un solo comando, due comportamenti, e nessun avviso. Chiedete allo strumento quale versione sta utilizzando:

npx @deepseek-ai/dsh --version

Pulizia della cache di npx

Con npm 11.2.0 e versioni successive sono disponibili sottocomandi dedicati.

npm cache npx ls
npm cache npx rm --force

Senza --force, npm rifiuta di eliminare tutto e stampa Please use --force to remove entire npx cache. Usate prima npm cache npx ls quando volete rimuovere una singola voce tramite la relativa chiave, invece di eliminarle tutte.

In npm 10 questi sottocomandi non esistono, quindi dovete eliminare manualmente la directory.

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

npm cache clean --force non è utile in questo caso. Cancella _cacache, l'archivio dei tarball, ma lascia intatta _npx. Questa separazione spiega perché npm ha aggiunto in seguito i sottocomandi npm cache npx. La cancellazione di _npx non comporta inoltre alcuna perdita permanente: contiene i pacchetti scaricati, mentre lo stato dell'harness si trova in $DSH_HOME/profiles/<name> e non viene modificato.

Come bloccare una release candidate esatta?

Indicate la stringa completa della versione, inclusa la parte -rc.N.

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

--yes è importante in uno script, perché in caso contrario npx visualizza una richiesta prima di installare un pacchetto che non ha ancora trovato e attende una risposta che non arriverà.

Una versione esatta è anche il percorso più rapido. npx basa la directory della cache sulla stringa della specifica immessa e, con una versione esatta, confronta questa stringa con l’ID del pacchetto già installato in quella directory ed esegue il pacchetto senza effettuare alcuna richiesta al registry. In npm 11.2.0 e versioni successive, un nome senza versione richiede il recupero del manifest a ogni avvio.

Un’installazione globale usa lo stesso criterio di blocco e consente di usare un comando più breve.

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

Nessuna versione corrispondente trovata per @deepseek-ai/dsh@^0.1.0

Un intervallo con caret o tilde non corrisponde a questo pacchetto. npm install -g @deepseek-ai/dsh@^0.1.0 restituisce il codice di errore ETARGET e la riga No matching version found for @deepseek-ai/dsh@^0.1.0. Il registry funziona correttamente. Si tratta di una regola semver: un intervallo di versioni non corrisponde a una versione prerelease se l’intervallo stesso non specifica una prerelease. Ogni build pubblicata di questo pacchetto è -rc.N, quindi è una prerelease e ^0.1.0 non corrisponde ad alcuna versione. Indicate la versione esatta.

Questa regola ha anche un effetto utile. Poiché gli intervalli non possono passare automaticamente a una nuova release candidate, non esiste uno stato parzialmente bloccato da valutare. Si usa una versione esatta oppure un tag soggetto a variazioni.

Devo usare npx o installare dsh globalmente?

Usa npx per una prima verifica, perché non rimane nulla, tranne una directory della cache che ora sai come eliminare. Usa un'installazione globale con versione bloccata per tutto ciò che deve continuare a funzionare dopo un riavvio, ad esempio un agente di programmazione che mantieni in esecuzione su un VPS.

Le due modalità possono produrre risultati diversi su un sistema in cui le hai usate entrambe, quindi confrontale.

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

which dsh non trovare nulla subito dopo un'installazione globale completata correttamente significa quasi sempre che la directory bin globale di npm non è presente nel tuo PATH. Esegui npm prefix -g per visualizzare la root; i binari si trovano nella directory bin al suo interno.

Una nota sulla sicurezza. npx scarica ed esegue il codice dal registry ogni volta che risolve un nuovo elemento; su un server questa è un'esposizione concreta, non teorica. Il blocco della versione è una parte della soluzione. Per il resto, consulta come gli attacchi alla supply chain di npm raggiungono un server.

Che cosa significa developer preview per la riproducibilità

0.1.0-rc.6 è stato pubblicato il 13 August 2026 e 0.1.0-rc.7 il 17 August 2026. Sono trascorsi quattro giorni. Con questo ritmo, le istruzioni scritte un mese fa possono descrivere una riga di comando che non esiste più, inclusa quella di questa pagina. Indica la data per ogni versione che annoti, comprese le tue note.

Due abitudini rendono gestibile la preview. Fissa la versione esatta in ogni comando e in ogni script, così la ricostruzione di un server produce lo stesso harness. Poi consulta l'output della guida della build fissata, invece di quello riportato in una guida qualsiasi.

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

La seconda parte della riproducibilità è il profilo. dsh --profile <name> avvia il profilo memorizzato in $DSH_HOME/profiles/<name>, mentre i profili web e headless vengono creati dai template inclusi al primo utilizzo. La stessa directory è anche il percorso da cui l'harness legge la chiave API, il modello e le impostazioni dell'endpoint, quindi una versione fissata e una configurazione funzionante sono due aspetti distinti da configurare correttamente. I bundle inclusi vengono risolti dall'installazione di dsh attualmente in esecuzione; di conseguenza, modificare la versione fissata modifica anche quei bundle. I plugin esterni all'albero dei sorgenti si comportano diversamente. Si trovano nella directory del profilo e dsh plugin --profile <name> add <package> inoltra i relativi argomenti a pnpm per installarli. pnpm deve quindi essere presente nel tuo PATH, e dsh lo indica chiaramente quando non lo è. Il package.json del profilo è ciò che fissa quei plugin, quindi una fissazione completa riguarda due file, non uno solo.

Questa separazione sarà familiare se hai mantenuto gli strumenti Python in ambienti isolati su un server: lo strumento e gli elementi che aggiungi sono fissati in percorsi separati. Quando l'harness è avviato, la domanda successiva riguarda di solito la rete, non le versioni. A questo punto subentrano l'accesso all'interfaccia Web di dsh su un VPS remoto e la guida più estesa all'installazione di DeepSeek Harness su un VPS.

Errori degli argomenti che vedrai effettivamente

Questi errori provengono dal parser della CLI, quindi sono stabili nell'intera serie delle release candidate e indicano esattamente il problema.

errore: --profile <name> è obbligatorio

Hai eseguito npx @deepseek-ai/dsh senza sottocomando e senza profilo. Il comando senza argomenti avvia un profilo, quindi richiede un nome. dsh web è il sottocomando che non accetta alcun --profile, perché avvia automaticamente il profilo web incluso nella release.

errore: --patch richiede un percorso

Hai passato --patch senza alcun valore successivo. Il flag può essere ripetuto e ogni occorrenza richiede il percorso di un file.

errore: --dump-config e --dump-default-config si escludono a vicenda

Scegline uno. --dump-default-config stampa i livelli del bundle incluso nella release e non accetta alcun --patch. --dump-config stampa la configurazione composta per un profilo. Entrambi stampano l'output e terminano senza avviare l'harness; sono quindi il metodo sicuro per verificare quali modifiche una nuova release candidate ha introdotto nella configurazione.

errore: plugin richiede argomenti pnpm da inoltrare, ad esempio add <package>

dsh plugin --profile <name> è stato specificato senza nulla da inoltrare. Se il profilo non esiste, il sottocomando lo inizializza, quindi passa il resto della riga di comando a pnpm e richiede argomenti come add @scope/dsh-plugin-example.

FAQ

Quale versione di Node.js richiede DeepSeek Harness?

Il repository dichiara ^22.19.0 || >=24.0.0 nel relativo package.json principale, consultato il 18 agosto 2026 alla versione 0.1.0-rc.7. Sono quindi necessarie Node 22.19.0 o successive nella linea 22, oppure Node 24 o versioni successive. Node 20 non funziona. Il pacchetto npm pubblicato non dispone di un proprio campo engines, quindi npm non visualizza avvisi e non blocca l'installazione. L'errore si verifica invece a runtime. Controllare prima node -v. Node 24 è comunque la scelta migliore, perché include npm 11, che corregge il riutilizzo delle versioni da parte di npx.

Come posso obbligare npx a usare la versione più recente di dsh invece di una versione nella cache?

Con npm 11.2.0 e versioni successive, npx @deepseek-ai/dsh verifica già nuovamente il registry per un nome di pacchetto non qualificato a ogni esecuzione. npm 10, incluso in ogni release di Node 22, non lo fa. Cancellare la cache di npx con npm cache npx rm --force su npm 11, oppure eliminare la directory con rm -rf "$(npm config get cache)/_npx" su npm 10. Verificare quindi con npx @deepseek-ai/dsh --version. npm cache clean --force cancella una directory diversa e non risolve il problema.

Perché l'installazione di @deepseek-ai/dsh@^0.1.0 non riesce?

npm restituisce il codice di errore ETARGET con la riga No matching version found for @deepseek-ai/dsh@^0.1.0.. Ogni build pubblicata è una prerelease, ad esempio 0.1.0-rc.7, e un intervallo semver non corrisponde alle versioni prerelease se l'intervallo stesso non ne specifica una. Installare la stringa di versione esatta, incluso il suffisso -rc.N. Eseguire npm view @deepseek-ai/dsh versions --json per verificare quali versioni esistono, perché la sequenza contiene lacune in corrispondenza delle release candidate mai pubblicate.

È meglio installare dsh globalmente o eseguirlo tramite npx?

npx è adatto per una prima valutazione, perché non conserva nulla oltre a una directory di cache. Un'installazione globale con versione bloccata, come npm install -g @deepseek-ai/dsh@0.1.0-rc.7, è adatta per tutto ciò che deve continuare a funzionare, perché la versione cambia soltanto quando la si modifica. Se dopo un'installazione globale il comando dsh non viene trovato, la directory bin globale di npm non è presente in PATH. npm prefix -g stampa la directory radice in cui si trova.

DeepSeek Harness è abbastanza stabile per costruirci sopra?

Non ancora, secondo la descrizione del progetto. Il README dichiara che il progetto è in anteprima per sviluppatori, viene sviluppato rapidamente e subirà modifiche incompatibili. Le release candidate 0.1.0-rc.6 e 0.1.0-rc.7 sono state pubblicate a quattro giorni di distanza nell'agosto 2026. Bloccare una versione esatta e leggere --help dalla build così bloccata, invece che da una guida qualsiasi. Datare le proprie note, per poter valutare quanto siano diventate obsolete.