PrijavaRezervirajte prezentaciju

Poglavlje 2.18

Model proširenja

Šest načina za proširenje sustava Nexus, od postavke do domenskog paketa, ograničenja svakog od njih te kako razine povjerenja i izolacije odlučuju gdje se vaš kod izvršava. Pročitajte ovo prije nego što otvorite komplet za razvoj softvera (SDK).

Ovu je stranicu s engleskog izvornika preveo AI. Ako je išta nejasno, mjerodavna je stranica na engleskom jeziku. Pročitajte ovu stranicu na engleskom jeziku

16 min čitanja

Prva stvar koju sam izgradio na Nexusu u tvrtki Corrán Orbital nije bio dodatak. Naš tim za dinamiku leta želio je da asistent na pitanje „koje prelete zemaljskih postaja gubimo ako antena na Svalbardu ispadne iz rada zbog održavanja?” svaki put odgovori u istom obliku, prvo s tablicom preleta, a ispod toga s troškom u minutama kontakta. Proveo sam pola dana čitajući komplet za razvoj softvera (SDK) prije nego što mi je kolega ukazao na to da je ono što zapravo želim vještina: mapa s datotekom SKILL.md u sebi, učitana u Skills Engine i objavljena nakon što prođe testove i dobije odobrenje recenzenta. Trajalo je četrdeset minuta.

Dva dodatka i jedan domenski paket kasnije, to je i dalje prvi savjet koji dajem. Nexus ima šest načina za proširenje, a oni su poredani na ljestvici zahtjevnosti. Jeftinije stepenice čine više nego što ljudi očekuju, dok one skuplje nose obveze koje je lako podcijeniti. Ovo poglavlje prikazuje tu ljestvicu. Odaberite najnižu stepenicu koja obavlja posao. Poglavlja koja slijede detaljno obrađuju svaku od njih: poglavlje 2.19, Pravila koja nasljeđuje svako proširenje; poglavlje 2.20, Vještine; poglavlje 2.21, SDK za dodatke; poglavlje 2.22, Izvršno okruženje za dodatke; i poglavlje 2.23, Domenski paketi.

Šest građevnih blokova

Evo ih redoslijedom kojim biste ih trebali razmotriti.

  1. Postavke i pravila. To su vrijednosti koje administrator postavlja u konzoli za organizaciju, jedinicu ili jednu osobu, unutar onoga što licenca dopušta. Uopće ne pišete kod.
  2. Vještine u sklopu sustava Skills Engine. Paket SKILL.md koji sadrži upute i alate koje vještina smije pozivati, uz izborne datoteke i skripte pored njega. Asistent, agenti, tijekovi rada i gumbi za AI (umjetnu inteligenciju) na zaslonima pokreću iste vještine, a isto čini i vaše integrirano razvojno okruženje (IDE).
  3. Dodaci. Vaš vlastiti kod, deklariran manifestom i izgrađen pomoću alata iz SDK-a. Dodatak dolazi u jednoj od tri razine: skills-only, ui-only ili full-service.
  4. Domenski paketi. Leće i predlošci jedne industrije, njezine vještine i model znanja, njezini konektori i zasloni za telefone, licencirani kao cjelina. Adverant ih isporučuje deset; možete izgraditi i vlastite.
  5. Leće. Ono što jedna uloga vidi unutar paketa ili platforme. Leća sužava osnovnu leću i nikada je ne proširuje.
  6. MCP veze i konektori. Alati protokola Model Context Protocol (MCP) koje dodatak objavljuje ili putem kojih se povezuje AI alat za programiranje, te konektori samo za čitanje koji donose zapise iz sustava koje već koristite.

Dva se pojma preklapaju, pa ih razjasnimo odmah. Vještina u sklopu sustava Skills Engine je paket SKILL.md u biblioteci. Vještina iz manifesta je tipizirani redak u polju skills[] dodatka, preveden u registar vještina platforme i pokrenut kroz UNO, sustav za upravljanje tijekovima rada. Oboje se na zaslonu naziva vještinama. Pišu se i njima se upravlja na različite načine, a u ovoj je dokumentaciji uvijek navedeno na koju se misli.

