CH 17 · Instalación de Plugins

Recuento de palabras~6,370 palabrasTiempo~20 minRequisitosCH 08 (Árbol de Plugins), CH 12 (Integración MCP)NivelReproducible

Objetivo del capítulo

En CH 12 ya instalaste tres plugins — dsh-mcp-client, dshmarket, dsh-skill-mcp-panel — pero eso fue "instalar de paso, con tal de que funcione", sin explicar los tres métodos de instalación. Este capítulo cubre de forma sistemática la instalación de plugins: de dónde vienen los plugins, dónde se instalan, los diferentes métodos de instalación, cómo gestionarlos, cómo verificar después de instalar — y finalmente instala uno tú mismo, y deja que dsh lo instale directamente por ti.

Primero recuerda una línea: instalar un plugin = añadir una dependencia npm a un profile. dsh es "todo es un plugin" (cubierto en CH 08), pero la "instalación" en sí sigue la gestión estándar de paquetes. Una vez que entiendas la instalación, CH 18 comienza escribiendo tu primer plugin.

Primero observa tu instalación

Abre la terminal, primero verifica la versión de dsh:

dsh --version

Mi salida:

0.1.1-rc.2

Luego verifica qué plugins ya tiene el profile web:

dsh plugin --profile web list

Mi salida (el resultado de instalar en CH 12):

Legend: production dependency, optional only, dev only

dsh-profile-web C:\Users\mortal\.dsh\profiles\web (PRIVATE)
│
│   dependencies:
├── @deepseek-ai/dsh-mcp-client@0.0.1-rc.1
├── dsh-skill-mcp-panel@2.0.1
└── dshmarket@1.40.0

3 packages

Observa que estas tres líneas corresponden exactamente a los tres métodos de instalación: mcp-client se instaló mediante la línea de comandos, dshmarket es el cuerpo del mercado instalado por línea de comandos, y dsh-skill-mcp-panel se instaló con un clic en el mercado — y la razón por la que pueden entrar directamente en el árbol de configuración y surtir efecto es el tercer mecanismo bundle auto-mount. Cada uno se explica a continuación.

De dónde vienen los plugins: cuatro fuentes

Un plugin es esencialmente un paquete npm, y las fuentes son estas:

Fuente	Sintaxis	Cuándo usarla
Paquete npm	@deepseek-ai/dsh-mcp-client	La más común. Los paquetes oficiales tienen el prefijo @deepseek-ai/, los paquetes de la comunidad usan su propio scope
Código fuente de GitHub	github:owner/repo	Cuando quieres instalar la rama main de un repo, y aún no se ha publicado en npm
Directorio local	. o file:../plugin	Cuando desarrollas un plugin tú mismo, instala tu checkout directamente, edita y prueba
tarball / Artefacto de Release	Una URL .tgz o ruta local	Cuando el autor solo publica artefactos compilados, p. ej. adjuntos en GitHub Releases

En cuanto al dsh-market (Plugin Market) instalado en CH 12, no es una fuente nueva, sino una entrada gráfica: una vez instalado, puedes navegar, buscar e instalar con un clic plugins de la comunidad en Settings, mientras sigue invocando las fuentes de arriba por detrás.

Dónde instalar: a nivel de Profile, sigue al Profile

dsh plugin gestiona los plugins de un profile, así que el comando debe ir acompañado de --profile <name>, decidiendo en qué entorno instalar. El paquete instalado aterriza en:

$DSH_HOME/profiles/<name>/node_modules

En Windows esto es C:\Users\<tu-usuario>\.dsh\profiles\web\node_modules, gestionado por pnpm, y también escrito en el package.json del profile.

Un punto fácil de confundir — la diferencia entre global y Profile:

• El cuerpo de dsh en sí se instala globalmente (npm install -g @deepseek-ai/dsh de antes), todos los profiles comparten el mismo dsh.
• Los plugins son por profile por defecto: dsh plugin --profile web add xxx solo surte efecto para web; si quieres que headless también lo use, tienes que instalarlo también para headless.
• La configuración a nivel de máquina es una capa diferente: $DSH_HOME/cordis.patch.yml la comparten todos los profiles (el término oficial es "machine-local preferences"), y tiene mayor prioridad que el cordis.patch.yml propio del profile — si quieres que todos los entornos apliquen el mismo cambio, escríbelo aquí.

Primero aclara dónde están estos archivos, no los confundas. El de nivel profile está en C:\Users\<tu-usuario>\.dsh\profiles\web\cordis.patch.yml (el que editamos para la configuración del servidor MCP en CH 12); el de nivel máquina está en C:\Users\<tu-usuario>\.dsh\cordis.patch.yml — fíjate en que este archivo no existe por defecto, solo se crea cuando escribes manualmente la configuración, dsh lo lee al arrancar, y lo omite si no existe. Así que para verificar "lo que escribí es a nivel de máquina", comprueba si aparece bajo el directorio raíz .dsh, no bajo profiles\<name>\.

