CH 05 · Ejecutar desde la línea de comandos: headless + CLI
Objetivo del capítulo
Los capítulos anteriores hicieron clic en la Web UI. Este capítulo cambia la forma: sin interfaz, un único comando en el terminal permite a dsh terminar un trabajo y salir — eso es headless. De paso, recorreremos todas las puertas que el "launcher" de dsh puede abrir; vendrá bien más adelante para scripts, CI y trabajos por lotes.
Primero entiende: dsh es un launcher multi-entrada
dsh no es solo "esa página web". Es un launcher — el mismo Harness, la misma pila de plugins, puede arrancar de distintas formas:
Los puntos de entrada oficiales son estas puertas:
| Entrada | Propósito | En palabras simples |
|---|---|---|
web | El workbench web con interfaz | El que usaste en los capítulos anteriores |
headless | Ejecuta una tarea, imprime la respuesta, sale | Tarea one-shot por línea de comandos, la estrella de este capítulo |
sdk | Servicio JSON-RPC stdio | Actúa como backend para programas, deja que otras aplicaciones lo llamen |
acp | Servicio ACP stdio | Proporciona servicio a clientes de automatización |
plugin | Gestión de plugins para profile | Instala plugins, añade dependencias a un profile — para eso sirve esto |
Sin importar la puerta por la que entres, la misma pila de plugins está haciendo el trabajo debajo. CH 02 dijo "todo es un plugin"; a estas alturas deberías notarlo: incluso la "entrada" en sí es una combination de plugins.
headless: una frase, una tarea
headless es la tarea one-shot en modo línea de comandos. El uso es muy simple:
dsh --profile headless "lo que quieres que haga"Su comportamiento, en una frase oficial: abrir una sesión persistente nueva de cero → hacer el trabajo → imprimir la respuesta final → salir.
Algunos puntos clave:
- Workspace = el directorio en el que estás cuando ejecutas el comando. Donde sea que ejecutes el comando, allí trabaja (no hace falta elegir manualmente un workspace como en la Web UI).
- "Abrir una sesión persistente nueva de cero" es literal: cada ejecución headless equivale a abrir una sesión nueva en el directorio actual como workspace, y guardarla en
$DSH_HOME/sessions. Esto es fácil de confundir, así que te lo desenredo — en el nivel de archivo: las sesiones se almacenan por carpeta de workspace, bajoC:\Users\<tu-usuario>\.dsh\sessions\, donde puedes ver directamente directorios nombrados según rutas de workspace (como--E-software-workspace-...--), que contienen archivos de sesión comprimidos; a nivel de Web UI: la sesión de una ejecución headless aparece en la categoría Sin agrupar, no agrupada automáticamente bajo ningún grupo de workspace (en la versión actual). El almacenamiento en disco es por workspace, la visualización en UI va a Sin agrupar — son dos cosas separadas. La sección práctica de abajo lo mostrará. - El modelo predeterminado es
deepseek-v4-flash: el escenario CLI no tiene UI ni necesita imágenes, así que el valor predeterminado oficial da el flash con mejor relación calidad/precio. - Sin UI, pero el pipeline completo está ahí: inyección de contexto, planificación, llamadas a herramientas, pensamiento, cierre — no falta nada, simplemente no te lo dibuja.
Práctica: primera tarea headless
Dale al Agent una "tarea grande": leer el repo, resumir la arquitectura y escribir un documento. Ejecútalo en el workspace:
dsh --profile headless "Read the deepseek-harness subdirectory's code and docs, summarize the overall architecture of DeepSeek Harness (plugin mechanism, layering, entry points, main packages and directories), and write a Chinese markdown architecture document saved to the current directory with the filename deepseek-harness-arch.md"Resultado impreso tras ejecutar:
Done. I read the key source and docs in the deepseek-harness subdirectory, organized it into a Chinese architecture document and saved it to the current directory.
File: E:\software-workspace\DeepSeek harness demo\deepseek-harness-arch.md (about 295 lines)Vuelve a la Web UI para verificar esta sesión: puedes encontrarla en la lista de sesiones, pero fíjate que aparece en la categoría Sin agrupar, no bajo un grupo de workspace (las sesiones headless no se agrupan automáticamente, este es el comportamiento real de la versión actual):
A la derecha puedes ver su proceso de ejecución completo: context injection → think → Pwsh list directory → read doc → write file. La barra de estadísticas inferior muestra 1 turn · 18 steps, LLM 2m1s, cache hit 92%, input 1.1M tokens.
Hoja de referencia rápida de parámetros CLI
| Comando | Efecto |
|---|---|
dsh --profile <name> "task" | Arrancar con el profile especificado (headless es uno de ellos) |
dsh web | Alias de --profile web, arranca la Web UI |
dsh --dump-config | Imprime el árbol de configuración combinado completo (joya para resolución de problemas, ver abajo) |
dsh --dump-default-config | Imprime el árbol de configuración predeterminado sin cambios del usuario |
dsh --patch <path> | Apila otra capa de configuración encima del profile |
dsh plugin --profile <name> add <package> | Instala un plugin en un profile |
dsh --help | Ver la ayuda del propio launcher |
--dump-config merece una mención aparte: imprime la combination de plugins final efectiva para un profile. Ejecútalo de verdad:
Lo que ves es una larga lista de plugins @deepseek-ai/dsh-* apilados en un árbol — llm (modelo), session (sesión), credentials (claves), session-persistence-jsonl (persistencia de sesión)... también puedes ver directamente que agent-default-model está configurado como deepseek-v4-flash. Al resolver problemas o intentar averiguar "de dónde viene este comportamiento", vacía primero el árbol de configuración.
Hay un truco aún más conveniente para resolver problemas: simplemente deja que la IA ejecute este comando por sí misma. Por ejemplo, en una sesión pregúntale "usa dsh --profile headless --dump-config para revisar el árbol de configuración actual y ver por qué el modelo predeterminado no es el que quiero" o "comprueba si hay un plugin que no está surtiendo efecto" — la IA ejecutará --dump-config por sí misma, leerá el árbol de configuración y revisará la configuración entrada por entrada para ayudarte a localizar el problema. Este combo es un golpe muy práctico al resolver problemas.
Cuándo usar headless, cuándo usar web
| Escenario | Cuál usar |
|---|---|
| Quieres ver al Agent trabajar, interrumpir en cualquier momento, resolver problemas paso a paso | web |
| Scripts, CI, tareas programadas, procesamiento por lotes, solo importa el resultado | headless |
| Otros programas/herramientas necesitan llamar a las capacidades de dsh | sdk / acp |
| Quieres confirmar configuración, resolver problemas de arranque | --dump-config / --help |
Recuerda también un límite oficial: cada llamada headless solo ejecuta una tarea, sin seguimiento interactivo. Si necesitas múltiples turnos o verlo trabajar, vuelve a web.
Lo que aprendiste en este capítulo
Apruebas si puedes completar los siguientes puntos:
- [ ] Describe al menos cuatro puntos de entrada de dsh (web / headless / sdk / acp / plugin) y qué hace cada uno
- [ ] Ejecuta una tarea one-shot por línea de comandos con
dsh --profile headless "task"y explica su comportamiento (sesión nueva → trabajo → imprime respuesta → salir) - [ ] Sabes que el workspace de headless es el directorio actual al ejecutar el comando, y que cada ejecución abre una sesión persistente (almacenada por workspace bajo $DSH_HOME/sessions; en la lista de sesiones de la Web UI, las sesiones headless están en Sin agrupar)
- [ ] Indica los escenarios para los que headless es adecuado (lotes, CI, programadas, análisis de repos) y el límite oficial (una tarea por llamada, sin interacción)
- [ ] Usa
dsh --dump-configpara ver el árbol de configuración, y conoce su uso en resolución de problemas - [ ] Determina si un escenario debe usar web o headless