NeboAI
NeboAI
Începe

Referință plugin.json

plugin.json este manifestul pe care Nebo îl citește pentru a instala și rula un plugin. Cheile sunt în camelCase. Această pagină listează fiecare câmp pe care Nebo îl citește astăzi și ce face fiecare.

Câmpuri de nivel superior

CâmpTipObligatoriuSemnificație
idstringdaIdentificatorul pluginului în magazin. Folosește slugul în timpul dezvoltării.
slugstringdaIdentificator stabil. [a-z0-9-], cel mult 64 de caractere, fără cratimă la început, la sfârșit sau dublă. Dă numele instrumentului plugin__<slug> și al variabilei <SLUG>_BIN.
namestringdaNumele afișat. Numește serviciul la care se conectează.
versionstringdaVersiune semantică, de exemplu 0.1.0.
platformsmapdaCheie de platformă către binar. Vezi Platforme.
descriptionstringnuO propoziție pentru oameni și angajați.
authorstringnuNumele editorului.
categorystringnuÎi ajută pe angajați să găsească pluginul.
triggerslistă de șirurinuCuvinte care descriu când se aplică pluginul. Folosite în sugestiile de căutare.
entrySkillslistă de șirurinuAbilități incluse care se numesc primele în descrierea instrumentului pluginului.
dependencieslistă de {name, version, optional}nuAlte pluginuri pe care acesta le rulează. version are implicit valoarea "*"; optional are false. Căile lor <SLUG>_BIN sunt setate la fiecare apel.
authobjectnuAutentificare și conturi. Vezi Autentificare.
capabilitiesobjectnuconfigSchema, hooks, commands, routes, providers.
permissionsobjectnuFiltrarea mediului și limita maximă de timp.
eventslistnuObservatori care alimentează fluxurile de lucru ale angajaților.
interfaceBindingsmapnuOperațiile tipizate pe care le oferă pluginul.
channelobjectnuO punte permanentă către un serviciu de mesagerie.
setupobjectnuUn asistent de configurare pas cu pas.

Nebo validează instalările din magazin: regulile pentru slug, o versiune semantică, cel puțin o platformă, un binaryName fără separatori de cale sau .., o comandă login dacă auth.type nu este env, nume de evenimente și comenzi nevide și șabloane de legare care pot fi analizate. Pluginurile din directorul de pluginuri al utilizatorului sar peste validare.

Platforme

Cheile sunt darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 și windows-amd64. Fiecare intrare are toate cele cinci câmpuri de mai jos. Când publici, magazinul scrie hashul, dimensiunea, semnătura și URL-ul de descărcare reale, așa că lasă-le goale în fișierul pe care îl încarci.

"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": "" }
}
CâmpSemnificație
binaryNameNumele fișierului executabil. Adaugă .exe pe Windows.
sha256Hashul binarului. Verificat la instalare.
signatureSemnătura binarului. Verificată la instalare când este disponibilă o cheie de semnare.
sizeDimensiunea în octeți.
downloadUrlDe unde descarcă Nebo pachetul.

Autentificare

CâmpSemnificație
typeoauth_cli pentru o autentificare în browser condusă de plugin; env pentru date de acces introduse ca valori; neboai pentru a primi tokenul NeboAI al proprietarului în fiecare cheie auth.env care se termină în _TOKEN.
envAsociere între numele variabilei și valoarea implicită. Sunt și singurele nume de date de acces pe care Nebo le transmite către login.
commands.loginAutentifică contul. Obligatorie dacă type nu este env. Rulează cu folderul contului setat.
commands.statusAfișează JSON care spune dacă contul este autentificat.
commands.refreshReînnoiește un token fără interacțiune.
commands.logoutDeconectează contul. Doar proprietarul o poate rula.
profileDirEnvVariabilă care primește un folder separat de date de acces pentru fiecare angajat și cont. Fără ea, pluginul păstrează un singur cont comun.
label, descriptionTextul de pe cardul de conectare.
help{url, urlLabel, text} afișat în timpul conectării.
publicRedirectSetează true când furnizorul refuză redirecționările către http://localhost; autentificarea trece atunci prin redirecționarea publică a NeboAI.

Nebo citește primul dintre authenticated, isAuthenticated, logged_in, loggedIn sau token_valid din rezultatul comenzii de stare. Un token_error nevid sau valoarea none în credential_source, auth_method, storage sau status înseamnă deconectat. Comanda de stare are la dispoziție 45 de secunde.

{"authenticated": true, "account": "finance@example.com"}

configSchema

capabilities.configSchema descrie valorile pe care un proprietar le setează pentru plugin. Fiecare valoare ajunge la binar ca variabilă de mediu numită după key. Pentru cheile de date de acces listate și în auth.env, schema etichetează câmpurile formularului de conectare per angajat.

CâmpTipImplicitSemnificație
keystringobligatoriuNumele variabilei de mediu.
labelstringobligatoriuEticheta câmpului.
descriptionstring""Text de ajutor.
fieldTypestring"string"Tipul de intrare, de exemplu string, number, boolean, select sau password.
defaultstringniciunaValoare precompletată.
requiredbooleanfalsePluginul nu este gata până când valoarea nu este setată.
secretbooleanfalseValoarea este mascată la citire.
optionslistă de șiruriniciunaOpțiuni pentru select.

permissions