Započnite nešto novo
Započnite nešto novo
Značajka Započnite nešto novo nudi šest preporučenih putova, po jedan za svaku vrstu proširenja. Svaki od njih stvara repozitorij iz verzioniranog predloška s manifestom koji deklarira što mu je potrebno te postavlja testove, razvojni prostor i podatkovne grane.

Što svaki od njih može, a što ne može

Tablica prikazuje kratku verziju. Stupac „Što ne može” uvrstio sam namjerno: svako ograničenje je svojstvo dizajna i svako me od njih spasilo od nečega.

Građevni blok Što može Što ne može Tko ga izrađuje
Postavka ili pravilo Promijeniti ponašanje značajke na bilo kojoj razini, od organizacije do pojedinca; zaključati vrijednost; delegirati je na nižu razinu; zatražiti odobrenje druge osobe pri promjeni Dodati zaslon ili rutu, pohraniti novu tablicu ili pokrenuti novu vrstu posla Administrator, u konzoli
Vještina u sklopu sustava Skills Engine Pružiti asistentu i agentima, tijekovima rada i AI gumbima ponovljiv način za obavljanje jednog posla, s vlastitim uputama i testnim slučajevima Čuvati vjerodajnicu; pozvati alat izvan popisa dopuštenih alata osobe koja ga pokreće (SKILL_CANNOT_WIDEN_TOOLS); postati aktivan bez provedenih testova i odobrenja Svatko tko ima odgovarajuće pravo, u alatu za izradu ili iz vlastitog IDE-a
Dodatak, skills-only Objaviti vještine iz manifesta koje se izvršavaju na platformi: povratne pozive glavnog sustava, poslove u redu čekanja, mapiranja preko popisa i, na razini povjerenja core ili verified, vještine podržane modelom Posluživati vlastite stranice Razvojni inženjer, pomoću SDK-a
Dodatak, ui-only Dodati sučelje unutar ljuske Pohranjivati vlastite podatke ili izvršavati izračune Razvojni inženjer, pomoću SDK-a
Dodatak, full-service Vlastiti pozadinski sustav i sučelje, Postgres shema, tablica ruta s pravima te vještine i MCP alati Pozvati pružatelja modela; čuvati ključ modela; čitati retke druge organizacije osim putem zabilježenog odobrenja; izvršavati izračune izvan UNO raspoređivača Razvojni inženjer, pomoću SDK-a
Domenski paket Donijeti leće i predloške industrije, njezine vještine i tijekove rada, model znanja, mapu dokaza i zaslone za telefone u jedinice koje odabere administrator Promijeniti ljusku ili njezine komponente, ili pravila pisanja; raditi a da to nije pokriveno licencom organizacije Adverant ili vaši vlastiti razvojni inženjeri u izdanju Enterprise
Leća Odabrati kartice i polja koje jedna uloga vidi unutar paketa ili platforme te radnje koje joj se nude Prikazati bilo što što njezina osnovna leća skriva (LENS_CANNOT_WIDEN); promijeniti ono što uloga smije raditi Izrađuje je autor paketa; administrator je dodjeljuje po jedinici
MCP alati i konektori Izložiti alate dodatka agentima i alatima za programiranje; čitati zapise iz sustava pravila ili arhive telemetrije u model znanja Zapisivati natrag u izvorni sustav putem konektora; djelovati izvan vlastitih dopuštenja prijavljene osobe Razvojni inženjer deklarira MCP alate; administrator postavlja konektore

Nekoliko tih ćelija zaslužuje još pokoju rečenicu.

Postavke su radni okvir i svaki dodatak koristi isti. Dodatak koji u svom manifestu deklarira blok settings dobiva razine (platforma, organizacija, paket, jedinica, grupa, repozitorij, osoba), zaključavanja i delegiranje, zapisnik promjena i odobrenje druge osobe, a sve to bez pisanja tablice postavki. Zato je najjeftinija stepenica često dovoljna: ako ponašanje koje želite već postoji i samo treba drugačiju vrijednost za jedinicu u Rotterdamu, riječ je o postavci.

