NeboAI
NeboAI
Inizia

Riferimento plugin.json

plugin.json è il manifest che Nebo legge per installare ed eseguire un plugin. Le chiavi sono in camelCase. Questa pagina elenca ogni campo che Nebo legge oggi e cosa fa ciascuno.

Campi di primo livello

CampoTipoObbligatorioSignificato
idstringsìL'identificatore del plugin nel marketplace. Usa lo slug durante lo sviluppo.
slugstringsì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.
namestringsìNome visualizzato. Indica il servizio a cui si collega.
versionstringsìVersione semantica, come 0.1.0.
platformsmapsìChiave della piattaforma verso il binario. Vedi Piattaforme.
descriptionstringnoUna frase per le persone e per i dipendenti.
authorstringnoNome dell'editore.
categorystringnoAiuta i dipendenti a trovare il plugin.
triggerselenco di stringhenoParole che descrivono quando il plugin è pertinente. Usate nei suggerimenti di ricerca.
entrySkillselenco di stringhenoSkill incluse da citare per prime nella descrizione dello strumento del plugin.
dependencieselenco di {name, version, optional}noAltri plugin che questo esegue. version vale "*" per impostazione predefinita; optional vale false. I loro percorsi <SLUG>_BIN vengono impostati a ogni chiamata.
authobjectnoAccesso e account. Vedi Autenticazione.
capabilitiesobjectnoconfigSchema, hooks, commands, routes, providers.
permissionsobjectnoFiltro dell'ambiente e limite massimo di timeout.
eventslistnoOsservatori che alimentano i flussi di lavoro dei dipendenti.
interfaceBindingsmapnoOperazioni tipizzate fornite dal plugin.
channelobjectnoUn ponte persistente verso un servizio di messaggistica.
setupobjectnoUna 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": "" }
}
CampoSignificato
binaryNameIl nome del file eseguibile. Aggiungi .exe su Windows.
sha256Hash del binario. Verificato all'installazione.
signatureFirma del binario. Verificata all'installazione quando è disponibile una chiave di firma.
sizeDimensione in byte.
downloadUrlDove Nebo scarica il pacchetto.

Autenticazione

CampoSignificato
typeoauth_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.
envMappa dal nome della variabile al valore predefinito. Sono anche gli unici nomi di credenziali che Nebo passa a login.
commands.loginEffettua l'accesso. Obbligatorio a meno che type sia env. Viene eseguito con la cartella dell'account impostata.
commands.statusStampa un JSON che indica se l'account ha effettuato l'accesso.
commands.refreshRinnova un token senza interazione.
commands.logoutDisconnette l'account. Solo il proprietario può eseguirlo.
profileDirEnvVariabile che riceve una cartella di credenziali separata per ogni dipendente e account. Senza di essa il plugin gestisce un unico account condiviso.
label, descriptionTesto sulla scheda di connessione.
help{url, urlLabel, text} mostrato durante la connessione.
publicRedirectImposta 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.

CampoTipoPredefinitoSignificato
keystringobbligatorioNome della variabile d'ambiente.
labelstringobbligatorioEtichetta del campo.
descriptionstring""Testo di aiuto.
fieldTypestring"string"Tipo di input, come string, number, boolean, select o password.
defaultstringnessunoValore precompilato.
requiredbooleanfalseIl plugin non è pronto finché il valore non è impostato.
secretbooleanfalseIl valore viene mascherato quando viene riletto.
optionselenco di stringhenessunoOpzioni per select.

permissions

CampoPredefinitoSignificato
envAllow[]Variabili ereditate che il plugin può vedere. Se vuoto, sono consentite tutte.
envDeny[]Variabili ereditate sempre rimosse.
maxTimeoutSeconds300Limite massimo per il timeout di qualsiasi chiamata.
networkfalseDichiara 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"
  }
]
CampoSignificato
nameNome dell'evento, senza lo slug. Obbligatorio.
commandArgomenti che avviano l'osservatore. Obbligatorio. {{key}} viene sostituito con i valori di input del dipendente.
descriptionCosa provoca l'evento.
multiplexedCon 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}"
}
SegnapostoSi 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.

CampoPredefinitoSignificato
hookobbligatorioUno 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.
commandobbligatorioArgomenti per il tuo binario.
priority100Il valore più basso viene eseguito per primo.
timeoutMs500Limite 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.

CampoPredefinitoSignificato
commandobbligatorioArgomenti che avviano il ponte.
name, description""Mostrato nelle impostazioni.
restartDelaySecs5Attesa prima del riavvio dopo un arresto anomalo.
sharedfalseUn 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.
needsLocalApifalseFornisce 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 passaggioCampi
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Mostra l'output del comando da copiare.
externaltitle, description, url, urlLabel, instructions
credentialstitle, description, fields, verifyCommand. Il passaggio è completato quando verifyCommand riesce.

I campi hanno key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) e required.