NeboAI
NeboAI
Loslegen

Plugins

Ein Plugin gibt Mitarbeitern etwas, womit sie arbeiten können: einen Onlinedienst, ein Geschäftssystem oder ein Programm auf dem Computer. Du baust es als Kommandozeilen-Binärdatei und beschreibst es mit einem plugin.json-Manifest. Mitarbeiter rufen seine Befehle auf, und Nebo kümmert sich um Installation, Konten pro Mitarbeiter und Updates.

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
ParameterTypBedeutung
commandString, erforderlichDer Plugin-Befehl und etwaige Positionswörter.
argsObjekt aus StringsBenannte Argumente. Jedes wird zu --key value.
timeoutintegerWartezeit in Sekunden. Standard 120, begrenzt durch permissions.maxTimeoutSeconds im Manifest.
displaystringDer 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.

VariableWert
auth.env-SchlüsselStandardwerte aus dem Manifest.
<SLUG>_BINPfad 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_DIRDer eigene Datenordner des Plugins, <data>/appdata/plugins/<slug>/. Er ist zugleich das Arbeitsverzeichnis und übersteht eine Deinstallation.
PATHZuerst die Plugin-Ordner, dann der geerbte Pfad.
EinstellungenWerte, die der Inhaber für configSchema-Felder gespeichert hat.
NEBO_AGENT_IDDer Mitarbeiter, der den Aufruf macht.
profileDirEnvDer 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 }
  ]
}
  1. auth.env benennt die Zugangsdaten. capabilities.configSchema beschriftet sie und legt ihre Reihenfolge im Verbindungsformular fest.
  2. auth.profileDirEnv benennt 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.
  3. 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.
  4. Dein status-Befehl gibt JSON wie {"authenticated": true} aus. Läuft ein Token ab, führt Nebo refresh aus, 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