Come funzionano i plugin
Un plugin è un eseguibile più un manifest. Nebo non tiene in esecuzione alcun processo del plugin tra una chiamata e l'altra. Ogni volta che un dipendente usa il plugin, Nebo avvia il binario con un comando e degli argomenti, attende che termini e restituisce l'output al dipendente.
- I comandi sono argomenti. Il dipendente sceglie un comando, come
notes search, e degli argomenti con nome. Nebo passa ogni argomento come--name value. Non c'è una shell, quindi pipe e reindirizzamenti non si applicano mai. - L'output è stdout. Scrivi i risultati su stdout. Il JSON funziona bene.
- L'input standard è chiuso per le chiamate ordinarie. Hook, route e provider di chat usano stdin; vedi il riferimento di plugin.json.
Ogni plugin installato e attivato appare ai dipendenti come un unico strumento chiamato plugin__<slug>. Un dipendente lo chiama così:
{
"command": "notes search",
"args": { "query": "quarterly plan", "limit": "5" },
"display": "Search notes for the quarterly plan"
} Nebo esegue:
notes-sync notes search --query "quarterly plan" --limit 5
| Parametro | Tipo | Significato |
|---|---|---|
command | stringa, obbligatorio | Il comando del plugin ed eventuali parole posizionali. |
args | oggetto di stringhe | Argomenti con nome. Ognuno diventa --key value. |
timeout | integer | Secondi di attesa. Predefinito 120, limitato da permissions.maxTimeoutSeconds del manifest. |
display | string | La frase che il proprietario vede quando la chiamata richiede approvazione. |
Crea il tuo primo plugin
Scrivi un binario in qualsiasi linguaggio che legga il comando dagli argomenti e stampi un risultato. Poi mettilo accanto a un plugin.json nella cartella dei plugin utente di un 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 e platforms sono obbligatori. Nella cartella dei plugin utente la mappa platforms può essere vuota: Nebo cerca un binario con il nome dello slug accanto a plugin.json, poi in target/release/ e target/debug/. Quando pubblichi, il marketplace compila platforms per ogni binario che carichi.
<data> è ~/Library/Application Support/Nebo su macOS, %APPDATA%\Nebo su Windows e ~/.local/share/nebo su Linux, oppure il valore di NEBO_HOME. Un plugin nella cartella utente sostituisce un plugin del marketplace con lo stesso slug, e per questo è il posto giusto per provare una nuova build.
Insegna ai dipendenti a usarlo
Metti una cartella skills/ accanto a plugin.json. Ogni skill al suo interno è disponibile per tutti i dipendenti finché il plugin è installato, e indica automaticamente il plugin come dipendenza. Usa la skill per dire quali comandi esistono, cosa restituiscono e quando usare ciascuno. Indica le skill più utili in entrySkills così la descrizione dello strumento del plugin rimanda prima a quelle.
La scheda del marketplace è un file separato, PLUGIN.md. Nebo non lo legge durante l'esecuzione; è la pagina che le persone vedono prima di installare. Vedi Distribuire un plugin.
Ambiente
Ogni chiamata eredita l'ambiente del bot, senza le variabili del loader e quelle di iniezione nella shell, poi aggiunge questi valori. Le voci successive prevalgono.
| Variabile | Valore |
|---|---|
Chiavi di auth.env | Valori predefiniti dal manifest. |
<SLUG>_BIN | Percorso del binario di questo plugin e di ogni plugin da cui dipende. Lo slug è in maiuscolo, con i trattini sostituiti da trattini bassi. |
NEBO_DATA_DIR | La cartella dei dati del plugin, <data>/appdata/plugins/<slug>/. È anche la cartella di lavoro e sopravvive alla disinstallazione. |
PATH | Prima le cartelle dei plugin, poi il percorso ereditato. |
| Impostazioni | Valori che il proprietario ha salvato per i campi di configSchema. |
NEBO_AGENT_ID | Il dipendente che effettua la chiamata. |
profileDirEnv | La cartella dell'account per questo dipendente e questo account, quando il plugin supporta gli account. |
permissions.envAllow e permissions.envDeny restringono ciò che il plugin eredita dal bot. Non rimuovono mai le variabili di autenticazione del plugin stesso.
Account e credenziali
Un plugin che accede a un servizio dovrebbe gestire un account per dipendente. Il contabile accede con le credenziali dell'amministrazione e l'assistente con le proprie, e nessuno dei due vede i token dell'altro. Lo dichiari nel manifest; al resto pensa Nebo.
"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.envindica le credenziali.capabilities.configSchemadà loro un'etichetta e ne stabilisce l'ordine nel modulo di connessione.auth.profileDirEnvindica la variabile che il tuo plugin legge per la sua cartella di credenziali. Nebo crea una cartella per ogni dipendente e account e imposta quella variabile a ogni chiamata.- Quando il proprietario collega un account, Nebo esegue il tuo comando
logincon i valori che il proprietario ha inserito e con la cartella dell'account impostata. Il tuo plugin salva ciò che gli serve in quella cartella. Nebo non conserva i valori. - Il tuo comando
statusstampa un JSON come{"authenticated": true}. Quando un token scade, Nebo eseguerefreshse ne dichiari uno.
Per un accesso dal browser, imposta type su oauth_cli e fai in modo che login stampi o apra l'URL di accesso del provider. I dipendenti non accedono mai da soli: quando una chiamata richiede un accesso, il proprietario vede una scheda di connessione. Un dipendente con più account ne sceglie uno aggiungendo --account <label> a un comando. Nebo rimuove quel flag prima che il tuo binario lo veda.
Dai il nome del servizio, non della forma. Il nome di un plugin dice a cosa si collega, come "Example Notes". Non mettere mai "CLI" nel nome di un plugin; per i dipendenti e i proprietari è una connessione, non una riga di comando.
Prossimi passi
- Riferimento di plugin.json: ogni campo, inclusi eventi, hook e operazioni tipizzate.
- Distribuire un plugin: piattaforme, binari, firma e aggiornamenti.
- Pubblicazione: il percorso nel marketplace per ogni artefatto.