NeboAI
NeboAI
Loslegen

plugin.json-Referenz

plugin.json ist das Manifest, das Nebo liest, um ein Plugin zu installieren und auszuführen. Schlüssel sind in camelCase. Diese Seite listet jedes Feld auf, das Nebo heute liest, und was es bewirkt.

Felder der obersten Ebene

FeldTypPflichtBedeutung
idstringjaDie Marktplatz-Kennung des Plugins. Verwende während der Entwicklung den Slug.
slugstringjaStabiler Bezeichner. [a-z0-9-], höchstens 64 Zeichen, kein Bindestrich am Anfang, am Ende oder doppelt. Benennt das Tool plugin__<slug> und die Variable <SLUG>_BIN.
namestringjaAnzeigename. Nenne den Dienst, mit dem es sich verbindet.
versionstringjaSemantische Version, etwa 0.1.0.
platformsmapjaPlattformschlüssel zur Binärdatei. Siehe Plattformen.
descriptionstringneinEin Satz für Menschen und Mitarbeiter.
authorstringneinName des Herausgebers.
categorystringneinHilft Mitarbeitern, das Plugin zu finden.
triggersListe von StringsneinBegriffe, die beschreiben, wann das Plugin passt. Werden für Suchhinweise verwendet.
entrySkillsListe von StringsneinMitgelieferte Skills, die in der Tool-Beschreibung des Plugins zuerst genannt werden.
dependenciesListe von {name, version, optional}neinAndere Plugins, die dieses ausführt. version ist standardmäßig "*", optional standardmäßig false. Ihre <SLUG>_BIN-Pfade werden bei jedem Aufruf gesetzt.
authobjectneinAnmeldung und Konten. Siehe Auth.
capabilitiesobjectneinconfigSchema, hooks, commands, routes, providers.
permissionsobjectneinFilterung der Umgebung und die Obergrenze für Timeouts.
eventslistneinWatcher, die Workflows von Mitarbeitern versorgen.
interfaceBindingsmapneinTypisierte Operationen, die das Plugin bereitstellt.
channelobjectneinEine dauerhafte Brücke zu einem Messaging-Dienst.
setupobjectneinEin Einrichtungsassistent Schritt für Schritt.

Nebo prüft Installationen aus dem Marktplatz: die Slug-Regeln, eine semantische Version, mindestens eine Plattform, einen binaryName ohne Pfadtrenner oder .., einen login-Befehl, sofern auth.type nicht env ist, nicht leere Event-Namen und Befehle sowie Binding-Vorlagen, die sich parsen lassen. Plugins im Benutzer-Plugin-Verzeichnis überspringen die Prüfung.

Plattformen

Die Schlüssel sind darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 und windows-amd64. Jeder Eintrag hat alle fünf unten aufgeführten Felder. Beim Veröffentlichen trägt der Marktplatz den echten Hash, die Größe, die Signatur und die Download-URL ein, also lass sie in der hochgeladenen Datei leer.

