Desarrollo de plugins — Shell Sentinel

Visión general

Los plugins permiten moldear los flujos de trabajo, exponer guías internas y añadir integraciones que se sienten nativas dentro de la TUI. Cada módulo Python colocado en el directorio configurado plugins/ se carga en el arranque, así que puedes iterar sin modificar la distribución principal.

Ciclo de vida resumido

1. Crea un módulo en plugins/ (ruta por defecto) o en la carpeta apuntada por SMART_AI_SYS_ADMIN_PLUGINS_DIR.
2. Expón register(registry). La TUI la invoca una vez tras iniciar la interfaz.
3. Desde ese punto registra comandos slash, traducciones, sugerencias de autocompletado y logging.
4. Reinicia la aplicación para recargar el plugin mientras iteras en local.

Plantilla de comando inicial

El siguiente ejemplo ilustra la estructura mínima de un comando conversacional:

# plugins/status_report.py
from smart_ai_sys_admin.plugins import PluginRegistry, PluginSlashCommand


def _server_report(args: list[str]) -> str:
    target = args[0] if args else "default"
    return (
        f"### Estado de `{target}`\n"
        "- Tareas pendientes: 3\n"
        "- Último backup: 2025-10-06\n"
        "- Contacto de guardia: infra@contoso.com"
    )


def register(registry: PluginRegistry) -> None:
    registry.register_translations(
        "es",
        {"plugins": {"status_report": {"description": "Resumen rápido de estado"}}},
    )
    registry.register_command(
        PluginSlashCommand(
            name="/status_report",
            aliases=("/estadoreporte",),
            handler=_server_report,
            description_key="plugins.status_report.description",
        )
    )

Los handlers devuelven Markdown que se renderiza en el panel de conversación. Cualquier excepción queda registrada mediante el logger smart_ai_sys_admin.plugins, así que procura incluir mensajes accionables y pasos de recuperación cuando sea posible.

Localización y experiencia

• Invoca register_translations(locale, payload) para cada idioma; la aplicación selecciona la versión correcta según el locale activo.
• Define un callback suggestion si quieres personalizar el autocompletado que aparece bajo el campo de entrada.
• Opta por Markdown conciso y resalta acciones destructivas o irreversibles antes de ejecutarlas.

Pruebas y observabilidad

• Crea pruebas unitarias o scripts ligeros para validar los handlers sin lanzar la TUI.
• Activa logging detallado con SMART_AI_SYS_ADMIN_LOG_LEVEL=DEBUG mientras iteras.
• Si un plugin falla al cargar, revisa logs/app.log y ejecuta /status para confirmar el registro del comando.

Empaquetado y distribución

Empaqueta los plugins junto a los artefactos de despliegue o publícalos en un índice interno. Shell Sentinel carga cualquier módulo disponible en la ruta de plugins, así que documenta requisitos (claves API, variables de entorno, endpoints) y define pasos de rollback para que el equipo de operaciones pueda desactivar la extensión rápidamente.