Corriger les erreurs d’installation de DeepSeek Harness

Ce qu’est réellement l’installation de DeepSeek Harness

L’installation de DeepSeek Harness tient en une commande : npx @deepseek-ai/dsh web. Il n’y a pas d’installateur ni de service à configurer. La plupart des problèmes rencontrés ne concernent pas l’installation. Ils viennent de la résolution de version : quelle build de @deepseek-ai/dsh npx a décidé d’exécuter aujourd’hui, et votre version de Node.js peut-elle l’exécuter ? Lorsqu’il démarre, l’adresse qu’il affiche est liée à localhost. Pourquoi l’interface Web répond uniquement sur 127.0.0.1:3080 est un problème distinct de ceux présentés sur cette page.

Deux faits expliquent tout ce qui suit. Premièrement, toutes les versions de @deepseek-ai/dsh publiées sur npm jusqu’à présent sont des versions de prépublication. La plupart sont des release candidates (-rc.N), et des builds alpha (-alpha.N) sont également publiées depuis le 30 août 2026. Le tag latest pointe vers une release candidate. Au 6 octobre 2026, il s’agit de 0.2.0-rc.2, publiée le 29 septembre 2026. Deuxièmement, le README du projet indique que le harness est en developer preview, qu’il évolue rapidement et que des changements incompatibles sont prévus. Un flag qui fonctionnait la semaine dernière peut avoir disparu cette semaine. Épinglez une version avant de construire quoi que ce soit dessus.

Commençons par quelques termes. dsh est l’outil en ligne de commande de DeepSeek Harness. Node.js est le runtime JavaScript dont il a besoin. npx est le package runner fourni avec npm (node package manager) ; il récupère un package à la demande au lieu de l’installer définitivement. Si le terme harness n’est pas clair dans cette phrase, un agent harness est le programme qui entoure le modèle : il gère la boucle, les outils, les permissions et l’état de la session. C’est pourquoi un numéro de version que vous n’avez pas choisi peut modifier le comportement de votre agent.

De quelle version de Node.js dsh a-t-il besoin ?

La racine du dépôt package.json déclare "engines": {"node": "^22.19.0 || >=24.0.0"}, lu le 6 octobre 2026, alors que le dépôt était en version 0.2.1-alpha.1. Il faut donc Node 22.19.0 ou une version ultérieure de la branche 22, ou Node 24 et les versions suivantes. Node 20 n’est pas pris en charge.

Vérifiez d’abord la version installée.

node -v
npm -v

Voici le point qui surprend souvent. Le package @deepseek-ai/dsh publié ne contient pas son propre champ engines. Seule la racine du monorepo en déclare un, et ce fichier racine n’est jamais publié sur npm. npm n’a donc rien à vérifier : il n’affiche aucun avertissement EBADENGINE et ne refuse rien. Avec Node 20, l’installation semble avoir réussi, puis l’échec survient plus tard, lorsque le code chargé utilise une syntaxe ou une API absente de votre runtime. Il n’existe pas de chaîne d’erreur unique et stable à rechercher, car la première ligne en échec dépend du module chargé en premier. Consultez node -v au lieu de vous fier au crash.

Si votre version de Node est trop ancienne, nvm (node version manager) est la solution la moins intrusive sur un VPS, car il s’installe dans votre répertoire personnel et ne modifie pas le Node du système.

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 doit maintenant afficher une version commençant par v24.. Si le shell affiche toujours l’ancienne version, la fonction shell de nvm n’a pas été chargée. Ouvrez alors un nouveau shell de connexion et réessayez. Node 24 est la branche LTS active (support à long terme) au 6 octobre 2026, et sa version la plus récente à cette date est 24.21.0. C’est une meilleure cible pour une deuxième raison présentée ci-dessous.

Pourquoi npx exécute-t-il une version différente chaque jour ?

npx @deepseek-ai/dsh web n’indiquent aucune version. npx demande donc au registry vers quelle version pointe le tag latest. Ce tag change, souvent. 0.1.0-rc.8 est sorti le 19 août 2026, deux jours après 0.1.0-rc.7, et le 6 octobre 2026 latest avait déjà été déplacé vers 0.2.0-rc.2. À chaque changement, la commande enregistrée dans vos notes exécute un code différent, sans demande de confirmation ni changelog sous vos yeux.

Vous pouvez vérifier chaque élément depuis la ligne de commande.

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

