Prihlásiť saRezervovať brífing

Kapitola 2.18

Model rozšírení

Šesť spôsobov, ako rozšíriť Nexus, od nastavenia až po doménový balík, obmedzenia každého z nich a to, ako úrovne dôvery a izolácie rozhodujú o tom, kde beží váš kód. Prečítajte si to skôr, než otvoríte sadu nástrojov na vývoj softvéru (SDK).

Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

16 min čítania

Prvá vec, ktorú som na platforme Nexus v spoločnosti Corrán Orbital vytvoril, nebol plugin. Náš tím letovej dynamiky chcel, aby asistent odpovedal na otázku „o ktoré prelety nad pozemnou stanicou prídeme, ak bude anténa na Svalbarde odstavená kvôli údržbe?“ zakaždým v rovnakom tvare, pričom najskôr mala byť tabuľka preletov a pod ňou náklady v minútach spojenia. Pol dňa som strávil čítaním sady pre vývoj softvéru (SDK), kým ma kolega neupozornil, že to, čo hľadám, je zručnosť (skill): priečinok so súborom SKILL.md, nahraný do Skills Engine a publikovaný po tom, čo prešli jeho testy a schválil ho recenzent. Trvalo to štyridsať minút.

O dva pluginy a jeden doménový balík neskôr je to stále rada, ktorú dávam ako prvú. Nexus ponúka šesť spôsobov rozšírenia, ktoré tvoria rebrík podľa náročnosti. Nízke priečky dokážu viac, než ľudia očakávajú, a tie drahé so sebou nesú záväzky, ktoré je ľahké podceniť. Táto kapitola tento rebrík predstavuje. Vyberte si najnižšiu priečku, ktorá splní danú úlohu. Nasledujúce kapitoly sa každej z nich venujú do hĺbky: kapitola 2.19, Pravidlá, ktoré dedí každé rozšírenie; kapitola 2.20, Zručnosti; kapitola 2.21, Plugin SDK; kapitola 2.22, Behové prostredie pluginov; a kapitola 2.23, Doménové balíky.

Šesť stavebných prvkov

Tu sú uvedené v poradí, v akom by ste ich mali zvažovať.

  1. Nastavenia a politiky. Ide o hodnoty, ktoré správca nastavuje v konzole pre organizáciu, organizačnú jednotku alebo jednu osobu v rámci toho, čo povoľuje licencia. Nepíšete vôbec žiadny kód.
  2. Zručnosti Skills Engine. Balík SKILL.md obsahujúci pokyny a nástroje, ktoré môže zručnosť volať, s voliteľnými súbormi a skriptami. Asistent, agenti, pracovné postupy a tlačidlá AI (umelej inteligencie) na obrazovkách spúšťajú tie isté zručnosti, a rovnako aj vaše IDE (integrované vývojové prostredie).
  3. Pluginy. Váš vlastný kód deklarovaný manifestom a zostavený pomocou nástrojov SDK. Plugin sa dodáva v jednej z troch úrovní: skills-only, ui-only alebo full-service.
  4. Doménové balíky. Pohľady (lenses) a šablóny jedného odvetvia, jeho zručnosti a znalostný model, jeho konektory a obrazovky pre telefóny, licencované ako jeden celok. Adverant ich dodáva desať; môžete si vytvoriť aj vlastné.
  5. Pohľady (Lenses). To, čo vidí jedna rola v rámci balíka alebo platformy. Pohľad zužuje základný pohľad a nikdy ho nerozširuje.
  6. MCP pripojenia a konektory. Nástroje protokolu Model Context Protocol (MCP), ktoré publikuje plugin alebo cez ktoré sa pripája nástroj na programovanie s AI, a konektory určené len na čítanie, ktoré prinášajú záznamy zo systémov, ktoré už prevádzkujete.

Dva pojmy sa často zamieňajú, preto ich hneď na úvod upresním. Zručnosť Skills Engine je balík SKILL.md v knižnici. Manifestová zručnosť je typizovaný riadok v poli skills[] pluginu, skompilovaný do registra zručností platformy a spúšťaný cez UNO, engine pracovných postupov. Obe sa na obrazovke nazývajú zručnosti (skills). Píšu a spravujú sa odlišne a táto dokumentácia vždy uvádza, ktorú z nich má na mysli.

