Solucionar errores de instalación y versiones de dsh

Qué es realmente la instalación de DeepSeek Harness

La instalación de DeepSeek Harness consiste en un solo comando: npx @deepseek-ai/dsh web. No hay ningún instalador ni ningún servicio que configurar. La mayoría de los problemas que aparecen no están relacionados con la instalación. Se deben a la resolución de versiones: qué compilación de @deepseek-ai/dsh decide ejecutar npx ese día y si la versión de Node.js puede ejecutarla.

Dos hechos determinan todo lo que sigue. Primero, todas las versiones de @deepseek-ai/dsh publicadas hasta ahora en npm son candidatas de lanzamiento, y la etiqueta latest apunta a una de ellas. A fecha de 18 August 2026, es 0.1.0-rc.7, publicada el 17 August 2026. Segundo, el README del proyecto indica que el harness está en developer preview, que evoluciona rápidamente y que introducirá cambios que pueden romper la compatibilidad. Una opción que funcionaba la semana pasada puede haber desaparecido esta semana. Fije una versión antes de construir cualquier cosa sobre ella.

Primero, algunos términos. dsh es la herramienta de línea de comandos de DeepSeek Harness. Node.js es el entorno de ejecución de JavaScript que necesita. npx es el ejecutor de paquetes que se distribuye con npm (node package manager) y obtiene un paquete cuando se necesita, en lugar de instalarlo de forma permanente.

¿Qué versión de Node.js necesita dsh?

La raíz del repositorio package.json declara "engines": {"node": "^22.19.0 || >=24.0.0"}, leído el 18 de agosto de 2026 en la versión 0.1.0-rc.7. Por tanto, necesita Node 22.19.0 o una versión posterior dentro de la línea 22, o Node 24 o posterior. Node 20 no es compatible.

Compruebe primero qué versión tiene.

node -v
npm -v

Esta es la parte que suele sorprender. El paquete publicado @deepseek-ai/dsh no contiene un campo engines propio. Sólo la raíz del monorepo declara uno, y ese archivo raíz nunca se publica en npm. Por tanto, npm no tiene nada que comprobar: no muestra ninguna advertencia EBADENGINE y no rechaza nada. En Node 20, la instalación parece correcta y el fallo aparece después, cuando el código cargado utiliza sintaxis o una API que el runtime no admite. No existe una cadena de error única y estable que buscar, porque la primera línea que falla depende del módulo que se cargue primero. Lea node -v en lugar de basarse en el error del proceso.

Si su versión de Node es demasiado antigua, nvm (gestor de versiones de Node) es la solución menos invasiva en un VPS, porque se instala en el directorio de inicio del usuario y no modifica el Node del 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 debería mostrar ahora una versión que empiece por v24.. Si el shell sigue mostrando la versión antigua, la función de shell de nvm no se cargó. Abra un nuevo shell de inicio de sesión y vuelva a intentarlo. Node 24.19.0 es la versión LTS (soporte a largo plazo) activa en agosto de 2026 y es el objetivo recomendado por un segundo motivo que se explica más abajo.

¿Por qué npx ejecuta una versión diferente cada día?

npx @deepseek-ai/dsh web no especifica ninguna versión, por lo que npx consulta en el registro a qué apunta la etiqueta latest. Esa etiqueta cambia. Cuando DeepSeek publica 0.1.0-rc.8, el comando guardado en sus notas empieza a ejecutar código diferente, sin ninguna confirmación y sin un registro de cambios visible.

Puede inspeccionar cada parte variable desde la línea 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 muestra a qué apunta latest en este momento. El 18 August 2026, latest y next apuntaban a 0.1.0-rc.7, por lo que no existe un canal estable separado al que cambiar. La lista de versions es más interesante porque contiene huecos: 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. Faltan números en esa secuencia porque algunas versiones candidatas nunca se publicaron. Intentar adivinar el siguiente -rc.N en un script de despliegue fallará; lea la lista en lugar de incrementarlo.

¿Por qué npx sigue ejecutando una versión antigua?

Esta es la queja opuesta, y ambas situaciones son posibles según la versión de npm que esté ejecutando.

npx mantiene su propio directorio de paquetes, separado de la caché de archivos tarball, en una carpeta llamada _npx dentro de la caché de npm. Muestre la ruta y revísela.

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

Durante años, npx reutilizaba lo que encontrara allí para un nombre de paquete simple y nunca volvía a consultar el registro. npm 11.2.0 cambió este comportamiento. Cuando la especificación es un nombre simple o un rango de versiones, npx ahora obtiene el manifiesto y reutiliza la copia en caché sólo cuando el tarball resuelto coincide con el que acaba de devolver el registro.

El comportamiento depende de la versión de Node, porque Node incluye una versión específica de npm:

• Node 20.20.2 incluye npm 10.8.2.
• Node 22.19.0 incluye npm 10.9.3.
• Node 22.23.2, la versión 22 más reciente, incluye npm 10.9.8.
• Node 24.19.0 incluye npm 11.17.0.

