Plugin-Entwicklung — Shell Sentinel

Überblick

Plugins helfen dabei, Workflows anzupassen, interne Leitfäden sichtbar zu machen und Integrationen nahtlos in der TUI bereitzustellen. Jedes Python-Modul im konfigurierten Verzeichnis plugins/ wird beim Start geladen – ohne Änderungen am Kernprodukt.

Lebenszyklus im Überblick

1. Lege ein Modul in plugins/ (Standardpfad) oder dem Pfad an, den SMART_AI_SYS_ADMIN_PLUGINS_DIR vorgibt.
2. Implementiere register(registry). Die TUI ruft die Funktion einmal kurz nach dem Start auf.
3. Registriere dort Slash-Commands, Übersetzungen, Autocomplete-Hinweise und Logging.
4. Starte die Anwendung neu, um das Plugin während der Entwicklung erneut zu laden.

Beispiel: erstes Kommando

Der folgende Ausschnitt zeigt die Minimalstruktur eines konversationellen Kommandos:

# 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"### Status für `{target}`\n"
        "- Ausstehende Jobs: 3\n"
        "- Letztes Backup: 2025-10-06\n"
        "- Bereitschaft: infra@contoso.com"
    )


def register(registry: PluginRegistry) -> None:
    registry.register_translations(
        "de",
        {"plugins": {"status_report": {"description": "Kurzer Systemstatus"}}},
    )
    registry.register_command(
        PluginSlashCommand(
            name="/status_report",
            aliases=("/statusbericht",),
            handler=_server_report,
            description_key="plugins.status_report.description",
        )
    )

Handler liefern Markdown, das im Konversations-Panel erscheint. Ausnahmen protokolliert der Logger smart_ai_sys_admin.plugins – halte Fehlermeldungen daher prägnant und ergänze wenn möglich Hinweise zur Behebung.

Lokalisierung & Nutzererlebnis

• Nutze register_translations(locale, payload), damit alle Sprachen abgedeckt sind; die App wählt automatisch das aktive Locale.
• Ergänze optional eine suggestion-Funktion, um den Inline-Autocomplete anzupassen.
• Verwende kompaktes Markdown und markiere irreversible Aktionen deutlich vor der Ausführung.

Tests & Beobachtbarkeit

• Schreibe Unit-Tests oder kleine Testskripte, um Handler ohne TUI zu validieren.
• Setze SMART_AI_SYS_ADMIN_LOG_LEVEL=DEBUG, um beim Entwickeln ausführlichere Logs zu erhalten.
• Bei Ladefehlern helfen logs/app.log sowie der Befehl /status, um registrierte Kommandos zu prüfen.

Paketierung & Verteilung

Verteile Plugins zusammen mit Deployments oder über ein internes Paket-Repository. Shell Sentinel lädt jede Erweiterung auf dem Plugin-Pfad, weshalb Dokumentation zu benötigten Credentials, Umgebungsvariablen und möglichen Rollbacks unerlässlich ist.