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.
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 usa
dsh --profile <name>para iniciar.Nada es ambas cosas a la vez.
| Concepto | Clave del manifest | Pregunta que responde | Quién lo escribe / Quién lo usa |
|---|---|---|---|
| bundle (paquete combinado) | dsh.bundle | Qué aporta este paquete (un archivo patch) | Lo escribe el autor del plugin y se distribuye con el paquete |
| profile | dsh.profile | Qué bundles componen esta configuración y en qué orden | Razó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.
| Campo | Descripción |
|---|---|
name | Nombre del paquete; la resolución de módulos de Node se basa en él para encontrar el código instalado |
version | Número de versión |
type | "module"Indica que se usa el formato de módulos ESM |
main | Archivo de entrada |
files | Lista de archivos que se incluyen al publicar |
dsh.bundle.patch | Manifest del bundle: declara la ruta del archivo patch que aporta |
Creamoshello-plugin/index.jsy escribimos la entrada del plugin.
Ejemplo
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
# 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 de
dsh.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
- 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
- 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:
- ¿Qué clave declara el manifest del bundle y a qué pregunta responde?
- ¿En qué directorio se encuentra el profile y a qué pregunta responde su manifest?
- ¿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?