Začať niečo nové
Začať niečo nové
Časť Začať niečo nové ponúka šesť osvedčených ciest (golden paths), jednu pre každý druh rozšírenia. Každá vytvorí repozitár z verzionovanej šablóny s manifestom, ktorý deklaruje, čo potrebuje, a nastaví testy, vývojový priestor a dátové vetvy.

Čo jednotlivé prvky dokážu a čo nie

Tabuľka predstavuje skrátenú verziu. Stĺpec „Čo nedokáže“ som pridal zámerne: každé obmedzenie je vlastnosťou návrhu a každé jedno z nich ma už pred niečím zachránilo.

Stavebný prvok Čo dokáže Čo nedokáže Kto ho vytvára
Nastavenie alebo politika Zmeniť správanie funkcie na akejkoľvek úrovni od organizácie až po jednotlivca; uzamknúť hodnotu; delegovať ju nižšie; vyžadovať schválenie druhou osobou pri zmene Pridať obrazovku alebo smerovanie (route), uložiť novú tabuľku alebo spustiť nový druh práce Správca v konzole
Zručnosť Skills Engine Poskytnúť asistentovi a agentom, pracovným postupom a tlačidlám AI opakovateľný spôsob vykonania jednej úlohy s vlastnými pokynmi a testovacími prípadmi Uchovávať prihlasovacie údaje; volať nástroj mimo zoznamu povolených položiek osoby, ktorá ho spúšťa (SKILL_CANNOT_WIDEN_TOOLS); prejsť do ostrej prevádzky bez testov a schválenia Ktokoľvek s príslušným oprávnením, v nástroji na tvorbu alebo zo svojho IDE
Plugin, skills-only Publikovať manifestové zručnosti, ktoré bežia na platforme: spätné volania hostiteľa, prácu vo fronte, mapovanie nad zoznamom a pri úrovni dôveryhodnosti core alebo verified aj zručnosti podporené modelom Poskytovať vlastné stránky Vývojár pomocou SDK
Plugin, ui-only Pridať frontendové rozhranie v rámci prostredia (shell) Ukladať vlastné dáta alebo spúšťať výpočty Vývojár pomocou SDK
Plugin, full-service Vlastný backend a frontend, schému Postgres, smerovaciu tabuľku s oprávneniami a zručnosti a nástroje MCP Volať poskytovateľa modelu; uchovávať kľúč k modelu; čítať riadky inej organizácie okrem prípadov so zaznamenaným udelením prístupu; spúšťať výpočty mimo dispečingu UNO Vývojár pomocou SDK
Doménový balík Priniesť pohľady a šablóny odvetvia, jeho zručnosti a pracovné postupy, znalostný model, mapu dôkazov a obrazovky pre telefóny do organizačných jednotiek, ktoré vyberie správca Zmeniť prostredie (shell) alebo jeho komponenty, prípadne pravidlá zápisu; bežať bez toho, aby ho pokrývala licencia organizácie Adverant alebo vaši vlastní vývojári v edícii Enterprise
Pohľad (Lens) Vybrať karty a polia, ktoré vidí jedna rola v rámci balíka alebo platformy, a akcie, ktoré ponúka Zobraziť čokoľvek, čo jeho základný pohľad skrýva (LENS_CANNOT_WIDEN); zmeniť to, čo môže rola robiť Autor balíka ho vytvorí; správca ho udeľuje pre jednotlivé organizačné jednotky
Nástroje a konektory MCP Sprístupniť nástroje pluginu agentom a programovacím nástrojom; čítať záznamy zo systému politík alebo archívu telemetrie do znalostného modelu Zapisovať späť do zdrojového systému cez konektor; konať nad rámec vlastných povolení prihlásenej osoby Vývojár deklaruje nástroje MCP; správca nastavuje konektory

Niekoľko z týchto buniek si zaslúži ešte jednu vetu.

Nastavenia sú framework a každý plugin používa ten istý. Plugin, ktorý vo svojom manifeste deklaruje blok settings, získa úrovne (platforma, organizácia, balík, jednotka, skupina, repozitár, osoba), zámky a delegovanie, denník zmien a schválenie druhou osobou – to všetko bez písania tabuľky nastavení. Preto často stačí najlacnejšia priečka: ak požadované správanie už existuje a potrebuje len inú hodnotu pre jednotku v Rotterdame, ide o nastavenie.

