InloggenBriefing plannen

Hoofdstuk 2.18

Het extensiemodel

De zes manieren om Nexus uit te breiden, van een instelling tot een domeinpakket, de grenzen van elk daarvan, en hoe vertrouwens- en isolatieniveaus bepalen waar uw code draait. Lees dit voordat u de software development kit (SDK) opent.

Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

16 minuten leestijd

Het eerste dat ik bij Corrán Orbital op Nexus bouwde, was geen plug-in. Ons vluchtdynamicateam wilde dat de assistent de vraag "welke grondstationpassages verliezen we als de Svalbard-antenne uitvalt voor onderhoud?" telkens in dezelfde vorm zou beantwoorden, met eerst de passagetabel en daaronder de kosten in contactminuten. Ik besteedde een halve dag aan het lezen van de software development kit (SDK) voordat een collega erop wees dat wat ik zocht een skill was: een map met een SKILL.md erin, geüpload naar de Skills Engine en gepubliceerd zodra de tests slaagden en een reviewer het goedkeurde. Het kostte veertig minuten.

Twee plug-ins en één domeinpakket later is dat nog steeds het eerste advies dat ik geef. Nexus biedt zes manieren om het uit te breiden, en deze vormen een ladder van oplopende inspanning. De onderste sporten doen meer dan mensen verwachten, en de bovenste brengen verplichtingen met zich mee die gemakkelijk te onderschatten zijn. Dit hoofdstuk zet deze ladder uiteen. Kies de laagste sport die de klus klaart. De volgende hoofdstukken gaan diep in op elk onderdeel: hoofdstuk 2.19, De regels die elke extensie erft; hoofdstuk 2.20, Skills; hoofdstuk 2.21, De Plugin SDK; hoofdstuk 2.22, De plug-in-runtime; en hoofdstuk 2.23, Domeinpakketten.

De zes bouwstenen

Hier staan ze in de volgorde waarin u ze zou moeten overwegen.

  1. Instellingen en beleidsregels. Dit zijn waarden die een beheerder in de console instelt voor de organisatie, een afdeling of één persoon, binnen wat de licentie toestaat. U schrijft helemaal geen code.
  2. Skills Engine-skills. Een SKILL.md-pakket met instructies en de tools die de skill mag aanroepen, met daarnaast optionele bestanden en scripts. De assistent, agents, workflows en de AI-knoppen (kunstmatige intelligentie) op schermen voeren allemaal dezelfde skills uit, en dat geldt ook voor uw IDE (integrated development environment).
  3. Plug-ins. Uw eigen code, gedeclareerd door een manifest en gebouwd met de tools van de SDK. Een plug-in is beschikbaar in een van de drie niveaus: skills-only, ui-only of full-service.
  4. Domeinpakketten. De lenzen en sjablonen van één sector, de bijbehorende skills en het kennismodel, de connectoren en de telefoonschermen, in licentie gegeven als één eenheid. Adverant levert er tien; u kunt uw eigen pakketten bouwen.
  5. Lenzen. Wat één rol ziet binnen een pakket of een platform. Een lens beperkt een basislens en verruimt deze nooit.
  6. MCP-verbindingen en connectoren. De Model Context Protocol (MCP)-tools die een plug-in publiceert of waarmee een AI-codeertool verbinding maakt, en de alleen-lezen connectoren die records binnenhalen uit systemen die u al gebruikt.

Twee begrippen worden vaak door elkaar gehaald, dus laat ik ze nu verduidelijken. Een Skills Engine-skill is een SKILL.md-pakket in de bibliotheek. Een manifest-skill is een getypeerde rij in de skills[]-array van een plug-in, gecompileerd in het skillregister van het platform en uitgevoerd via UNO, de workflow-engine. Beide worden op het scherm skills genoemd. Ze worden op verschillende manieren geschreven en beheerd, en deze documentatie vermeldt altijd welke van de twee wordt bedoeld.

Start iets nieuws
Start iets nieuws
Start iets nieuws biedt zes 'golden paths', één voor elk type extensie. Elk pad maakt een repository aan vanuit een sjabloon met versiebeheer en een manifest dat declareert wat het nodig heeft, en zet tests, een ontwikkelomgeving en datavertakkingen op.

Wat elk onderdeel wel en niet kan

De tabel is de korte versie. Ik heb de kolom "Wat het niet kan" er met opzet in gezet: elke limiet is een eigenschap van het ontwerp, en stuk voor stuk hebben ze mij wel een keer ergens voor behoed.

