NeboAI
NeboAI
Începe

Pluginuri

Un plugin le dă angajaților ceva asupra căruia să acționeze: un serviciu online, un sistem de business sau un program de pe calculator. Îl construiești ca binar de linie de comandă și îl descrii cu un manifest plugin.json. Angajații îi apelează comenzile, iar Nebo se ocupă de instalare, de conturile per angajat și de actualizări.

Cum funcționează pluginurile

Un plugin este un executabil plus un manifest. Nebo nu ține niciun proces al pluginului pornit între apeluri. De fiecare dată când un angajat folosește pluginul, Nebo pornește binarul cu o comandă și argumente, așteaptă să se încheie și îi predă rezultatul angajatului.

  • Comenzile sunt argumente. Angajatul alege o comandă, de exemplu notes search, și argumente cu nume. Nebo transmite fiecare argument ca --name value. Nu există shell, așa că pipe-urile și redirecționările nu se aplică niciodată.
  • Rezultatul este stdout. Scrie rezultatele în stdout. JSON funcționează bine.
  • Intrarea standard este închisă pentru apelurile obișnuite. Hookurile, rutele și furnizorii de chat folosesc stdin; vezi referința plugin.json.

Fiecare plugin instalat și activat le apare angajaților ca un singur instrument numit plugin__<slug>. Un angajat îl apelează astfel:

{
  "command": "notes search",
  "args": { "query": "quarterly plan", "limit": "5" },
  "display": "Search notes for the quarterly plan"
}

Nebo rulează:

notes-sync notes search --query "quarterly plan" --limit 5
ParametruTipSemnificație
commandșir, obligatoriuComanda pluginului și eventualele cuvinte poziționale.
argsobiect de șiruriArgumente cu nume. Fiecare devine --key value.
timeoutintegerSecundele de așteptare. Implicit 120, limitat de permissions.maxTimeoutSeconds din manifest.
displaystringPropoziția pe care o vede proprietarul când apelul necesită aprobare.

Construiește-ți primul plugin

Scrie un binar în orice limbaj care își citește comanda din argumente și afișează un rezultat. Apoi pune-l lângă un plugin.json în directorul de pluginuri al utilizatorului de pe 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 și platforms sunt obligatorii. În directorul de pluginuri al utilizatorului, harta platforms poate fi goală: Nebo caută un binar numit după slug lângă plugin.json, apoi în target/release/ și target/debug/. Când publici, magazinul completează platforms pentru fiecare binar pe care îl încarci.

<data> este ~/Library/Application Support/Nebo pe macOS, %APPDATA%\Nebo pe Windows și ~/.local/share/nebo pe Linux, sau valoarea lui NEBO_HOME. Un plugin din directorul utilizatorului înlocuiește un plugin din magazin cu același slug, ceea ce îl face locul potrivit pentru a testa o versiune nouă.

Învață-i pe angajați să-l folosească

Pune un folder skills/ lângă plugin.json. Fiecare abilitate din el este disponibilă pentru toți angajații cât timp pluginul este instalat și listează automat pluginul ca dependență. Folosește abilitatea ca să spui ce comenzi există, ce returnează și când se folosește fiecare. Numește cele mai utile abilități în entrySkills, astfel încât descrierea instrumentului pluginului să trimită mai întâi la ele.

Pagina din magazin este un fișier separat, PLUGIN.md. Nebo nu îl citește la rulare; este pagina pe care oamenii o văd înainte de instalare. Vezi Lansarea unui plugin.

Mediu

Fiecare apel moștenește mediul botului, fără variabilele de încărcare și de injectare în shell, apoi adaugă aceste valori. Intrările ulterioare au prioritate.

VariabilăValoare
Cheile auth.envValori implicite din manifest.
<SLUG>_BINCalea binarului acestui plugin și a fiecărui plugin de care depinde. Slugul este scris cu majuscule, cu cratimele înlocuite de liniuțe de subliniere.
NEBO_DATA_DIRFolderul de date propriu al pluginului, <data>/appdata/plugins/<slug>/. Este și directorul de lucru și rămâne după dezinstalare.
PATHMai întâi folderele pluginurilor, apoi calea moștenită.
SetăriValorile salvate de proprietar pentru câmpurile configSchema.
NEBO_AGENT_IDAngajatul care face apelul.
profileDirEnvFolderul contului pentru acest angajat și acest cont, când pluginul suportă conturi.

permissions.envAllow și permissions.envDeny restrâng ce moștenește pluginul de la bot. Nu elimină niciodată variabilele de autentificare proprii ale pluginului.

Conturi și date de acces

Un plugin care se autentifică la un serviciu ar trebui să păstreze câte un cont pentru fiecare angajat. Contabilul se autentifică cu contul financiar, iar asistentul cu al său, și niciunul nu vede tokenurile celuilalt. Declari asta în manifest; Nebo face restul.

"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 numește datele de acces. capabilities.configSchema le etichetează și le stabilește ordinea în formularul de conectare.
  2. auth.profileDirEnv numește variabila pe care pluginul tău o citește pentru folderul de date de acces. Nebo creează câte un folder pentru fiecare angajat și cont și setează acea variabilă la fiecare apel.
  3. Când proprietarul conectează un cont, Nebo rulează comanda ta login cu valorile tastate de proprietar și cu folderul contului setat. Pluginul tău salvează în acel folder ce are nevoie. Nebo nu păstrează valorile.
  4. Comanda ta status afișează JSON, de exemplu {"authenticated": true}. Când un token expiră, Nebo rulează refresh, dacă ai declarat-o.

Pentru o autentificare în browser, setează type la oauth_cli și fă ca login să afișeze sau să deschidă URL-ul de autentificare al furnizorului. Angajații nu se autentifică niciodată singuri: când un apel are nevoie de autentificare, proprietarul vede un card de conectare. Un angajat cu mai multe conturi alege unul adăugând --account <label> la o comandă. Nebo elimină această opțiune înainte ca binarul tău să o vadă.

Numește serviciul, nu forma. Numele unui plugin spune la ce se conectează, de exemplu „Example Notes”. Nu pune niciodată „CLI” în numele unui plugin; pentru angajați și proprietari este o conexiune, nu o linie de comandă.

Mai departe