DeepSeek Harness bundle y profile: dos manifests

En los capítulos anteriores usábamos--patchoverlay para cargar plugins locales; en este artículo comenzaremos a empaquetarlos como bundles instalables.

En este capítulo aclararemos los dos conceptos más básicos:bundle (paquete combinado)yprofile, así como sus respectivos manifests.


Dos conceptos, dos manifests

El mecanismo de instalación se basa en dos conceptos, ambos descritos por un package.json.

Los manifests que llevan bajo la clavedshson de tipos diferentes y responden a preguntas diferentes.

bundle 与 profile 关系图

Un bundle es un paquete npm que incluye una capa de configuración.

Su manifest declaradsh.bundle, que responde a la pregunta «¿qué aporta este paquete?»: un archivo patch que inserta o sobrescribe líneas de plugins.

Un profile es un directorio ubicado bajo$DSH_HOME/profiles/<name>, que describe una composición iniciable.

Su manifest declaradsh.profile, y responde a la pregunta «qué bundles componen esta configuración y en qué orden».

bundlees lo que tú escribes y distribuyes;profilees lo que el usuario usadsh --profile <name>para iniciar.

Nada es ambas cosas a la vez.

ConceptoClave del manifestPregunta que respondeQuién lo escribe / Quién lo usa
bundle (paquete combinado)dsh.bundleQué aporta este paquete (un archivo patch)Lo escribe el autor del plugin y se distribuye con el paquete
profiledsh.profileQué bundles componen esta configuración y en qué ordenRazóndsh pluginSe crea y mantiene automáticamente; lo inicia el usuario

El profile se ubica fuera del directorio de instalación; la plantilla de ruta es$DSH_HOME/profiles/<name>。


Manos a la obra: crear el bundle hello-plugin

Siguiendo el tutorial oficial, primero creamos el directorio del paquete.

Ejemplo

mkdir -p hello-plugin

La estructura del directorio del bundle es la siguiente: tres archivos en total.

Ejemplo

hello-plugin/
├── package.json       # 声明 dsh.bundle
├── cordis.patch.yml   # profile 列出该 bundle 时应用的配置层
└── index.js           # patch 行引用的插件模块

Creamoshello-plugin/package.jsony declaramos el manifest del bundle.

Ejemplo

{
  "name": "dsh-hello-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "index.js",
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

El significado de cada campo de package.json es el siguiente.

CampoDescripción
nameNombre del paquete; la resolución de módulos de Node se basa en él para encontrar el código instalado
versionNúmero de versión
type"module"Indica que se usa el formato de módulos ESM
mainArchivo de entrada
filesLista de archivos que se incluyen al publicar
dsh.bundle.patchManifest del bundle: declara la ruta del archivo patch que aporta

Creamoshello-plugin/index.jsy escribimos la entrada del plugin.

Ejemplo

// Ruta del archivo: hello-plugin/index.js
export const name = 'hello-plugin'  // Nombre del plugin, para registro y diagnóstico

export function apply() {
  console.log('[hello-plugin] plugin loaded!')  // Imprime una línea de registro al cargar
}

Creamoshello-plugin/cordis.patch.yml。

Ejemplo

# Ruta del archivo: hello-plugin/cordis.patch.yml
# Este patch, al igual que el overlay --patch que hemos estado usando, es un array YAML de entradas de patch
# Diferencia: las líneas de plugin se referencian por nombre de paquete en lugar de una ruta relativa al código fuente, para que la resolución de módulos de Node pueda encontrar el código instalado
- insert
:
    - id
: hello
      name
: dsh-hello-plugin

Este patch es completamente isomorfo--patchal overlay.

La diferencia clave está en el camponame: aquí se escribe el nombre del paquetedsh-hello-plugin, no una ruta relativa al código fuente.

Tras la instalación, pnpm enlaza el paquete en node_modules, y la resolución de módulos de Node puede encontrar el código instalado por nombre de paquete.

Los paquetes sin la declaración dedsh.bundleaún pueden instalarse, pero solo como dependencias normales.

En este caso,dsh pluginse imprimirá una advertencia y no se activará ninguna capa.

Si una librería está destinada a ser importada por paquetes de plugins, y no a ser habilitada por el usuario, se utiliza este formato de paquete.


El manifest de profile: nunca hay que escribirlo a mano

El directorio del profile contiene dos archivos.

El primero espackage.json, que contiene las dependencias de plugins fuera del árbol del profile (gestionadas por pnpm), junto con eldsh.profilemanifest y su lista ordenada debundlesbundles.

El segundo escordis.patch.yml, que es la capa de patch propia del usuario y se aplica después de cada capa de bundle.

El manifest del profile nunca necesita escribirse a mano.

dsh pluginSe encarga de crearlo y mantenerlo; en el próximo artículo, al instalar plugins, se mostrará su resultado real.


Avanzado: hacer que el bundle de nivel superior tenga su propia línea de comandos

Un bundle que define una aplicación ejecutable puede montar un plugin proveedor normal para tener su propia línea de comandos.

Este plugin proveedor exportainject = ['cmdlineArgs'], utiliza su propio program de commander para invocarparseCmdliney luego, en la action del propio program, expone los servicios propios de la aplicación.

Ejemplo

# Montar el plugin proveedor: el id es libre; name apunta al módulo startup dentro del paquete del bundle
- id
: hello-startup
  name
: 'dsh-hello-plugin/startup'

Las líneas configuradas por estos parámetros reciben la inyección del servicio proveedor y lo leen en su propia opción!!js, mientras que el valor de despliegue se escribe al lado como respaldo.

Ejemplo

# Ejemplo: el número de puerto proviene del servicio proveedor; si no se obtiene, se usa 8080 como respaldo
- id
: my-app
  name
: '@example/my-app'
  inject
: [myAppStartup]
  config
:
    port
: !!js ctx.myAppStartup.port ?? 8080

El lanzador entrega a cada plugin los mismos argumentos inmutables, situados después de sus propios flags; por lo tanto, añadir flags específicos de la aplicación no requiere modificar el lanzador, y varios plugins pueden analizar la misma instantánea.

Cuando se encuentra--help, el proveedor no publica ese servicio, por lo que esas líneas no se activan.

El Loader solo monta la composición una vez, espera la inyección normal de cada línea y, basándose en su contexto ya inyectado, evalúa la!!jsconfiguración de esa línea.


Resumen y autoevaluación

El bundle declaradsh.bundle, que responde a «qué aporta»; el profile declaradsh.profile, que responde a «qué bundles lo componen». Ambos están contenidos en un mismo package.json, pero sus manifests son diferentes.

Preguntas de autoevaluación:

  1. ¿Qué clave declara el manifest del bundle y a qué pregunta responde?
  2. ¿En qué directorio se encuentra el profile y a qué pregunta responde su manifest?
  3. ¿Por qué en cordis.patch.yml de hello-plugin se usa el nombre del paquete en lugar de una ruta relativa al código fuente?
Otras extensiones