NeboAI
NeboAI
Aan de slag

plugin.json-referentie

plugin.json is het manifest dat Nebo leest om een plugin te installeren en uit te voeren. Sleutels zijn in camelCase. Deze pagina noemt elk veld dat Nebo vandaag leest en wat het doet.

Velden op het hoogste niveau

VeldTypeVerplichtBetekenis
idstringjaDe marktplaats-identificatie van de plugin. Gebruik de slug tijdens het ontwikkelen.
slugstringjaStabiele identificatie. [a-z0-9-], maximaal 64 tekens, geen koppelteken aan het begin of eind en geen dubbel koppelteken. Geeft de naam aan de tool plugin__<slug> en de variabele <SLUG>_BIN.
namestringjaWeergavenaam. Noem de dienst waarmee hij verbindt.
versionstringjaSemantische versie, zoals 0.1.0.
platformsmapjaPlatformsleutel naar binary. Zie Platforms.
descriptionstringneeEén zin voor mensen en medewerkers.
authorstringneeNaam van de uitgever.
categorystringneeHelpt medewerkers de plugin te vinden.
triggerslijst met stringsneeWoorden die beschrijven wanneer de plugin van toepassing is. Gebruikt in zoekhints.
entrySkillslijst met stringsneeMeegeleverde skills die als eerste in de toolbeschrijving van de plugin worden genoemd.
dependencieslijst met {name, version, optional}neeAndere plugins die deze plugin uitvoert. version is standaard "*"; optional standaard false. Hun <SLUG>_BIN-paden worden bij elke aanroep ingesteld.
authobjectneeAanmelding en accounts. Zie Authenticatie.
capabilitiesobjectneeconfigSchema, hooks, commands, routes, providers.
permissionsobjectneeFiltering van de omgeving en de maximale time-out.
eventslistneeWatchers die workflows van medewerkers voeden.
interfaceBindingsmapneeGetypeerde bewerkingen die de plugin levert.
channelobjectneeEen blijvende brug naar een berichtendienst.
setupobjectneeEen stapsgewijze installatiewizard.

Nebo valideert installaties vanuit de marktplaats: de slugregels, een semantische versie, minstens één platform, een binaryName zonder padscheidingstekens of .., een login-opdracht tenzij auth.type gelijk is aan env, niet-lege eventnamen en opdrachten, en bindingsjablonen die geparsed kunnen worden. Plugins in de map met gebruikersplugins slaan de validatie over.

Platforms

Sleutels zijn darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 en windows-amd64. Elke vermelding heeft alle vijf de velden hieronder. Bij het publiceren schrijft de marktplaats de echte hash, grootte, handtekening en download-URL in, dus laat ze leeg in het bestand dat je uploadt.

"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": "" }
}
VeldBetekenis
binaryNameDe bestandsnaam van het uitvoerbare bestand. Voeg .exe toe op Windows.
sha256Hash van de binary. Wordt bij installatie gecontroleerd.
signatureHandtekening van de binary. Wordt bij installatie gecontroleerd als er een ondertekeningssleutel beschikbaar is.
sizeGrootte in bytes.
downloadUrlWaar Nebo het pakket downloadt.

Authenticatie

VeldBetekenis
typeoauth_cli voor inloggen via de browser dat de plugin uitvoert; env voor inloggegevens die als waarden worden ingevoerd; neboai om de NeboAI-token van de eigenaar te ontvangen in elke auth.env-sleutel die eindigt op _TOKEN.
envKoppeling van variabelenaam naar standaardwaarde. Ook de enige namen van inloggegevens die Nebo aan login doorgeeft.
commands.loginLogt in. Verplicht tenzij type gelijk is aan env. Draait met de accountmap ingesteld.
commands.statusDrukt JSON af die aangeeft of het account is ingelogd.
commands.refreshVernieuwt een token zonder interactie.
commands.logoutLogt uit. Alleen de eigenaar kan dit uitvoeren.
profileDirEnvVariabele die een aparte map met inloggegevens krijgt voor elke medewerker en elk account. Zonder deze variabele heeft de plugin één gedeeld account.
label, descriptionTekst op de verbindingskaart.
help{url, urlLabel, text}, getoond tijdens het verbinden.
publicRedirectZet op true als de provider redirects naar http://localhost weigert; het inloggen loopt dan via de openbare redirect van NeboAI.

Nebo leest de eerste van authenticated, isAuthenticated, logged_in, loggedIn of token_valid in de statusuitvoer. Een niet-lege token_error, of de waarde none in credential_source, auth_method, storage of status, betekent uitgelogd. De statusopdracht heeft 45 seconden.

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

configSchema

capabilities.configSchema beschrijft de waarden die een eigenaar voor de plugin instelt. Elke waarde bereikt de binary als omgevingsvariabele met de naam uit key. Voor sleutels van inloggegevens die ook in auth.env staan, geeft het schema de velden van het verbindingsformulier per medewerker een label.

VeldTypeStandaardBetekenis
keystringverplichtNaam van de omgevingsvariabele.
labelstringverplichtVeldlabel.
descriptionstring""Helptekst.
fieldTypestring"string"Invoertype, zoals string, number, boolean, select of password.
defaultstringgeenVooraf ingevulde waarde.
requiredbooleanfalseDe plugin is pas gereed als de waarde is ingesteld.
secretbooleanfalseDe waarde wordt gemaskeerd bij het teruglezen.
optionslijst met stringsgeenKeuzes voor select.

