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
| Parameter | Type | Betekenis |
|---|---|---|
command | string, verplicht | De pluginopdracht en eventuele positionele woorden. |
args | object met strings | Benoemde argumenten. Elk wordt --key value. |
timeout | integer | Seconden om te wachten. Standaard 120, begrensd door permissions.maxTimeoutSeconds uit het manifest. |
display | string | De 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.
| Variabele | Waarde |
|---|---|
auth.env-sleutels | Standaardwaarden uit het manifest. |
<SLUG>_BIN | Pad 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_DIR | De eigen gegevensmap van de plugin, <data>/appdata/plugins/<slug>/. Dit is ook de werkmap, en hij blijft bewaard bij verwijdering. |
PATH | Eerst de pluginmappen, daarna het overgenomen pad. |
| Instellingen | Waarden die de eigenaar heeft opgeslagen voor configSchema-velden. |
NEBO_AGENT_ID | De medewerker die de aanroep doet. |
profileDirEnv | De 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 }
]
} auth.envnoemt de inloggegevens.capabilities.configSchemageeft ze een label en bepaalt hun volgorde in het verbindingsformulier.auth.profileDirEnvnoemt 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.- 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. - Je
status-opdracht print JSON zoals{"authenticated": true}. Als een token verloopt, voert Neborefreshuit 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
- Naslag voor plugin.json: elk veld, inclusief events, hooks en getypeerde bewerkingen.
- Een plugin uitbrengen: platforms, binaries, ondertekening en updates.
- Publiceren: de marktplaatsflow voor elk artefact.