"platforms": {
  "darwin-arm64":  { "binaryName": "notes-sync",     "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
  "linux-amd64":   { "binaryName": "notes-sync",     "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
  "windows-amd64": { "binaryName": "notes-sync.exe", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" }
}
FeldBedeutung
binaryNameDer Dateiname der ausführbaren Datei. Unter Windows .exe anhängen.
sha256Hash der Binärdatei. Wird bei der Installation geprüft.
signatureSignatur der Binärdatei. Wird bei der Installation geprüft, wenn ein Signaturschlüssel verfügbar ist.
sizeGröße in Bytes.
downloadUrlWo Nebo das Paket herunterlädt.

Auth

FeldBedeutung
typeoauth_cli für eine vom Plugin gesteuerte Browser-Anmeldung; env für Zugangsdaten, die als Werte eingegeben werden; neboai, um das NeboAI-Token des Inhabers in jedem auth.env-Schlüssel zu erhalten, der auf _TOKEN endet.
envZuordnung von Variablennamen zu Standardwerten. Zugleich die einzigen Namen von Zugangsdaten, die Nebo an login übergibt.
commands.loginMeldet an. Pflicht, sofern type nicht env ist. Läuft mit gesetztem Kontoordner.
commands.statusGibt JSON aus, das angibt, ob das Konto angemeldet ist.
commands.refreshErneuert ein Token ohne Interaktion.
commands.logoutMeldet ab. Nur der Inhaber kann es ausführen.
profileDirEnvVariable, die für jeden Mitarbeiter und jedes Konto einen eigenen Ordner für Zugangsdaten erhält. Ohne sie hat das Plugin ein gemeinsames Konto.
label, descriptionText auf der Verbindungskarte.
help{url, urlLabel, text}, angezeigt während der Verbindung.
publicRedirectAuf true setzen, wenn der Anbieter Weiterleitungen an http://localhost ablehnt; die Anmeldung läuft dann über die öffentliche Weiterleitung von NeboAI.

Nebo liest in der Statusausgabe den ersten vorhandenen Wert von authenticated, isAuthenticated, logged_in, loggedIn oder token_valid. Ein nicht leeres token_error oder der Wert none in credential_source, auth_method, storage oder status bedeutet abgemeldet. Der Statusbefehl hat 45 Sekunden Zeit.

{"authenticated": true, "account": "finance@example.com"}

configSchema

capabilities.configSchema beschreibt die Werte, die ein Inhaber für das Plugin festlegt. Jeder Wert erreicht die Binärdatei als Umgebungsvariable mit dem Namen aus key. Für Zugangsdaten-Schlüssel, die auch in auth.env aufgeführt sind, beschriftet das Schema die Felder des Verbindungsformulars pro Mitarbeiter.

FeldTypStandardBedeutung
keystringerforderlichName der Umgebungsvariablen.
labelstringerforderlichFeldbeschriftung.
descriptionstring""Hilfetext.
fieldTypestring"string"Eingabetyp, etwa string, number, boolean, select oder password.
defaultstringkeinerVorausgefüllter Wert.
requiredbooleanfalseDas Plugin ist erst bereit, wenn der Wert gesetzt ist.
secretbooleanfalseDer Wert wird beim Auslesen maskiert.
optionsListe von StringskeinerAuswahlmöglichkeiten für select.

permissions

FeldStandardBedeutung
envAllow[]Geerbte Variablen, die das Plugin sehen darf. Leer erlaubt alle.
envDeny[]Geerbte Variablen, die immer entfernt werden.
maxTimeoutSeconds300Obergrenze für das Timeout jedes Aufrufs.
networkfalseGibt die Netzwerknutzung an. Nur informativ; wird nicht erzwungen.

events

Ein Event ist ein lang laufender Watcher. Nebo startet ihn, wenn ein Workflow eines Mitarbeiters ihn beobachtet, und startet ihn neu, wenn er sich beendet. Jede Zeile, die der Watcher nach stdout schreibt, ist ein Event. Zur Laufzeit wird dem Event-Namen der Slug vorangestellt, sodass aus note.created notes-sync.note.created wird.

"events": [
  {
    "name": "note.created",
    "description": "A note was created in the watched notebook.",
    "command": "watch --notebook {{notebook}} --format ndjson"
  }
]
FeldBedeutung
nameEvent-Name ohne den Slug. Pflicht.
commandArgumente, die den Watcher starten. Pflicht. {{key}} wird durch die Eingabewerte des Mitarbeiters ersetzt.
descriptionWas das Event auslöst.
multiplexedBei true gibt ein Watcher mehrere Event-Typen aus und jede Zeile enthält ein Feld "event".

Workflows abonnieren Events mit einem watch-Trigger. Siehe Trigger.

interfaceBindings

Ein Binding ordnet eine Interface-Operation einem deiner Befehle zu. Jedes Binding wird für Mitarbeiter zu einem typisierten Tool, benannt nach der Operation in Kleinbuchstaben, mit Unterstrichen statt Punkten und Bindestrichen: Aus notes.search wird notes_search. Über Bindings erfüllt ein Plugin die Fähigkeiten, die ein Mitarbeiter benötigt; siehe Fähigkeiten.

"interfaceBindings": {
  "notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
  "invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
}
PlatzhalterWird zu
{field}Der Wert des Felds als ein Wort. Das Feld wird nicht zusätzlich als Flag übergeben.
{field[]:--flag}Ein Paar --flag <item> für jedes Element eines Listenfelds.
{field?:--flag}--flag <value>, wenn das Feld vorhanden ist; nichts, wenn es fehlt.
{field:cents->dollars}Ein ganzzahliger Betrag in Cent, als Dollar geschrieben.

Eingabefelder, die eine Vorlage nicht nennt, werden als --field value angehängt. Listen- und optionale Platzhalter müssen ganze Wörter sein. Eine Operation, die eine Freigabe erfordert, lässt sich nicht erreichen, indem man denselben Befehl über plugin__<slug> aufruft.

Hooks, Slash-Befehle und Routen

"capabilities": {
  "hooks": [
    { "hook": "tool.post_execute", "hookType": "filter", "command": "hook redact", "priority": 50, "timeoutMs": 500 }
  ],
  "commands": [
    { "name": "notes", "description": "Show today's notes", "command": "notes today", "slash": true }
  ],
  "routes": [
    { "path": "/callback", "method": "GET", "command": "http callback" }
  ]
}

hooks

Ein Hook führt deinen Befehl an einem bestimmten Punkt in einem Durchgang eines Mitarbeiters aus. Nebo schreibt eine JSON-Payload nach stdin. Die Ausgabe eines action-Hooks wird ignoriert. Ein filter-Hook gibt {"payload": ..., "handled": false} zurück; "handled": true stoppt spätere Hooks. Fehler und Timeouts behalten die vorherige Payload bei und blockieren den Durchgang nie. Nach drei Fehlschlägen in Folge wird ein Hook für fünf Minuten pausiert.

FeldStandardBedeutung
hookerforderlichEines von tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue.
hookType"action"action oder filter.
commanderforderlichArgumente für deine Binärdatei.
priority100Niedrigere Werte laufen zuerst.
timeoutMs500Zeitlimit in Millisekunden.

commands

Mit "slash": true führt die Eingabe von /name args im Chat direkt command args aus, ohne den Mitarbeiter. Die Ausgabe ist die Antwort. Das Zeitlimit beträgt 30 Sekunden.

routes

Eine Route beantwortet HTTP-Anfragen unter /api/v1/plugins/<slug>/api/<path> auf dem Bot, zugeordnet über path und method. Der Anfragetext geht an stdin, und deine stdout-Ausgabe ist die Antwort. Das Zeitlimit beträgt 30 Sekunden.

providers

Ein Provider fügt eine Quelle für Chatmodelle hinzu. Deklariere id, displayName, providerType, modelsCommand und chatCommand. Nebo sendet eine Chat-Anfrage als JSON über stdin an chatCommand und liest gestreamte Events als zeilenweise getrenntes JSON von stdout, bis zu 300 Sekunden lang. Derzeit wird nur Chat-Streaming genutzt.

channel

Ein Kanal verbindet einen Messaging-Dienst. Nebo hält command am Laufen, liest eingehende Nachrichten von dessen stdout und schreibt Antworten auf dessen stdin, beides als zeilenweise getrenntes JSON.

FeldStandardBedeutung
commanderforderlichArgumente, die die Brücke starten.
name, description""Wird in den Einstellungen angezeigt.
restartDelaySecs5Wartezeit vor dem Neustart nach einem Absturz.
sharedfalseEine Brücke für alle Mitarbeiter; Nachrichten werden nach Mitarbeitername zugestellt, und Antworten tragen die Identität des jeweiligen Mitarbeiters.
needsLocalApifalseGib der Brücke die lokale API-Adresse des Bots, ein Token und die Mitarbeiter-ID. Aus, sofern du es nicht brauchst.

setup

Ein Einrichtungsassistent führt den Inhaber durch Schritte, die ein einzelnes Formular nicht abdecken kann. Werte aus form-Schritten füllen {{key}} in späteren generate-Argumenten. Werte aus credentials-Schritten werden als Umgebungsvariablen des Plugins gespeichert.

"setup": {
  "title": "Connect Example Chat",
  "steps": [
    { "kind": "form", "title": "Bot name", "fields": [ { "key": "bot_name", "label": "Name", "required": true } ] },
    { "kind": "generate", "title": "App manifest", "command": "manifest", "args": ["--name", "{{bot_name}}"], "outputFormat": "yaml" },
    { "kind": "external", "title": "Create the app", "url": "https://example.com/apps", "urlLabel": "Open admin" },
    { "kind": "credentials", "title": "Paste the token", "fields": [ { "key": "EXAMPLE_CHAT_TOKEN", "label": "Token", "inputType": "password", "required": true } ], "verifyCommand": "auth status" }
  ]
}
Art des SchrittsFelder
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Zeigt die Ausgabe des Befehls zum Kopieren an.
externaltitle, description, url, urlLabel, instructions
credentialstitle, description, fields, verifyCommand. Der Schritt ist abgeschlossen, wenn verifyCommand erfolgreich ist.

Felder haben key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) und required.