Zručnosť Skills Engine beží pod identitou danej osoby. Nikdy neuchováva kľúč a má dosah len na nástroje v zozname povolených položiek toho, kto ju spúšťa, a môže čítať len to, čo môže daná osoba otvoriť. Zručnosť, ktorá pridáva nástroj vykonávajúci zápis, je pozdržaná, kým ju neschvália dvaja ľudia, potom sa spustí v tieňovom režime (shadow), následne v kanárikovom režime (canary) a nakoniec pre všetkých.

Plugin skills-only predstavuje strednú priečku. Potrebujete ho vtedy, keď je prácou kód, ktorý vlastníte: deterministický výpočet, worker vo fronte, rozvetvenie (fan-out) nad zoznamom. Platforma volá váš kód; váš kód nikdy nevolá model.

Plugin full-service je malý produkt. Vlastní schému Postgres, smerovaciu tabuľku s registrom oprávnení, frontend, sadu databázových rolí a každú povinnosť izolácie uvedenú v kapitole 2.19, Pravidlá, ktoré dedí každé rozšírenie. Je to správne riešenie častejšie, než sa ľudia obávajú, a nesprávne riešenie častejšie, než ľudia dúfajú.

Ktorý z nich potrebujem?

Začnite na vrchu tejto tabuľky a zastavte sa na prvom riadku, ktorý vyhovuje.

Chcete… Použite Prečo nie niečo jednoduchšie
Zmeniť hodnotu alebo limit, prípadne to, kto môže niečo urobiť Nastavenie alebo politiku Nič jednoduchšie neexistuje
Dosiahnuť, aby asistent vykonával jednu úlohu zakaždým rovnakým spôsobom Zručnosť Skills Engine Nastavenie nemôže obsahovať pokyny
Umiestniť na obrazovku „tlačidlo AI“, ktoré túto úlohu spustí Zručnosť Skills Engine naviazanú na tlačidlo Tlačidlo spúšťa iba zručnosti; netreba nič programovať
Umožniť nástroju na programovanie s AI prístup do platformy Nexus Pripojenie MCP cez Workbench Netreba nič písať; osoba sa prihlási cez svoj prehliadač
Čítať záznamy z existujúceho systému do znalostného modelu Konektor určený len na čítanie Konektor nič nezapisuje späť, takže nenesie žiadne riziko zápisu
Spúšťať deterministický kód, ktorý vlastníte, podľa rozvrhu platformy Plugin skills-only so zručnosťou host_callback alebo plugin_queue Zručnosť Skills Engine nedokáže spustiť váš kód
Pridať jednu alebo dve obrazovky do prostredia (shell) Plugin ui-only Obrazovky pridávajú iba pluginy
Uchovávať vlastné záznamy za vlastnými smerovaniami a oprávneniami Plugin full-service Iba táto úroveň vlastní schému
Poskytnúť jednej role užší pohľad na obrazovky odvetvia Pohľad (lens) na existujúcom balíku Pohľad sú dáta, nie kód
Priniesť znalostný model a pohľady odvetvia vrátane obrazoviek pre telefóny do viacerých jednotiek Doménový balík Samotný plugin nemá pohľady ani licenčnú bránu

V spoločnosti Corrán Orbital zostala otázka plánovania preletov zručnosťou Skills Engine. Výpočet šírenia obežnej dráhy, ktorý potrebuje, sa stal pluginom skills-only s jednou zručnosťou host_callback, pretože numerická práca je naša a musí dať dvakrát rovnakú odpoveď. Naša komisia pre kontrolu anomálií sa stala pluginom full-service, pretože si vedie vlastné záznamy o tom, kto sa zaoberal ktorou telemetrickou odchýlkou a ako rozhodol. Balík prišiel na rad ako posledný, keď druhá jednotka chcela to isté.

Ako sa jednotlivé časti spájajú