Bouwsteen Wat het kan Wat het niet kan Wie het maakt
Instelling of beleid Wijzigen hoe een functie zich gedraagt op elk niveau, van de organisatie tot aan één persoon; een waarde vergrendelen; deze naar beneden delegeren; vragen om een tweede persoon bij een wijziging Een scherm of een route toevoegen, een nieuwe tabel opslaan, of een nieuw soort werk starten Een beheerder, in de console
Skills Engine-skill De assistent en agents, workflows en AI-knoppen een herhaalbare manier geven om één taak uit te voeren, met eigen instructies en testcases Inloggegevens bewaren; een tool aanroepen buiten de allow-list van de persoon die deze uitvoert (SKILL_CANNOT_WIDEN_TOOLS); live gaan zonder de bijbehorende tests en goedkeuring Iedereen met het juiste recht, in de creator of vanuit hun IDE
Plug-in, skills-only Manifest-skills publiceren die op het platform draaien: host-callbacks, werk in de wachtrij, bewerkingen over een lijst en, bij vertrouwensniveau core of verified, door een model ondersteunde skills Eigen pagina's aanbieden Een ontwikkelaar, met de SDK
Plug-in, ui-only Een frontend-oppervlak toevoegen binnen de shell Eigen gegevens opslaan of rekenkracht uitvoeren Een ontwikkelaar, met de SDK
Plug-in, full-service Een eigen backend en frontend, een Postgres-schema, een routetabel met rechten, en skills en MCP-tools Een modelprovider aanroepen; een modelsleutel bewaren; rijen van een andere organisatie lezen behalve via een vastgelegde toestemming; rekenkracht uitvoeren buiten UNO-dispatch om Een ontwikkelaar, met de SDK
Domeinpakket De lenzen en sjablonen van een sector, de bijbehorende skills en workflows, een kennismodel, een bewijskaart en telefoonschermen naar de afdelingen brengen die een beheerder kiest De shell of de componenten ervan wijzigen, of de schrijfregels aanpassen; draaien zonder dat de licentie van de organisatie dit dekt Adverant, of uw eigen ontwikkelaars op Enterprise
Lens De kaarten en velden kiezen die één rol ziet binnen een pakket of platform, evenals de acties die worden aangeboden Iets tonen wat de basislens verbergt (LENS_CANNOT_WIDEN); wijzigen wat een rol mag doen Een pakketauteur bouwt het; een beheerder kent het toe per afdeling
MCP-tools en connectoren De tools van een plug-in beschikbaar stellen aan agents en codeertools; records lezen uit een polissysteem of een telemetrie-archief naar het kennismodel Terugschrijven naar het bronsysteem via een connector; handelen buiten de eigen machtigingen van de ingelogde persoon Een ontwikkelaar declareert MCP-tools; een beheerder stelt connectoren in

Een paar van die cellen verdienen een zin extra uitleg.

Instellingen vormen een raamwerk, en elke plug-in gebruikt hetzelfde raamwerk. Een plug-in die een settings-blok in zijn manifest declareert, krijgt de niveaus (platform, organisatie, pakket, afdeling, groep, repository, persoon), vergrendelingen en delegatie, een wijzigingslogboek en goedkeuring door een tweede persoon, allemaal zonder een instellingentabel te hoeven schrijven. Daarom is de onderste sport vaak al genoeg: als het gewenste gedrag al bestaat en alleen een andere waarde nodig heeft voor de afdeling Rotterdam, dan is het een instelling.

Een Skills Engine-skill draait namens de persoon. Het bewaart nooit een sleutel, kan alleen tools bereiken binnen de allow-list van degene die het uitvoert, en leest alleen wat die persoon mag openen. Een skill die een schrijvende tool toevoegt, wordt vastgehouden totdat twee personen deze goedkeuren, gaat daarna live in schaduwmodus, vervolgens in canary-modus en ten slotte voor iedereen.

Een skills-only-plug-in is de middelste sport. U heeft deze nodig wanneer het werk bestaat uit uw eigen code: een deterministische berekening, een queue-worker, een fan-out over een lijst. Het platform roept uw code aan; uw code roept nooit een model aan.

Een full-service-plug-in is een klein product op zich. Het bezit een Postgres-schema, een routetabel met een rechtenregister, een frontend, een reeks databaserollen en elke isolatieverplichting uit hoofdstuk 2.19, De regels die elke extensie erft. Het is vaker het juiste antwoord dan mensen vrezen en vaker het verkeerde antwoord dan mensen hopen.

Welke heb ik nodig?

Begin bovenaan deze tabel en stop bij de eerste rij die past.

