Iniciar sesiónReservar sesión

Capítulo 2.18

El modelo de extensión

Las seis formas de ampliar Nexus, desde un ajuste hasta un paquete de dominio, los límites de cada una y cómo los niveles de confianza y aislamiento deciden dónde se ejecuta su código. Léalo antes de abrir el kit de desarrollo de software (SDK).

Esta página fue traducida por IA a partir del original en inglés. Si algo no está claro, la página en inglés es la referencia. Leer esta página en inglés

16 minutos de lectura

Lo primero que construí en Nexus en Corrán Orbital no fue un plugin. Nuestro equipo de dinámica de vuelo quería que el asistente respondiera a «¿qué pases de estación terrena perdemos si la antena de Svalbard queda fuera de servicio por mantenimiento?» siempre con el mismo formato, con la tabla de pases primero y el coste en minutos de contacto debajo. Pasé medio día leyendo el kit de desarrollo de software (SDK) antes de que un compañero me señalara que lo que necesitaba era una habilidad: una carpeta con un SKILL.md dentro, subida al Skills Engine y publicada una vez superadas sus pruebas y aprobada por un revisor. Me llevó cuarenta minutos.

Dos plugins y un paquete de dominio después, ese sigue siendo el primer consejo que doy. Nexus ofrece seis formas de ampliarlo, dispuestas en una escalera de esfuerzo. Los peldaños económicos hacen más de lo que la gente espera, y los costosos conllevan obligaciones fáciles de subestimar. Este capítulo presenta la escalera. Elija el peldaño más bajo que cumpla la función. Los capítulos siguientes profundizan en cada uno: capítulo 2.19, Las reglas que hereda toda extensión; capítulo 2.20, Habilidades; capítulo 2.21, El SDK de plugins; capítulo 2.22, El entorno de ejecución de plugins; y capítulo 2.23, Paquetes de dominio.

Los seis bloques de construcción

Aquí están en el orden en que debería considerarlos.

  1. Ajustes y políticas. Son valores que un administrador establece en la consola para la organización, una unidad o una persona, dentro de lo que permite la licencia. No se escribe nada de código.
  2. Habilidades del Skills Engine. Un paquete SKILL.md que contiene instrucciones y las herramientas que la habilidad puede invocar, junto con archivos y scripts opcionales. El asistente, los agentes, los flujos de trabajo y los botones de IA (inteligencia artificial) de las pantallas ejecutan las mismas habilidades, al igual que su IDE (entorno de desarrollo integrado).
  3. Plugins. Su propio código, declarado mediante un manifiesto y compilado con las herramientas del SDK. Un plugin se presenta en uno de tres niveles: skills-only, ui-only o full-service.
  4. Paquetes de dominio. Las lentes y plantillas de un sector, sus habilidades y su modelo de conocimiento, sus conectores y sus pantallas de teléfono, con licencia como una unidad. Adverant incluye diez; usted puede crear los suyos propios.
  5. Lentes. Lo que ve un rol dentro de un paquete o una plataforma. Una lente restringe una lente base y nunca la amplía.
  6. Conexiones MCP y conectores. Las herramientas del Protocolo de Contexto de Modelo (MCP) que publica un plugin o a través de las cuales se conecta una herramienta de programación con IA, y los conectores de solo lectura que incorporan registros desde sistemas que usted ya opera.

Hay dos términos sobrecargados, así que los aclararé ahora. Una habilidad del Skills Engine es un paquete SKILL.md en la biblioteca. Una habilidad de manifiesto es una fila tipada en la matriz skills[] de un plugin, compilada en el registro de habilidades de la plataforma y ejecutada a través de UNO, el motor de flujos de trabajo. Ambas se denominan habilidades en pantalla. Se escriben y gobiernan de forma diferente, y esta documentación siempre especifica a cuál se refiere.

Empezar algo nuevo
Empezar algo nuevo
Empezar algo nuevo ofrece seis rutas recomendadas, una por cada tipo de extensión. Cada una crea un repositorio a partir de una plantilla versionada con un manifiesto que declara lo que necesita, y configura pruebas, un espacio de desarrollo y ramas de datos.

Qué puede hacer cada uno y qué no

La tabla es la versión resumida. He incluido la columna «Lo que no puede hacer» a propósito: cada límite es una propiedad del diseño, y todos ellos me han salvado de algún problema.