Vještina u sklopu sustava Skills Engine izvršava se u ime osobe. Nikada ne čuva ključ, može pristupiti samo alatima s popisa dopuštenih alata osobe koja je pokreće i čitati samo ono što ta osoba smije otvoriti. Vještina koja dodaje alat za zapisivanje zadržava se dok je ne odobre dvije osobe, zatim postaje aktivna u sjeni (shadow), potom u kanarinskom izdanju (canary), a tek onda za sve.

Dodatak skills-only je srednja stepenica. Potreban vam je kada posao predstavlja vaš vlastiti kod: deterministički izračun, radnik u redu čekanja, raspršivanje (fan-out) preko popisa. Platforma poziva vaš kod; vaš kod nikada ne poziva model.

Dodatak full-service je mali proizvod. Posjeduje Postgres shemu, tablicu ruta s registrom prava, korisničko sučelje, skup uloga baze podataka i svaku obvezu izolacije iz poglavlja 2.19, Pravila koja nasljeđuje svako proširenje. To je ispravan odgovor češće nego što se ljudi boje i pogrešan odgovor češće nego što se ljudi nadaju.

Koji mi je potreban?

Krenite od vrha ove tablice i zaustavite se na prvom retku koji odgovara vašim potrebama.

Želite… Koristite Zašto ne nešto jednostavnije
Promijeniti vrijednost ili ograničenje, ili odrediti tko smije nešto učiniti Postavku ili pravilo Ne postoji ništa jednostavnije
Navesti asistenta da jedan posao svaki put obavi na isti način Vještinu u sklopu sustava Skills Engine Postavka ne može sadržavati upute
Postaviti „AI gumb” na zaslon koji pokreće taj posao Vještinu u sklopu sustava Skills Engine povezanu s gumbom Gumb pokreće samo vještine; nema se što graditi
Omogućiti AI alatu za programiranje pristup Nexusu MCP vezu kroz Workbench Nema pisanja koda; osoba se prijavljuje putem svog preglednika
Čitati zapise iz postojećeg sustava u model znanja Konektor samo za čitanje Konektor ništa ne zapisuje natrag, pa ne nosi rizik zapisivanja
Pokretati vlastiti deterministički kod prema rasporedu platforme Dodatak skills-only s vještinom host_callback ili plugin_queue Vještina u sklopu sustava Skills Engine ne može pokretati vaš kod
Dodati zaslon ili dva unutar ljuske Dodatak ui-only Samo dodaci dodaju zaslone
Čuvati vlastite zapise iza vlastitih ruta i prava Dodatak full-service Samo ova razina posjeduje shemu
Dati jednoj ulozi uži prikaz zaslona određene industrije Leću na postojećem paketu Leća je podatak, a ne kod
Donijeti model znanja i leće određene industrije, sa zaslonima za telefone, u nekoliko jedinica Domenski paket Sam dodatak nema leće niti licencnu provjeru

U tvrtki Corrán Orbital pitanje planiranja preleta ostalo je vještina u sklopu sustava Skills Engine. Propagacija orbite koju ono zahtijeva postala je dodatak skills-only s jednom vještinom host_callback, jer je numerički izračun naš i mora dvaput dati isti odgovor. Naš odbor za reviziju anomalija postao je dodatak full-service, jer vodi vlastite zapise o tome tko je pregledao koje odstupanje u telemetriji i što je odlučeno. Paket je došao posljednji, kada je druga jedinica poželjela istu stvar.

Kako se dijelovi spajaju