U wilt… Gebruik Waarom niet iets lichters
Een waarde of een limiet wijzigen, of bepalen wie iets mag doen Een instelling of een beleid Er bestaat niets lichters
De assistent één taak elke keer op dezelfde manier laten uitvoeren Een Skills Engine-skill Een instelling kan geen instructies bevatten
Een "AI-knop" op een scherm plaatsen die deze taak uitvoert Een Skills Engine-skill gekoppeld aan de knop Een knop voert alleen skills uit; er hoeft niets gebouwd te worden
Een AI-codeertool toegang geven tot Nexus Een MCP-verbinding via de Workbench Niets te schrijven; de persoon logt in via de browser
Records lezen uit een bestaand systeem naar het kennismodel Een alleen-lezen connector Een connector schrijft niets terug en draagt dus geen schrijfrisico
Deterministische code die u zelf bezit uitvoeren volgens het schema van het platform Een skills-only-plug-in met een host_callback- of plugin_queue-skill Een Skills Engine-skill kan uw code niet uitvoeren
Een of twee schermen toevoegen binnen de shell Een ui-only-plug-in Alleen plug-ins voegen schermen toe
Uw eigen records bijhouden achter uw eigen routes en rechten Een full-service-plug-in Alleen dit niveau bezit een schema
Eén rol een beperktere weergave geven van de schermen voor een sector Een lens op een bestaand pakket Een lens bestaat uit gegevens, niet uit code
Het kennismodel en de lenzen van een sector, inclusief telefoonschermen, beschikbaar maken voor meerdere afdelingen Een domeinpakket Een plug-in alleen heeft geen lenzen of licentiepoort

Bij Corrán Orbital bleef de vraag over de passageplanning een Skills Engine-skill. De baanpropagatie die daarvoor nodig is, werd een skills-only-plug-in met één host_callback-skill, omdat het numerieke werk van ons is en twee keer hetzelfde antwoord moet opleveren. Onze beoordelingscommissie voor anomalieën werd een full-service-plug-in, omdat deze eigen records bijhoudt van wie naar welke telemetrie-afwijking heeft gekeken en wat er is besloten. Het pakket kwam als laatste, toen een tweede afdeling hetzelfde wilde.

Hoe de onderdelen combineren

De bouwstenen bouwen van onder naar boven op elkaar voort. Een domeinpakket is het duidelijkste voorbeeld, omdat het een bundeling is van de andere bouwstenen plus een licentiepoort:

  • een kennismodel, de soorten zaken die de sector kent en hoe deze samenhangen, vaak gebouwd op een basismodel uit een ander pakket;
  • lenzen, één per rol, die elk een basislens beperken;
  • sjablonen en workflows, en de Skills Engine-skills die ze aanroepen;
  • plug-ins waar het pakket eigen code nodig heeft;
  • alleen-lezen connectoren naar de systemen die de records al bevatten;
  • een mobiele overlay die bepaalt welke kaarten en vastleggingsstappen op telefoons verschijnen;
  • en het gebruiksrecht: de functiegroepen die de licentie moet bevatten voordat dit alles wordt ingeschakeld.
Teken een stapel horizontale banden. Onderaan "Nexus-kernfuncties" (assistent, bestanden, geheugen, taken) en daarnaast "UNO-dispatch" en "AI Provider Router". Daarboven een band "Plug-ins" met twee vakken, "skills-only" en "full-service", en een band "Skills Engine-skills". Daarboven een breed vak "Domeinpakket" met daarin vier kleinere vakken: "Kennismodel", "Lenzen", "Sjablonen en workflows", "Mobiele overlay". Links van het pakket een vak "Alleen-lezen connectoren" met een pijl naar "Kennismodel". Helemaal bovenaan drie afdelingsvakken ("Rotterdam", "Felixstowe", "Hoofdkantoor") met pijlen naar beneden vanuit het pakket met het label "lens toegekend per rol". Een hangslot op de rand van het pakket heeft het label "licentie: domain_packs".
Hoe een domeinpakket de andere bouwstenen bundelt.

Niets hiervan is technisch loodgieterswerk per app. Het pakket levert geen eigen isolatiecode, geen modelclient en geen licentiecontrole mee: het erft deze van het platform. Dat is het onderwerp van het volgende hoofdstuk, en het is de reden waarom een pakketauteur bij een bank en een bij een haven dezelfde hoeveelheid beveiligingscode schrijven, namelijk geen.

Domeinpakketten
Domeinpakketten
De pagina Domeinpakketten toont alle tien pakketten met wat elk pakket nodig heeft en waar het draait. Een pakket dat niet onder de licentie valt, blijft zichtbaar maar wordt grijs weergegeven, inclusief wat het nodig zou hebben.

Vertrouwensniveaus