CâmpImplicitSemnificație
envAllow[]Variabile moștenite pe care pluginul le poate vedea. Gol le permite pe toate.
envDeny[]Variabile moștenite care sunt eliminate întotdeauna.
maxTimeoutSeconds300Limita maximă pentru timpul de așteptare al oricărui apel.
networkfalseDeclară folosirea rețelei. Informativ; nu este impus.

events

Un eveniment este un observator care rulează mult timp. Nebo îl pornește când fluxul de lucru al unui angajat îl urmărește și îl repornește dacă se oprește. Fiecare linie pe care observatorul o scrie în stdout este un eveniment. La rulare, numele evenimentului primește ca prefix slugul, așa că note.created devine notes-sync.note.created.

"events": [
  {
    "name": "note.created",
    "description": "A note was created in the watched notebook.",
    "command": "watch --notebook {{notebook}} --format ndjson"
  }
]
CâmpSemnificație
nameNumele evenimentului, fără slug. Obligatoriu.
commandArgumentele care pornesc observatorul. Obligatoriu. {{key}} este înlocuit din valorile introduse pentru angajat.
descriptionCe declanșează evenimentul.
multiplexedCând este true, un singur observator emite mai multe tipuri de evenimente, iar fiecare linie are un câmp "event".

Fluxurile de lucru se abonează la evenimente cu un declanșator watch. Vezi Declanșatoare.

interfaceBindings

O legare asociază o operație de interfață cu una dintre comenzile tale. Fiecare legare devine un instrument tipizat pentru angajați, numit după operație cu litere mici, cu puncte și cratime înlocuite de liniuțe de subliniere: notes.search devine notes_search. Legările sunt modul în care un plugin îndeplinește capabilitățile cerute de un angajat; vezi Capabilități.

"interfaceBindings": {
  "notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
  "invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
}
SubstituentSe extinde la
{field}Valoarea câmpului ca un singur cuvânt. Câmpul nu este transmis și ca opțiune.
{field[]:--flag}O pereche --flag <item> pentru fiecare element dintr-un câmp de tip listă.
{field?:--flag}--flag <value> când câmpul este prezent; nimic când lipsește.
{field:cents->dollars}O sumă întreagă în cenți, scrisă în dolari.

Câmpurile de intrare pe care un șablon nu le numește sunt adăugate la final ca --field value. Substituenții de listă și cei opționali trebuie să fie cuvinte întregi. O operație care necesită aprobare nu poate fi accesată apelând aceeași comandă prin plugin__<slug>.

Hookuri, comenzi slash și rute

"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 îți rulează comanda într-un anumit moment din tura unui angajat. Nebo scrie un payload JSON în stdin. Rezultatul unui hook action este ignorat. Un hook filter returnează {"payload": ..., "handled": false}; "handled": true oprește hookurile următoare. Erorile și depășirile de timp păstrează payloadul anterior și nu blochează niciodată tura. După trei eșecuri la rând, un hook este pus pe pauză timp de cinci minute.

CâmpImplicitSemnificație
hookobligatoriuUnul dintre tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue.
hookType"action"action sau filter.
commandobligatoriuArgumente pentru binarul tău.
priority100Valoarea mai mică rulează prima.
timeoutMs500Limita de timp în milisecunde.

commands

Cu "slash": true, tastarea /name args în chat rulează direct command args, fără angajat. Rezultatul este răspunsul. Limita de timp este de 30 de secunde.

routes

O rută răspunde la cereri HTTP la /api/v1/plugins/<slug>/api/<path> pe bot, potrivite după path și method. Corpul cererii merge în stdin, iar stdout-ul tău este răspunsul. Limita de timp este de 30 de secunde.

providers

Un furnizor adaugă o sursă de modele de chat. Declară id, displayName, providerType, modelsCommand și chatCommand. Nebo trimite o cerere de chat ca JSON în stdin către chatCommand și citește evenimentele transmise în flux ca JSON delimitat pe linii din stdout, timp de până la 300 de secunde. Deocamdată se folosește doar transmiterea în flux a chatului.

channel

Un canal face legătura cu un serviciu de mesagerie. Nebo ține command pornită, citește mesajele primite din stdout-ul ei și scrie răspunsurile în stdin-ul ei, ambele ca JSON delimitat pe linii.

CâmpImplicitSemnificație
commandobligatoriuArgumentele care pornesc puntea.
name, description""Afișat în setări.
restartDelaySecs5Așteptarea înainte de repornire după o cădere.
sharedfalseO singură punte pentru toți angajații; mesajele sunt direcționate după numele angajatului, iar răspunsurile poartă identitatea fiecărui angajat.
needsLocalApifalseOferă punții adresa API locală a botului, un token și id-ul angajatului. Dezactivat, dacă nu ai nevoie de el.

setup

Un asistent de configurare îl ghidează pe proprietar prin pași pe care un singur formular nu îi poate acoperi. Valorile din pașii form completează {{key}} în argumentele generate de mai târziu. Valorile din pașii credentials sunt salvate ca variabile de mediu ale pluginului.

"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" }
  ]
}
Tipul pasuluiCâmpuri
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Afișează rezultatul comenzii pentru a fi copiat.
externaltitle, description, url, urlLabel, instructions
credentialstitle, description, fields, verifyCommand. Pasul se încheie când verifyCommand reușește.

Câmpurile au key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) și required.