Versiune 1.0.0-alpha.1cea mai recentă
Capitolul 2.18
Modelul de extensie
Cele șase moduri de a extinde Nexus, de la o setare la un pachet de domeniu, limitele fiecăruia și modul în care nivelurile de încredere și de izolare decid unde rulează codul dvs. Citiți acest capitol înainte de a deschide kitul de dezvoltare software (SDK).
Această pagină a fost tradusă cu ajutorul IA din originalul în limba engleză. Dacă există neclarități, pagina în limba engleză rămâne cea de referință. Citiți această pagină în limba engleză

Primul lucru pe care l-am construit pe Nexus la Corrán Orbital nu a fost un plugin. Echipa noastră de dinamică a zborului dorea ca asistentul să răspundă la întrebarea „ce treceri peste stațiile de la sol pierdem dacă antena din Svalbard intră în mentenanță?” în aceeași formă de fiecare dată, cu tabelul trecerilor la început și costul în minute de contact dedesubt. Am petrecut o jumătate de zi citind kitul de dezvoltare software (SDK) înainte ca un coleg să îmi atragă atenția că ceea ce îmi trebuia era o abilitate (skill): un dosar care conține un SKILL.md, încărcat în Skills Engine și publicat după ce testele aferente au trecut și un revizor l-a aprobat. A durat patruzeci de minute.
După două pluginuri și un pachet de domeniu (domain pack), acesta este în continuare primul sfat pe care îl ofer. Nexus oferă șase modalități de extindere, așezate pe o scară a efortului. Treptele ieftine fac mai mult decât se așteaptă lumea, iar cele scumpe implică obligații ușor de subestimat. Acest capitol prezintă această scară. Alegeți cea mai de jos treaptă care rezolvă sarcina. Capitolele următoare detaliază fiecare opțiune: capitolul 2.19, Regulile pe care le moștenește fiecare extensie; capitolul 2.20, Abilități; capitolul 2.21, SDK-ul pentru pluginuri; capitolul 2.22, Mediul de execuție al pluginurilor; și capitolul 2.23, Pachete de domeniu.
Cele șase elemente de bază
Iată-le în ordinea în care ar trebui să le luați în considerare.
- Setări și politici. Acestea sunt valori pe care un administrator le configurează în consolă pentru organizație, o unitate sau o singură persoană, în limitele permise de licență. Nu scrieți niciun rând de cod.
- Abilități Skills Engine. Un pachet
SKILL.mdcare conține instrucțiuni și instrumentele pe care abilitatea le poate apela, alături de fișiere și scripturi opționale. Asistentul, agenții, fluxurile de lucru și butoanele IA (inteligență artificială) de pe ecrane rulează toate aceleași abilități, la fel și mediul dumneavoastră de dezvoltare integrat (IDE). - Pluginuri. Propriul dumneavoastră cod, declarat printr-un manifest și construit cu instrumentele din SDK. Un plugin se încadrează într-unul dintre următoarele trei niveluri:
skills-only,ui-onlysaufull-service. - Pachete de domeniu. Lentilele (lenses) și șabloanele specifice unei industrii, abilitățile și modelul său de cunoștințe, conectorii și ecranele sale pentru telefon, licențiate ca o singură unitate. Adverant livrează zece astfel de pachete; vă puteți construi și propriile pachete.
- Lentile. Ceea ce vede un anumit rol în interiorul unui pachet sau al unei platforme. O lentilă restrânge o lentilă de bază și nu o lărgește niciodată.
- Conexiuni și conectori MCP. Instrumentele Model Context Protocol (MCP) pe care le publică un plugin sau prin care se conectează un instrument de programare bazat pe IA, precum și conectorii doar pentru citire (read-only) care aduc înregistrări din sistemele pe care le rulați deja.
Două expresii sunt folosite cu sensuri multiple, așa că le voi clarifica acum. O abilitate Skills Engine este un pachet SKILL.md din bibliotecă. O abilitate de manifest este un rând tipizat din tabloul skills[] al unui plugin, compilat în registrul de abilități al platformei și rulat prin UNO, motorul de fluxuri de lucru. Ambele sunt numite abilități (skills) pe ecran. Sunt scrise și guvernate diferit, iar această documentație precizează întotdeauna la care dintre ele se referă.
Ce poate face fiecare și ce nu poate face
Tabelul reprezintă versiunea pe scurt. Am inclus coloana „Ce nu poate face” în mod intenționat: fiecare limită este o proprietate a arhitecturii și fiecare dintre ele m-a salvat de la o problemă.
| Element de construcție | Ce poate face | Ce nu poate face | Cine îl creează |
|---|---|---|---|
| Setare sau politică | Modifică modul în care se comportă o funcționalitate la orice nivel, de la organizație până la o singură persoană; blochează o valoare; o deleagă către nivelurile inferioare; solicită aprobarea unei a doua persoane pentru o modificare | Să adauge un ecran sau o rută, să stocheze un tabel nou sau să inițieze un nou tip de activitate | Un administrator, în consolă |
| Abilitate Skills Engine | Oferă asistentului, agenților, fluxurilor de lucru și butoanelor IA o modalitate repetabilă de a îndeplini o sarcină, cu propriile instrucțiuni și cazuri de testare | Să păstreze acreditări; să apeleze un instrument din afara listei permise (allow-list) a persoanei care îl rulează (SKILL_CANNOT_WIDEN_TOOLS); să intre în producție fără teste și aprobare |
Oricine deține acest drept, în instrumentul de creare sau din propriul IDE |
Plugin, skills-only |
Publică abilități de manifest care rulează pe platformă: apeluri inverse (callbacks) către gazdă, sarcini în coadă, mapări peste o listă și, la nivelul de încredere core sau verified, abilități bazate pe modele |
Să servească pagini proprii | Un dezvoltator, cu ajutorul SDK-ului |
Plugin, ui-only |
Adaugă o suprafață frontend în interiorul interfeței cadru (shell) | Să stocheze date proprii sau să execute procese de calcul | Un dezvoltator, cu ajutorul SDK-ului |
Plugin, full-service |
Propriul backend și frontend, o schemă Postgres, un tabel de rute cu drepturi, precum și abilități și instrumente MCP | Să apeleze un furnizor de modele; să păstreze o cheie de model; să citească rândurile altei organizații, cu excepția cazului în care există o autorizare înregistrată; să execute calcule în afara dispecerizării UNO | Un dezvoltator, cu ajutorul SDK-ului |
| Pachet de domeniu | Aduce lentilele și șabloanele unei industrii, abilitățile și fluxurile sale de lucru, un model de cunoștințe, o hartă a dovezilor și ecrane pentru telefon către unitățile alese de un administrator | Să modifice interfața cadru (shell) sau componentele acesteia, ori regulile de scriere; să ruleze fără a fi acoperit de licența organizației | Adverant sau propriii dumneavoastră dezvoltatori în ediția Enterprise |
| Lentilă | Alege cardurile și câmpurile pe care le vede un rol în interiorul unui pachet sau al unei platforme, precum și acțiunile pe care le oferă | Să afișeze orice element pe care lentila sa de bază îl ascunde (LENS_CANNOT_WIDEN); să modifice ceea ce are voie să facă un rol |
Autorul unui pachet o construiește; un administrator o acordă la nivel de unitate |
| Instrumente și conectori MCP | Expun instrumentele unui plugin către agenți și instrumente de programare; citesc înregistrări dintr-un sistem de politici sau dintr-o arhivă de telemetrie în modelul de cunoștințe | Să scrie înapoi în sistemul sursă printr-un conector; să acționeze dincolo de permisiunile proprii ale persoanei autentificate | Un dezvoltator declară instrumentele MCP; un administrator configurează conectorii |
Câteva dintre aceste celule merită o propoziție în plus.
Setările reprezintă un cadru de lucru (framework), iar fiecare plugin îl folosește pe același. Un plugin care declară un bloc settings în manifestul său primește nivelurile (platformă, organizație, pachet, unitate, grup, depozit, persoană), blocările și delegarea, un jurnal de modificări și aprobarea unei a doua persoane, toate acestea fără a scrie un tabel de setări. De aceea, cea mai ieftină treaptă este adesea suficientă: dacă comportamentul dorit există deja și are nevoie doar de o valoare diferită pentru unitatea din Rotterdam, atunci este o setare.
O abilitate Skills Engine rulează în numele persoanei. Nu păstrează niciodată o cheie, poate accesa doar instrumentele din lista permisă (allow-list) a persoanei care o rulează și poate citi doar ceea ce acea persoană are dreptul să deschidă. O abilitate care adaugă un instrument ce efectuează scrieri este reținută până când două persoane o aprobă, apoi intră în producție în modul shadow, apoi în modul canary, iar în final pentru toată lumea.
Un plugin skills-only reprezintă treapta de mijloc. Aveți nevoie de el atunci când activitatea constă în cod pe care îl dețineți: un calcul determinist, un proces de lucru în coadă (queue worker), o distribuire (fan-out) peste o listă. Platforma apelează codul dumneavoastră; codul dumneavoastră nu apelează niciodată un model.
Un plugin full-service este un mic produs. Deține o schemă Postgres, un tabel de rute cu un registru de drepturi, un frontend, un set de roluri de bază de date și toate obligațiile de izolare din capitolul 2.19, Regulile pe care le moștenește fiecare extensie. Este răspunsul corect mai des decât se tem oamenii și răspunsul greșit mai des decât speră aceștia.
De care am nevoie?
Începeți din partea de sus a acestui tabel și opriți-vă la primul rând care se potrivește.
| Doriți să… | Utilizați | De ce nu ceva mai simplu |
|---|---|---|
| Modificați o valoare sau o limită, ori cine are voie să facă ceva | O setare sau o politică | Nu există nimic mai simplu |
| Faceți asistentul să îndeplinească o sarcină în același mod de fiecare dată | O abilitate Skills Engine | O setare nu poate conține instrucțiuni |
| Puneți un „buton IA” pe un ecran care să ruleze acea sarcină | O abilitate Skills Engine asociată butonului | Un buton rulează doar abilități; nu este nimic de construit |
| Permiteți unui instrument de programare bazat pe IA să acceseze Nexus | O conexiune MCP prin Workbench | Nu este nimic de scris; persoana se autentifică prin propriul browser |
| Citiți înregistrări dintr-un sistem existent în modelul de cunoștințe | Un conector doar pentru citire (read-only) | Un conector nu scrie nimic înapoi, deci nu prezintă niciun risc la scriere |
| Rulați cod determinist pe care îl dețineți, conform programării platformei | Un plugin skills-only cu o abilitate host_callback sau plugin_queue |
O abilitate Skills Engine nu poate rula codul dumneavoastră |
| Adăugați unul sau două ecrane în interiorul interfeței cadru (shell) | Un plugin ui-only |
Doar pluginurile adaugă ecrane |
| Păstrați propriile înregistrări în spatele propriilor rute și drepturi | Un plugin full-service |
Doar acest nivel deține o schemă |
| Oferiți unui rol o vizualizare mai restrânsă a ecranelor specifice unei industrii | O lentilă aplicată unui pachet existent | O lentilă reprezintă date, nu cod |
| Aduceți modelul de cunoștințe și lentilele unei industrii, împreună cu ecrane pentru telefon, către mai multe unități | Un pachet de domeniu | Un plugin singur nu are lentile sau control de licență |
La Corrán Orbital, întrebarea legată de planificarea trecerilor a rămas o abilitate Skills Engine. Propagarea orbitei de care are nevoie a devenit un plugin skills-only cu o singură abilitate host_callback, deoarece calculul numeric ne aparține și trebuie să ofere același răspuns de două ori. Comisia noastră de analiză a anomaliilor a devenit un plugin full-service, deoarece păstrează propriile înregistrări despre cine a analizat fiecare deviație de telemetrie și ce a decis. Pachetul a venit la urmă, când o a doua unitate a dorit același lucru.
Cum se combină piesele
Elementele de construcție se compun de jos în sus. Un pachet de domeniu este cel mai clar exemplu, deoarece reprezintă un pachet format din celelalte elemente, plus un control de licență:
- un model de cunoștințe, tipurile de entități pe care le cunoaște industria și modul în care acestea se leagă, adesea construit pe baza unui model dintr-un alt pachet;
- lentile, câte una pentru fiecare rol, fiecare restrângând o lentilă de bază;
- șabloane și fluxuri de lucru, precum și abilitățile Skills Engine pe care le apelează;
- pluginuri, acolo unde pachetul are nevoie de cod propriu;
- conectori doar pentru citire (read-only) către sistemele care dețin deja înregistrările;
- un strat de suprapunere pentru mobil (mobile overlay) care stabilește ce carduri și pași de captură apar pe telefoane;
- și dreptul de utilizare (entitlement): grupurile de funcționalități pe care licența trebuie să le includă înainte ca oricare dintre aceste elemente să fie activat.
Nimic din toate acestea nu reprezintă infrastructură internă per aplicație. Pachetul nu livrează cod de izolare propriu, nici client de model și nicio verificare a licenței: le moștenește pe cele ale platformei. Acesta este subiectul capitolului următor și este motivul pentru care un autor de pachete de la o bancă și unul dintr-un port scriu aceeași cantitate de cod de securitate, adică deloc.
Niveluri de încredere
Fiecare plugin declară un nivel trust în manifestul său. Încrederea nu este o poartă de control pe care SDK-ul să o poată ocoli. Reprezintă metadate consultative pe care platforma le citește pentru a decide cât de izolat rulează contribuțiile unui plugin și care sunt cele mai sensibile date pe care le pot accesa abilitățile sale. Porțile de control active (clasificarea și rezidența datelor, exportul și cheltuielile) rămân exact acolo unde sunt.
| Încredere | Cui i se adresează | Postură de izolare | Plafon de clasificare |
|---|---|---|---|
core |
Cod primar (first-party) care este livrat împreună cu platforma | none: aceeași origine (same-origin), fără izolare suplimentară |
restricted |
verified |
O terță parte verificată, un editor verificat | Suprafață same-origin, abilități intermediate (brokered) |
restricted |
community |
O terță parte neverificată; valoarea implicită pentru un plugin nou | Suprafață sandboxed, abilități intermediate (brokered) |
tenant |
untrusted |
Orice element provenit dintr-o sursă necunoscută | strict: suprafață izolată (sandboxed), doar abilități intermediate, fără încredere din partea gazdei |
public |
Din acest tabel rezultă două reguli, iar create-nexus-plugin validate le impune pe amândouă înainte ca orice element să fie construit.
În primul rând, valoarea classification a unei abilități nu poate depăși plafonul pluginului său. Clasificările sunt ordonate astfel: public, apoi tenant, apoi restricted. Un plugin community care declară o abilitate restricted eșuează la compilare.
În al doilea rând, doar pluginurile core și verified pot declara abilități care accesează AI Provider Router. Acestea sunt nivelurile tool_using și llm_only. Un plugin community sau untrusted intermediază activități deterministe (host_callback, plugin_queue și map peste acestea) și solicită platformei să execute orice acțiune care necesită un model. Primul meu plugin a fost community și am pierdut o după-amiază încercând să declar o abilitate de rezumare llm_only înainte să înțeleg că refuzul era chiar scopul acestui mecanism.
Dacă omiteți trust, SDK-ul tratează pluginul drept community. Un câmp omis nu poate constitui niciodată o promovare la un nivel superior.
Nivelurile de izolare de la 1 la 4
Separat de nivelul de încredere, blocul runtime al manifestului indică modul în care rulează pluginul. isolationLevel este un număr întreg de la 1 la 4, iar modul de execuție decurge din acesta. Nu le alegeți pe cele două în mod independent: validatorul îl deduce pe unul din celălalt și refuză un manifest a cărui pereche nu corespunde.
isolationLevel |
executionMode |
Ce înseamnă |
|---|---|---|
| 1 | external_https |
Pluginul rulează în afara instalării și este accesat prin HTTPS |
| 2 | mcp_container |
Un container care expune instrumente MCP |
| 3 | hardened_docker |
Un container securizat (hardened) în propriile pod-uri ale pluginului; valoarea implicită a șablonului |
| 4 | firecracker |
Un microVM, cel mai puternic nivel de separare |
"runtime": {
"nodeVersion": "20",
"executionMode": "hardened_docker",
"isolationLevel": 3,
"entrypoint": "dist/server.js",
"healthCheck": "/health"
}entrypoint este obligatoriu. Punctele de intrare (entrypoints) sunt artefacte livrate și nu sunt niciodată preluate la momentul execuției (runtime): SDK-ul nu are nicio cale de import dinamic sau de încărcare de la distanță, astfel încât încrederea este consemnată și verificată o singură dată, apoi înghețată, niciodată descărcată.
La ce vă angajați pe fiecare treaptă
Fiecare treaptă de deasupra setărilor implică un cost de întreținere. Iată cât vă costă fiecare dintre ele.
- O abilitate Skills Engine are nevoie de cazuri de testare, de un revizor care să nu fiți dumneavoastră și de un istoric al versiunilor despre care veți fi întrebat atunci când nu funcționează corect. Aceiași octeți nu sunt publicați niciodată de două ori (
CONTENT_HASH_ALREADY_PUBLISHED), așa că „doar încarc-o din nou” nu este o soluție. - Un plugin are nevoie de un manifest al cărui tabel de rute să corespundă cu rutele pe care le înregistrează codul dumneavoastră, în ambele direcții. O rută care există, dar nu este declarată, reprezintă o eroare de conformitate, la fel și o rută declarată pe care codul nu o înregistrează niciodată.
- Un plugin
full-servicedeține o schemă cu cinci roluri de bază de date, securitate la nivel de rând (row-level security) impusă pe fiecare tabel și o secvență de pornire care refuză să asculte conexiuni până când baza de date nu demonstrează că bariera de izolare este activă. De asemenea, acesta reafirmă cele trei legi ale platformei în manifestul său, cuvânt cu cuvânt. - Un pachet de domeniu este licențiat. Acesta se activează câte o unitate pe rând, printr-un proiect pilot, iar licența organizației trebuie să îl includă. Nu dumneavoastră decideți dacă un client îl deține.
- O lentilă poate doar să elimine elemente. Dacă un rol are nevoie să vadă mai mult, trebuie modificată lentila de bază, ceea ce presupune o discuție cu persoana care deține acea bază.
Niciunul dintre aceste costuri nu poate fi negociat la nivel de aplicație, acesta fiind compromisul asumat. Renunțați la o parte din libertate la primul plugin și o recuperați la fiecare dintre următoarele.
CONNECTION_SCOPE_EXCEEDED.Instrumente și conexiuni MCP
MCP apare în trei locuri, iar acestea sunt ușor de confundat.
Un plugin poate publica instrumente MCP declarându-le în mcpTools[]: un name, un description și un inputSchema. Singura regulă pe care o adaugă validatorul este că un inputSchema nu poate utiliza un oneOf, allOf sau anyOf la nivel superior, deoarece un combinator în vârful schemei face ca fiecare client MCP care importă instrumentul să eșueze cu o eroare 400. Un plugin la nivelul isolationLevel 2 rulează ca un mcp_container.
Biblioteca Skills Engine este accesibilă prin MCP. Claude Code și agenții utilizează treisprezece instrumente MCP pentru a găsi și a potrivi abilități, a le rula și a înregistra execuția, precum și pentru a le crea, importa sau sincroniza, iar fiecare apel rulează în numele persoanei care l-a inițiat, în limitele listei sale permise (allow-list).
Iar un instrument de programare bazat pe IA se conectează prin Workbench: o singură adresă per instalare, o autentificare prin browserul persoanei, un permis valabil o oră în locul unei chei stocate și doar instrumentele pe care persoana respectivă le bifează. Capitolul 2.26, Construirea cu instrumente de programare bazate pe IA, prezintă acest proces pas cu pas.
Conectorii sunt vecinul mai discret. Modelul de cunoștințe al unui pachet de domeniu este alimentat de conectori doar pentru citire (read-only) către sisteme precum cele de administrare a polițelor sau de gestionare a daunelor, fiecare având o programare și un buton de testare. Nimic nu este scris înapoi în sursă.
Din ramura dvs. pe ecranele oamenilor
Indiferent pe ce treaptă vă aflați, ruta către producție este aceeași. Fiecare lansare trece din spațiul dumneavoastră de dezvoltare în mediul de staging, apoi către o unitate pilot, iar apoi către toate unitățile, fiecare pas având porți de control: teste, un manifest care nu și-a lărgit drepturile, o execuție de probă (dry run) pe o copie mascată a datelor și revizori desemnați care nu sunt autorul. O promovare care încearcă să sară peste un pas este refuzată cu GATE_CANNOT_BE_SKIPPED. Fiecare mediu păstrează versiunea anterioară timp de 30 de zile, iar revenirea unei unități la versiunea anterioară (rollback) este o modificare supusă revizuirii care durează aproximativ un minut.
Implementarea propriu-zisă se realizează exclusiv prin canalele de lansare ale instalării. Unitățile își aleg canalul, iar administratorul lor își dă acordul pentru fiecare trecere. Pe pagina Canale și instalări vedeți numărul de utilizări și ratele de eroare pe unitate, dar niciodată ce a făcut cineva cu extensia dumneavoastră. Capitolul 2.28, Lansarea extensiei dumneavoastră, acoperă întregul proces de lansare de la un capăt la altul.
O notă privind edițiile
Cea mai mare parte a acestei scări există în ambele ediții. Ediția Community oferă setări și abilități Skills Engine, pluginuri la fiecare nivel și aceleași căi optime (golden paths) pe un singur server, cu codul în propria dumneavoastră gazdă Git. Ediția Enterprise adaugă promovarea din spațiul de dezvoltare prin staging către o unitate pilot cu porțile sale de control, plus clustere de editori și copii mascate ale datelor din producție. De asemenea, adaugă propriul dumneavoastră catalog privat și pachete de domeniu. Capitolul 2.25, Construirea pentru fiecare ediție, conține toate detaliile.
Capitolul următor este cel pe care trebuie să îl citiți înainte de a scrie orice cod. Oferă puține opțiuni, dar multe reguli, iar regulile sunt aceleași și pentru prima extensie, și pentru a mia.



