Logg innBestill en gjennomgang

Kapittel 2.18

Utvidelsesmodellen

De seks måtene å utvide Nexus på, fra en innstilling til en domenepakke, grensene for hver av dem, og hvordan tillits- og isolasjonsnivåer avgjør hvor koden din kjører. Les dette før du åpner programvareutviklingssettet (SDK).

Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

16 minutter å lese

Det første jeg bygde på Nexus hos Corrán Orbital, var ikke en plugin. Teamet vårt for banedynamikk ønsket at assistenten skulle svare på «hvilke bakkestasjonspasseringer mister vi hvis Svalbard-antennen tas ned for vedlikehold?» på samme måte hver gang, med passeringstabellen først og kostnaden i kontaktminutter under. Jeg brukte en halv dag på å lese om programvareutviklingssettet (SDK-et) før en kollega påpekte at det jeg trengte, var en ferdighet (skill): en mappe med en SKILL.md i, lastet opp til Skills Engine og publisert så snart testene var bestått og en kontrollør hadde godkjent den. Det tok førti minutter.

To plugins og én domenepakke senere er det fortsatt dette rådet jeg gir først. Nexus har seks måter å utvide plattformen på, og de utgjør en stige etter arbeidsmengde. De rimelige trinnene gjør mer enn folk forventer, og de kostbare trinnene fører med seg forpliktelser som er lette å undervurdere. Dette kapittelet legger frem hele stigen. Velg det laveste trinnet som løser oppgaven. Kapitlene som følger, går i dybden på hvert trinn: kapittel 2.19, Reglene enhver utvidelse arver; kapittel 2.20, Ferdigheter; kapittel 2.21, Plugin-SDK-et; kapittel 2.22, Kjøremiljøet for plugins; og kapittel 2.23, Domenepakker.

De seks byggeklossene

Her er de i den rekkefølgen du bør vurdere dem.

  1. Innstillinger og retningslinjer. Dette er verdier en administrator angir i konsollen for organisasjonen, en enhet eller én enkeltperson, innenfor rammene av det lisensen tillater. Du skriver ingen kode i det hele tatt.
  2. Skills Engine-ferdigheter. En SKILL.md-pakke som inneholder instruksjoner og verktøyene ferdigheten kan kalle opp, med valgfrie filer og skript ved siden av. Assistenten, agenter, arbeidsflyter og KI-knappene (kunstig intelligens) på skjermbildene kjører alle de samme ferdighetene, og det samme gjør utviklingsmiljøet (IDE-et) ditt.
  3. Plugins. Din egen kode, deklarert av et manifest og bygd med verktøyene i SDK-et. En plugin kommer på ett av tre nivåer: skills-only, ui-only eller full-service.
  4. Domenepakker. Én bransjes linser og maler, dens ferdigheter og kunnskapsmodell, dens tilkoblinger og dens mobilskjermer, lisensiert som en samlet enhet. Adverant leverer ti; du kan bygge dine egne.
  5. Linser. Det én rolle ser inne i en pakke eller på en plattform. En linse snevrer inn en basislinse og utvider den aldri.
  6. MCP-forbindelser og tilkoblinger. Model Context Protocol-verktøyene (MCP) som en plugin publiserer eller et KI-kodeverktøy kobler til gjennom, og de skrivebeskyttede tilkoblingene som henter inn oppføringer fra systemer du allerede bruker.

To begreper brukes om flere ting, så la meg avklare dem nå. En Skills Engine-ferdighet er en SKILL.md-pakke i biblioteket. En manifestferdighet er en typet rad i en plugins skills[]-matrise, kompilert inn i plattformens ferdighetsregister og kjørt gjennom UNO, arbeidsflytmotoren. Begge kalles ferdigheter (skills) på skjermen. De skrives og styres ulikt, og denne dokumentasjonen oppgir alltid hvilken av dem det er snakk om.

Start noe nytt
Start noe nytt
Start noe nytt tilbyr seks anbefalte hovedspor (golden paths), ett for hver type utvidelse. Hvert spor oppretter et kodelager fra en versjonert mal med et manifest som deklarerer hva det trenger, og setter opp tester, et utviklingsområde og datagrener.

Hva hver enkelt kan gjøre, og hva den ikke kan

Tabellen er kortversjonen. Jeg har tatt med «kan ikke»-kolonnen med vilje: hver begrensning er en egenskap ved designet, og hver eneste en av dem har reddet meg fra noe.