Por tanto, toda la línea Node 22, que el entorno de pruebas admite oficialmente, incluye una versión de npm anterior a 11.2.0. En Node 22, un npx @deepseek-ai/dsh web simple seguirá ejecutando la versión candidata que almacenó en caché hace semanas. El mismo comando en Node 24 vuelve a resolver la versión en cada ejecución. Un comando, dos comportamientos y ninguno muestra una advertencia. Consulte la versión de la herramienta:

npx @deepseek-ai/dsh --version

Borrar la caché de npx

En npm 11.2.0 y versiones posteriores hay subcomandos específicos.

npm cache npx ls
npm cache npx rm --force

Sin --force, npm se niega a borrar todo y muestra Please use --force to remove entire npx cache. Use npm cache npx ls primero cuando quiera eliminar una entrada por clave en lugar de eliminarlas todas.

En npm 10 esos subcomandos no existen, así que elimine el directorio manualmente.

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

npm cache clean --force no sirve en este caso. Borra _cacache, el almacén de tarballs, pero deja _npx intacto. Esta separación explica precisamente por qué npm añadió después los subcomandos npm cache npx. Borrar _npx tampoco tiene consecuencias permanentes: contiene paquetes descargados, mientras que el estado del entorno de pruebas se encuentra en $DSH_HOME/profiles/<name> y no se modifica.

¿Cómo se fija un release candidate exacto?

Especifique la cadena de versión completa, incluida la parte -rc.N.

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

--yes es importante en un script porque, de lo contrario, npx muestra un aviso antes de instalar un paquete que no ha encontrado y espera una respuesta que nunca llega.

Una versión exacta también es la opción más rápida. npx basa el directorio de caché en la especificación que escribió. Para una versión exacta, la compara con el identificador del paquete que ya está instalado allí y lo ejecuta sin realizar ninguna consulta al registro. En npm 11.2.0 y versiones posteriores, usar sólo el nombre implica obtener el manifiesto en cada inicio.

Una instalación global se fija de la misma forma y proporciona un comando corto.

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

No se encontró ninguna versión coincidente para @deepseek-ai/dsh@^0.1.0

Un rango con caret o tilde no coincide con este paquete. npm install -g @deepseek-ai/dsh@^0.1.0 responde con el código de error ETARGET y la línea No matching version found for @deepseek-ai/dsh@^0.1.0. El registro funciona correctamente. Es una regla de semver: un rango de versiones no coincide con una versión prerelease, a menos que el propio rango especifique una prerelease. Todas las compilaciones publicadas de este paquete son -rc.N, es decir, prerelease, por lo que ^0.1.0 no coincide con nada. Especifique la versión exacta.

Esta regla tiene un efecto secundario útil. Como los rangos no pueden avanzar automáticamente a un nuevo release candidate, no existe un estado parcialmente fijado que deba analizarse. Se usa una versión exacta o un tag que cambia.

¿Debo usar npx o instalar dsh globalmente?

Use npx para una primera prueba, porque no deja nada salvo un directorio de caché que ahora sabe cómo limpiar. Use una instalación global fijada para cualquier herramienta que deba seguir funcionando después de un reinicio, como un agente de programación que mantiene ejecutándose en un VPS.

Ambas opciones pueden producir resultados distintos en un equipo donde haya usado las dos. Compárelas.

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

which dsh encontrar que no aparece nada justo después de una instalación global correcta casi siempre significa que falta el directorio global de binarios de npm en su PATH. Ejecute npm prefix -g para mostrar la raíz. Los binarios se encuentran en el directorio bin que cuelga de ella.

Una consideración de seguridad. npx descarga y ejecuta código del registro cada vez que resuelve algo nuevo. En un servidor, esto supone una exposición real, no teórica. Fijar las versiones es parte de la solución. El resto se explica en cómo los ataques a la cadena de suministro de npm llegan a un servidor.

Qué significa la vista previa para la reproducibilidad

0.1.0-rc.6 se publicó el 13 de agosto de 2026 y 0.1.0-rc.7 el 17 de agosto de 2026. Sólo los separan cuatro días. A ese ritmo, unas instrucciones escritas hace un mes pueden describir una línea de comandos que ya no existe, y esta página también puede quedar desactualizada. Feche cada afirmación de versión que escriba, incluidas sus propias notas.

Dos hábitos permiten trabajar con la vista previa. Fije la versión exacta en cada comando y cada script para que reconstruir un servidor produzca el mismo entorno de pruebas. Después, consulte la salida de ayuda de la compilación fijada en lugar de la de cualquier guía.

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

La otra mitad de la reproducibilidad es el perfil. dsh --profile <name> inicia el perfil almacenado en $DSH_HOME/profiles/<name>, y los perfiles web y headless se crean a partir de las plantillas incluidas la primera vez que se usan. Ese directorio también es donde el entorno de pruebas lee la clave de API, el modelo y la configuración del endpoint, por lo que una versión fijada y una configuración funcional son dos aspectos independientes que deben configurarse correctamente. Los paquetes incluidos se resuelven desde la instalación de dsh que se está ejecutando, lo que significa que cambiar la versión fijada también cambia esos paquetes. Los plugins externos se comportan de otra forma. Se almacenan en el directorio del perfil, y dsh plugin --profile <name> add <package> reenvía sus argumentos a pnpm para instalarlos. Por tanto, pnpm debe estar en su PATH, y dsh lo indica claramente cuando no lo está. El package.json del propio perfil es lo que fija esos plugins, así que una fijación completa abarca dos archivos, no uno.

