CH 23 · Publicar y Distribuir

Recuento de palabras~3,910 palabrasTiempo~20 minRequisitosCH 17, CH 22NivelReproducible

Objetivo del capítulo

Recorriendo PART 04, has aprendido a instalar plugins, y escribir plugins — pero sigue estando en la carpeta de tu propio workspace, ¿cómo lo obtienen otros? Este capítulo lo convierte en una distribución de "un comando para instalar": primero explica el mecanismo subyacente por el cual otros instalan tu plugin (paquete bundle), luego da tres métodos de distribución, y finalmente instálalo tú mismo antes de publicar para verificar, confirma que no hay problema antes de publicar.

Primero aclara: cómo instalan otros tu plugin

dsh no tiene un plugin market integrado; la instalación oficial va uniformemente a través de dsh plugin --profile <name> add <source>. Las fuentes son de cuatro tipos: nombre de paquete npm / directorio local / tarball / GitHub Release (cubierto sistemáticamente en CH 17). Así que lo que necesitas hacer es convertir tu plugin en cualquiera de estas cuatro fuentes.

Y "un plugin que puede ser addado por otros" tiene un nombre oficial en dsh — bundle (paquete). No confundas los dos conceptos:

• bundle es lo que tú escribes y distribuyes. Su package.json declara dsh.bundle, respondiendo "qué aporta este paquete" — un archivo patch que inserta o sobreescribe líneas de plugin.
• profile es con lo que el usuario arranca dsh --profile <name>. Su package.json declara dsh.profile, respondiendo "qué bundles, en qué orden, componen esta configuración".

Nada es ambas cosas a la vez. Tú distribuyes el bundle, el usuario lo instala con un profile y lo ejecuta.

Qué aspecto tiene un plugin publicable

En el directorio de tu plugin terminado, las tres cosas más importantes:

your-plugin/
├── package.json       # Declara dsh.bundle (y dsh.client si tiene UI)
├── cordis.patch.yml   # La capa patch aplicada cuando se instala
└── lib/               # Artefactos de build — esto es lo que otros realmente instalan

Estos campos en package.json, ninguno puede ser descuidado:

Campo	Descripción
name	Nombre del paquete, coincide con el plugin, se lee bien
version	Versión semántica, major.minor.patch, empieza en 0.0.1
description	Una línea explicando qué hace el plugin, mostrada en la lista de instalación
type	module (ESM)
main	Apunta al artefacto de build, p. ej. lib/index.js
files	Solo empaqueta lo que necesitas enviar: lib, cordis.patch.yml, LICENSE, etc. Si falta lib, otros fallarán al cargar tras la instalación
keywords	Palabras clave de búsqueda, ["deepseek","harness","dsh","dsh-plugin",...] — dsh-plugin es el estándar para ser encontrado
license	El open source debe declarar, p. ej. MIT
dsh.bundle	{"patch":"./cordis.patch.yml"} — declara que esto es un paquete, auto-montado al instalar
dsh.client	Los plugins con UI declaran inyección de cliente (el conjunto cubierto en CH 22)

Tres métodos de distribución

De ligero a pesado. El primero es autoprueba puramente local, no necesita ninguna cuenta; los dos últimos necesitan cuenta — GitHub necesita una cuenta de GitHub, npm necesita una cuenta de npm.

Método uno: directorio local / tarball — autoprueba antes de publicar

• Directorio local: dsh plugin --profile demo add ./your-plugin, pnpm enlaza directamente ese directorio, adecuado para pruebas rápidas durante el desarrollo.
• tarball: en el directorio del plugin pnpm pack para hacer un .tgz, luego dsh plugin --profile demo add ./your-plugin-0.0.1.tgz.

Antes de publicar, instálate siempre primero con tarball — el tarball es exactamente lo mismo que enviarás; si se puede instalar y ejecutar, entonces puedes considerar publicar. Autoprueba completa en tres pasos:

# Empaqueta en el directorio del plugin
pnpm pack

# Instala en un profile temporal limpio
dsh plugin --profile test add ./your-plugin-0.0.1.tgz

# Mira si entró en el árbol de configuración
dsh --profile test --dump-config

Si ves la capa de tu plugin en la salida de --dump-config, el paquete cargó con éxito. Luego dsh --profile test para arrancar, prueba si las características del plugin funcionan normalmente, todo normal entonces publica.

Dos detalles para recordar:

• Tras un cambio en un miembro de bundle, debes reiniciar el profile para que surta efecto — un profile en ejecución conserva el conjunto de bundles que tenía al arrancar (el límite en CH 17), instala y luego reinicia antes de probar.
• Orden de carga: lista de bundles del profile → cordis.patch.yml propio del profile → $DSH_HOME/cordis.patch.yml → overlay --patch, ganan las líneas aplicadas después. Tu plugin pertenece a la primera capa.

También puedes hacer que dsh lo haga por ti: envía lo siguiente, y leerá los docs, empaquetará, instalará un profile temporal, verificará; tú solo verificas.

Pack the plugin in my current workspace into a publishable form, and do a pre-publish self-test: first read the dsh official docs to understand how to pack and install plugins (bundle packages, the four sources of dsh plugin add), do it per the official spec; pack the plugin into a tarball, check whether the package.json metadata (version, description, files, keywords, license) is complete; install it into a temporary profile and verify it can load and the features work normally; finally tell me the verification result and the path of the packaged product, and explain what I still need to do to publish to npm.

Método dos: GitHub — otros instalan con una URL