Componente Lo que puede hacer Lo que no puede hacer Quién lo crea
Ajuste o política Cambiar el comportamiento de una función en cualquier nivel, desde la organización hasta una persona; bloquear un valor; delegarlo hacia abajo; solicitar la aprobación de una segunda persona ante un cambio Añadir una pantalla o una ruta, almacenar una tabla nueva o iniciar un nuevo tipo de trabajo Un administrador, en la consola
Habilidad del Skills Engine Proporcionar al asistente y a los agentes, a los flujos de trabajo y a los botones de IA una forma repetible de realizar una tarea, con sus propias instrucciones y casos de prueba Guardar una credencial; invocar una herramienta fuera de la lista permitida de la persona que la ejecuta (SKILL_CANNOT_WIDEN_TOOLS); pasar a producción sin sus pruebas y aprobación Cualquier persona con el permiso correspondiente, en el creador o desde su IDE
Plugin, skills-only Publicar habilidades de manifiesto que se ejecutan en la plataforma: retrollamadas al host, trabajo en cola, mapeos sobre una lista y, con nivel de confianza core o verified, habilidades respaldadas por modelos Servir páginas propias Un desarrollador, con el SDK
Plugin, ui-only Añadir una superficie de frontend dentro del shell Almacenar datos propios o ejecutar cómputo Un desarrollador, con el SDK
Plugin, full-service Su propio backend y frontend, un esquema de Postgres, una tabla de rutas con permisos, y habilidades y herramientas MCP Invocar a un proveedor de modelos; guardar una clave de modelo; leer filas de otra organización salvo mediante una concesión registrada; ejecutar cómputo fuera del despacho de UNO Un desarrollador, con el SDK
Paquete de dominio Aportar las lentes y plantillas de un sector, sus habilidades y flujos de trabajo, un modelo de conocimiento, un mapa de evidencias y pantallas de teléfono a las unidades que elija un administrador Cambiar el shell o sus componentes, o las reglas de escritura; ejecutarse sin que lo cubra la licencia de la organización Adverant, o sus propios desarrolladores en Enterprise
Lente Elegir las tarjetas y los campos que ve un rol dentro de un paquete o plataforma, y las acciones que ofrece Mostrar cualquier elemento que oculte su lente base (LENS_CANNOT_WIDEN); cambiar lo que puede hacer un rol El autor de un paquete la construye; un administrador la concede por unidad
Herramientas MCP y conectores Exponer las herramientas de un plugin a agentes y herramientas de programación; leer registros de un sistema de pólizas o de un archivo de telemetría hacia el modelo de conocimiento Escribir de vuelta en el sistema de origen a través de un conector; actuar más allá de los permisos propios de la persona que ha iniciado sesión Un desarrollador declara herramientas MCP; un administrador configura los conectores

Algunas de esas celdas merecen una frase más.

Los ajustes son un marco de trabajo, y todos los plugins usan el mismo. Un plugin que declara un bloque settings en su manifiesto obtiene los niveles (plataforma, organización, paquete, unidad, grupo, repositorio, persona), bloqueos y delegación, un registro de cambios y aprobación de una segunda persona, todo ello sin escribir una tabla de ajustes. Por eso el peldaño más económico suele bastar: si el comportamiento que busca ya existe y solo necesita un valor diferente para la unidad de Rotterdam, es un ajuste.

Una habilidad del Skills Engine se ejecuta en nombre de la persona. Nunca guarda una clave, solo puede acceder a herramientas dentro de la lista permitida de quien la ejecuta y leer únicamente lo que esa persona tiene permiso para abrir. Una habilidad que añade una herramienta de escritura queda retenida hasta que dos personas la aprueban; luego pasa a producción en modo sombra, después en modo canario y, finalmente, para todos.

Un plugin skills-only es el peldaño intermedio. Lo necesita cuando el trabajo consiste en código propio: un cálculo determinista, un trabajador de cola o una distribución en abanico sobre una lista. La plataforma invoca su código; su código nunca invoca un modelo.

Un plugin full-service es un producto pequeño. Posee un esquema de Postgres, una tabla de rutas con un registro de permisos, un frontend, un conjunto de roles de base de datos y todas las obligaciones de aislamiento del capítulo 2.19, Las reglas que hereda toda extensión. Es la respuesta correcta más veces de lo que se teme y la respuesta equivocada más veces de lo que se espera.

