CH 03 · Instalación y arranque

Extensión~3.130 palabrasTiempo~20 minNivelReproducible

Objetivo del capítulo

Este capítulo pone dsh en marcha desde cero: confirmar/instalar Node.js, luego arrancar la Web UI con un comando, completar la configuración inicial (clave del modelo + workspace), y finalmente enviar tu primera tarea real. Una vez hecho esto, estás oficialmente dentro.

Antes de la práctica: solo necesitas dos cosas

1. Node.js — dsh se ejecuta sobre Node; esta es la única dependencia de entorno. Sin base de datos, sin Java que configurar.
2. Una API Key de DeepSeek — dsh en sí es gratis y open-source, pero llamar al modelo cuesta dinero. Ve a la Plataforma Abierta DeepSeek, regístrate e inicia sesión, luego en la barra lateral izquierda "API Keys" → Crear, cópiala y guárdala. La Key se muestra completa solo una vez, en formato de cadena larga con prefijo sk-; guárdala en un lugar seguro antes de cerrar la página.

Paso 1: comprueba el Node.js local

Abre un terminal (en Windows pulsa Win + R, escribe cmd, pulsa Enter), y teclea:

node --version
npm --version

Si ves números de versión, ya está. dsh tiene requisitos de versión de Node: la declaración oficial es ^22.19 || >=24. En palabras simples: Node 22.x en 22.19 o superior, o Node 24 o superior. Dicho de otra forma: 22.x anteriores a 22.19, y versiones impares como Node 23, no son compatibles y fallarán al arrancar.

Si, como yo, ya tenías Node instalado y la versión cumple el requisito, salta al paso 3.

Paso 2: ¿No tienes Node.js? Instala uno (Windows)

Abre el sitio web de Node.js, descarga el instalador de Windows (.msi, 64 bits) de la versión LTS, haz doble clic y Siguiente todo el rato. Por defecto también instala npm y los añade al PATH del sistema.

Después de instalar, recuerda reabrir el terminal antes de volver a verificar — muchos problemas de "acabo de instalarlo pero no se encuentra el comando" son solo variables de entorno que no se han refrescado:

node --version
npm --version

Paso 3: cambia npm a un mirror de China (opcional pero recomendado)

Descargar paquetes npm directamente en China suele ser lento o agotar el tiempo. Cambiar al mirror de Taobao ayuda mucho:

npm config set registry https://registry.npmmirror.com
npm config get registry

Si ves https://registry.npmmirror.com, está en vigor.

Paso 4: instala y arranca dsh

Este tutorial utiliza una instalación global de npm: un comando para instalar, luego el comando dsh está disponible en cualquier parte sin volver a descargar en el sitio — lo más fácil para recién llegados.

Instala el paquete global:

npm install -g @deepseek-ai/dsh

Después de instalar, verifica la versión:

dsh --version

Luego arranca la Web UI:

dsh web

La primera vez pasará uno o dos minutos descargando dependencias, con un montón de logs desplazándose en el terminal — eso es normal. Cuando veas algo como lo siguiente, está arriba:

dsh web: http://127.0.0.1:3080
dsh web: opening the default browser; pass --no-open to disable

Para actualizar a la última versión (las instalaciones globales no se actualizan solas; hazlo manualmente):

npm install -g @deepseek-ai/dsh@latest

Paso 5: abre la Web UI

La primera vez que ejecutes dsh web, abrirá automáticamente el navegador en la interfaz. Si no se abre solo, abre manualmente el navegador y visita:

http://127.0.0.1:3080

Esta es la dirección de loopback local; solo funciona en esta máquina y no se expone a la red exterior.

La primera vez que lo abras, aparece un aviso beta — DeepSeek Harness 0.1 sigue siendo una versión de prueba orientada a desarrolladores e iterará rápidamente. Pulsa Continuar para entrar en la interfaz principal.

Paso 6: configuración inicial (Key + workspace)

6.1 Rellena la API Key Después de pulsar Continuar en el paso anterior, dsh mostrará directamente una guía "Añade una API Key para comenzar" — pega tu clave con prefijo sk- en el cuadro de entrada y pulsa Guardar y continuar. (Para cambiar la Key o cambiar de modelo más tarde, ve al botón Ajustes abajo a la izquierda → Modelos.)

La Key solo se escribe localmente en C:\Users\<tu-usuario>\.dsh\.credentials.yaml; la UI nunca muestra el texto plano. No hagas capturas y las compartas.

6.2 Elige un workspace Después de rellenar la Key, entras en la interfaz principal. Pulsa el desplegable Elegir workspace y elige un directorio donde quieras que trabaje el Agent (p. ej. la carpeta de tu proyecto). Hasta que se seleccione un workspace, el cuadro de entrada de abajo seguirá diciendo "Pick a workspace to start" — esto es así a propósito: sin decirle al Agent dónde trabajar, no se atreverá a actuar.