Stavebné prvky sa skladajú smerom nahor. Doménový balík je najjasnejším príkladom, pretože ide o súbor ostatných prvkov plus licenčnú bránu:

  • znalostný model, teda druhy entít, ktoré odvetvie pozná, a spôsob ich prepojenia, často postavený na základnom modeli z iného balíka;
  • pohľady (lenses), jeden pre každú rolu, pričom každý zužuje základný pohľad;
  • šablóny a pracovné postupy a zručnosti Skills Engine, ktoré volajú;
  • pluginy tam, kde balík potrebuje vlastný kód;
  • konektory určené len na čítanie do systémov, ktoré už záznamy uchovávajú;
  • mobilná vrstva (overlay), ktorá určuje, ktoré karty a kroky zachytávania údajov sa zobrazia na telefónoch;
  • a oprávnenie (entitlement): skupiny funkcií, ktoré musí licencia obsahovať predtým, než sa čokoľvek z toho zapne.
Nakreslite stĺpec vodorovných pásov. Úplne dole „Základné funkcie Nexus“ (asistent, súbory, pamäť, úlohy) a vedľa toho „UNO dispečing“ a „AI Provider Router“. Nad tým pás „Pluginy“ s dvoma poľami, „iba zručnosti (skills-only)“ a „plná služba (full-service)“, a pás „Zručnosti Skills Engine“. Nad nimi široké pole „Doménový balík“ obsahujúce štyri menšie polia: „Znalostný model“, „Pohľady (Lenses)“, „Šablóny a pracovné postupy“, „Mobilná vrstva“. Naľavo od balíka pole „Konektory len na čítanie“ so šípkou do poľa „Znalostný model“. Navrchu tri polia organizačných jednotiek („Rotterdam“, „Felixstowe“, „Centrála“) so šípkami smerujúcimi nadol z balíka označenými „pohľad udelený podľa roly“. Visiaci zámok na okraji balíka je označený „licencia: domain_packs“.
Ako doménový balík združuje ostatné stavebné prvky.

Nič z toho nie je infraštruktúra budovaná pre každú aplikáciu zvlášť. Balík nedodáva žiadny vlastný izolačný kód, žiadneho klienta modelu ani žiadnu kontrolu licencií: dedí ich od platformy. To je témou nasledujúcej kapitoly a je to dôvod, prečo autor balíka v banke a autor v prístave napíšu rovnaké množstvo bezpečnostného kódu – čiže žiadny.

Odvetvové balíky
Doménové balíky
Stránka Doménové balíky uvádza všetkých desať balíkov spolu s tým, čo každý z nich potrebuje a kde beží. Balík, ktorý licencia nepokrýva, zostáva v zozname sivý s uvedením toho, čo by potreboval.

Úrovne dôvery

Každý plugin deklaruje vo svojom manifeste úroveň trust. Dôveryhodnosť nie je brána, ktorú by SDK dokázalo obísť. Ide o odporúčacie metadáta, ktoré platforma číta, aby rozhodla, ako izolovane pobežia príspevky pluginu a akých najcitlivejších údajov sa môžu jeho zručnosti dotknúť. Aktívne brány (klasifikácia a umiestnenie dát, export a výdavky) zostávajú presne tam, kde sú.

Dôveryhodnosť Pre koho je určený Postoj k izolácii Strop klasifikácie
core Kód prvej strany dodávaný priamo v platforme none: rovnaký pôvod (same-origin), žiadna dodatočná izolácia restricted
verified Skontrolovaná tretia strana, overený vydavateľ Rozhranie same-origin, sprostredkované (brokered) zručnosti restricted
community Neskontrolovaná tretia strana; predvolená hodnota pre nový plugin Rozhranie sandboxed, sprostredkované (brokered) zručnosti tenant
untrusted Čokoľvek z neznámeho zdroja strict: rozhranie v sandboxe, iba sprostredkované zručnosti, žiadna dôvera hostiteľa public

Z tejto tabuľky vyplývajú dve pravidlá a create-nexus-plugin validate vynucuje obe predtým, než sa čokoľvek zostaví.

Po prvé, classification zručnosti nemôže prekročiť strop svojho pluginu. Klasifikácie sa radia v poradí public, potom tenant, potom restricted. Plugin community, ktorý deklaruje zručnosť restricted, pri zostavovaní zlyhá.