dist-tags indique vers quoi pointe actuellement latest. Le 6 octobre 2026, latest et next pointaient tous deux vers 0.2.0-rc.2, tandis qu’un troisième tag, alpha, pointait vers 0.2.1-alpha.1. Aucun de ces tags ne constitue un canal stable vers lequel basculer. La liste versions est plus intéressante, car elle comporte des trous. Le 6 octobre 2026, elle contenait 30 versions, de 0.0.1-rc.1 à 0.2.1-alpha.1. La série 0.0.1 passe de -rc.2 à -rc.5, la série 0.1.0 passe de -rc.3 à -rc.6, les builds alpha commencent à 0.1.2-alpha.2 et 0.1.3-alpha.2, et il n’existe aucun 0.1.4. Des numéros manquent parce que certains builds n’ont jamais été publiés, et les builds alpha et les release candidates sont mélangés dans la même liste. Deviner le prochain -rc.N dans un script de déploiement échouera. Lisez donc la liste au lieu d’incrémenter les numéros.

Pourquoi npx continue-t-il d’exécuter une ancienne version ?

C’est la plainte inverse, et les deux situations sont possibles selon la version de npm utilisée.

npx possède son propre répertoire de packages, distinct du cache des archives tar, dans un dossier appelé _npx à l’intérieur du cache npm. Affichez son chemin et examinez son contenu.

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

Pendant des années, npx réutilisait ce qu’il trouvait dans ce répertoire pour un nom de package simple et n’interrogeait plus le registre. npm 11.2.0 a changé ce comportement. Lorsque la spécification est un nom simple ou une plage de versions, npx récupère maintenant le manifeste et réutilise la copie en cache uniquement lorsque l’archive tar résolue correspond à celle que le registre vient de retourner.

Le comportement dépend de la version de Node utilisée, car Node intègre une version précise de npm :

• Node 20.20.2 intègre npm 10.8.2.
• Node 22.19.0 intègre npm 10.9.3.
• Node 22.23.3, la version 22 la plus récente au 6 octobre 2026, intègre npm 10.9.9.
• Node 24.19.0 intègre npm 11.17.0.
• Node 24.21.0, la version 24 la plus récente au 6 octobre 2026, intègre npm 11.19.0.

Toute la branche Node 22, officiellement prise en charge par le harness, intègre donc une version de npm antérieure à 11.2.0. Avec Node 22, un npx @deepseek-ai/dsh web simple continue d’exécuter la release candidate mise en cache plusieurs semaines auparavant. La même commande avec Node 24 effectue une nouvelle résolution à chaque exécution. Une seule commande, deux comportements, et aucun avertissement. Demandez à l’outil quelle version il utilise :

npx @deepseek-ai/dsh --version

Vider le cache de npx

Avec npm 11.2.0 et les versions ultérieures, des sous-commandes dédiées sont disponibles.

npm cache npx ls
npm cache npx rm --force

Sans --force, npm refuse de tout supprimer et affiche Please use --force to remove entire npx cache. Utilisez d’abord npm cache npx ls lorsque vous voulez supprimer une entrée par clé plutôt que toutes les entrées.

Avec npm 10, ces sous-commandes n’existent pas. Supprimez donc vous-même le répertoire.

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

npm cache clean --force n’est pas utile ici. Cette commande vide _cacache, le stockage des archives tar, mais laisse _npx intact. Cette séparation explique précisément pourquoi npm a ensuite ajouté les sous-commandes npm cache npx. Vider _npx n’a aucune conséquence permanente : ce répertoire contient les packages téléchargés, tandis que l’état de votre harness se trouve sous $DSH_HOME/profiles/<name> et n’est pas modifié.

Comment épingler une release candidate exacte ?

Indiquez la chaîne de version complète, y compris la partie -rc.N.

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

Les exemples de cette page utilisent 0.1.0-rc.7. Remplacez-la par le build que vous avez réellement testé. Le 6 October 2026, le tag latest pointait vers 0.2.0-rc.2.

--yes est important dans un script, car npx affiche sinon une invite avant d’installer un package qu’il n’a pas encore rencontré, puis attend une réponse qui ne vient jamais.

Une version exacte est également la méthode la plus rapide. npx base le répertoire de cache sur la chaîne de spécification saisie. Pour une version exacte, il compare cette chaîne à l’identifiant du package déjà installé dans ce répertoire et l’exécute sans aucun aller-retour vers le registry. Avec npm 11.2.0 et les versions ultérieures, un nom seul entraîne un téléchargement du manifest à chaque démarrage.

Une installation globale s’épingle de la même manière et permet d’utiliser une commande plus courte.

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

Aucune version correspondante trouvée pour @deepseek-ai/dsh@^0.1.0