Byggekloss Hva den kan gjøre Hva den ikke kan gjøre Hvem som lager den
Innstilling eller retningslinje Endre hvordan en funksjon oppfører seg på ethvert nivå fra organisasjonen og ned til én person; låse en verdi; delegere den nedover; kreve godkjenning fra en ekstra person ved en endring Legge til en skjerm eller en rute, lagre en ny tabell eller starte en ny type arbeid En administrator, i konsollen
Skills Engine-ferdighet Gi assistenten og agenter, arbeidsflyter og KI-knapper en repeterbar måte å utføre én jobb på, med egne instruksjoner og testtilfeller Oppbevare påloggingsinformasjon; kalle opp et verktøy utenfor tillatelseslisten til personen som kjører den (SKILL_CANNOT_WIDEN_TOOLS); settes i drift uten beståtte tester og godkjenning Alle med riktig rettighet, i opprettingsverktøyet eller fra eget IDE
Plugin, skills-only Publisere manifestferdigheter som kjører på plattformen: vertstilbakekall, arbeid i kø, tilordninger over en liste og, ved tillitsnivå core eller verified, modellstøttede ferdigheter Levere egne sider En utvikler, med SDK-et
Plugin, ui-only Legge til en brukergrensesnittflate inne i skallet Lagre egne data eller kjøre beregninger En utvikler, med SDK-et
Plugin, full-service Sin egen backend og frontend, et Postgres-skjema, en rutetabell med rettigheter samt ferdigheter og MCP-verktøy Kalle opp en modelleverandør; oppbevare en modellnøkkel; lese en annen organisasjons rader unntatt gjennom en registrert tildeling; kjøre beregninger utenom UNO-utsendelse En utvikler, med SDK-et
Domenepakke Tilføre en bransjes linser og maler, dens ferdigheter og arbeidsflyter, en kunnskapsmodell, et beviskart og mobilskjermer til enhetene en administrator velger Endre skallet eller dets komponenter, eller skrivereglene; kjøre uten at organisasjonens lisens dekker den Adverant, eller deres egne utviklere på Enterprise
Linse Velge kortene og feltene én rolle ser inne i en pakke eller plattform, samt handlingene den tilbyr Vise noe som basislinsen skjuler (LENS_CANNOT_WIDEN); endre hva en rolle har tillatelse til å gjøre En pakkeforfatter bygger den; en administrator tildeler den per enhet
MCP-verktøy og tilkoblinger Eksponere en plugins verktøy for agenter og kodeverktøy; lese oppføringer fra et polisesystem eller et telemetriarkiv inn i kunnskapsmodellen Skrive tilbake til kildesystemet gjennom en tilkobling; handle utover den påloggede personens egne tillatelser En utvikler deklarerer MCP-verktøy; en administrator setter opp tilkoblinger

Noen av disse rutene fortjener en setning til.

Innstillinger er et rammeverk, og hver plugin bruker det samme. En plugin som deklarerer en settings-blokk i manifestet sitt, får nivåene (plattform, organisasjon, pakke, enhet, gruppe, kodelager, person), låser og delegering, en endringslogg og godkjenning fra en ekstra person, helt uten å måtte skrive en innstillingstabell. Det er grunnen til at det rimeligste trinnet ofte er nok: hvis atferden du ønsker allerede finnes og bare trenger en annen verdi for Rotterdam-enheten, er det en innstilling.

En Skills Engine-ferdighet kjører som personen. Den oppbevarer aldri en nøkkel, og den kan bare nå verktøy innenfor tillatelseslisten til den som kjører den, og kun lese det denne personen har tilgang til å åpne. En ferdighet som legger til et verktøy som skriver, holdes tilbake til to personer godkjenner den, og settes deretter i drift i skyggemodus, så som kanariutgivelse, og til slutt for alle.

En skills-only-plugin er det midterste trinnet. Du trenger den når arbeidet er kode du eier selv: en deterministisk beregning, en køarbeider, en utgrening (fan-out) over en liste. Plattformen kaller opp koden din; koden din kaller aldri opp en modell.

En full-service-plugin er et lite produkt. Den eier et Postgres-skjema, en rutetabell med et rettighetsregister, en frontend, et sett med databaseroller og hver eneste isoleringsforpliktelse i kapittel 2.19, Reglene enhver utvidelse arver. Det er det riktige svaret oftere enn folk frykter, og det gale svaret oftere enn folk håper.

Hvilken trenger jeg?

