Campi di primo livello
| Campo | Tipo | Obbligatorio | Significato |
|---|---|---|---|
id | string | sì | L'identificatore del plugin nel marketplace. Usa lo slug durante lo sviluppo. |
slug | string | sì | Identificatore stabile. [a-z0-9-], al massimo 64 caratteri, senza trattini iniziali, finali o doppi. Dà il nome allo strumento plugin__<slug> e alla variabile <SLUG>_BIN. |
name | string | sì | Nome visualizzato. Indica il servizio a cui si collega. |
version | string | sì | Versione semantica, come 0.1.0. |
platforms | map | sì | Chiave della piattaforma verso il binario. Vedi Piattaforme. |
description | string | no | Una frase per le persone e per i dipendenti. |
author | string | no | Nome dell'editore. |
category | string | no | Aiuta i dipendenti a trovare il plugin. |
triggers | elenco di stringhe | no | Parole che descrivono quando il plugin è pertinente. Usate nei suggerimenti di ricerca. |
entrySkills | elenco di stringhe | no | Skill incluse da citare per prime nella descrizione dello strumento del plugin. |
dependencies | elenco di {name, version, optional} | no | Altri plugin che questo esegue. version vale "*" per impostazione predefinita; optional vale false. I loro percorsi <SLUG>_BIN vengono impostati a ogni chiamata. |
auth | object | no | Accesso e account. Vedi Autenticazione. |
capabilities | object | no | configSchema, hooks, commands, routes, providers. |
permissions | object | no | Filtro dell'ambiente e limite massimo di timeout. |
events | list | no | Osservatori che alimentano i flussi di lavoro dei dipendenti. |
interfaceBindings | map | no | Operazioni tipizzate fornite dal plugin. |
channel | object | no | Un ponte persistente verso un servizio di messaggistica. |
setup | object | no | Una procedura guidata di configurazione passo per passo. |
Nebo convalida le installazioni dal marketplace: le regole dello slug, una versione semantica, almeno una piattaforma, un binaryName senza separatori di percorso né .., un comando login a meno che auth.type sia env, nomi di eventi e comandi non vuoti, e modelli di binding analizzabili. I plugin nella cartella dei plugin utente saltano la convalida.
Piattaforme
Le chiavi sono darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 e windows-amd64. Ogni voce ha tutti e cinque i campi qui sotto. Quando pubblichi, il marketplace scrive l'hash, la dimensione, la firma e l'URL di download reali, quindi lasciali vuoti nel file che carichi.
"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": "" }
} | Campo | Significato |
|---|---|
binaryName | Il nome del file eseguibile. Aggiungi .exe su Windows. |
sha256 | Hash del binario. Verificato all'installazione. |
signature | Firma del binario. Verificata all'installazione quando è disponibile una chiave di firma. |
size | Dimensione in byte. |
downloadUrl | Dove Nebo scarica il pacchetto. |
Autenticazione
| Campo | Significato |
|---|---|
type | oauth_cli per un accesso dal browser gestito dal plugin; env per credenziali inserite come valori; neboai per ricevere il token NeboAI del proprietario in ogni chiave di auth.env che termina con _TOKEN. |
env | Mappa dal nome della variabile al valore predefinito. Sono anche gli unici nomi di credenziali che Nebo passa a login. |
commands.login | Effettua l'accesso. Obbligatorio a meno che type sia env. Viene eseguito con la cartella dell'account impostata. |
commands.status | Stampa un JSON che indica se l'account ha effettuato l'accesso. |
commands.refresh | Rinnova un token senza interazione. |
commands.logout | Disconnette l'account. Solo il proprietario può eseguirlo. |
profileDirEnv | Variabile che riceve una cartella di credenziali separata per ogni dipendente e account. Senza di essa il plugin gestisce un unico account condiviso. |
label, description | Testo sulla scheda di connessione. |
help | {url, urlLabel, text} mostrato durante la connessione. |
publicRedirect | Imposta true quando il provider rifiuta i reindirizzamenti a http://localhost; l'accesso passa allora dal reindirizzamento pubblico di NeboAI. |
Nebo legge il primo tra authenticated, isAuthenticated, logged_in, loggedIn o token_valid nell'output di stato. Un token_error non vuoto, oppure il valore none in credential_source, auth_method, storage o status, significa accesso non effettuato. Il comando di stato ha 45 secondi.
{"authenticated": true, "account": "finance@example.com"} configSchema
capabilities.configSchema descrive i valori che un proprietario imposta per il plugin. Ogni valore arriva al binario come variabile d'ambiente con il nome indicato da key. Per le chiavi di credenziali elencate anche in auth.env, lo schema dà le etichette ai campi del modulo di connessione per dipendente.
| Campo | Tipo | Predefinito | Significato |
|---|---|---|---|
key | string | obbligatorio | Nome della variabile d'ambiente. |
label | string | obbligatorio | Etichetta del campo. |
description | string | "" | Testo di aiuto. |
fieldType | string | "string" | Tipo di input, come string, number, boolean, select o password. |
default | string | nessuno | Valore precompilato. |
required | boolean | false | Il plugin non è pronto finché il valore non è impostato. |
secret | boolean | false | Il valore viene mascherato quando viene riletto. |
options | elenco di stringhe | nessuno | Opzioni per select. |
permissions
| Campo | Predefinito | Significato |
|---|---|---|
envAllow | [] | Variabili ereditate che il plugin può vedere. Se vuoto, sono consentite tutte. |
envDeny | [] | Variabili ereditate sempre rimosse. |
maxTimeoutSeconds | 300 | Limite massimo per il timeout di qualsiasi chiamata. |
network | false | Dichiara l'uso della rete. Informativo; non viene imposto. |
events
Un evento è un osservatore di lunga durata. Nebo lo avvia quando un flusso di lavoro di un dipendente lo osserva, e lo riavvia se termina. Ogni riga che l'osservatore scrive su stdout è un evento. Al momento dell'esecuzione il nome dell'evento riceve lo slug come prefisso, quindi note.created diventa notes-sync.note.created.
"events": [
{
"name": "note.created",
"description": "A note was created in the watched notebook.",
"command": "watch --notebook {{notebook}} --format ndjson"
}
] | Campo | Significato |
|---|---|
name | Nome dell'evento, senza lo slug. Obbligatorio. |
command | Argomenti che avviano l'osservatore. Obbligatorio. {{key}} viene sostituito con i valori di input del dipendente. |
description | Cosa provoca l'evento. |
multiplexed | Con true, un solo osservatore emette diversi tipi di evento e ogni riga contiene un campo "event". |
I flussi di lavoro si iscrivono agli eventi con un trigger watch. Vedi Trigger.
interfaceBindings
Un binding associa un'operazione di interfaccia a uno dei tuoi comandi. Ogni binding diventa uno strumento tipizzato per i dipendenti, con il nome dell'operazione in minuscolo e punti e trattini sostituiti da trattini bassi: notes.search diventa notes_search. I binding sono il modo in cui un plugin soddisfa le capacità richieste da un dipendente; vedi Capacità.
"interfaceBindings": {
"notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
"invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
} | Segnaposto | Si espande in |
|---|---|
{field} | Il valore del campo come una sola parola. Il campo non viene passato anche come flag. |
{field[]:--flag} | Una coppia --flag <item> per ogni elemento di un campo elenco. |
{field?:--flag} | --flag <value> quando il campo è presente; niente quando è assente. |
{field:cents->dollars} | Un importo intero in centesimi, scritto in dollari. |
I campi di input che un modello non nomina vengono aggiunti in coda come --field value. I segnaposto di elenco e facoltativi devono essere parole intere. Un'operazione che richiede approvazione non si può raggiungere chiamando lo stesso comando tramite plugin__<slug>.
Hook, comandi slash e route
"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
Un hook esegue il tuo comando in un punto del turno di un dipendente. Nebo scrive un payload JSON su stdin. L’output di un hook action viene ignorato. Un hook filter restituisce {"payload": ..., "handled": false}; "handled": true ferma gli hook successivi. Errori e timeout mantengono il payload precedente e non bloccano mai il turno. Dopo tre errori consecutivi, un hook viene messo in pausa per cinque minuti.
| Campo | Predefinito | Significato |
|---|---|---|
hook | obbligatorio | Uno tra tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue. |
hookType | "action" | action o filter. |
command | obbligatorio | Argomenti per il tuo binario. |
priority | 100 | Il valore più basso viene eseguito per primo. |
timeoutMs | 500 | Limite di tempo in millisecondi. |
commands
Con "slash": true, digitare /name args in chat esegue direttamente command args, senza il dipendente. L'output è la risposta. Il limite di tempo è di 30 secondi.
routes
Una route risponde alle richieste HTTP su /api/v1/plugins/<slug>/api/<path> nel bot, abbinate in base a path e method. Il corpo della richiesta va su stdin e il tuo stdout è la risposta. Il limite di tempo è di 30 secondi.
providers
Un provider aggiunge una fonte di modelli per la chat. Dichiara id, displayName, providerType, modelsCommand e chatCommand. Nebo invia una richiesta di chat come JSON su stdin a chatCommand e legge gli eventi in streaming come JSON delimitato da newline su stdout, per un massimo di 300 secondi. Oggi viene usato solo lo streaming della chat.
channel
Un canale fa da ponte con un servizio di messaggistica. Nebo tiene in esecuzione command, legge i messaggi in arrivo dal suo stdout e scrive le risposte sul suo stdin, entrambi come JSON delimitato da newline.
| Campo | Predefinito | Significato |
|---|---|---|
command | obbligatorio | Argomenti che avviano il ponte. |
name, description | "" | Mostrato nelle impostazioni. |
restartDelaySecs | 5 | Attesa prima del riavvio dopo un arresto anomalo. |
shared | false | Un solo ponte per tutti i dipendenti; i messaggi vengono instradati in base al nome del dipendente e le risposte portano l'identità di ciascun dipendente. |
needsLocalApi | false | Fornisce al ponte l'indirizzo dell'API locale del bot, un token e l'id del dipendente. Disattivato, a meno che ti serva. |
setup
Una procedura guidata di configurazione accompagna il proprietario attraverso passaggi che un singolo modulo non può coprire. I valori dei passaggi form riempiono {{key}} negli argomenti generate successivi. I valori dei passaggi credentials vengono salvati come variabili d’ambiente del 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" }
]
} | Tipo di passaggio | Campi |
|---|---|
form | title, description, fields |
generate | title, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Mostra l'output del comando da copiare. |
external | title, description, url, urlLabel, instructions |
credentials | title, description, fields, verifyCommand. Il passaggio è completato quando verifyCommand riesce. |
I campi hanno key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) e required.