NeboAI
NeboAI
Inizia

Plugin

Un plugin dà ai dipendenti qualcosa su cui agire: un servizio online, un sistema aziendale o un programma sul computer. Lo crei come binario da riga di comando e lo descrivi con un manifest plugin.json. I dipendenti chiamano i suoi comandi, e Nebo si occupa di installazione, account per dipendente e aggiornamenti.

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
ParametroTipoSignificato
commandstringa, obbligatorioIl comando del plugin ed eventuali parole posizionali.
argsoggetto di stringheArgomenti con nome. Ognuno diventa --key value.
timeoutintegerSecondi di attesa. Predefinito 120, limitato da permissions.maxTimeoutSeconds del manifest.
displaystringLa 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.

VariabileValore
Chiavi di auth.envValori predefiniti dal manifest.
<SLUG>_BINPercorso 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_DIRLa cartella dei dati del plugin, <data>/appdata/plugins/<slug>/. È anche la cartella di lavoro e sopravvive alla disinstallazione.
PATHPrima le cartelle dei plugin, poi il percorso ereditato.
ImpostazioniValori che il proprietario ha salvato per i campi di configSchema.
NEBO_AGENT_IDIl dipendente che effettua la chiamata.
profileDirEnvLa 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 }
  ]
}
  1. auth.env indica le credenziali. capabilities.configSchema dà loro un'etichetta e ne stabilisce l'ordine nel modulo di connessione.
  2. auth.profileDirEnv indica 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.
  3. Quando il proprietario collega un account, Nebo esegue il tuo comando login con 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.
  4. Il tuo comando status stampa un JSON come {"authenticated": true}. Quando un token scade, Nebo esegue refresh se 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