So funktionieren Plugins
Ein Plugin ist eine ausführbare Datei plus ein Manifest. Nebo hält zwischen Aufrufen keinen Plugin-Prozess am Laufen. Jedes Mal, wenn ein Mitarbeiter das Plugin nutzt, startet Nebo die Binärdatei mit einem Befehl und Argumenten, wartet, bis sie sich beendet, und gibt die Ausgabe an den Mitarbeiter zurück.
- Befehle sind Argumente. Der Mitarbeiter wählt einen Befehl, etwa
notes search, und benannte Argumente. Nebo übergibt jedes Argument als--name value. Es gibt keine Shell, Pipes und Umleitungen greifen also nie. - Ausgabe ist stdout. Schreibe Ergebnisse nach stdout. JSON eignet sich gut.
- Die Standardeingabe ist geschlossen bei gewöhnlichen Aufrufen. Hooks, Routen und Chat-Provider nutzen stdin; siehe die plugin.json-Referenz.
Jedes installierte und aktivierte Plugin erscheint Mitarbeitern als ein Tool namens plugin__<slug>. Ein Mitarbeiter ruft es so auf:
{
"command": "notes search",
"args": { "query": "quarterly plan", "limit": "5" },
"display": "Search notes for the quarterly plan"
} Nebo führt aus:
notes-sync notes search --query "quarterly plan" --limit 5
| Parameter | Typ | Bedeutung |
|---|---|---|
command | String, erforderlich | Der Plugin-Befehl und etwaige Positionswörter. |
args | Objekt aus Strings | Benannte Argumente. Jedes wird zu --key value. |
timeout | integer | Wartezeit in Sekunden. Standard 120, begrenzt durch permissions.maxTimeoutSeconds im Manifest. |
display | string | Der Satz, den der Inhaber sieht, wenn der Aufruf eine Freigabe braucht. |
Dein erstes Plugin bauen
Schreibe in einer beliebigen Sprache eine Binärdatei, die ihren Befehl aus den Argumenten liest und ein Ergebnis ausgibt. Lege sie dann neben eine plugin.json in das Benutzer-Plugin-Verzeichnis eines Bots.
<data>/user/plugins/notes-sync/
├── plugin.json # runtime manifest
├── notes-sync # your binary, named after the slug
└── skills/ # optional: skills that teach employees to use it
└── notes-sync/
└── SKILL.md {
"id": "notes-sync",
"slug": "notes-sync",
"name": "Notes Sync",
"version": "0.1.0",
"description": "Search, read and create notes in Example Notes.",
"platforms": {}
} id, slug, name, version und platforms sind Pflicht. Im Benutzer-Plugin-Verzeichnis darf die Zuordnung platforms leer sein: Nebo sucht eine nach dem Slug benannte Binärdatei neben plugin.json, dann in target/release/ und target/debug/. Beim Veröffentlichen füllt der Marktplatz platforms für jede hochgeladene Binärdatei aus.
<data> ist ~/Library/Application Support/Nebo unter macOS, %APPDATA%\Nebo unter Windows und ~/.local/share/nebo unter Linux oder der Wert von NEBO_HOME. Ein Plugin im Benutzerverzeichnis überschreibt ein Marktplatz-Plugin mit demselben Slug, deshalb ist es der richtige Ort, um einen neuen Build zu testen.
Mitarbeitern den Umgang beibringen
Lege einen Ordner skills/ neben plugin.json. Jeder Skill darin steht jedem Mitarbeiter zur Verfügung, solange das Plugin installiert ist, und führt das Plugin automatisch als Abhängigkeit. Beschreibe im Skill, welche Befehle es gibt, was sie zurückgeben und wann man welchen nutzt. Nenne die nützlichsten Skills in entrySkills, damit die Tool-Beschreibung des Plugins zuerst auf sie verweist.
Der Marktplatz-Eintrag ist eine eigene Datei, PLUGIN.md. Nebo liest sie zur Laufzeit nicht; sie ist die Seite, die Menschen vor der Installation sehen. Siehe Ein Plugin ausliefern.
Umgebung
Jeder Aufruf erbt die Umgebung des Bots ohne Loader- und Shell-Injection-Variablen und fügt dann diese Werte hinzu. Spätere Einträge haben Vorrang.
| Variable | Wert |
|---|---|
auth.env-Schlüssel | Standardwerte aus dem Manifest. |
<SLUG>_BIN | Pfad der Binärdatei dieses Plugins und jedes Plugins, von dem es abhängt. Der Slug wird in Großbuchstaben geschrieben, mit Unterstrichen statt Bindestrichen. |
NEBO_DATA_DIR | Der eigene Datenordner des Plugins, <data>/appdata/plugins/<slug>/. Er ist zugleich das Arbeitsverzeichnis und übersteht eine Deinstallation. |
PATH | Zuerst die Plugin-Ordner, dann der geerbte Pfad. |
| Einstellungen | Werte, die der Inhaber für configSchema-Felder gespeichert hat. |
NEBO_AGENT_ID | Der Mitarbeiter, der den Aufruf macht. |
profileDirEnv | Der Kontoordner für diesen Mitarbeiter und dieses Konto, wenn das Plugin Konten unterstützt. |
permissions.envAllow und permissions.envDeny schränken ein, was das Plugin vom Bot erbt. Die eigenen Auth-Variablen des Plugins entfernen sie nie.
Konten und Zugangsdaten
Ein Plugin, das sich bei einem Dienst anmeldet, sollte ein Konto pro Mitarbeiter führen. Die Buchhaltung meldet sich mit dem Finanz-Login an, die Assistenz mit ihrem eigenen, und keiner sieht die Tokens des anderen. Du legst das im Manifest fest; Nebo erledigt den Rest.
"auth": {
"type": "env",
"label": "Example Notes account",
"env": { "EXAMPLE_NOTES_TOKEN": "" },
"commands": { "login": "auth login", "status": "auth status", "logout": "auth logout" },
"profileDirEnv": "EXAMPLE_NOTES_CONFIG_DIR"
},
"capabilities": {
"configSchema": [
{ "key": "EXAMPLE_NOTES_TOKEN", "label": "API token", "fieldType": "password", "secret": true, "required": true }
]
} auth.envbenennt die Zugangsdaten.capabilities.configSchemabeschriftet sie und legt ihre Reihenfolge im Verbindungsformular fest.auth.profileDirEnvbenennt die Variable, aus der dein Plugin seinen Ordner für Zugangsdaten liest. Nebo legt für jeden Mitarbeiter und jedes Konto einen Ordner an und setzt diese Variable bei jedem Aufruf.- Wenn der Inhaber ein Konto verbindet, führt Nebo deinen
login-Befehl mit den Werten aus, die der Inhaber eingegeben hat, und setzt dabei den Kontoordner. Dein Plugin speichert in diesem Ordner, was es braucht. Nebo behält die Werte nicht. - Dein
status-Befehl gibt JSON wie{"authenticated": true}aus. Läuft ein Token ab, führt Neborefreshaus, sofern du es deklarierst.
Für eine Browser-Anmeldung setze type auf oauth_cli und lass login die Anmelde-URL des Anbieters ausgeben oder öffnen. Mitarbeiter melden sich nie selbst an: Wenn ein Aufruf eine Anmeldung braucht, sieht der Inhaber eine Verbindungskarte. Ein Mitarbeiter mit mehreren Konten wählt eines, indem er einem Befehl --account <label> hinzufügt. Nebo entfernt dieses Flag, bevor deine Binärdatei es sieht.
Nenne den Dienst, nicht die Form. Der Name eines Plugins sagt, womit es sich verbindet, etwa „Example Notes“. Schreib nie „CLI“ in einen Plugin-Namen; für Mitarbeiter und Inhaber ist es eine Verbindung, keine Kommandozeile.
Weiter
- plugin.json-Referenz: jedes Feld, einschließlich Events, Hooks und typisierter Operationen.
- Ein Plugin ausliefern: Plattformen, Binärdateien, Signierung und Updates.
- Veröffentlichen: der Marktplatz-Ablauf für jedes Artefakt.