Građevni blokovi slažu se prema gore. Domenski paket je najjasniji primjer jer predstavlja sklop ostalih blokova uz licencnu provjeru:

  • model znanja, vrste pojmova koje industrija poznaje i način na koji su povezani, često izgrađen na osnovnom modelu iz drugog paketa;
  • leće, po jedna za svaku ulogu, pri čemu svaka sužava osnovnu leću;
  • predlošci i tijekovi rada te vještine u sklopu sustava Skills Engine koje oni pozivaju;
  • dodaci na mjestima gdje paket treba vlastiti kod;
  • konektori samo za čitanje prema sustavima koji već čuvaju zapise;
  • mobilni sloj koji određuje koje se kartice i koraci unosa prikazuju na telefonima;
  • i ovlaštenje: grupe značajki koje licenca mora sadržavati prije nego što se bilo što od toga uključi.
Nacrtajte stog vodoravnih traka. Na dnu se nalaze „Osnovne značajke Nexusa” (asistent, datoteke, memorija, poslovi), a pored toga „UNO raspoređivač” i „AI Provider Router”. Iznad toga je traka „Dodaci” s dva okvira, „samo vještine (skills-only)” i „puna usluga (full-service)”, te traka „Vještine u sklopu sustava Skills Engine”. Iznad njih je široki okvir „Domenski paket” koji sadrži četiri manja okvira: „Model znanja”, „Leće”, „Predlošci i tijekovi rada”, „Mobilni sloj”. Lijevo od paketa nalazi se okvir „Konektori samo za čitanje” sa strelicom prema okviru „Model znanja”. Na vrhu su tri okvira jedinica („Rotterdam”, „Felixstowe”, „Središnjica”) sa strelicama prema dolje iz paketa koje nose oznaku „leća dodijeljena po ulozi”. Lokot na rubu paketa nosi oznaku „licenca: domain_packs”.
Kako domenski paket objedinjuje ostale građevne blokove.

Ništa od ovoga nije infrastruktura koja se gradi zasebno za svaku aplikaciju. Paket ne isporučuje vlastiti kod za izolaciju, vlastitog klijenta modela niti provjeru licence: on nasljeđuje one s platforme. To je tema sljedećeg poglavlja i razlog zašto autor paketa u banci i onaj u luci pišu istu količinu sigurnosnog koda – nimalo.

Domenski paketi
Domenski paketi
Stranica Domenski paketi navodi svih deset paketa s onim što svaki od njih treba i gdje se izvršava. Paket koji nije pokriven licencom ostaje naveden i zasivljen, uz prikaz onoga što bi mu bilo potrebno.

Razine povjerenja

Svaki dodatak u svom manifestu deklarira razinu povjerenja trust. Povjerenje nije prepreka koju SDK može zaobići pregovaranjem. To su savjetodavni metapodaci koje platforma čita kako bi odlučila koliko se izolirano izvršavaju doprinosi dodatka i koje najosjetljivije podatke njegove vještine smiju doticati. Aktivne kontrole (klasifikacija i rezidentnost podataka, izvoz i potrošnja) ostaju točno tamo gdje jesu.

Povjerenje Kome je namijenjen Stupanj izolacije Gornja granica klasifikacije
core Kod prve strane koji se isporučuje u sklopu platforme none: isto podrijetlo (same-origin), bez dodatne izolacije restricted
verified Recenzirana treća strana, verificirani izdavač Površina same-origin, posredovane vještine restricted
community Nerecenzirana treća strana; zadana vrijednost za novi dodatak Površina sandboxed, posredovane vještine tenant
untrusted Sve iz nepoznatog izvora strict: površina u sigurnosnom okruženju (sandbox), samo posredovane vještine, bez povjerenja glavnog sustava public

Iz te tablice proizlaze dva pravila, a create-nexus-plugin validate provodi oba prije nego što se išta izgradi.

Prvo, classification vještine ne može premašiti gornju granicu svog dodatka. Klasifikacije se rangiraju kao public, zatim tenant, pa restricted. Dodatak razine community koji deklarira vještinu razine restricted neće se uspjeti izgraditi.

