Plugins installieren & betreiben
Der Betreiber-Lebenszyklus: installieren, aktivieren, gewähren, konfigurieren, überwachen, widerrufen und entfernen.
Dies ist die Betreiberseite der Plattform. Die Plugin-Administration erfordert die Capability organization:manage — ausschließlich Workspace-Owner und -Admins.
Ein gebündeltes Plugin installieren (Tier 1)
Gebündelte Plugins werden zur Build-Zeit komponiert; die Installation ist deshalb eine Code-Änderung und keine Aktion im Dashboard.
Das Paket installieren
Fügen Sie es als direkte Root-Abhängigkeit (dependencies oder optionalDependencies) aus der npm-Registry hinzu. Die Codegen prüft die Identität des installierten Pakets, den Integritätseintrag in bun.lock und das Realpath-Containment. Aliase, git-/URL-/file-/Workspace-Quellen und externe Symlinks schlagen fail-closed fehl.
Es registrieren
bun packages/plugin-cli/src/index.ts add @vendor/owlat-plugin-example
Das bearbeitet die eingecheckte plugins.config.ts und gibt das Capability-Diff aus, das die Änderung einführt. Führen Sie es zunächst mit --dry-run aus, um das Diff und die vorgeschlagene Datei ohne Schreibvorgang zu prüfen.
Die Komposition neu generieren
bun run plugins:codegen
Committen Sie plugins.config.ts und die generierten Kompositionsdateien in derselben Änderung. Die CI führt bun run plugins:check aus, was fehlschlägt, wenn die generierte Ausgabe veraltet oder ungültig ist.
Neu bauen und deployen
Das Plugin existiert nun im Deployment. Sein Feature-Flag steht auf dem im Manifest deklarierten Standardwert — normalerweise false — und es ist keine Capability gewährt, es läuft also noch nichts.
Das Diff ist die Prüffläche für die Sicherheitsbetrachtung eines gebündelten Plugins: Es ist die vollständige Liste der Host-Operationen, die das Paket jemals anfordern kann. Gebündelter Code läuft mit demselben Vertrauen wie Ihr eigener deployter Code — lesen Sie das Diff, nicht nur die README.
Aktivieren und gewähren
Einstellungen → Plugins listet jedes registrierte Plugin mit seinem Zustand, seinen Capabilities und seinen erforderlichen Umgebungsvariablen auf.
Das Aktivieren eines gebündelten Plugins ist eine explizite Einwilligungshandlung:
- Im Deployment muss jeder
flag.requiredEnvVars-Wert vorhanden sein. Andernfalls schlägt die Aktivierung mit der Liste der fehlenden Variablen fehl. - Die Aktivierungsanfrage muss jede im Manifest deklarierte Capability freigeben — nicht mehr, nicht weniger, keine Duplikate. Eine teilweise oder unbekannte Freigabe wird abgelehnt.
- Das Deaktivieren des Plugins löscht seinen Grant-Datensatz vollständig.
So sieht „Grants können das Manifest nur einschränken“ in Tier 1 in der Praxis aus: Der Betreiber kann entweder dem vollständigen deklarierten Satz zustimmen oder das Plugin ausgeschaltet lassen. Connected Apps (Tier 2) sind das Tier, in dem pro App eine Teilmenge des Manifests gewährt wird.
Sowohl der Flag-Zustand als auch der Grant-Datensatz werden innerhalb der Transaktion jedes Aufrufers frisch gelesen — das Deaktivieren eines Plugins oder das Widerrufen einer Grant wirkt daher schon bei der nächsten Operation: kein Redeploy, kein Cache, den man abwarten müsste.
Konfigurieren
Deklariert das Plugin ein settingsSchema, rendert seine Detailseite ein generisches Formular: String-, Number-, Boolean- und Select-Felder mit den deklarierten Labels, Beschreibungen, Standardwerten und Grenzen. Der Host validiert die Eingaben serverseitig gegen das Schema.
Ein secret-Feld ist nicht Teil des Formulars. Owlat speichert keine Plugin-Credentials: Das Feld benennt eine Umgebungsvariable mit PLUGIN_-Präfix, die Sie im Deployment setzen, und die Seite zeigt nur den Namen dieser Variable und ob sie vorhanden ist. Ein Speichern, das einen Wert für einen Secret-Key mitführt, wird abgelehnt. „Auf Standardwerte zurücksetzen“ setzt gespeicherte Werte auf die Schema-Standardwerte zurück.
Wird ein Plugin aus dem Build entfernt, während Einstellungszeilen bestehen bleiben, bietet die Indexseite für diese verwaiste ID „Plugin-Einstellungen löschen“ an.
Die Tiers betreiben
Tier 2 — Connected Apps
Werden aus dem Dashboard registriert; kein Rebuild. Jede App ist an eine Plugin-ID gebunden, fordert eine Teilmenge der von diesem Plugin deklarierten Capabilities an und hält ein verschlüsseltes Shared Secret, mit dem Hooks signiert werden. Die Status sind enabled, disabled und revoked (terminal). Siehe Connected Apps.
Tier 3 — gesandboxte Jobs
Der Code-Worker behält das ruhende Plugin-Job-Polling-Protokoll, aber es wird weder ein Host-Enqueue-Adapter noch eine Betreiber-Job-UI ausgeliefert. Das Profil plugin-tasks ist deshalb heute keine nutzbare Plugin-Fläche:
COMPOSE_PROFILES=plugin-tasks docker compose up -d code-worker
Derselbe Container bedient unter dem Profil inbox-codetasks aktiv die Coding-Agent-Queue. Siehe Gesandboxte Jobs für den reservierten Tier-3-Vertrag.
Überwachen
| Fläche | Was sie zeigt |
|---|---|
| Audit-Log | Jede gehostete Plugin-Operation, attribuiert mit organizationId und pluginId, mit ausschließlich festen Operations- und Ergebniscodes |
| Hook-Zustellprotokolle | Auflösungen signierter Hooks je App und Art: versucht oder nicht, welche Seite gewonnen hat, der feste Fallback-Grund und die Netzwerkdauer. 30 Tage aufbewahrt |
| Webhook-Zustellprotokolle | Ausgehende Webhook-Zustellungen, einschließlich von Plugins veröffentlichter Events |
| Plugin-Task-Liste | Jüngste Tier-3-Jobs mit Status, Versuchen und Zeiten |
Keine dieser Flächen enthält Payloads, Prompts, generierten Text, Mail-Inhalte, Secrets oder Signaturen — die Schwärzung ist strukturell, sodass kein Lesepfad sie preisgeben kann.
Widerrufen und entfernen
| Ziel | Aktion | Wirkt |
|---|---|---|
| Ein gebündeltes Plugin stoppen und seine Autorität entziehen | Sein Feature-Flag deaktivieren — dies löscht auch seinen Grant-Datensatz | Bei der nächsten Operation |
| Eine Connected App sofort stoppen | Sie deaktivieren | Beim nächsten Hook-Aufruf oder API-Request |
| Eine Connected App dauerhaft stilllegen | Sie widerrufen (terminal) | Beim nächsten Hook-Aufruf oder API-Request |
| Einen plugin-gebundenen API-Key widerrufen | Den Key widerrufen oder das Plugin deaktivieren, an das er gebunden ist | Beim nächsten Request — der effektive Scope-Satz wird pro Request neu abgeleitet |
| Ein gebündeltes Plugin entfernen | owlat-plugins remove <package>, neu generieren, neu bauen, deployen | Nach dem Redeploy |
Das Entfernen des Pakets aus plugins.config.ts entfernt auch seine Convex-Komponentenregistrierung. Plugin-Storage-Zeilen und Einstellungen überdauern das Entfernen; nutzen Sie „Plugin-Einstellungen löschen“ im Plugin-Index, um die verwaisten Einstellungen zu bereinigen.
Verhält sich ein Plugin auffällig, deaktivieren Sie zuerst das Flag — das wirkt sofort und braucht kein Deployment. Untersuchen Sie erst danach und entfernen Sie das Paket im Anschluss. Beginnen Sie nicht mit einem Rebuild: Das ist der langsamste Hebel, den Sie haben.
Deployments ohne Plugins
Die Null-Plugin-Komposition ist ein gültiges No-op-Deployment. Eine plugins.config.ts mit leerem bundledPluginPackages-Array erzeugt eine Komposition ohne Plugins, und jede Registry fällt auf ihre eingebauten Mitglieder mit ursprünglicher Reihenfolge, ursprünglichen Standardwerten und ursprünglicher Fehlersemantik zurück.