Po druhé, iba pluginy core a verified môžu deklarovať zručnosti, ktoré pristupujú k AI Provider Router. Ide o úrovne tool_using a llm_only. Plugin community alebo untrusted sprostredkúva deterministickú prácu (host_callback, plugin_queue a map nad nimi) a o čokoľvek, čo potrebuje model, požiada platformu. Môj prvý plugin bol community a stratil som jedno popoludnie snahou deklarovať sumarizačnú zručnosť llm_only, kým som pochopil, že toto odmietnutie bolo zámerom.

Ak vynecháte trust, SDK považuje plugin za community. Vynechané pole nikdy nemôže viesť k povýšeniu úrovne.

Úrovne izolácie 1 až 4

Nezávisle od dôveryhodnosti blok runtime v manifeste určuje, ako plugin beží. isolationLevel je celé číslo od 1 do 4 a z neho vyplýva režim vykonávania. Tieto dve hodnoty si nevyberáte nezávisle: validátor odvodí jednu z druhej a odmietne manifest, ktorého dvojica sa nezhoduje.

isolationLevel executionMode Čo to znamená
1 external_https Plugin beží mimo inštalácie a pristupuje sa k nemu cez HTTPS
2 mcp_container Kontajner, ktorý sprístupňuje nástroje MCP
3 hardened_docker Zabezpečený (hardened) kontajner vo vlastných podoch pluginu; predvolená hodnota šablóny
4 firecracker MikroVM, najsilnejšie oddelenie
"runtime": {
  "nodeVersion": "20",
  "executionMode": "hardened_docker",
  "isolationLevel": 3,
  "entrypoint": "dist/server.js",
  "healthCheck": "/health"
}

Položka entrypoint je povinná. Vstupné body (entrypoints) sú dodávané artefakty a nikdy sa nenačítavajú za behu: SDK nemá vôbec žiadnu cestu pre dynamický import ani vzdialené načítanie, takže dôveryhodnosť sa zapíše a skontroluje raz, potom sa zmrazí a nikdy sa nesťahuje.

K čomu sa zaväzujete na jednotlivých stupňoch

Udržiavanie každej priečky nad nastaveniami niečo stojí. Tu je uvedené, čo vás každá z nich stojí.

  • Zručnosť Skills Engine potrebuje testovacie prípady, recenzenta, ktorým nie ste vy, a históriu verzií, na ktorú sa vás budú pýtať, keď sa začne správať nesprávne. Tie isté bajty sa nikdy nepublikujú dvakrát (CONTENT_HASH_ALREADY_PUBLISHED), takže „jednoducho to znova nahrať“ nie je riešením.
  • Plugin potrebuje manifest, ktorého smerovacia tabuľka sa zhoduje so smerovaniami, ktoré váš kód registruje, a to v oboch smeroch. Smerovanie, ktoré existuje, ale nie je deklarované, je zlyhaním zhody, a rovnako aj deklarované smerovanie, ktoré kód nikdy nezaregistruje.
  • Plugin full-service vlastní schému s piatimi databázovými rolami, zabezpečením na úrovni riadkov (row-level security) vynúteným pre každú tabuľku a štartovacím procesom, ktorý odmietne počúvať, kým databáza nepreukáže, že ohraničenie drží. Vo svojom manifeste tiež od slova do slova opätovne potvrdzuje tri zákony platformy.
  • Doménový balík je licencovaný. Zapína sa postupne po jednotlivých organizačných jednotkách prostredníctvom pilotnej prevádzky a musí ho pokrývať licencia organizácie. Vy nerozhodujete o tom, či ho zákazník má.
  • Pohľad (lens) môže iba uberať. Ak rola potrebuje vidieť viac, musí sa zmeniť základný pohľad, čo si vyžaduje dohodu s tým, kto daný základ vlastní.

O žiadnom z týchto nákladov sa nedá vyjednávať pre jednotlivé aplikácie, čo je podstatou tohto kompromisu. Pri prvom plugine sa vzdáte časti slobody a pri každom ďalšom ju získate späť.

Inštalácia pluginu tretej strany
Inštalácia pluginu tretej strany
Inštalácia pluginu tretej strany funguje ako povolenia aplikácií. Každý rozsah (scope), ktorý jeho manifest deklaruje, sa udeľuje alebo odopiera pre jednotlivé organizačné jednotky a volanie čohokoľvek, čo nedeklaroval, sa odmietne s kódom CONNECTION_SCOPE_EXCEEDED.