Elke plug-in declareert een trust-niveau in zijn manifest. Vertrouwen is geen poort waar de SDK zich langs kan praten. Het is adviserende metadata die het platform leest om te beslissen hoe geïsoleerd de bijdragen van een plug-in draaien en wat de meest gevoelige gegevens zijn die de bijbehorende skills mogen aanraken. De actieve poorten (classificatie en dataverblijfplaats, export en uitgaven) blijven precies waar ze zijn.

Vertrouwen Voor wie het is Isolatiestatus Classificatieplafond
core First-party code die met het platform wordt meegeleverd none: same-origin, geen extra isolatie restricted
verified Een beoordeelde derde partij, een geverifieerde uitgever same-origin-oppervlak, bemiddelde skills restricted
community Een niet-beoordeelde derde partij; de standaard voor een nieuwe plug-in sandboxed-oppervlak, bemiddelde skills tenant
untrusted Alles van een onbekende bron strict: gesandboxt oppervlak, alleen bemiddelde skills, geen host-vertrouwen public

Uit die tabel volgen twee regels, en create-nexus-plugin validate dwingt ze allebei af voordat er iets wordt gebouwd.

Ten eerste mag de classification van een skill het plafond van zijn plug-in niet overschrijden. Classificaties lopen van public, naar tenant, naar restricted. Het bouwen van een community-plug-in die een restricted-skill declareert, zal mislukken.

Ten tweede mogen alleen core- en verified-plug-ins skills declareren die de AI Provider Router bereiken. Dat zijn de niveaus tool_using en llm_only. Een community- of untrusted-plug-in bemiddelt bij deterministisch werk (host_callback, plugin_queue, en map daarover) en vraagt het platform om alles te doen waarvoor een model nodig is. Mijn eerste plug-in was community, en ik verloor een middag met pogingen om een llm_only-samenvattingsskill te declareren voordat ik begreep dat de weigering juist de bedoeling was.

Als u trust weglaat, behandelt de SDK de plug-in als community. Een weggelaten veld kan nooit tot een verhoging van rechten leiden.

Isolatieniveaus 1 tot en met 4

Los van het vertrouwensniveau geeft het runtime-blok van het manifest aan hoe de plug-in draait. isolationLevel is een geheel getal van 1 tot 4, en de uitvoeringsmodus volgt daaruit. U kiest deze twee niet onafhankelijk van elkaar: de validator leidt de ene af uit de andere en weigert een manifest waarvan het paar niet overeenkomt.

isolationLevel executionMode Wat het betekent
1 external_https De plug-in draait buiten de installatie en wordt bereikt via HTTPS
2 mcp_container Een container die MCP-tools beschikbaar stelt
3 hardened_docker Een beveiligde (hardened) container in de eigen pods van de plug-in; de standaard van het sjabloon
4 firecracker Een microVM, de sterkste scheiding
"runtime": {
  "nodeVersion": "20",
  "executionMode": "hardened_docker",
  "isolationLevel": 3,
  "entrypoint": "dist/server.js",
  "healthCheck": "/health"
}

entrypoint is verplicht. Entrypoints zijn meegeleverde artefacten en worden nooit tijdens runtime opgehaald: de SDK heeft helemaal geen pad voor dynamische import of extern laden, dus vertrouwen wordt vastgelegd en één keer gecontroleerd, daarna bevroren en nooit gedownload.

Waar u op elk niveau voor tekent

Elke sport boven instellingen kost iets om te onderhouden. Hier ziet u wat elke sport u kost.

  • Een Skills Engine-skill vereist testcases, een reviewer die niet uzelf bent, en een versiegeschiedenis waarnaar u zult worden gevraagd wanneer de skill zich niet goed gedraagt. Dezelfde bytes worden nooit twee keer gepubliceerd (CONTENT_HASH_ALREADY_PUBLISHED), dus "gewoon opnieuw uploaden" is geen oplossing.
  • Een plug-in heeft een manifest nodig waarvan de routetabel overeenkomt met de routes die uw code registreert, in beide richtingen. Een route die bestaat maar niet is gedeclareerd, is een conformiteitsfout, en dat geldt ook voor een gedeclareerde route die de code nooit registreert.
  • Een full-service-plug-in bezit een schema met vijf databaserollen, afgedwongen beveiliging op rijniveau (row-level security) op elke tabel, en een opstartproces dat weigert te luisteren totdat de database bewijst dat de afscherming standhoudt. Het herhaalt ook de drie platformwetten in zijn manifest, woord voor woord.
  • Voor een domeinpakket geldt een licentie. Het wordt één afdeling tegelijk ingeschakeld, via een pilot, en de licentie van de organisatie moet het dekken. U bepaalt niet zelf of een klant het heeft.
  • Een lens kan alleen dingen weglaten. Als een rol meer moet zien, moet de basislens veranderen, wat neerkomt op een gesprek met de eigenaar van die basis.