Start øverst i denne tabellen og stopp ved den første raden som passer.

Du vil … Bruk Hvorfor ikke noe enklere
Endre en verdi eller en grense, eller hvem som kan gjøre noe En innstilling eller en retningslinje Det finnes ikke noe enklere
Få assistenten til å utføre én jobb på samme måte hver gang En Skills Engine-ferdighet En innstilling kan ikke inneholde instruksjoner
Sette en «KI-knapp» på en skjerm som kjører den jobben En Skills Engine-ferdighet knyttet til knappen En knapp kjører kun ferdigheter; det er ingenting å bygge
La et KI-kodeverktøy nå Nexus En MCP-forbindelse gjennom Workbench Ingenting å skrive; personen logger på via nettleseren sin
Lese oppføringer fra et eksisterende system inn i kunnskapsmodellen En skrivebeskyttet tilkobling En tilkobling skriver ingenting tilbake, så den medfører ingen skriverisiko
Kjøre deterministisk kode du eier etter plattformens tidsplan En skills-only-plugin med en host_callback- eller plugin_queue-ferdighet En Skills Engine-ferdighet kan ikke kjøre koden din
Legge til en skjerm eller to inne i skallet En ui-only-plugin Kun plugins legger til skjermer
Oppbevare dine egne oppføringer bak dine egne ruter og rettigheter En full-service-plugin Kun dette nivået eier et skjema
Gi én rolle en mer begrenset visning av en bransjes skjermer En linse på en eksisterende pakke En linse er data, ikke kode
Tilføre en bransjes kunnskapsmodell og linser, med mobilskjermer, til flere enheter En domenepakke En plugin alene har ingen linser eller lisenssperre

Hos Corrán Orbital forble spørsmålet om passeringsplanlegging en Skills Engine-ferdighet. Banepropageringen den trenger, ble en skills-only-plugin med én host_callback-ferdighet, fordi det numeriske arbeidet er vårt og må gi samme svar to ganger. Utvalget vårt for avviksgjennomgang ble en full-service-plugin, fordi det fører sine egne registre over hvem som så på hvilket telemetriavvik og hva de bestemte. Pakken kom til slutt, da en annen enhet ønsket det samme.

Hvordan delene kombineres

Byggeklossene settes sammen oppover. En domenepakke er det tydeligste eksempelet, fordi den er en samling av de andre pluss en lisenssperre:

  • en kunnskapsmodell, hva slags ting bransjen kjenner til og hvordan de henger sammen, ofte bygd på en basismodell fra en annen pakke;
  • linser, én per rolle, der hver enkelt snevrer inn en basislinse;
  • maler og arbeidsflyter, og Skills Engine-ferdighetene de kaller opp;
  • plugins der pakken trenger sin egen kode;
  • skrivebeskyttede tilkoblinger mot systemene som allerede inneholder oppføringene;
  • et mobiloverlegg som bestemmer hvilke kort og registreringstrinn som vises på telefoner;
  • og rettigheten (entitlement): funksjonsgruppene lisensen må inneholde før noe av det slås på.
Tegn en stabel med horisontale bånd. Nederst, «Nexus-kjernefunksjoner» (assistent, filer, minne, jobber) og ved siden av «UNO-utsendelse» og «AI Provider Router». Over dette, et bånd «Plugins» med to bokser, «skills-only» og «full-service», og et bånd «Skills Engine-ferdigheter». Over disse, en bred boks «Domenepakke» som inneholder fire mindre bokser: «Kunnskapsmodell», «Linser», «Maler og arbeidsflyter», «Mobiloverlegg». Til venstre for pakken, en boks «Skrivebeskyttede tilkoblinger» med en pil inn i «Kunnskapsmodell». Øverst, tre enhetsbokser («Rotterdam», «Felixstowe», «Hovedkontor») med piler ned fra pakken merket «linse tildelt per rolle». En hengelås på kanten av pakken er merket «lisens: domain_packs».
Hvordan en domenepakke samler de andre byggeklossene.

Ingenting av dette er underliggende infrastruktur per app. Pakken leverer ingen egen isoleringskode, ingen modellklient og ingen lisenssjekk: den arver plattformens. Det er temaet for neste kapittel, og det er grunnen til at en pakkeforfatter i en bank og en i en havn skriver like mye sikkerhetskode, som er null.

Bransjepakker
Domenepakker
Siden Domenepakker lister opp alle de ti pakkene med hva hver enkelt trenger og hvor den kjører. En pakke som lisensen ikke dekker, blir stående i listen som nedtonet, med informasjon om hva den ville kreve.

