NeboAI
NeboAI
Aan de slag

Plugins

Een plugin geeft medewerkers iets om mee te werken: een onlinedienst, een bedrijfssysteem of een programma op de computer. Je bouwt hem als binary voor de opdrachtregel en beschrijft hem met een plugin.json-manifest. Medewerkers roepen de opdrachten ervan aan, en Nebo regelt de installatie, accounts per medewerker en updates.

Zo werken plugins

Een plugin is een uitvoerbaar bestand plus een manifest. Nebo houdt tussen aanroepen geen pluginproces draaiende. Telkens wanneer een medewerker de plugin gebruikt, start Nebo de binary met een opdracht en argumenten, wacht tot hij stopt en geeft de uitvoer terug aan de medewerker.

  • Opdrachten zijn argumenten. De medewerker kiest een opdracht, zoals notes search, en benoemde argumenten. Nebo geeft elk argument door als --name value. Er is geen shell, dus pipes en omleidingen werken nooit.
  • Uitvoer is stdout. Schrijf resultaten naar stdout. JSON werkt goed.
  • Standaardinvoer is gesloten bij gewone aanroepen. Hooks, routes en chatproviders gebruiken stdin; zie de naslag voor plugin.json.

Elke geïnstalleerde en ingeschakelde plugin verschijnt voor medewerkers als één tool met de naam plugin__<slug>. Een medewerker roept hem zo aan:

{
  "command": "notes search",
  "args": { "query": "quarterly plan", "limit": "5" },
  "display": "Search notes for the quarterly plan"
}

Nebo voert uit:

notes-sync notes search --query "quarterly plan" --limit 5
ParameterTypeBetekenis
commandstring, verplichtDe pluginopdracht en eventuele positionele woorden.
argsobject met stringsBenoemde argumenten. Elk wordt --key value.
timeoutintegerSeconden om te wachten. Standaard 120, begrensd door permissions.maxTimeoutSeconds uit het manifest.
displaystringDe zin die de eigenaar ziet als de aanroep goedkeuring nodig heeft.

Bouw je eerste plugin

Schrijf in een willekeurige taal een binary die zijn opdracht uit de argumenten leest en een resultaat afdrukt. Zet hem daarna naast een plugin.json in de map met gebruikersplugins van een bot.

<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 en platforms zijn verplicht. In de map met gebruikersplugins mag de platforms-map leeg zijn: Nebo zoekt een binary met de naam van de slug naast plugin.json, en daarna in target/release/ en target/debug/. Bij het publiceren vult de marktplaats platforms in voor elke binary die je uploadt.

<data> is ~/Library/Application Support/Nebo op macOS, %APPDATA%\Nebo op Windows en ~/.local/share/nebo op Linux, of de waarde van NEBO_HOME. Een plugin in de gebruikersmap gaat voor op een marktplaatsplugin met dezelfde slug, waardoor dat de plek is om een nieuwe build te testen.

Leer medewerkers hem gebruiken

Zet een map skills/ naast plugin.json. Elke skill daarin is beschikbaar voor elke medewerker zolang de plugin is geïnstalleerd, en noemt de plugin automatisch als afhankelijkheid. Gebruik de skill om te vertellen welke opdrachten er zijn, wat ze teruggeven en wanneer je welke gebruikt. Noem de nuttigste skills in entrySkills, zodat de toolbeschrijving van de plugin er als eerste naar verwijst.

De marktplaatsvermelding is een apart bestand, PLUGIN.md. Nebo leest het niet tijdens het uitvoeren; het is de pagina die mensen zien voordat ze installeren. Zie Een plugin uitbrengen.

Omgeving

Elke aanroep neemt de omgeving van de bot over, zonder loader- en shell-injectievariabelen, en voegt daarna deze waarden toe. Latere vermeldingen winnen.

VariabeleWaarde
auth.env-sleutelsStandaardwaarden uit het manifest.
<SLUG>_BINPad van de binary van deze plugin en van elke plugin waarvan hij afhankelijk is. De slug wordt in hoofdletters gezet, met koppeltekens als underscores.
NEBO_DATA_DIRDe eigen gegevensmap van de plugin, <data>/appdata/plugins/<slug>/. Dit is ook de werkmap, en hij blijft bewaard bij verwijdering.
PATHEerst de pluginmappen, daarna het overgenomen pad.
InstellingenWaarden die de eigenaar heeft opgeslagen voor configSchema-velden.
NEBO_AGENT_IDDe medewerker die de aanroep doet.
profileDirEnvDe accountmap voor deze medewerker en dit account, als de plugin accounts ondersteunt.

permissions.envAllow en permissions.envDeny beperken wat de plugin van de bot overneemt. Ze verwijderen nooit de eigen authenticatievariabelen van de plugin.

Accounts en inloggegevens

Een plugin die inlogt bij een dienst, hoort één account per medewerker te hebben. De boekhouder logt in met de financiële login en de assistent met een eigen login, en geen van beiden ziet de tokens van de ander. Je legt dit vast in het manifest; Nebo doet de 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 noemt de inloggegevens. capabilities.configSchema geeft ze een label en bepaalt hun volgorde in het verbindingsformulier.
  2. auth.profileDirEnv noemt de variabele die je plugin leest voor zijn map met inloggegevens. Nebo maakt één map aan voor elke medewerker en elk account en stelt die variabele bij elke aanroep in.
  3. Wanneer de eigenaar een account verbindt, voert Nebo je login-opdracht uit met de waarden die de eigenaar heeft getypt en met de accountmap ingesteld. Je plugin bewaart wat hij nodig heeft in die map. Nebo bewaart de waarden niet.
  4. Je status-opdracht print JSON zoals {"authenticated": true}. Als een token verloopt, voert Nebo refresh uit als je die hebt gedeclareerd.

Voor inloggen via de browser zet je type op oauth_cli en laat je login de inlog-URL van de provider afdrukken of openen. Medewerkers loggen nooit zelf in: wanneer een aanroep een login nodig heeft, ziet de eigenaar een verbindingskaart. Een medewerker met meerdere accounts kiest er een door --account <label> aan een opdracht toe te voegen. Nebo verwijdert die flag voordat je binary hem ziet.

Noem de dienst, niet de vorm. De naam van een plugin zegt waarmee hij verbindt, zoals "Example Notes". Zet nooit "CLI" in de naam van een plugin; voor medewerkers en eigenaren is het een verbinding, geen opdrachtregel.

Volgende