La más común en la comunidad: compila el artefacto, súbelo a un GitHub Release, otros instalan con una sola URL. El DSH Skill & MCP Panel que instalamos en CH 12 se distribuyó de esta manera.

Tres pasos:

1. Empaqueta: en el directorio del plugin pnpm pack, obtén your-plugin-0.0.1.tgz.
2. Sube: haz push del repo a GitHub, crea un Release en la página del repo (escribe un número de versión v0.0.1), sube el .tgz.
3. Da la dirección de instalación: otros instalan con esta dirección:

dsh plugin --profile web add https://github.com/your-username/repo-name/releases/download/v0.0.1/your-plugin-0.0.1.tgz

Lo que se instala es el artefacto de build, no necesita autorización de allowBuilds, tan fácil como instalar desde npm. Para fijar una dirección "siempre apunta a la última", sustituye download/v0.0.1/... por releases/latest/download/your-plugin.tgz (no incluyas el número de versión en el nombre de archivo).

Nota: los plugins que van por esta ruta, lib/ generalmente no está en git — el repo solo tiene código fuente, compila localmente antes de publicar, pnpm pack a tarball, luego sube al Release.

Avanzado: GitHub Actions auto-build y publicación

Empaquetar manualmente, crear Release y subir archivos una vez está bien, pero con muchas versiones se vuelve pesado. Deja que GitHub Actions lo haga por ti: haz push de un tag v0.0.1, Actions ejecuta automáticamente build → pnpm pack → crear Release → subir el tarball. A partir de ahí, solo haz push de un nuevo tag para una nueva versión, todo lo demás es automático.

Un workflow típico va en el .github/workflows/release.yml del repo: el trigger es push: tags: ['v*'], pasos en orden: checkout del código, instalar Node, pnpm install, pnpm build, pnpm pack, usa softprops/action-gh-release para crear un Release y subir el .tgz generado como adjunto. Configúralo una vez, y no necesitas subir archivos manualmente para cada versión.

También puedes hacer que dsh haga la publicación por ti

Empaquetar, hacer push del repo, crear el Release — estas tareas repetitivas, solo pásaselas a dsh. Envía esto en el cuadro de entrada de la Web UI:

Publish the plugin in my current workspace to GitHub, release v0.0.1, use GitHub Actions for auto-build and publish per the dsh official spec, and finally tell me what address others can use to install.

Irá a leer los docs por sí mismo, ejecutará comandos por sí mismo, manejará git y Release por sí mismo. Solo necesitas confirmar según la política de permisos cuando haga operaciones que cruzan límites como hacer push del repo y crear el Release, y finalmente verifica que la dirección de instalación sea correcta.

Método tres: publicar en npm — otros solo escriben el nombre del paquete

Publica el plugin en npm, y es lo más conciso para que otros instalen: dsh plugin --profile web add your-plugin.

Cuatro pasos:

1. Regístrate e inicia sesión en npm: regístrate con una cuenta en el sitio web de npm (gratis), luego npm login (te pedirá username, password y email).
2. Compila: asegúrate de que lib/ es el artefacto de build. Los plugins de tipo fuente necesitan pnpm build antes de publicar — npm instala código pre-compilado, publica sin compilar, y otros obtienen un paquete vacío.
3. Publica: ejecuta pnpm publish en el directorio del plugin.
4. Verifica: cambia a un profile limpio, dsh plugin --profile test add your-plugin, confirma que puede instalar y ejecutarse.

Tras publicar: etiqueta el topic dsh-plugin

Independientemente del método, añade dsh-plugin a los Topics del repo de GitHub — el equipo oficial recomienda explícitamente hacer esto, para que otros puedan encontrar más fácilmente tu plugin. Recuerda incluir también dsh-plugin en los keywords del paquete npm, doble vía.

Errores comunes

Problema	Qué está pasando	Cómo manejarlo
Instalado pero sin efecto	El cambio de miembro de bundle no se reinició	Reinicia el profile tras la instalación y luego prueba
Otros fallan al cargar tras la instalación	files omitió lib/, solo se envió el fuente	Añade el directorio de artefactos de build a files, reempaqueta
Número de versión duplicado	La misma versión publish es rechazada permanentemente por npm	Cambia a una versión diferente y luego publica
Nombre del paquete tomado	Ya existe en npm con el mismo nombre	Elige un nombre de paquete no relacionado
Instalado pero no activado	El paquete no declaró dsh.bundle	Añade "dsh":{"bundle":{...}}, si no es solo una dependencia normal y no se monta

Lo que aprendiste en este capítulo

Apruebas si puedes completar los puntos de abajo:

• [ ] Sabes que un bundle es "lo que distribuyes", un profile es "con lo que el usuario arranca", y sus manifests son diferentes
• [ ] Escribes un package.json correcto para un plugin publicable: name / version / files / keywords / license / dsh.bundle, y dsh.client si tiene UI
• [ ] Conoces los escenarios apropiados para los tres métodos de distribución: autoprueba local/tarball, tarball de GitHub Release (instalación mainstream con un clic, soporta auto-publicación con Actions), npm publish
• [ ] Autoprueba antes de publicar: pnpm pack → add en profile temporal → --dump-config confirma → reinicia para verificar
• [ ] Sabes que puedes hacer que dsh haga el empaquetado, autoprueba y publicación en GitHub, sin necesidad de hacerlo paso a paso manualmente
• [ ] Sabes que tras publicar, etiqueta el repo de GitHub con el topic dsh-plugin, y los keywords del paquete npm incluyen dsh-plugin
• [ ] Puedes evitar errores comunes: files omite lib/, cambios de bundle no reiniciados, el paquete no declaró dsh.bundle