6.3 Elige un modelo y permiso (configura antes de enviar la primera tarea) Tras seleccionar un workspace, aparece un selector de modelo abajo a la derecha; verás los tres modelos de DeepSeek:

Model ID	Posicionamiento
deepseek-v4-pro	Flagship — el más potente pero el más caro
deepseek-v4-flash	Rápido, alta relación calidad/precio
deepseek-v4-flash-vision-exp	Versión multimodal con visión: puede leer imágenes, ver capturas, analizar gráficos; al nivel de flash en texto puro, muy por delante en multimodal

deepseek-v4-flash-vision-exp es el primer modelo de visión de la familia DeepSeek V4 (experimental, API lanzada el 21 de agosto de 2026; pesos open-sourceados el 31 de agosto). Puede leer imágenes, ver capturas, analizar gráficos y también ejecutar tareas de texto normales. Todas las demos de este libro usan este modelo — selecciónalo en el panel, elige un nivel de razonamiento (el valor predeterminado High está bien), guarda y surte efecto inmediatamente; no hace falta reiniciar.

A la izquierda del cuadro de entrada también hay un selector de permiso (mostrando Workspace Write en la captura), que determina qué puede tocar el Agent en tu ordenador — mantén el predeterminado por ahora. Las diferencias detalladas entre estas opciones (qué puede hacer cada uno de los tres niveles de permiso, cómo elegir un nivel de razonamiento) se cubren en CH 04 cuando recorramos la interfaz.

Paso 7: ejecuta tu primera tarea

Crea una sesión nueva y escribe una frase, por ejemplo:

Resume el repositorio DeepSeek harness e identifica sus módulos principales.

El Agent empezará a leer archivos, ejecutar comandos y mantener un plan, con cada llamada a herramienta expuesta en la interfaz — la captura muestra la cadena de ejecución completa Context injection → Think → Pwsh → Read. Para operaciones sensibles, muestra un diálogo de aprobación según la política de permisos actual. En la parte superior izquierda de la interfaz hay dos pestañas, Conversación / Trajectory; Trajectory es la misma Trajectory mencionada en CH 02, y la cubriremos más adelante.

Tras terminar, obtienes un resumen completo — mi respuesta esta vez se titulaba "Resumen del repositorio DeepSeek Harness": el posicionamiento en una línea es "framework de ejecución de Agent Everything is a plugin / workbench, construido sobre Cordis", y también recorrió la estructura de directorios packages/apps/docs del repo y los módulos principales de la serie de paquetes dsh-*.

Una vez superado este paso, estás oficialmente dentro.

Uso avanzado

Cambiar de puerto (cuando 3080 está ocupado): usa el siguiente comando en lugar de dsh web al arrancar —

dsh web --port 8080

Luego visita http://127.0.0.1:8080.

Tarea one-shot por línea de comandos (headless):

dsh --profile headless "Run the tests in the current directory and summarize the results"

Imprime el resultado y sale, adecuado para scripts y CI. El manual completo de headless (múltiples puntos de entrada, parámetros CLI, práctica real) se cubre en CH 05.

Ver el árbol de configuración realmente efectivo (muy útil para resolución de problemas):

dsh web --dump-config

Resolución de problemas comunes

Síntoma	Solución
node no es un comando interno o externo	Node no está instalado correctamente, o no se reabrió el terminal. Reabre PowerShell e inténtalo de nuevo
Node version ... is not supported	Versión por debajo de 22.19, o Node 23. Actualiza a 22.19+ / 24
La primera instalación se queda colgada o falla la descarga	Problema de red. Configura primero el registro npmmirror y reintenta
Puerto 3080 ocupado	Cambia de puerto: dsh web --port 8080
La página no se abre	Confirma que el terminal donde se ejecuta el comando de arranque sigue abierto; la dirección es http://127.0.0.1:3080
Indica MISSING_CREDENTIAL	No hay API Key guardada (ve a Ajustes → Modelos para añadir una) o no se reabrió la ventana
Indica UNKNOWN_MODEL	Se ha seleccionado un modelo no configurado; añade el Model ID bajo un provider personalizado
Errores de compilación nativa (p. ej. node-pty)	En Windows, instala Visual Studio Build Tools (con componentes C++)

Recordatorio de seguridad: tu API Key es tu cartera. No la captures en un chat grupal ni la commitees a un repo Git. Si sospechas que se ha filtrado, ve a la plataforma, revócala y créala de nuevo; la Key antigua deja de ser válida inmediatamente.

Lo que aprendiste en este capítulo

Apruebas si puedes completar los siguientes puntos:

• [ ] Usa node --version para confirmar que Node está en 22.19+ / 24+ (si no, instala como en el paso 1)
• [ ] Instala dsh con npm install -g @deepseek-ai/dsh, arranca con dsh web y abre http://127.0.0.1:3080
• [ ] Completa la configuración inicial: Ajustes → Modelos con la API Key y elige un workspace
• [ ] Envía tu primera tarea real con éxito y ve al Agent en acción