Tillitsnivåer

Hver plugin deklarerer et trust-nivå i manifestet sitt. Tillit er ikke en port som SDK-et kan snakke seg forbi. Det er veiledende metadata som plattformen leser for å avgjøre hvor isolert en plugins bidrag skal kjøre, og hvor sensitive data ferdighetene dens kan berøre. De aktive portene (klassifisering og datalagringssted, eksport og forbruk) blir stående nøyaktig der de er.

Tillit Hvem det er for Isoleringsposisjon Klassifiseringstak
core Førstepartskode som leveres i plattformen none: samme opprinnelse (same-origin), ingen ekstra isolering restricted
verified En kontrollert tredjepart, en verifisert utgiver same-origin-flate, formidlede ferdigheter restricted
community En ukontrollert tredjepart; standarden for en ny plugin sandboxed-flate, formidlede ferdigheter tenant
untrusted Alt fra en ukjent kilde strict: sandkassebasert flate, kun formidlede ferdigheter, ingen vertstillit public

To regler følger av den tabellen, og create-nexus-plugin validate håndhever begge før noe som helst bygges.

For det første kan ikke en ferdighets classification overstige taket til pluginen den tilhører. Klassifiseringer rangeres som public, deretter tenant, deretter restricted. En community-plugin som deklarerer en restricted-ferdighet, feiler under bygging.

For det andre kan kun core- og verified-plugins deklarere ferdigheter som når AI Provider Router. Dette er nivåene tool_using og llm_only. En community- eller untrusted-plugin formidler deterministisk arbeid (host_callback, plugin_queue og map over disse) og ber plattformen om å gjøre alt som krever en modell. Min første plugin var community, og jeg mistet en ettermiddag på å prøve å deklarere en llm_only-oppsummeringsferdighet før jeg forsto at avvisningen var hele poenget.

Hvis du utelater trust, behandler SDK-et pluginen som community. Et utelatt felt kan aldri føre til en oppgradering av tillitsnivå.

Isolasjonsnivå 1 til 4

Uavhengig av tillit angir manifestets runtime-blokk hvordan pluginen kjører. isolationLevel er et heltall fra 1 til 4, og kjøremodusen følger av dette. Du velger ikke de to uavhengig av hverandre: validatoren utleder den ene fra den andre og avviser et manifest der paret ikke samsvarer.

isolationLevel executionMode Hva det betyr
1 external_https Pluginen kjører utenfor installasjonen og nås over HTTPS
2 mcp_container En konteiner som eksponerer MCP-verktøy
3 hardened_docker En herdet konteiner i pluginens egne podder; malens standardvalg
4 firecracker En mikro-VM, den sterkeste adskillelsen
"runtime": {
  "nodeVersion": "20",
  "executionMode": "hardened_docker",
  "isolationLevel": 3,
  "entrypoint": "dist/server.js",
  "healthCheck": "/health"
}

entrypoint er påkrevd. Inngangspunkter (entrypoints) er leverte artefakter og hentes aldri under kjøring: SDK-et har ingen sti for dynamisk import eller fjerninnlasting i det hele tatt, så tillit skrives ned og kontrolleres én gang, for deretter å fryses og aldri lastes ned.

Hva du forplikter deg til på hvert trinn

Hvert trinn over innstillinger koster noe å vedlikeholde. Her er hva hvert enkelt trinn koster deg.

  • En Skills Engine-ferdighet trenger testtilfeller, en kontrollør som ikke er deg, og en versjonshistorikk du vil bli spurt om når den oppfører seg feil. De samme bytene publiseres aldri to ganger (CONTENT_HASH_ALREADY_PUBLISHED), så «bare last den opp på nytt» er ikke en løsning.
  • En plugin trenger et manifest der rutetabellen samsvarer med rutene koden din registrerer, i begge retninger. En rute som eksisterer, men ikke er deklarert, er et samsvarsavvik, og det samme er en deklarert rute som koden aldri registrerer.
  • En full-service-plugin eier et skjema med fem databaseroller, sikkerhet på radnivå (RLS) påtvunget på hver tabell, og en oppstartsprosess som nekter å lytte før databasen beviser at gjerdet holder. Den gjentar også de tre plattformlovene i manifestet sitt, ord for ord.
  • En domenepakke er lisensiert. Den slås på for én enhet om gangen, gjennom en pilot, og organisasjonens lisens må dekke den. Du kan ikke selv bestemme at en kunde skal ha den.
  • En linse kan bare trekke fra. Hvis en rolle trenger å se mer, må basislinsen endres, noe som krever en samtale med den som eier den basisen.