• Los bundles integrados oficiales (@deepseek-ai/dsh-base, @deepseek-ai/dsh-web-app, etc.) vienen con dsh, desde la instalación global; los plugins que añades tú mismo se instalan en el node_modules propio del profile.

Una línea para recordar: el cuerpo de dsh es global, los plugins siguen al profile, los patches a nivel de máquina se aplican a todo el sitio.

Tres métodos de instalación

① Línea de comandos dsh plugin: la más fundamental

Este es el método más fundamental. dsh plugin --profile <name> pasará los argumentos tal cual a pnpm — así que los verbos de pnpm como add, remove, update, why, list están todos disponibles, y la sintaxis también es la sintaxis de gestión de paquetes npm:

dsh plugin --profile web add @deepseek-ai/dsh-mcp-client

Un ejemplo típico de los docs oficiales es instalar dos plugins de subagent (son bundles opcionales):

dsh plugin --profile web add @deepseek-ai/dsh-subagent-codex @deepseek-ai/dsh-subagent-claude-code
dsh plugin --profile web remove @deepseek-ai/dsh-subagent-codex

Instalar tu propio plugin desde un directorio local también pasa por aquí — ejecuta dsh plugin --profile web add . en el directorio fuente del plugin, y lo que se instala es tu checkout actual (las rutas relativas se anclan al directorio en el que ejecutaste el comando, no al directorio del profile).

② Plugin Market dsh-market: el más fácil

Instalación gráfica. Primero instala el cuerpo del mercado:

dsh plugin --profile web add dshmarket

Tras la instalación, reinicia dsh (los cambios de bundle requieren reinicio, explicado más abajo), Settings tendrá un nuevo "Plugin Market", donde puedes navegar por categoría, buscar e instalar con un clic plugins de la comunidad. La mayoría de plugins instalados mediante el mercado surtan efecto simplemente recargando la página, sin necesidad de reiniciar dsh; algunos plugins a nivel de host pedirán "restart required", solo sigue las instrucciones. El dsh-skill-mcp-panel de CH 12 se buscó en el mercado y se instaló con un clic.

③ Bundle Auto-Mount: instalar y entrar en el árbol de configuración

Primero una respuesta a un fenómeno que seguro te has preguntado: ¿por qué mcp-client necesita insertar manualmente la configuración del servidor en cordis.patch.yml tras la instalación, mientras que dshmarket y dsh-skill-mcp-panel surten efecto sin configuración tras la instalación? La respuesta está en el package.json del propio plugin — la diferencia es si se declara dsh.bundle. Si un plugin quiere "entrar automáticamente en el árbol de configuración al instalarse", tiene que declarar este campo en su manifest:

{
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    }
  }
}

dsh, tras cada ejecución exitosa de dsh plugin, conciliará la lista de bundles: cualquier paquete en dependencies que se resuelva con una declaración dsh.bundle se añadirá automáticamente a la capa de bundle de ese profile (la capa base en la parte inferior del árbol de configuración, cubierta en CH 08), sin que tengas que insertarlo manualmente.

Como ejemplo, mira el package.json de dos plugins con declaraciones. dshmarket@1.40.0:

"dsh": {
  "bundle": { "patch": "./cordis.patch.yml" },
  "client": { "inject": ["@deepseek-ai/dsh-client-connection", "..."], "platform": "web" }
}

dsh-skill-mcp-panel@2.0.1:

"dsh": {
  "client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-runtime", "..."] },
  "bundle": { "patch": "./cordis.patch.yml" }
}

Ambos tienen declaraciones bundle.patch, así que ambos se introducen automáticamente en la lista de bundles del manifest del profile. Abre el package.json del profile web, y la capa de bundle se ve así:

"dsh": {
  "profile": {
    "bundles": [
      "@deepseek-ai/dsh-base",
      "@deepseek-ai/dsh-web-app",
      "dsh-skill-mcp-panel",
      "dshmarket"
    ]
  }
}

Los dos primeros son bundles oficiales integrados (que van con la instalación global de dsh), los dos últimos son los que instalaste y se montaron automáticamente. ¿Y qué pasa con dsh-mcp-client? No tiene declaración dsh.bundle, así que es solo una dependencia normal — aparece en las dependencies del package.json del profile, pero no en la lista bundles. Una analogía: un plugin bundle es como una herramienta "instrucciones autoinstalables, lista para usar"; una dependencia normal es como "solo la herramienta, sin instrucciones" — la mercancía llega, pero dsh no cargará automáticamente sus capacidades, tienes que configurarla tú mismo.