¿Cuál necesito?

Empiece por la parte superior de esta tabla y deténgase en la primera fila que se ajuste a su caso.

Usted quiere… Use Por qué no algo más ligero
Cambiar un valor o un límite, o quién puede hacer algo Un ajuste o una política No existe nada más ligero
Hacer que el asistente realice una tarea siempre de la misma forma Una habilidad del Skills Engine Un ajuste no puede contener instrucciones
Poner un «botón de IA» en una pantalla que ejecute esa tarea Una habilidad del Skills Engine vinculada al botón Un botón solo ejecuta habilidades; no hay nada que construir
Permitir que una herramienta de programación con IA acceda a Nexus Una conexión MCP a través del Workbench No hay nada que escribir; la persona inicia sesión a través de su navegador
Leer registros de un sistema existente hacia el modelo de conocimiento Un conector de solo lectura Un conector no escribe nada de vuelta, por lo que no conlleva riesgo de escritura
Ejecutar código determinista propio según la programación de la plataforma Un plugin skills-only con una habilidad host_callback o plugin_queue Una habilidad del Skills Engine no puede ejecutar su código
Añadir una o dos pantallas dentro del shell Un plugin ui-only Solo los plugins añaden pantallas
Mantener sus propios registros detrás de sus propias rutas y permisos Un plugin full-service Solo este nivel posee un esquema
Ofrecer a un rol una vista más restringida de las pantallas de un sector Una lente sobre un paquete existente Una lente consta de datos, no de código
Llevar el modelo de conocimiento y las lentes de un sector, con pantallas de teléfono, a varias unidades Un paquete de dominio Un plugin por sí solo no tiene lentes ni control de licencia

En Corrán Orbital, la consulta de planificación de pases se quedó como una habilidad del Skills Engine. La propagación orbital que necesita se convirtió en un plugin skills-only con una habilidad host_callback, porque el cálculo numérico es nuestro y debe dar la misma respuesta dos veces. Nuestro comité de revisión de anomalías se convirtió en un plugin full-service, porque mantiene sus propios registros de quién examinó qué desviación de telemetría y qué decidió. El paquete llegó al final, cuando una segunda unidad quiso lo mismo.

Cómo se combinan las piezas

Los componentes se combinan hacia arriba. Un paquete de dominio es el ejemplo más claro, porque agrupa los demás junto con un control de licencia:

  • un modelo de conocimiento, los tipos de entidades que maneja el sector y cómo se relacionan, a menudo construido sobre un modelo base de otro paquete;
  • lentes, una por rol, cada una de las cuales restringe una lente base;
  • plantillas y flujos de trabajo, y las habilidades del Skills Engine que invocan;
  • plugins allí donde el paquete necesita código propio;
  • conectores de solo lectura hacia los sistemas que ya contienen los registros;
  • una capa móvil que indica qué tarjetas y pasos de captura aparecen en los teléfonos;
  • y la habilitación: los grupos de funciones que debe incluir la licencia antes de que nada de esto se active.
Dibuje una pila de bandas horizontales. En la parte inferior, «Funciones principales de Nexus» (asistente, archivos, memoria, trabajos) y, a su lado, «Despacho de UNO» y «AI Provider Router». Encima, una banda «Plugins» con dos recuadros, «skills-only» y «full-service», y una banda «Habilidades del Skills Engine». Sobre ellas, un recuadro ancho «Paquete de dominio» que contiene cuatro recuadros más pequeños: «Modelo de conocimiento», «Lentes», «Plantillas y flujos de trabajo» y «Capa móvil». A la izquierda del paquete, un recuadro «Conectores de solo lectura» con una flecha hacia «Modelo de conocimiento». En la parte superior, tres recuadros de unidades («Rotterdam», «Felixstowe», «Sede central») con flechas que bajan desde el paquete con la etiqueta «lente concedida por rol». Un candado en el borde del paquete lleva la etiqueta «licencia: domain_packs».
Cómo agrupa un paquete de dominio los demás componentes.

Nada de esto es infraestructura específica de cada aplicación. El paquete no incluye código de aislamiento propio, ni cliente de modelos, ni comprobación de licencia: hereda los de la plataforma. Ese es el tema del próximo capítulo, y es la razón por la que el autor de un paquete en un banco y otro en un puerto escriben la misma cantidad de código de seguridad, que es ninguna.

