Câmpuri de nivel superior
| Câmp | Tip | Obligatoriu | Semnificație |
|---|---|---|---|
id | string | da | Identificatorul pluginului în magazin. Folosește slugul în timpul dezvoltării. |
slug | string | da | Identificator 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. |
name | string | da | Numele afișat. Numește serviciul la care se conectează. |
version | string | da | Versiune semantică, de exemplu 0.1.0. |
platforms | map | da | Cheie de platformă către binar. Vezi Platforme. |
description | string | nu | O propoziție pentru oameni și angajați. |
author | string | nu | Numele editorului. |
category | string | nu | Îi ajută pe angajați să găsească pluginul. |
triggers | listă de șiruri | nu | Cuvinte care descriu când se aplică pluginul. Folosite în sugestiile de căutare. |
entrySkills | listă de șiruri | nu | Abilități incluse care se numesc primele în descrierea instrumentului pluginului. |
dependencies | listă de {name, version, optional} | nu | Alte pluginuri pe care acesta le rulează. version are implicit valoarea "*"; optional are false. Căile lor <SLUG>_BIN sunt setate la fiecare apel. |
auth | object | nu | Autentificare și conturi. Vezi Autentificare. |
capabilities | object | nu | configSchema, hooks, commands, routes, providers. |
permissions | object | nu | Filtrarea mediului și limita maximă de timp. |
events | list | nu | Observatori care alimentează fluxurile de lucru ale angajaților. |
interfaceBindings | map | nu | Operațiile tipizate pe care le oferă pluginul. |
channel | object | nu | O punte permanentă către un serviciu de mesagerie. |
setup | object | nu | Un 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âmp | Semnificație |
|---|---|
binaryName | Numele fișierului executabil. Adaugă .exe pe Windows. |
sha256 | Hashul binarului. Verificat la instalare. |
signature | Semnătura binarului. Verificată la instalare când este disponibilă o cheie de semnare. |
size | Dimensiunea în octeți. |
downloadUrl | De unde descarcă Nebo pachetul. |
Autentificare
| Câmp | Semnificație |
|---|---|
type | oauth_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. |
env | Asociere între numele variabilei și valoarea implicită. Sunt și singurele nume de date de acces pe care Nebo le transmite către login. |
commands.login | Autentifică contul. Obligatorie dacă type nu este env. Rulează cu folderul contului setat. |
commands.status | Afișează JSON care spune dacă contul este autentificat. |
commands.refresh | Reînnoiește un token fără interacțiune. |
commands.logout | Deconectează contul. Doar proprietarul o poate rula. |
profileDirEnv | Variabilă 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, description | Textul de pe cardul de conectare. |
help | {url, urlLabel, text} afișat în timpul conectării. |
publicRedirect | Setează 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âmp | Tip | Implicit | Semnificație |
|---|---|---|---|
key | string | obligatoriu | Numele variabilei de mediu. |
label | string | obligatoriu | Eticheta câmpului. |
description | string | "" | Text de ajutor. |
fieldType | string | "string" | Tipul de intrare, de exemplu string, number, boolean, select sau password. |
default | string | niciuna | Valoare precompletată. |
required | boolean | false | Pluginul nu este gata până când valoarea nu este setată. |
secret | boolean | false | Valoarea este mascată la citire. |
options | listă de șiruri | niciuna | Opțiuni pentru select. |
permissions
| Câmp | Implicit | Semnificație |
|---|---|---|
envAllow | [] | Variabile moștenite pe care pluginul le poate vedea. Gol le permite pe toate. |
envDeny | [] | Variabile moștenite care sunt eliminate întotdeauna. |
maxTimeoutSeconds | 300 | Limita maximă pentru timpul de așteptare al oricărui apel. |
network | false | Declară 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âmp | Semnificație |
|---|---|
name | Numele evenimentului, fără slug. Obligatoriu. |
command | Argumentele care pornesc observatorul. Obligatoriu. {{key}} este înlocuit din valorile introduse pentru angajat. |
description | Ce declanșează evenimentul. |
multiplexed | Câ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}"
} | Substituent | Se 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âmp | Implicit | Semnificație |
|---|---|---|
hook | obligatoriu | Unul 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. |
command | obligatoriu | Argumente pentru binarul tău. |
priority | 100 | Valoarea mai mică rulează prima. |
timeoutMs | 500 | Limita 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âmp | Implicit | Semnificație |
|---|---|---|
command | obligatoriu | Argumentele care pornesc puntea. |
name, description | "" | Afișat în setări. |
restartDelaySecs | 5 | Așteptarea înainte de repornire după o cădere. |
shared | false | O singură punte pentru toți angajații; mesajele sunt direcționate după numele angajatului, iar răspunsurile poartă identitatea fiecărui angajat. |
needsLocalApi | false | Oferă 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 pasului | Câmpuri |
|---|---|
form | title, description, fields |
generate | title, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Afișează rezultatul comenzii pentru a fi copiat. |
external | title, description, url, urlLabel, instructions |
credentials | title, 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.