AutentificareProgramați o prezentare

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ă

16 minute de lectură

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.

  1. 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.
  2. Abilități Skills Engine. Un pachet SKILL.md care 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).
  3. 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-only sau full-service.
  4. 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.
  5. 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ă.
  6. 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ă.

Începeți ceva nou
Începeți ceva nou
Opțiunea „Începeți ceva nou” oferă șase căi optime (golden paths), câte una pentru fiecare tip de extensie. Fiecare creează un depozit (repository) dintr-un șablon versionat, cu un manifest care declară ce necesită, și configurează teste, un spațiu de dezvoltare și ramuri de date.

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.
Desenați o stivă de benzi orizontale. În partea de jos, „Funcționalități de bază Nexus” (asistent, fișiere, memorie, sarcini) și alături „Dispecerizare UNO” și „AI Provider Router”. Deasupra acesteia, o bandă „Pluginuri” cu două casete, „skills-only” și „full-service”, și o bandă „Abilități Skills Engine”. Deasupra acestora, o casetă lată „Pachet de domeniu” care conține patru casete mai mici: „Model de cunoștințe”, „Lentile”, „Șabloane și fluxuri de lucru”, „Strat de suprapunere pentru mobil”. În stânga pachetului, o casetă „Conectori doar pentru citire” cu o săgeată către „Model de cunoștințe”. În partea de sus, trei casete de unități („Rotterdam”, „Felixstowe”, „Sediu central”) cu săgeți în jos dinspre pachet, etichetate „lentilă acordată pe rol”. Un lacăt pe marginea pachetului este etichetat „licență: domain_packs”.
Modul în care un pachet de domeniu grupează celelalte elemente de construcție.

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.

Pachete de domeniu
Pachete de domeniu
Pagina Pachete de domeniu listează toate cele zece pachete, împreună cu cerințele fiecăruia și locul în care rulează. Un pachet care nu este acoperit de licență rămâne afișat în listă, dar inactiv (gri), indicând ce ar fi necesar pentru activare.

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-service deț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.

Instalarea unui plugin de la o terță parte
Instalarea unui plugin de la o terță parte
Instalarea unui plugin de la o terță parte funcționează asemenea permisiunilor pentru aplicații. Fiecare domeniu de aplicare (scope) declarat în manifestul său este acordat sau refuzat la nivel de unitate, iar un apel pentru orice element pe care nu l-a declarat este respins cu 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ă.

Pluginuri și sincronizarea MCP
Pluginuri și sincronizarea MCP
Secțiunea „Pluginuri și sincronizarea MCP” arată ce pluginuri aduc abilități, ce sincronizări au fost refuzate în întregime și cele treisprezece instrumente MCP pe care Claude Code și agenții le folosesc pentru a accesa biblioteca.

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.