permissions

VeldStandaardBetekenis
envAllow[]Overgenomen variabelen die de plugin mag zien. Leeg staat alles toe.
envDeny[]Overgenomen variabelen die altijd worden verwijderd.
maxTimeoutSeconds300Bovengrens voor de time-out van elke aanroep.
networkfalseGeeft netwerkgebruik aan. Informatief; wordt niet afgedwongen.

events

Een event is een langlopende watcher. Nebo start hem wanneer de workflow van een medewerker hem bewaakt, en start hem opnieuw als hij stopt. Elke regel die de watcher naar stdout schrijft, is één event. Tijdens het uitvoeren krijgt de eventnaam de slug als voorvoegsel, zodat note.created wordt tot notes-sync.note.created.

"events": [
  {
    "name": "note.created",
    "description": "A note was created in the watched notebook.",
    "command": "watch --notebook {{notebook}} --format ndjson"
  }
]
VeldBetekenis
nameEventnaam, zonder de slug. Verplicht.
commandArgumenten die de watcher starten. Verplicht. {{key}} wordt vervangen door de invoerwaarden van de medewerker.
descriptionWat het event veroorzaakt.
multiplexedBij true geeft één watcher meerdere eventtypen af en bevat elke regel een veld "event".

Workflows abonneren zich op events met een watch-trigger. Zie Triggers.

interfaceBindings

Een binding koppelt een interfacebewerking aan een van je opdrachten. Elke binding wordt een getypeerde tool voor medewerkers, genoemd naar de bewerking in kleine letters met punten en koppeltekens als underscores: notes.search wordt notes_search. Met bindings voldoet een plugin aan de capabilities die een medewerker vereist; zie Capabilities.

"interfaceBindings": {
  "notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
  "invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
}
PlaceholderWordt
{field}De waarde van het veld als één woord. Het veld wordt niet ook als flag doorgegeven.
{field[]:--flag}Eén --flag <item>-paar voor elk item in een lijstveld.
{field?:--flag}--flag <value> als het veld aanwezig is; niets als het ontbreekt.
{field:cents->dollars}Een geheel bedrag in centen, geschreven als dollars.

Invoervelden die een sjabloon niet noemt, worden toegevoegd als --field value. Lijst- en optionele placeholders moeten hele woorden zijn. Een bewerking waarvoor goedkeuring nodig is, kan niet worden bereikt door dezelfde opdracht via plugin__<slug> aan te roepen.

Hooks, slash-opdrachten en routes

"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

Een hook voert je opdracht uit op een bepaald moment in de beurt van een medewerker. Nebo schrijft een JSON-payload naar stdin. De uitvoer van een action-hook wordt genegeerd. Een filter-hook geeft {"payload": ..., "handled": false} terug; "handled": true stopt latere hooks. Bij fouten en time-outs blijft de vorige payload staan en wordt de beurt nooit geblokkeerd. Na drie fouten op rij wordt een hook vijf minuten gepauzeerd.

VeldStandaardBetekenis
hookverplichtEen van tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue.
hookType"action"action of filter.
commandverplichtArgumenten voor je binary.
priority100Lager draait eerst.
timeoutMs500Tijdslimiet in milliseconden.

commands

Met "slash": true voert het typen van /name args in de chat direct command args uit, zonder de medewerker. De uitvoer is het antwoord. De tijdslimiet is 30 seconden.

routes

Een route beantwoordt HTTP-verzoeken op /api/v1/plugins/<slug>/api/<path> op de bot, gematcht op path en method. De body van het verzoek gaat naar stdin en je stdout is het antwoord. De tijdslimiet is 30 seconden.

providers

Een provider voegt een bron voor chatmodellen toe. Declareer id, displayName, providerType, modelsCommand en chatCommand. Nebo stuurt een chatverzoek als JSON via stdin naar chatCommand en leest gestreamde events als JSON met één object per regel op stdout, tot 300 seconden lang. Vandaag wordt alleen chatstreaming gebruikt.

channel

Een channel overbrugt een berichtendienst. Nebo houdt command draaiende, leest inkomende berichten uit de stdout ervan en schrijft antwoorden naar de stdin, beide als JSON met één object per regel.

VeldStandaardBetekenis
commandverplichtArgumenten die de brug starten.
name, description""Getoond in de instellingen.
restartDelaySecs5Wachttijd voor een herstart na een crash.
sharedfalseEén brug voor alle medewerkers; berichten worden gerouteerd op naam van de medewerker en antwoorden dragen de identiteit van elke medewerker.
needsLocalApifalseGeef de brug het lokale API-adres van de bot, een token en het id van de medewerker. Uit, tenzij je het nodig hebt.

setup

Een installatiewizard leidt de eigenaar door stappen die met één formulier niet te doen zijn. Waarden uit form-stappen vullen {{key}} in latere generate-argumenten. Waarden uit credentials-stappen worden opgeslagen als omgevingsvariabelen van de plugin.

"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" }
  ]
}
Soort stapVelden
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Toont de uitvoer van de opdracht om te kopiëren.
externaltitle, description, url, urlLabel, instructions
credentialstitle, description, fields, verifyCommand. De stap is voltooid wanneer verifyCommand slaagt.

Velden hebben key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) en required.