dsh-mcp-client es lo segundo: es el "motor que se conecta a servidores MCP", sabe cómo conectarse, pero no sabe a cuál conectarse. Tienes que decirle personalmente a qué servidor conectarse, la dirección, cómo se pasa la clave — esa acción es escribir un insert en cordis.patch.yml (insertando una línea de configuración del servidor en el árbol de configuración). La configuración de Firecrawl que escribiste en CH 12 fue uno de esos inserts.

Fíjate también: estos dos plugins también tienen declaraciones dsh.client (platform: web + inject de una lista de plugins de cliente). Por eso pueden añadir interfaces a Settings de la Web UI (Plugin Market, MCP Management) — ambos son bundles (entran en el árbol de configuración) y declaran inyección de cliente (entran en la interfaz).

Un límite que debes recordar: tras un cambio en un miembro del bundle (algo en la lista bundles), tienes que reiniciar el profile para que surta efecto — un profile en ejecución conserva el conjunto de bundles que tenía al arrancar, los bundles recién instalados solo se cargan en el siguiente arranque. Fíjate en que "reiniciar" aquí solo es para que se auto-cargue, no para que tengas que configurar nada — una vez que el plugin bundle está cargado está listo para usar, no necesitas tocar la configuración. Las ediciones normales de cordis.patch.yml pasan por hot-reload, sin necesidad de reiniciar, pero añadir/quitar/actualizar un bundle y reiniciar es inevitable. La razón por la que reiniciaste dsh tras instalar dshmarket en CH 12 fue para que se auto-cargara.

Hoja de referencia de comandos de gestión

Comando	Efecto
dsh plugin --profile web list	Listar lo que este profile tiene instalado (equivalente a pnpm list)
dsh plugin --profile web add <fuente>	Instalar, fuente ver los cuatro tipos de arriba
dsh plugin --profile web remove <paquete>	Eliminar
dsh plugin --profile web update <paquete>	Actualizar al último (los que tienen declaración bundle se conciliarán con el nuevo)
dsh plugin --profile web why <paquete>	Ver por qué se instaló este paquete (quién depende de él)

¿Cómo verificar la instalación una vez hecha? Dos formas:

• Ver dependencias y atribución de bundle: dsh plugin --profile web list muestra las dependencias; para ver si está en la capa de bundle, mira directamente el package.json del profile (el dsh.profile.bundles de arriba).
• Ver si está realmente montado en el árbol de configuración: dsh --profile web --dump-config imprime el árbol de configuración completo, busca el nombre del plugin; para ver solo la capa base del bundle, usa dsh --profile web --dump-default-config.

Instala tres plugins de la comunidad que realmente usarás

Los plugins instalados antes eran para explicar el mecanismo, y también eran cosas que realmente se necesitaban en el proceso — dsh es así, instala lo que quieras, todo es un plugin. Ahora instalemos tres plugins de la comunidad que "mejoran al instante la experiencia", exactamente desde fuentes de GitHub y npm. No hace falta que escribas comandos tú mismo, solo pásaselo a dsh.

dsh-theme: cambia el aspecto de la Web UI

Un plugin de tema independiente; tras la instalación, Settings tiene un nuevo "Appearance":

• Tres modos de apariencia: light / dark / follow system
• 15 temas seleccionados, incluyendo 5 temas orientados a lectura + 1 tema Carbon Code orientado a código
• Cada tema empaqueta niveles de color, fuente de UI, fuente de código, tamaño de fuente en una configuración unificada, conmutable con un clic
• Ajusta en tiempo real el color de acento, fondo, primer plano, superficie, color de la barra lateral individualmente
• Los ajustes se almacenan localmente en el navegador, no se pierden al recargar (no se sincronizan entre navegadores o profiles)

Para que dsh lo instale por ti, envía en el cuadro de entrada:

Help me install the dsh-theme plugin to the web profile and confirm it's working; it's in the oil-oil/dsh-theme repo on GitHub.

Open source: oil-oil/dsh-theme. Tras instalar reinicia el profile web, Settings → Appearance te permite cambiar temas, se ve así:

dsh-oil-sticky-prompt: fija el último mensaje del usuario en la parte superior al desplazarse

Al desplazarte por una respuesta larga, el último mensaje del usuario se convierte en una barra compacta de ancho completo fijada en la parte superior de la conversación, haz clic para saltar al original:

• Una única barra sticky, varios temas no entran en conflicto
• Los saltos de línea originales se aplanan a espacios, máximo dos líneas
• No modifica el mensaje, no toca el registro de sesión, no persiste ajustes

Para que dsh lo instale por ti, envía en el cuadro de entrada:

Help me install the dsh-oil-sticky-prompt plugin to the web profile and confirm it's working; it's in the oil-oil/dsh-oil-sticky-prompt repo on GitHub.