Ingen av disse kostnadene kan forhandles per app, og det er selve byttehandelen. Du gir opp litt frihet på den første pluginen og får den tilbake på hver eneste en etterpå.

Installer en tredjeparts plugin
Installer en tredjeparts plugin
Å installere en tredjeparts plugin fungerer som apptillatelser. Hvert omfang (scope) som manifestet deklarerer, innvilges eller holdes tilbake per enhet, og et kall etter noe den ikke har deklarert, avvises med CONNECTION_SCOPE_EXCEEDED.

MCP-verktøy og -tilkoblinger

MCP dukker opp på tre steder, og det er lett å blande dem sammen.

En plugin kan publisere MCP-verktøy ved å deklarere dem i mcpTools[]: en name, en description og et inputSchema. Den ene regelen validatoren legger til, er at et inputSchema ikke kan bruke en oneOf, allOf eller anyOf på toppnivå, fordi en kombinator øverst i skjemaet får hver eneste MCP-klient som importerer verktøyet, til å feile med en 400. En plugin på isolationLevel 2 kjører som en mcp_container.

Biblioteket i Skills Engine kan nås over MCP. Claude Code og agenter bruker tretten MCP-verktøy til å finne og matche ferdigheter, kjøre dem og registrere kjøringen, samt opprette, importere eller synkronisere dem, og hvert kall kjører som personen som startet det, innenfor vedkommendes tillatelsesliste.

Og et KI-kodeverktøy kobler til gjennom Workbench: én adresse per installasjon, en pålogging gjennom personens nettleser, et adgangspass på én time i stedet for en lagret nøkkel, og kun de verktøyene personen krysser av for. Kapittel 2.26, Bygge med KI-kodeverktøy, gjennomgår dette.

Tilkoblinger er den mer lavmælte naboen. En domenepakkes kunnskapsmodell mates av skrivebeskyttede tilkoblinger mot systemer som poliseadministrasjon eller et skadebehandlingssystem, hver med en tidsplan og en testknapp. Ingenting skrives tilbake til kilden.

Plugins og MCP-synkronisering
Plugins og MCP-synkronisering
Plugins og MCP-synkronisering viser hvilke plugins som tilfører ferdigheter, hvilke synkroniseringer som ble avvist i sin helhet, og de tretten MCP-verktøyene Claude Code og agenter bruker for å nå biblioteket.

Fra grenen din til brukernes skjermer

Uansett hvilket trinn du er på, er veien til produksjon den samme. Hver utgivelse flyttes fra utviklingsområdet ditt til testmiljøet (staging), deretter til en pilotenhet, og så til alle enheter, og hvert trinn har kontrollporter: tester, et manifest som ikke har blitt utvidet, en prøvekjøring på en maskert kopi, og navngitte kontrollører som ikke er forfatteren. En forfremmelse som forsøker å hoppe over et trinn, avvises med GATE_CANNOT_BE_SKIPPED. Hvert miljø beholder den forrige versjonen i 30 dager, og å rulle én enhet tilbake er en kontrollert endring som tar omtrent et minutt.

Selve utrullingen går utelukkende gjennom installasjonens utgivelseskanaler. Enheter velger sin kanal, og administratoren deres godkjenner hver flytting. Du ser antall og feilrater per enhet på siden Kanaler og installasjoner, aldri hva noen har gjort med utvidelsen din. Kapittel 2.28, Utgivelse av utvidelsen din, dekker utgivelsesløpet fra start til slutt.

En merknad om utgaver

Det meste av denne stigen finnes i begge utgavene. Community får innstillinger og Skills Engine-ferdigheter, plugins på alle nivåer, og de samme anbefalte hovedsporene på én server med kode hos din egen Git-vert. Enterprise legger til forfremmelse fra utviklingsområdet via testmiljøet til en pilotenhet med tilhørende kontrollporter, pluss utgiverklynger og maskerte kopier av produksjonsdata. Den legger også til din egen private katalog, samt domenepakker. Kapittel 2.25, Bygge for hver utgave, inneholder detaljene.

Det neste kapittelet er det du bør lese før du skriver noe kode. Det har få valgmuligheter og mange regler, og reglene er de samme for den første utvidelsen som for den tusende.