Over geen van deze kosten valt per app te onderhandelen; dat is de wisselwerking. U levert wat vrijheid in bij de eerste plug-in en krijgt die terug bij elke volgende.

Een plug-in van derden installeren
Een plug-in van derden installeren
Het installeren van een plug-in van derden werkt net als app-machtigingen. Elke scope die het manifest declareert, wordt per afdeling toegekend of onthouden, en een aanroep voor iets dat niet is gedeclareerd, wordt geweigerd met CONNECTION_SCOPE_EXCEEDED.

MCP-tools en -verbindingen

MCP duikt op drie plaatsen op, en ze zijn gemakkelijk te verwarren.

Een plug-in kan MCP-tools publiceren door ze te declareren in mcpTools[]: een name, een description en een inputSchema. De enige regel die de validator toevoegt, is dat een inputSchema op het hoogste niveau geen oneOf, allOf of anyOf mag gebruiken, omdat een combinator boven in het schema ervoor zorgt dat elke MCP-client die de tool importeert, faalt met een 400-fout. Een plug-in op isolationLevel 2 draait als een mcp_container.

De bibliotheek van de Skills Engine is bereikbaar via MCP. Claude Code en agents gebruiken dertien MCP-tools om skills te vinden en te matchen, ze uit te voeren en de uitvoering vast te leggen, en ze aan te maken, te importeren of te synchroniseren, waarbij elke aanroep wordt uitgevoerd namens de persoon die deze heeft gestart, binnen diens allow-list.

En een AI-codeertool maakt verbinding via de Workbench: één adres per installatie, een aanmelding via de browser van de persoon, een pas voor één uur in plaats van een opgeslagen sleutel, en alleen de tools die deze persoon aanvinkt. Hoofdstuk 2.26, Bouwen met AI-codeertools, neemt dit stap voor stap door.

Connectoren zijn de stillere buren. Het kennismodel van een domeinpakket wordt gevoed door alleen-lezen connectoren naar systemen zoals een polisadministratie of een claimsysteem, elk met een tijdschema en een testknop. Er wordt niets teruggeschreven naar de bron.

Plug-ins en MCP-synchronisatie
Plug-ins en MCP-synchronisatie
Plug-ins en MCP-synchronisatie laat zien welke plug-ins skills leveren, welke synchronisaties in hun geheel zijn geweigerd, en welke dertien MCP-tools Claude Code en agents gebruiken om de bibliotheek te bereiken.

Van uw branch naar de schermen van gebruikers

Op welke sport u zich ook bevindt, de route naar productie is hetzelfde. Elke release gaat van uw ontwikkelomgeving naar staging, vervolgens naar een pilotafdeling en daarna naar alle afdelingen, waarbij elke stap poorten heeft: tests, een manifest dat niet is verruimd, een proefdraai op een gemaskeerde kopie en aangewezen reviewers die niet de auteur zijn. Een promotie die een stap probeert over te slaan, wordt geweigerd met GATE_CANNOT_BE_SKIPPED. Elke omgeving bewaart de vorige versie gedurende 30 dagen, en het terugzetten van één afdeling is een beoordeelde wijziging die ongeveer een minuut duurt.

De implementatie zelf verloopt uitsluitend via de releasekanalen van de installatie. Afdelingen kiezen hun kanaal en hun beheerder stemt in met elke stap. U ziet aantallen en foutpercentages per afdeling op de pagina Kanalen en installaties, maar nooit wat iemand met uw extensie heeft gedaan. Hoofdstuk 2.28, Uw extensie vrijgeven, behandelt de releasekant van begin tot eind.

Een opmerking over edities

Het grootste deel van deze ladder bestaat in beide edities. Community krijgt instellingen en Skills Engine-skills, plug-ins op elk niveau en dezelfde 'golden paths' op één server met code in uw eigen Git-host. Enterprise voegt daar de promotie van ontwikkelomgeving via staging naar een pilotafdeling met de bijbehorende poorten aan toe, plus uitgeversclusters en gemaskeerde kopieën van live gegevens. Het voegt ook uw eigen privécatalogus en domeinpakketten toe. Hoofdstuk 2.25, Bouwen voor elke editie, bevat de details.

Het volgende hoofdstuk moet u lezen voordat u enige code schrijft. Het biedt weinig keuzes maar veel regels, en die regels zijn hetzelfde voor de eerste extensie als voor de duizendste.