Une plage avec caret ou tilde échoue pour ce package. npm install -g @deepseek-ai/dsh@^0.1.0 renvoie le code d’erreur ETARGET et la ligne No matching version found for @deepseek-ai/dsh@^0.1.0.. Le registry fonctionne correctement. Il s’agit d’une règle semver : une plage de versions ne correspond pas à une version prerelease, sauf si la plage mentionne elle-même une prerelease. Chaque build publié de ce package est une prerelease, soit -rc.N, soit -alpha.N. Par conséquent, ^0.1.0 ne correspond à rien. Indiquez la version exacte.

Cette règle a un effet secondaire utile. Comme les plages ne peuvent pas basculer vers une nouvelle release candidate, il n’existe pas d’état partiellement épinglé à gérer. Vous utilisez soit une version exacte, soit un tag mobile.

Faut-il utiliser npx ou installer dsh globalement ?

Utilisez npx pour un premier test, car il ne laisse rien derrière lui, à part un répertoire de cache que vous savez maintenant supprimer. Utilisez une installation globale avec une version figée pour tout ce qui doit continuer à fonctionner après un redémarrage, par exemple un agent de programmation que vous laissez fonctionner sur un VPS.

Les deux installations peuvent produire des résultats différents sur un serveur où vous avez utilisé les deux. Comparez-les.

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

which dsh ne rien trouver juste après une installation globale réussie signifie presque toujours que le répertoire global des binaires de npm n’est pas présent dans votre PATH. Exécutez npm prefix -g pour afficher la racine. Les binaires se trouvent dans le répertoire bin situé dessous.

Un point de sécurité. npx télécharge et exécute du code depuis le registry chaque fois qu’il résout un nouvel élément. Sur un serveur, cela constitue une véritable exposition, et non un risque théorique. Figer les versions est une partie de la réponse. Le reste est expliqué dans la manière dont les attaques de la chaîne logistique npm atteignent un serveur.

Ce que la developer preview implique pour la reproductibilité

0.1.0-rc.6 a été publié le 13 août 2026 et 0.1.0-rc.7 le 17 août 2026. Quatre jours d’écart. Le rythme n’a pas ralenti depuis : 23 versions supplémentaires ont été publiées entre le 19 août et le 3 octobre 2026, notamment 0.2.0-rc.1 le 28 septembre et 0.2.0-rc.2 le lendemain. À ce rythme, des instructions rédigées il y a un mois peuvent décrire une ligne de commande qui n’existe plus, et cette page n’y fait pas exception. Datez chaque affirmation concernant une version, y compris vos propres notes.

Deux habitudes permettent de gérer la preview. Épinglez la version exacte dans chaque commande et chaque script, afin que la reconstruction d’un serveur produise le même harness. Lisez ensuite la sortie de l’aide de la build épinglée, plutôt que celle d’un guide.

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

La seconde moitié de la reproductibilité concerne le profil. dsh --profile <name> démarre avec le profil stocké dans $DSH_HOME/profiles/<name>, et les profils web et headless sont créés à partir des templates fournis lors de leur première utilisation. Ce répertoire contient également les paramètres que le harness lit pour sa clé API, son modèle et son endpoint. Une version épinglée et une configuration fonctionnelle sont donc deux éléments distincts à configurer correctement. Les bundles intégrés sont résolus depuis l’installation dsh actuellement utilisée, ce qui signifie que la modification de la version épinglée modifie également ces bundles. Les plugins out-of-tree se comportent différemment. Ils résident dans le répertoire du profil, et dsh plugin --profile <name> add <package> transmet leurs arguments à pnpm pour les installer. pnpm doit donc être présent dans votre PATH, et dsh l’indique clairement lorsque ce n’est pas le cas. Chaque plugin que vous ajoutez s’exécute avec les mêmes permissions que votre agent. Il est donc utile de vérifier ce à quoi un plugin peut accéder avant de l’installer. Le propre package.json du profil sert à épingler ces plugins. Une pinning complète couvre donc deux fichiers, et non un seul.

Cette séparation vous semblera familière si vous avez déjà conservé des outils Python dans des environnements isolés sur un serveur : l’outil et les éléments que vous lui ajoutez sont épinglés à des endroits distincts. Une fois le harness démarré, la question suivante concerne généralement le réseau plutôt que les versions. C’est là que l’accès à l’interface Web dsh sur un VPS distant et le guide détaillé installer DeepSeek Harness sur un VPS prennent le relais.

Erreurs d’arguments que vous rencontrerez réellement

Ces erreurs proviennent de l’analyseur de la CLI. Chacune indique précisément le problème. Le texte est resté globalement stable d’une build à l’autre, mais pas complètement. Les messages ci-dessous ont été vérifiés avec 0.2.0-rc.2 le 6 octobre 2026.

error: --profile <name> is required