Paquetes de dominio
Paquetes de dominio
La página Paquetes de dominio enumera los diez paquetes con lo que necesita cada uno y dónde se ejecuta. Un paquete que no esté cubierto por la licencia permanece en la lista y atenuado, indicando lo que necesitaría.

Niveles de confianza

Todo plugin declara un nivel de trust en su manifiesto. La confianza no es una barrera que el SDK pueda sortear. Se trata de metadatos orientativos que la plataforma lee para decidir con qué grado de aislamiento se ejecutan las contribuciones de un plugin y cuáles son los datos más sensibles que pueden tocar sus habilidades. Los controles activos (clasificación y residencia, exportación y gasto) permanecen exactamente donde están.

Confianza Para quién es Postura de aislamiento Techo de clasificación
core Código propio incluido en la plataforma none: mismo origen, sin aislamiento adicional restricted
verified Un tercero revisado, un editor verificado Superficie same-origin, habilidades intermediadas restricted
community Un tercero no revisado; el valor predeterminado para un plugin nuevo Superficie sandboxed, habilidades intermediadas tenant
untrusted Cualquier elemento de un origen desconocido strict: superficie en entorno aislado (sandbox), solo habilidades intermediadas, sin confianza en el host public

De esa tabla se desprenden dos reglas, y create-nexus-plugin validate aplica ambas antes de que se compile nada.

En primer lugar, el classification de una habilidad no puede superar el techo de su plugin. Las clasificaciones se ordenan como public, luego tenant y después restricted. Un plugin community que declare una habilidad restricted fallará al compilarse.

En segundo lugar, solo los plugins core y verified pueden declarar habilidades que accedan al AI Provider Router. Esos son los niveles tool_using y llm_only. Un plugin community o untrusted intermedia trabajo determinista (host_callback, plugin_queue, y map sobre ellos) y pide a la plataforma que haga todo lo que requiera un modelo. Mi primer plugin era community, y perdí una tarde intentando declarar una habilidad de resumen llm_only antes de comprender que el rechazo era precisamente el objetivo.

Si omite trust, el SDK trata el plugin como community. Un campo omitido nunca puede suponer una elevación de nivel.

Niveles de aislamiento del 1 al 4

Con independencia de la confianza, el bloque runtime del manifiesto indica cómo se ejecuta el plugin. isolationLevel es un número entero del 1 al 4, y el modo de ejecución se deriva de él. No se eligen ambos de forma independiente: el validador deduce uno a partir del otro y rechaza cualquier manifiesto cuyo par no coincida.

isolationLevel executionMode Qué significa
1 external_https El plugin se ejecuta fuera de la instalación y se accede a él mediante HTTPS
2 mcp_container Un contenedor que expone herramientas MCP
3 hardened_docker Un contenedor reforzado en los propios pods del plugin; el valor predeterminado de la plantilla
4 firecracker Una microVM, la separación más estricta
"runtime": {
  "nodeVersion": "20",
  "executionMode": "hardened_docker",
  "isolationLevel": 3,
  "entrypoint": "dist/server.js",
  "healthCheck": "/health"
}

entrypoint es obligatorio. Los puntos de entrada son artefactos distribuidos y nunca se obtienen en tiempo de ejecución: el SDK no tiene ninguna ruta de importación dinámica ni de carga remota, por lo que la confianza se escribe y se comprueba una sola vez, luego se congela y nunca se descarga.

A qué se compromete en cada escalón

Mantener cualquier peldaño por encima de los ajustes tiene un coste. Esto es lo que le cuesta cada uno.

  • Una habilidad del Skills Engine necesita casos de prueba, un revisor que no sea usted y un historial de versiones por el que le preguntarán cuando falle. Los mismos bytes nunca se publican dos veces (CONTENT_HASH_ALREADY_PUBLISHED), así que «volver a subirla sin más» no es una solución.
  • Un plugin necesita un manifiesto cuya tabla de rutas coincida con las rutas que registra su código, en ambos sentidos. Una ruta que existe pero no está declarada supone un fallo de conformidad, al igual que una ruta declarada que el código nunca llega a registrar.
  • Un plugin full-service posee un esquema con cinco roles de base de datos, seguridad a nivel de fila forzada en cada tabla y un arranque que se niega a escuchar hasta que la base de datos demuestra que la barrera se mantiene. También reafirma las tres leyes de la plataforma en su manifiesto, palabra por palabra.
  • Un paquete de dominio está sujeto a licencia. Se activa unidad por unidad, a través de un piloto, y la licencia de la organización debe incluirlo. Usted no decide si un cliente dispone de él.
  • Una lente solo puede quitar elementos. Si un rol necesita ver más, debe cambiar la lente base, lo que implica hablar con el responsable de dicha base.