Nástroje a pripojenia MCP

MCP sa objavuje na troch miestach a je ľahké si ich pomýliť.

Plugin môže publikovať nástroje MCP ich deklarovaním v mcpTools[]: name, description a inputSchema. Jediné pravidlo, ktoré validátor pridáva, je, že inputSchema nesmie na najvyššej úrovni používať oneOf, allOf ani anyOf, pretože kombinátor na vrchu schémy spôsobí, že každý klient MCP, ktorý nástroj importuje, zlyhá s chybou 400. Plugin na úrovni isolationLevel 2 beží ako mcp_container.

Knižnica Skills Engine je dostupná cez MCP. Claude Code a agenti používajú trinásť nástrojov MCP na vyhľadávanie a priraďovanie zručností, ich spúšťanie a zaznamenávanie behu a na ich vytváranie, importovanie alebo synchronizáciu, pričom každé volanie beží pod identitou osoby, ktorá ho spustila, v rámci jej zoznamu povolených položiek.

A nástroj na programovanie s AI sa pripája cez Workbench: jedna adresa na inštaláciu, prihlásenie cez prehliadač danej osoby, jednohodinový prístupový lístok namiesto uloženého kľúča a iba tie nástroje, ktoré daná osoba zaškrtne. Podrobne tým sprevádza kapitola 2.26, Vývoj s nástrojmi na programovanie s AI.

Konektory sú tichším susedom. Znalostný model doménového balíka je napájaný konektormi určenými len na čítanie do systémov, ako je správa poistných zmlúv alebo systém likvidácie poistných udalostí, pričom každý má svoj rozvrh a testovacie tlačidlo. Do zdroja sa nič nezapisuje späť.

Pluginy a synchronizácia MCP
Pluginy a synchronizácia MCP
Časť Pluginy a synchronizácia MCP ukazuje, ktoré pluginy prinášajú zručnosti, ktoré synchronizácie boli úplne odmietnuté, a trinásť nástrojov MCP, ktoré Claude Code a agenti používajú na prístup do knižnice.

Z vašej vetvy na obrazovky používateľov

Bez ohľadu na to, na ktorej priečke sa nachádzate, cesta do produkcie je rovnaká. Každé vydanie sa presúva z vášho vývojového priestoru do prostredia staging, potom do pilotnej jednotky a nakoniec do všetkých jednotiek, pričom každý krok má svoje brány: testy, manifest, ktorý sa nerozšíril, skúšobný beh (dry run) na maskovanej kópii a menovaných recenzentov, ktorí nie sú autormi. Povýšenie, ktoré sa pokúsi preskočiť krok, je odmietnuté s kódom GATE_CANNOT_BE_SKIPPED. Každé prostredie si uchováva predchádzajúcu verziu po dobu 30 dní a vrátenie jednej jednotky späť (rollback) je kontrolovaná zmena, ktorá trvá približne minútu.

Samotné nasadenie prebieha výlučne cez kanály vydaní (release channels) danej inštalácie. Jednotky si vyberajú svoj kanál a ich správca odsúhlasuje každý presun. Na stránke Kanály a inštalácie vidíte počty a mieru chybovosti pre jednotlivé jednotky, nikdy však to, čo niekto s vaším rozšírením robil. Kapitola 2.28, Vydávanie vášho rozšírenia, pokrýva celý proces vydávania od začiatku do konca.

Poznámka k edíciám

Väčšina tohto rebríka existuje v oboch edíciách. Edícia Community získava nastavenia a zručnosti Skills Engine, pluginy na každej úrovni a rovnaké osvedčené cesty (golden paths) na jednom serveri s kódom vo vašom vlastnom hostingu Git. Edícia Enterprise pridáva povýšenie z vývojového priestoru cez staging do pilotnej jednotky s príslušnými bránami, plus klastre vydavateľov a maskované kópie živých dát. Pridáva tiež váš vlastný súkromný katalóg a doménové balíky. Podrobnosti obsahuje kapitola 2.25, Vývoj pre jednotlivé edície.

Nasledujúcu kapitolu by ste si mali prečítať predtým, než napíšete akýkoľvek kód. Obsahuje málo možností výberu a veľa pravidiel, pričom pravidlá sú rovnaké pre prvé aj tisíce rozšírenie.