Vous avez exécuté npx @deepseek-ai/dsh sans sous-commande ni profil. La commande seule démarre un profil et nécessite donc un nom. dsh web fonctionne sans --profile, car l’analyseur interprète le premier mot seul comme le nom du profil. Il démarre donc pour vous le profil web fourni avec le logiciel.

error: --patch needs a path

Vous avez fourni --patch sans argument. Cette option peut être répétée. Chaque occurrence doit être suivie du chemin d’un fichier.

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

Choisissez une seule option. Dans 0.2.0-rc.2, la build vers laquelle pointait latest le 6 octobre 2026, le message mentionne une troisième option et s’affiche sous la forme error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive, car --dump-config-schema, qui affiche le JSON Schema des entrées de profil et des patches, a rejoint les deux autres. --dump-default-config affiche les couches du bundle fourni avec le logiciel et n’accepte aucun --patch. --dump-config affiche la configuration composée d’un profil. Toutes ces options affichent le résultat puis quittent le programme sans démarrer le harness. Elles permettent donc de vérifier sans risque les changements introduits par une nouvelle release candidate.

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

Vous avez exécuté dsh plugin --profile <name> sans rien à transmettre. Si le profil est absent, la sous-commande l’initialise, puis transmet le reste de la ligne de commande à pnpm. Elle nécessite donc des arguments tels que add @scope/dsh-plugin-example.

FAQ

De quelle version de Node.js DeepSeek Harness a-t-il besoin ?

Le dépôt déclare ^22.19.0 || >=24.0.0 dans son package.json racine, consulté le 6 octobre 2026, lorsque le dépôt était en version 0.2.1-alpha.1. Il faut donc Node 22.19.0 ou une version ultérieure de la branche 22, ou Node 24 et les versions suivantes. Node 20 ne fonctionnera pas. Le package npm publié ne possède pas son propre champ engines. npm ne vous avertit donc pas et ne bloque pas l’installation. L’échec apparaît à l’exécution. Vérifiez d’abord node -v. Node 24 reste le meilleur choix, car il intègre npm 11, qui corrige la réutilisation des versions par npx.

Comment forcer npx à utiliser le dernier dsh plutôt qu’une version mise en cache ?

Avec npm 11.2.0 et les versions suivantes, npx @deepseek-ai/dsh vérifie déjà le registry à chaque exécution pour un nom de package sans version. Avec npm 10, fourni avec toutes les versions de Node 22, ce n’est pas le cas. Videz le cache de npx avec npm cache npx rm --force sous npm 11, ou supprimez le dossier avec rm -rf "$(npm config get cache)/_npx" sous npm 10. Vérifiez ensuite avec npx @deepseek-ai/dsh --version. Notez que npm cache clean --force vide un autre répertoire et ne résoudra pas ce problème.

Pourquoi l’installation de @deepseek-ai/dsh@^0.1.0 échoue-t-elle ?

npm renvoie le code d’erreur ETARGET avec la ligne No matching version found for @deepseek-ai/dsh@^0.1.0.. Toutes les builds publiées sont des prerelease, comme 0.2.0-rc.2 ou 0.2.1-alpha.1. Une plage semver ne correspond pas aux versions prerelease, sauf si la plage en désigne elle-même une. Installez la chaîne de version exacte, suffixe inclus. Exécutez npm view @deepseek-ai/dsh versions --json pour voir les versions disponibles, car la séquence comporte des trous correspondant à des builds qui n’ont jamais été publiées.

Dois-je installer dsh globalement ou l’exécuter avec npx ?

npx convient pour une première prise en main, car rien ne persiste à part un répertoire de cache. Une installation globale avec une version figée, comme npm install -g @deepseek-ai/dsh@0.1.0-rc.7, convient à tout ce qui doit continuer à fonctionner, car la version ne change que lorsque vous la modifiez. Si la commande dsh est introuvable après une installation globale, le répertoire global des binaires npm ne figure pas dans votre PATH. npm prefix -g affiche la racine sous laquelle il se trouve.

DeepSeek Harness est-il suffisamment stable pour servir de base à un projet ?

Pas encore, d’après sa propre description. Le README indique que le projet est en developer preview, qu’il évolue rapidement et qu’il fera l’objet de changements incompatibles. Les release candidates 0.1.0-rc.6 et 0.1.0-rc.7 ont été publiées à 4 jours d’intervalle en août 2026, puis 0.2.0-rc.1 et 0.2.0-rc.2 à 1 jour d’intervalle en septembre 2026. Figez une version exacte et consultez --help dans cette build figée plutôt que dans un guide. Datez vos propres notes afin de pouvoir déterminer depuis quand elles sont obsolètes.