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
| Parametru | Tip | Semnificație |
|---|---|---|
command | șir, obligatoriu | Comanda pluginului și eventualele cuvinte poziționale. |
args | obiect de șiruri | Argumente cu nume. Fiecare devine --key value. |
timeout | integer | Secundele de așteptare. Implicit 120, limitat de permissions.maxTimeoutSeconds din manifest. |
display | string | Propoziț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.env | Valori implicite din manifest. |
<SLUG>_BIN | Calea 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_DIR | Folderul de date propriu al pluginului, <data>/appdata/plugins/<slug>/. Este și directorul de lucru și rămâne după dezinstalare. |
PATH | Mai întâi folderele pluginurilor, apoi calea moștenită. |
| Setări | Valorile salvate de proprietar pentru câmpurile configSchema. |
NEBO_AGENT_ID | Angajatul care face apelul. |
profileDirEnv | Folderul 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 }
]
} auth.envnumește datele de acces.capabilities.configSchemale etichetează și le stabilește ordinea în formularul de conectare.auth.profileDirEnvnumeș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.- Când proprietarul conectează un cont, Nebo rulează comanda ta
logincu valorile tastate de proprietar și cu folderul contului setat. Pluginul tău salvează în acel folder ce are nevoie. Nebo nu păstrează valorile. - Comanda ta
statusafiș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
- Referința plugin.json: fiecare câmp, inclusiv evenimente, hookuri și operații tipizate.
- Lansarea unui plugin: platforme, binare, semnare și actualizări.
- Publicare: fluxul din magazin pentru fiecare tip de produs.