Introducción al desarrollo de plugins¶
Bienvenido al Plugin Developer Handbook de Cortex HIVE. Aquí aprendes a extender la plataforma sin modificar el framework.
Regla cardinal¶
No toques el core del framework. El código en core/ y framework/ es la plataforma; cualquier funcionalidad de negocio nueva o modificada debe vivir en un plugin instalable.
WordPress, CakePHP y Adobe Commerce siguen la misma idea: el producto base se actualiza de forma independiente; tus extensiones se empaquetan aparte y se activan en runtime. Cortex HIVE aplica el mismo principio con paquetes Python descubiertos por entry points.
Qué es un plugin en Cortex¶
Un plugin es un paquete Python que:
- Declara un entry point
cortex.pluginsenpyproject.toml. - Exporta
create_plugin()con un descriptor (PluginDescriptor) y, como mínimo,api_router(). - Opcionalmente registra UI, MCP, WebSocket, eventos y configuración mediante hooks de bootstrap.
El framework no conoce tus plugins de antemano: los descubre en el catálogo instalado y carga solo los que el state store marca como activos en /control/plugins.
Mapa del handbook¶
| Sección | Página | Para qué |
|---|---|---|
| Fundamentos | ¿Qué es un plugin? | SPI, descriptor, hooks |
| Fundamentos | Anatomía de un plugin | Archivos, carpetas, responsabilidades |
| Fundamentos | Integración con el framework | Discovery, activación, paneles generativos |
| Tutorial | Primer plugin | Paso a paso desde el template |
| Fundamentos | Ciclo de vida | Bootstrap vs runtime, orden de hooks |
| Referencia | Recursos, API REST, … | Contratos CUS y HTTP |
| Operación | Activación, Repositorios | SaaS, submódulos, pip |
Frontera de documentación¶
| Capa | Qué documenta | Dónde |
|---|---|---|
| Plataforma (este handbook) | Mecanismos: hooks, activación, namespaces, contratos HTTP genéricos | docs/guias/plugins/ en cortex-docs |
| Plugin | Dominio, reglas de negocio, API detallada, eventos | docs/ dentro de cada repo cortex-plugin-* |
El handbook puede citar plugins como ejemplos (_template, helloworld, clients). No documenta reglas de negocio de accounting, booking, LangGraph ni similares — solo enlaza a la documentación del plugin.
Ver Documentación framework vs plugins.
Plugins de ejemplo en el monorepo¶
| Plugin | Rol en la documentación |
|---|---|
_template | Plantilla mínima; punto de partida del tutorial |
helloworld | Sandbox To-Do en panel samples — API interna |
clients, booking, … | Ejemplos reales citados en guías de referencia |
Siguiente paso¶
¿Qué es un plugin? — contrato SPI y diferencia con entry points legacy.