Drugo, samo dodaci razine core i verified smiju deklarirati vještine koje pristupaju usmjerivaču AI Provider Router. To su razine tool_using i llm_only. Dodatak razine community ili untrusted posreduje u determinističkom poslu (host_callback, plugin_queue i map nad njima) i traži od platforme da obavi sve što zahtijeva model. Moj prvi dodatak bio je community, i izgubio sam cijelo poslijepodne pokušavajući deklarirati vještinu sažimanja llm_only prije nego što sam shvatio da je upravo to odbijanje bilo smisao sustava.

Ako izostavite trust, SDK tretira dodatak kao community. Izostavljeno polje nikada ne može rezultirati višom razinom prava.

Razine izolacije od 1 do 4

Neovisno o povjerenju, blok runtime u manifestu određuje kako se dodatak izvršava. isolationLevel je cijeli broj od 1 do 4, a način izvršavanja proizlazi iz njega. Ne birate ih neovisno: validator izvodi jedno iz drugoga i odbija manifest čiji se par ne podudara.

isolationLevel executionMode Što to znači
1 external_https Dodatak se izvršava izvan instalacije i pristupa mu se putem HTTPS-a
2 mcp_container Kontejner koji izlaže MCP alate
3 hardened_docker Ojačani kontejner u vlastitim podovima dodatka; zadana vrijednost predloška
4 firecracker MicroVM, najsnažnije odvajanje
"runtime": {
  "nodeVersion": "20",
  "executionMode": "hardened_docker",
  "isolationLevel": 3,
  "entrypoint": "dist/server.js",
  "healthCheck": "/health"
}

Polje entrypoint je obvezno. Ulazne točke su isporučeni artefakti i nikada se ne dohvaćaju u vremenu izvođenja: SDK uopće nema putanju za dinamički uvoz ili udaljeno učitavanje, tako da se povjerenje zapisuje i provjerava jednom, a zatim zamrzava, te se nikada ne preuzima naknadno.

Na što pristajete na svakoj stepenici

Svaka stepenica iznad postavki nosi određeni trošak održavanja. Evo koliko vas svaka od njih stoji.

  • Vještina u sklopu sustava Skills Engine zahtijeva testne slučajeve, recenzenta koji niste vi i povijest verzija o kojoj će vas pitati kada se vještina ne bude ponašala kako treba. Isti se bajtovi nikada ne objavljuju dvaput (CONTENT_HASH_ALREADY_PUBLISHED), pa „samo je ponovno učitaj” nije rješenje.
  • Dodatak zahtijeva manifest čija se tablica ruta podudara s rutama koje vaš kod registrira, u oba smjera. Ruta koja postoji, a nije deklarirana, predstavlja pogrešku sukladnosti, baš kao i deklarirana ruta koju kod nikada ne registrira.
  • Dodatak full-service posjeduje shemu s pet uloga baze podataka, prisilnu sigurnost na razini retka (row-level security) na svakoj tablici i proces pokretanja koji odbija slušati zahtjeve dok baza podataka ne dokaže da zaštitna ograda drži. Također u svom manifestu ponavlja tri zakona platforme, od riječi do riječi.
  • Domenski paket je licenciran. Uključuje se za jednu po jednu jedinicu, kroz pilot-projekt, i mora biti pokriven licencom organizacije. Vi ne možete samostalno odlučiti da ga korisnik ima.
  • Leća može samo oduzimati. Ako određena uloga treba vidjeti više, mora se promijeniti osnovna leća, što zahtijeva razgovor s vlasnikom te osnove.

Ni o jednom od ovih troškova ne može se pregovarati na razini pojedine aplikacije, u čemu i leži kompromis. Odričete se dijela slobode na prvom dodatku, ali vam se to vraća na svakom sljedećem.

Instalirajte dodatak treće strane
Instalirajte dodatak treće strane
Instaliranje dodatka treće strane funkcionira poput dopuštenja za aplikacije. Svaki opseg koji njegov manifest deklarira odobrava se ili uskraćuje po jedinici, a poziv za bilo što što nije deklarirano odbija se uz CONNECTION_SCOPE_EXCEEDED.