Esta separación resultará familiar si ha mantenido herramientas de Python en entornos aislados en un servidor: la herramienta y los elementos que se le añaden se fijan en ubicaciones independientes. Cuando el entorno de pruebas se inicia, la siguiente cuestión suele ser la red, no las versiones. En ese punto resultan útiles el acceso a la interfaz web de dsh en un VPS remoto y el procedimiento detallado de instalación de DeepSeek Harness en un VPS.

Errores de argumentos que verá realmente

Estos errores proceden del analizador de la propia CLI, por lo que son estables en toda la línea de versiones release candidate y cada uno identifica el problema exacto.

error: --profile <name> is required

Ejecutó npx @deepseek-ai/dsh sin subcomando ni perfil. El comando sin argumentos inicia un perfil, por lo que necesita un nombre. dsh web es el subcomando que no acepta ningún --profile, porque inicia por usted el perfil web incluido.

error: --patch needs a path

Se pasó --patch sin ningún valor después. La opción se puede repetir y cada aparición recibe una ruta de archivo.

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

Elija una opción. --dump-default-config muestra las capas del paquete incluido y no acepta ningún --patch. --dump-config muestra la configuración compuesta de un perfil. Ambos muestran la información y terminan sin iniciar el harness, por lo que son la forma segura de comprobar qué ha cambiado una nueva versión release candidate.

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

Se ejecutó dsh plugin --profile <name> sin nada que reenviar. El subcomando inicializa el perfil si falta y después pasa el resto de la línea de comandos a pnpm, por lo que necesita argumentos como add @scope/dsh-plugin-example.

FAQ

¿Qué versión de Node.js necesita DeepSeek Harness?

El repositorio declara ^22.19.0 || >=24.0.0 en su package.json raíz, consultado el 18 de agosto de 2026, con la versión 0.1.0-rc.7. Por tanto, necesita Node 22.19.0 o posterior dentro de la línea 22, o Node 24 y versiones posteriores. Node 20 no funcionará. El paquete npm publicado no tiene su propio campo engines, por lo que npm nunca muestra una advertencia ni bloquea la instalación. El fallo aparece durante la ejecución. Compruebe primero node -v. Node 24 es la mejor opción de todos modos porque incluye npm 11, que corrige la reutilización de versiones por parte de npx.

¿Cómo fuerzo a npx a usar la versión más reciente de dsh en lugar de una versión almacenada en caché?

En npm 11.2.0 y versiones posteriores, npx @deepseek-ai/dsh vuelve a comprobar el registro para un nombre de paquete sin versión en cada ejecución. En npm 10, incluido en todas las versiones de Node 22, no lo hace. Borre la caché de npx con npm cache npx rm --force en npm 11 o elimine la carpeta con rm -rf "$(npm config get cache)/_npx" en npm 10. Después, confirme el resultado con npx @deepseek-ai/dsh --version. Tenga en cuenta que npm cache clean --force borra un directorio diferente y no resolverá este problema.

¿Por qué falla la instalación de @deepseek-ai/dsh@^0.1.0?

npm devuelve el código de error ETARGET con la línea No matching version found for @deepseek-ai/dsh@^0.1.0.. Todas las compilaciones publicadas son versiones preliminares, como 0.1.0-rc.7, y un rango semver no coincide con versiones preliminares a menos que el propio rango incluya una. Instale la cadena de versión exacta, incluido el sufijo -rc.N. Ejecute npm view @deepseek-ai/dsh versions --json para ver qué versiones existen, porque la secuencia tiene huecos en los que nunca se publicaron candidatos de versión.

¿Debo instalar dsh globalmente o ejecutarlo mediante npx?

npx es adecuado para una primera evaluación, porque no persiste nada salvo un directorio de caché. Una instalación global fijada, como npm install -g @deepseek-ai/dsh@0.1.0-rc.7, es adecuada para cualquier uso que deba seguir funcionando, porque la versión sólo cambia cuando usted la cambia. Si no se encuentra el comando dsh después de una instalación global, el directorio binario global de npm no está incluido en su PATH, y npm prefix -g muestra la raíz bajo la que se encuentra.

¿DeepSeek Harness es suficientemente estable para usarlo como base?

Todavía no, según su propia descripción. El README indica que el proyecto está en vista previa para desarrolladores, que evoluciona rápidamente y que tendrá cambios que romperán la compatibilidad. Las versiones candidatas 0.1.0-rc.6 y 0.1.0-rc.7 se publicaron con cuatro días de diferencia en agosto de 2026. Fije una versión exacta y lea --help de esa compilación fijada, no de una guía cualquiera. Feche sus propias notas para poder determinar cuándo han quedado obsoletas.