Open source: oil-oil/dsh-oil-sticky-prompt. Tras instalar reinicia dsh. La imagen de abajo es una conversación de dsh instalándolo por mí — explicó que el aviso de Peer dependency es un comportamiento esperado, y señaló que surtirá efecto cuando el profile web se reinicie la próxima vez:

dsh-better-sidebar: convierte la barra lateral en un banco de trabajo completo

El más pesado en características, convierte la barra lateral derecha en un "banco de trabajo". Su filosofía de diseño está en la misma línea que las barras laterales de herramientas de programación de IA como Codex — mover archivos, terminales, Git para que estén junto al Agent, observar mientras se trabaja:

• Banco de trabajo de archivos: árbol de directorios + editor de código, vista previa inline para imágenes / Markdown / HTML / PDF / Office
• Navegador embebido: múltiples pestañas de páginas web, el contenido se ejecuta en un iframe sandboxed
• Terminal real: xterm + node-pty ejecuta un shell real, reconexión al desconectar, opcional inyectar herramientas de terminal al modelo
• Panel Git: diff real, historial, stage / commit / revert con clic derecho
• Página de jobs en segundo plano: ver topología de subagents y jobs en segundo plano (código de salida / salida en vivo / terminar forzado)
• Barra lateral derecha + panel inferior doble banco de trabajo, layout recordado por sesión

Para que dsh lo instale por ti, envía en el cuadro de entrada:

Help me install the dsh-better-sidebar plugin to the web profile and confirm it's working; it's in the omdsh-dev/DSH-better-sidebar repo on GitHub (npm package name dsh-better-sidebar).

Open source: omdsh-dev/DSH-better-sidebar. Tras instalar reinicia dsh, luego haz un hard-refresh del navegador para ver la barra lateral (es miembro de bundle, solo se carga al reiniciar), el explorador de archivos del lado derecho + la terminal inferior aparecen juntos:

Todos estos tres tienen declaraciones bundle, se auto-montan al instalarse (el mecanismo en ③). La primera vez que instales esos dos desde fuente de GitHub, si pnpm lo bloquea con allowBuilds, manéjalo según la entrada en "Errores comunes".

Errores comunes

Problema	Qué está pasando	Cómo manejarlo
¿Instalado pero sin cambio en la UI?	Si instalaste un miembro de bundle, un profile en ejecución no se recargará solo	Reinicia dsh y vuelve a comprobar Settings
¿La primera add de un plugin desde fuente GitHub reporta error de allowBuilds?	pnpm ≥10 por defecto impide que los paquetes fuente ejecuten scripts de build prepare	Según el aviso impreso en el error, copia la clave allow en pnpm-workspace.yaml bajo el directorio del profile, luego re-ejecuta add
¿Instalar dsh-better-sidebar reporta "Ignored build scripts"?	pnpm 11 interceptó los scripts de build de módulos nativos como node-pty	Ejecuta pnpm approve-builds --all en el directorio del profile (C:\Users\<tu-usuario>\.dsh\profiles\web), luego haz hard-refresh
¿Aparecen dos barras laterales tras la instalación?	Una línea que montaste manualmente antes se montó dos veces con el bundle automático	Elimina la antigua línea de montaje manual - insert: ... better-sidebar ... en cordis.patch.yml
¿Instalado en el entorno equivocado?	--profile decide dónde instalar	Confirma que el nombre del profile en el comando es el que quieres (web / headless …)
¿Instalado pero sin efecto, sin error?	Puede que hayas instalado una dependencia normal (sin declaración dsh.bundle)	Es solo "el paquete llegó", las capacidades hay que insertarlas tú mismo en cordis.patch.yml para conectarlas (mcp-client es el caso típico)

Lo que aprendiste en este capítulo

Apruebas si puedes completar los puntos de abajo:

• [ ] Enuncia las cuatro fuentes de plugins (npm / GitHub / directorio local / tarball), y que el Plugin Market no es una fuente sino una entrada gráfica
• [ ] Sabes que dsh plugin --profile <name> gestiona los plugins de un profile, instalando en su node_modules
• [ ] Distingues: el cuerpo de dsh instalado globalmente, plugins por profile, $DSH_HOME/cordis.patch.yml a nivel de máquina y para todo el sitio
• [ ] Conoces los tres métodos de instalación: add por línea de comandos / instalación con un clic desde el mercado / dependencia con declaración dsh.bundle se auto-monta
• [ ] Enuncias el propósito de los tres plugins de la comunidad (dsh-theme cambia el aspecto / dsh-oil-sticky-prompt barra de prompt fija / dsh-better-sidebar banco de trabajo en la barra lateral), y los instalas tú mismo
• [ ] Sabes que los cambios en miembros de bundle requieren reiniciar el profile, las ediciones normales de patch pasan por hot-reload
• [ ] Usas list / remove / update para gestionar plugins, usas --dump-config para verificar que está montado en el árbol de configuración