MCP alati i veze

MCP se pojavljuje na tri mjesta i lako ih je pomiješati.

Dodatak može objaviti MCP alate njihovim deklariranjem u polju mcpTools[]: name, description i inputSchema. Jedino pravilo koje validator dodaje jest da inputSchema ne smije koristiti oneOf, allOf ili anyOf na najvišoj razini, jer kombinator na vrhu sheme uzrokuje pogrešku 400 kod svakog MCP klijenta koji uveze taj alat. Dodatak na razini isolationLevel 2 izvršava se kao mcp_container.

Biblioteci sustava Skills Engine može se pristupiti putem MCP-a. Claude Code i agenti koriste trinaest MCP alata za pronalazak i usklađivanje vještina, njihovo pokretanje i bilježenje izvršavanja te za njihovo stvaranje, uvoz ili sinkronizaciju, pri čemu se svaki poziv izvršava u ime osobe koja ga je pokrenula, unutar njezina popisa dopuštenih alata.

Nadalje, AI alat za programiranje povezuje se kroz Workbench: jedna adresa po instalaciji, prijava putem preglednika osobe, jednosatna propusnica umjesto pohranjenog ključa i samo oni alati koje ta osoba označi. Poglavlje 2.26, Izgradnja pomoću AI alata za programiranje, detaljno prolazi kroz taj postupak.

Konektori su tiši susjed. Model znanja domenskog paketa puni se putem konektora samo za čitanje iz sustava kao što su sustavi za administraciju polica ili obradu odštetnih zahtjeva, pri čemu svaki ima svoj raspored i gumb za testiranje. Ništa se ne zapisuje natrag u izvor.

Dodaci i MCP sinkronizacija
Dodaci i MCP sinkronizacija
Značajka Dodaci i MCP sinkronizacija prikazuje koji dodaci donose vještine, koje su sinkronizacije u cijelosti odbijene te trinaest MCP alata koje Claude Code i agenti koriste za pristup biblioteci.

Od vaše grane do zaslona korisnika

Na kojoj god se stepenici nalazili, put do produkcije je isti. Svako izdanje kreće se iz vašeg razvojnog prostora u pripremno okruženje (staging), zatim u pilot-jedinicu, pa u sve jedinice, a svaki korak ima kontrolne točke: testove, manifest koji se nije proširio, probno pokretanje na maskiranoj kopiji i imenovane recenzente koji nisu autori. Promaknuće koje pokuša preskočiti korak odbija se uz GATE_CANNOT_BE_SKIPPED. Svako okruženje čuva prethodnu verziju 30 dana, a vraćanje jedne jedinice na staru verziju je recenzirana promjena koja traje oko minutu.

Sama implementacija odvija se isključivo putem kanala izdanja instalacije. Jedinice biraju svoj kanal, a njihov administrator pristaje na svaki pomak. Na stranici Kanali i instalacije vidite brojke i stope pogrešaka po jedinici, ali nikada što je tko radio s vašim proširenjem. Poglavlje 2.28, Objavljivanje vašeg proširenja, pokriva proces izdavanja od početka do kraja.

Napomena o izdanjima

Većina ove ljestvice postoji u oba izdanja. Izdanje Community dobiva postavke i vještine u sklopu sustava Skills Engine, dodatke na svim razinama i iste preporučene putove na jednom poslužitelju s kodom na vašem vlastitom Git poslužitelju. Izdanje Enterprise dodaje promaknuće iz razvojnog prostora kroz pripremno okruženje do pilot-jedinice s njezinim kontrolnim točkama, uz klastere izdavača i maskirane kopije produkcijskih podataka. Također dodaje vaš vlastiti privatni katalog i domenske pakete. Poglavlje 2.25, Izgradnja za pojedino izdanje, sadrži sve pojedinosti.

Sljedeće poglavlje je ono koje trebate pročitati prije nego što napišete imalo koda. U njemu ima malo izbora, a puno pravila, i ta su pravila ista za prvo i za tisućito proširenje.