Ninguno de estos costes es negociable por aplicación; esa es la contrapartida. Se cede algo de libertad en el primer plugin y se recupera en todos los siguientes.

Instalar un plugin de terceros
Instalar un plugin de terceros
La instalación de un plugin de terceros funciona como los permisos de las aplicaciones. Cada alcance que declara su manifiesto se concede o se deniega por unidad, y cualquier llamada a algo que no haya declarado se rechaza con CONNECTION_SCOPE_EXCEEDED.

Herramientas y conexiones MCP

MCP aparece en tres lugares, y es fácil confundirlos.

Un plugin puede publicar herramientas MCP declarándolas en mcpTools[]: un name, una description y un inputSchema. La única regla que añade el validador es que un inputSchema no puede usar un oneOf, allOf o anyOf en el nivel superior, porque un combinador en la raíz del esquema hace que cualquier cliente MCP que importe la herramienta falle con un error 400. Un plugin con isolationLevel 2 se ejecuta como un mcp_container.

Se puede acceder a la biblioteca del Skills Engine mediante MCP. Claude Code y los agentes utilizan trece herramientas MCP para buscar y emparejar habilidades, ejecutarlas y registrar la ejecución, así como crearlas, importarlas o sincronizarlas; cada llamada se ejecuta en nombre de la persona que la inició, dentro de su lista permitida.

Y una herramienta de programación con IA se conecta a través del Workbench: una dirección por instalación, un inicio de sesión mediante el navegador de la persona, un pase de una hora en lugar de una clave almacenada y únicamente las herramientas que marque esa persona. El capítulo 2.26, Desarrollo con herramientas de programación con IA, lo explica paso a paso.

Los conectores son el vecino más discreto. El modelo de conocimiento de un paquete de dominio se alimenta mediante conectores de solo lectura hacia sistemas como el de administración de pólizas o el de siniestros, cada uno con una programación y un botón de prueba. No se escribe nada de vuelta en el origen.

Plugins y sincronización MCP
Plugins y sincronización MCP
Plugins y sincronización MCP muestra qué plugins aportan habilidades, qué sincronizaciones se rechazaron por completo y las trece herramientas MCP que utilizan Claude Code y los agentes para acceder a la biblioteca.

De su rama a las pantallas de los usuarios

Sea cual sea el peldaño en el que se encuentre, el camino a producción es el mismo. Cada versión pasa de su espacio de desarrollo a preproducción (staging), luego a una unidad piloto y después a todas las unidades, y cada paso tiene controles: pruebas, un manifiesto que no haya ampliado su alcance, una ejecución de prueba sobre una copia enmascarada y revisores designados que no sean el autor. Una promoción que intente saltarse un paso se rechaza con GATE_CANNOT_BE_SKIPPED. Cada entorno conserva la versión anterior durante 30 días, y revertir una unidad es un cambio revisado que lleva alrededor de un minuto.

El despliegue en sí se realiza únicamente a través de los canales de lanzamiento de la instalación. Las unidades eligen su canal y su administrador aprueba cada movimiento. En la página Canales e instalaciones verá recuentos y tasas de error por unidad, pero nunca lo que alguien haya hecho con su extensión. El capítulo 2.28, Publicación de su extensión, cubre todo el proceso de lanzamiento de principio a fin.

Una nota sobre las ediciones

La mayor parte de esta escalera existe en ambas ediciones. Community dispone de ajustes y habilidades del Skills Engine, plugins en todos los niveles y las mismas rutas recomendadas en un solo servidor con el código en su propio alojamiento Git. Enterprise añade la promoción desde el espacio de desarrollo a través de preproducción hasta una unidad piloto con sus controles, además de clústeres de editores y copias enmascaradas de datos reales. También añade su propio catálogo privado y paquetes de dominio. El capítulo 2.25, Desarrollo para cada edición, contiene los detalles.

El próximo capítulo es el que debe leer antes de escribir nada de código. Tiene pocas opciones y muchas reglas, y las reglas son las mismas para la primera extensión y para la milésima.