Versio 1.0.0-alpha.1uusin
Luku 2.18
Laajennusmalli
Kuusi tapaa laajentaa Nexusta asetuksesta toimialapakettiin, kunkin rajoitukset sekä kuinka luottamus- ja eristystasot määräävät, missä koodisi suoritetaan. Lue tämä ennen kuin avaat ohjelmistokehityspaketin (SDK).
Tämä sivu on käännetty tekoälyllä englanninkielisestä alkuperäistekstistä. Jos jokin kohta on epäselvä, englanninkielinen sivu on ensisijainen lähde. Lue tämä sivu englanniksi

Ensimmäinen asia, jonka rakensin Nexukseen Corrán Orbitalilla, ei ollut lisäosa. Lentodynamiikkatiimimme halusi avustajan vastaavan kysymykseen ”mitkä maa-aseman ylilennot menetämme, jos Svalbardin antenni on poissa käytöstä huollon vuoksi?” joka kerta samassa muodossa: ylilento-taulukko ensin ja sen alla kustannus yhteysminuutteina. Vietin puoli päivää lukemalla ohjelmistokehityspakettia (SDK), ennen kuin kollega huomautti, että tarvitsemani asia oli taito (skill): kansio, jossa on SKILL.md, joka ladataan Skills Engineen ja julkaistaan, kun sen testit ovat menneet läpi ja tarkastaja on hyväksynyt sen. Siihen meni neljäkymmentä minuuttia.
Kaksi lisäosaa ja yhden toimialapaketin myöhemmin annan edelleen saman neuvon ensimmäisenä. Nexusta voi laajentaa kuudella tavalla, ja ne asettuvat työmäärän mukaisille tikapuille. Edulliset puolat tekevät enemmän kuin ihmiset odottavat, ja kalliisiin liittyy velvoitteita, jotka on helppo aliarvioida. Tässä luvussa esitellään nämä tikapuut. Valitse alin puola, joka hoitaa tehtävän. Seuraavissa luvuissa syvennytään kuhunkin: luku 2.19, Säännöt, jotka jokainen laajennus perii; luku 2.20, Taidot; luku 2.21, Plugin SDK; luku 2.22, Lisäosien ajonaikainen ympäristö; ja luku 2.23, Toimialapaketit.
Kuusi rakennuspalikkaa
Tässä ne ovat siinä järjestyksessä, jossa sinun tulisi harkita niitä.
- Asetukset ja käytännöt. Nämä ovat arvoja, jotka pääkäyttäjä asettaa konsolissa organisaatiolle, yksikölle tai yhdelle henkilölle sen puitteissa, mitä lisenssi sallii. Et kirjoita lainkaan koodia.
- Skills Enginen taidot.
SKILL.md-paketti, joka sisältää ohjeet ja työkalut, joita taito voi kutsua, sekä valinnaiset tiedostot ja komentosarjat sen rinnalla. Avustaja, agentit, työnkulut ja näyttöjen tekoälypainikkeet (AI, artificial intelligence) suorittavat kaikki samoja taitoja, ja niin tekee myös kehitysympäristösi (IDE, integrated development environment). - Lisäosat (Plugins). Omaa koodiasi, joka on määritelty manifestissa ja rakennettu SDK:n työkaluilla. Lisäosa kuuluu yhteen kolmesta tasosta:
skills-only,ui-onlytaifull-service. - Toimialapaketit (Domain packs). Yhden toimialan näkymälinssit ja mallipohjat, sen taidot ja tietomalli, sen liittimet ja puhelinnäkymät yhtenä kokonaisuutena lisensoituna. Adverant toimittaa kymmenen; voit rakentaa omasi.
- Näkymälinssit (Lenses). Mitä yksi rooli näkee paketin tai alustan sisällä. Näkymälinssi kaventaa peruslinssiä eikä koskaan laajenna sitä.
- MCP-yhteydet ja liittimet. Model Context Protocol (MCP) -työkalut, joita lisäosa julkaisee tai joiden kautta tekoälypohjainen koodaustyökalu yhdistää, sekä vain luku -liittimet, jotka tuovat tietueita jo käyttämistäsi järjestelmistä.
Kaksi sanaa kuormittuu liikaa, joten täsmennetään ne nyt. Skills Engine -taito on kirjastossa oleva SKILL.md-paketti. Manifestitaito on tyypitetty rivi lisäosan skills[]-taulukossa, joka käännetään alustan taitorekisteriin ja suoritetaan työnkulkumoottori UNOn kautta. Molempia kutsutaan näytöllä taidoiksi (skills). Ne kirjoitetaan ja niitä hallitaan eri tavoin, ja tässä dokumentaatiossa kerrotaan aina, kumpaa tarkoitetaan.
Mitä kukin voi tehdä ja mitä ei
Taulukko on lyhyt versio. Olen ottanut ”Mitä se ei voi tehdä” -sarakkeen mukaan tarkoituksella: jokainen rajoitus on suunnittelun ominaisuus, ja jokainen niistä on pelastanut minut joltakin.
| Rakennuspalikka | Mitä se voi tehdä | Mitä se ei voi tehdä | Kuka sen tekee |
|---|---|---|---|
| Asetus tai käytäntö | Muuttaa ominaisuuden toimintaa millä tahansa tasolla organisaatiosta yhteen henkilöön; lukita arvon; delegoida sen alaspäin; pyytää toista henkilöä hyväksymään muutoksen | Lisätä näytön tai reitin, tallentaa uuden taulun tai aloittaa uudenlaista työtä | Pääkäyttäjä, konsolissa |
| Skills Engine -taito | Antaa avustajalle ja agenteille, työnkuluille ja tekoälypainikkeille toistettavan tavan tehdä yksi tehtävä omilla ohjeillaan ja testitapauksillaan | Säilyttää tunnistetietoa; kutsua työkalua sitä suorittavan henkilön sallittujen listan (SKILL_CANNOT_WIDEN_TOOLS) ulkopuolelta; siirtyä tuotantoon ilman testejä ja hyväksyntää |
Kuka tahansa, jolla on oikeus, luontityökalussa tai omasta IDE-ympäristöstään |
Lisäosa, skills-only |
Julkaista manifestitaitoja, jotka suoritetaan alustalla: isäntäkutsuja (host callbacks), jonotettua työtä, listojen läpikäyntejä (maps) sekä luottamustasolla core tai verified tekoälymalliin perustuvia taitoja |
Tarjoilla omia sivujaan | Kehittäjä, SDK:n avulla |
Lisäosa, ui-only |
Lisätä käyttöliittymäpinnan kuoren (shell) sisään | Tallentaa omaa dataansa tai suorittaa laskentaa | Kehittäjä, SDK:n avulla |
Lisäosa, full-service |
Oma tausta- ja käyttöliittymäjärjestelmä, Postgres-skeema, reittitaulu oikeuksineen sekä taidot ja MCP-työkalut | Kutsua mallintarjoajaa; pitää hallussaan malliavainta; lukea toisen organisaation rivejä muuten kuin kirjatun valtuutuksen kautta; suorittaa laskentaa UNO-välityksen ulkopuolella | Kehittäjä, SDK:n avulla |
| Toimialapaketti | Tuoda toimialan näkymälinssit ja mallipohjat, sen taidot ja työnkulut, tietomallin, todistekartan ja puhelinnäkymät pääkäyttäjän valitsemiin yksiköihin | Muuttaa kuorta tai sen komponentteja tai kirjoitussääntöjä; toimia ilman, että organisaation lisenssi kattaa sen | Adverant tai omat kehittäjäsi Enterprise-versiossa |
| Näkymälinssi | Valita kortit ja kentät, jotka yksi rooli näkee paketin tai alustan sisällä, sekä sen tarjoamat toiminnot | Näyttää mitään, minkä sen peruslinssi piilottaa (LENS_CANNOT_WIDEN); muuttaa sitä, mitä rooli saa tehdä |
Paketin tekijä rakentaa sen; pääkäyttäjä myöntää sen yksiköittäin |
| MCP-työkalut ja liittimet | Tuoda lisäosan työkalut agenttien ja koodaustyökalujen saataville; lukea tietueita käytäntöjärjestelmästä tai telemetria-arkistosta tietomalliin | Kirjoittaa takaisin lähdejärjestelmään liittimen kautta; toimia kirjautuneen henkilön omien käyttöoikeuksien ulkopuolella | Kehittäjä määrittelee MCP-työkalut; pääkäyttäjä määrittää liittimet |
Muutamat näistä soluista ansaitsevat vielä yhden virkkeen.
Asetukset ovat kehys, ja jokainen lisäosa käyttää samaa kehystä. Lisäosa, joka määrittelee settings-lohkon manifestissaan, saa tasot (alusta, organisaatio, paketti, yksikkö, ryhmä, koodivarasto, henkilö), lukitukset ja delegoinnin, muutoslokin ja toisen henkilön hyväksynnän – kaikki tämä kirjoittamatta asetustaulua. Siksi edullisin puola usein riittää: jos haluamasi toiminnallisuus on jo olemassa ja tarvitsee vain eri arvon Rotterdamin yksikölle, kyseessä on asetus.
Skills Engine -taito suoritetaan henkilönä. Se ei koskaan pidä hallussaan avainta, ja se voi käyttää vain sen suorittajan sallittujen listalla olevia työkaluja sekä lukea vain sitä, minkä kyseinen henkilö saa avata. Taito, joka lisää kirjoittavan työkalun, pidätetään, kunnes kaksi henkilöä hyväksyy sen, minkä jälkeen se siirtyy tuotantoon ensin varjotilassa (shadow), sitten kanariatilassa (canary) ja lopuksi kaikille.
skills-only-lisäosa on keskimmäinen puola. Tarvitset sitä, kun työ on omistamaasi koodia: deterministinen laskenta, jonotyöläinen tai hajautus listan yli (fan-out). Alusta kutsuu koodiasi; koodisi ei koskaan kutsu mallia.
full-service-lisäosa on pieni tuote. Se omistaa Postgres-skeeman, reittitaulun oikeusrekisterillä, käyttöliittymän, joukon tietokantaroolia ja jokaisen eristysvelvoitteen, jotka on kuvattu luvussa 2.19, Säännöt, jotka jokainen laajennus perii. Se on oikea vastaus useammin kuin ihmiset pelkäävät ja väärä vastaus useammin kuin ihmiset toivovat.
Mitä niistä tarvitsen?
Aloita tämän taulukon yläosasta ja pysähdy ensimmäiselle sopivalle riville.
| Haluat… | Käytä | Miksi ei jotain kevyempää |
|---|---|---|
| Muuttaa arvoa tai rajaa tai sitä, kuka saa tehdä jotakin | Asetusta tai käytäntöä | Mitään kevyempää ei ole olemassa |
| Saada avustajan tekemään yhden tehtävän samalla tavalla joka kerta | Skills Engine -taitoa | Asetus ei voi sisältää ohjeita |
| Laittaa näytölle ”tekoälypainikkeen”, joka suorittaa kyseisen tehtävän | Painikkeeseen sidottua Skills Engine -taitoa | Painike suorittaa vain taitoja; mitään rakennettavaa ei ole |
| Antaa tekoälypohjaisen koodaustyökalun saada yhteyden Nexukseen | MCP-yhteyttä Workbenchin kautta | Ei mitään kirjoitettavaa; henkilö kirjautuu sisään selaimensa kautta |
| Lukea tietueita olemassa olevasta järjestelmästä tietomalliin | Vain luku -liitintä | Liitin ei kirjoita mitään takaisin, joten siihen ei liity kirjoitusriskiä |
| Suorittaa omistamaasi determinististä koodia alustan aikataulun mukaisesti | skills-only-lisäosaa, jossa on host_callback- tai plugin_queue-taito |
Skills Engine -taito ei voi suorittaa koodiasi |
| Lisätä yhden tai kaksi näyttöä kuoren sisään | ui-only-lisäosaa |
Vain lisäosat lisäävät näyttöjä |
| Pitää omat tietueesi omien reittiesi ja oikeuksiesi takana | full-service-lisäosaa |
Vain tämä taso omistaa skeeman |
| Antaa yhdelle roolille kapeamman näkymän toimialan näyttöihin | Näkymälinssiä olemassa olevan paketin päällä | Näkymälinssi on dataa, ei koodia |
| Tuoda toimialan tietomallin ja näkymälinssit puhelinnäkymineen useisiin yksiköihin | Toimialapakettia | Pelkällä lisäosalla ei ole näkymälinssejä tai lisenssiporttia |
Corrán Orbitalilla ylilentoja koskeva suunnittelukysymys säilyi Skills Engine -taitona. Sen tarvitsemasta kiertoradan laskennasta (orbit propagation) tuli skills-only-lisäosa yhdellä host_callback-taidolla, koska numeerinen työ on meidän ja sen on annettava sama vastaus kahdesti. Poikkeamien arviointilautakunnastamme tuli full-service-lisäosa, koska se pitää omia tietueitaan siitä, kuka tarkasteli mitäkin telemetriapoikkeamaa ja mitä he päättivät. Paketti tuli viimeisenä, kun toinen yksikkö halusi saman asian.
Kuinka osat yhdistyvät
Rakennuspalikat yhdistyvät ylöspäin. Toimialapaketti on selkein esimerkki, koska se on kokoelma muita palikoita lisättynä lisenssiportilla:
- tietomalli, eli asiat, jotka toimiala tuntee, ja miten ne linkittyvät toisiinsa, usein rakennettuna toisen paketin perusmallin päälle;
- näkymälinssit, yksi roolia kohden, joista jokainen kaventaa peruslinssiä;
- mallipohjat ja työnkulut sekä Skills Engine -taidot, joita ne kutsuvat;
- lisäosat silloin, kun paketti tarvitsee omaa koodiaan;
- vain luku -liittimet järjestelmiin, joissa tietueet jo ovat;
- mobiilikerros (mobile overlay), joka määrittää, mitkä kortit ja tallennusvaiheet näkyvät puhelimissa;
- ja oikeutus (entitlement): ominaisuusryhmät, jotka lisenssin on katettava ennen kuin mikään näistä kytkeytyy päälle.
Mikään tästä ei ole sovelluskohtaista putkitusta. Paketti ei sisällä omaa eristyskoodia, omaa malliasiakasohjelmaa eikä lisenssitarkistusta: se perii ne alustalta. Se on seuraavan luvun aihe, ja se on syy siihen, miksi paketin tekijä pankissa ja paketin tekijä satamassa kirjoittavat saman määrän tietoturvakoodia – eli eivät lainkaan.
Luottamustasot
Jokainen lisäosa määrittelee manifestissaan trust-tason. Luottamus (trust) ei ole portti, jonka ohi SDK voisi puhua tiensä. Se on neuvoa-antavaa metatietoa, jota alusta lukee päättääkseen, kuinka eristettyinä lisäosan osat suoritetaan ja mikä on arkaluonteisinta dataa, johon sen taidot saavat koskea. Käytössä olevat portit (luokittelu ja sijainti, vienti ja kulutus) pysyvät täsmälleen paikoillaan.
| Luottamus | Kenelle se on tarkoitettu | Eristystaso | Luokittelukatto |
|---|---|---|---|
core |
Ensimmäisen osapuolen koodi, joka toimitetaan alustan mukana | none: sama alkuperä (same-origin), ei lisäeristystä |
restricted |
verified |
Tarkastettu kolmas osapuoli, vahvistettu julkaisija | same-origin-pinta, välitetyt taidot (brokered skills) |
restricted |
community |
Tarkastamaton kolmas osapuoli; oletusarvo uudelle lisäosalle | sandboxed-pinta, välitetyt taidot (brokered skills) |
tenant |
untrusted |
Mikä tahansa tuntemattomasta lähteestä tuleva | strict: hiekkalaatikoitu pinta, vain välitetyt taidot, ei isäntäluottamusta |
public |
Tuosta taulukosta seuraa kaksi sääntöä, ja create-nexus-plugin validate panee molemmat täytäntöön ennen kuin mitään rakennetaan.
Ensiksi, taidon classification ei voi ylittää sen lisäosan kattoa. Luokittelut asettuvat järjestykseen public, sitten tenant, sitten restricted. community-lisäosa, joka määrittelee restricted-taidon, epäonnistuu käännöksessä.
Toiseksi, vain core- ja verified-lisäosat saavat määritellä taitoja, jotka ottavat yhteyden AI Provider Routeriin. Nämä ovat tool_using- ja llm_only-tasot. community- tai untrusted-lisäosa välittää determinististä työtä (host_callback, plugin_queue ja map näiden yli) ja pyytää alustaa tekemään kaiken, mikä tarvitsee mallia. Ensimmäinen lisäosani oli community, ja hukkasin iltapäivän yrittäessäni määritellä llm_only-tiivistelmätaitoa ennen kuin ymmärsin, että hylkäys oli koko asian ydin.
Jos jätät trust-kentän pois, SDK käsittelee lisäosaa tasolla community. Pois jätetty kenttä ei voi koskaan korottaa tasoa.
Eristystasot 1–4
Luottamuksesta erillään manifestin runtime-lohko kertoo, miten lisäosa suoritetaan. isolationLevel on kokonaisluku väliltä 1–4, ja suoritustila määräytyy sen perusteella. Et valitse näitä kahta toisistaan riippumatta: validaattori johtaa toisen toisesta ja hylkää manifestin, jonka pari on ristiriidassa.
isolationLevel |
executionMode |
Mitä se tarkoittaa |
|---|---|---|
| 1 | external_https |
Lisäosa suoritetaan asennuksen ulkopuolella ja siihen otetaan yhteys HTTPS:n kautta |
| 2 | mcp_container |
Kontti, joka tuo MCP-työkalut saataville |
| 3 | hardened_docker |
Kovennettu kontti lisäosan omissa podeissa; mallipohjan oletusarvo |
| 4 | firecracker |
Mikrovirtuaalikone (microVM), vahvin eristys |
"runtime": {
"nodeVersion": "20",
"executionMode": "hardened_docker",
"isolationLevel": 3,
"entrypoint": "dist/server.js",
"healthCheck": "/health"
}entrypoint on pakollinen. Aloituspisteet (entrypoints) ovat toimitettuja artefakteja, eikä niitä koskaan haeta ajon aikana: SDK:ssa ei ole lainkaan dynaamista tuontia tai etälatauspolkua, joten luottamus kirjataan ylös ja tarkistetaan kerran, minkä jälkeen se jäädytetään, eikä sitä koskaan ladata verkosta.
Mihin sitoudut kullakin portaalla
Jokaisen asetusten yläpuolella olevan puolan ylläpito maksaa jotakin. Tässä on se, mitä kukin niistä sinulle maksaa.
- Skills Engine -taito tarvitsee testitapauksia, tarkastajan, joka et ole sinä, sekä versiohistorian, josta sinulta kysytään, kun se toimii väärin. Samoja tavuja ei koskaan julkaista kahdesti (
CONTENT_HASH_ALREADY_PUBLISHED), joten ”lataa se vain uudelleen” ei ole korjaus. - Lisäosa tarvitsee manifestin, jonka reittitaulu vastaa koodisi rekisteröimiä reittejä molempiin suuntiin. Reitti, joka on olemassa mutta jota ei ole määritelty, on vaatimustenmukaisuusvirhe, ja niin on myös määritelty reitti, jota koodi ei koskaan rekisteröi.
full-service-lisäosa omistaa skeeman, jossa on viisi tietokantaroolia, jokaiseen tauluun pakotettu rivitason suojaus (row-level security) sekä käynnistysprosessi, joka kieltäytyy kuuntelemasta, kunnes tietokanta todistaa suojauksen pitävän. Se myös toistaa alustan kolme lakia manifestissaan sanasta sanaan.- Toimialapaketti on lisensoitu. Se kytketään päälle yksi yksikkö kerrallaan pilottikokeilun kautta, ja organisaation lisenssin on katettava se. Sinä et saa päättää, onko asiakkaalla se.
- Näkymälinssi voi vain ottaa pois. Jos roolin on nähtävä enemmän, peruslinssin on muututtava, mikä tarkoittaa keskustelua kyseisen peruslinssin omistajan kanssa.
Mistään näistä kustannuksista ei voida neuvotella sovelluskohtaisesti, mikä on osa vaihtokauppaa. Luovut osasta vapautta ensimmäisen lisäosan kohdalla ja saat sen takaisin jokaisessa seuraavassa.
CONNECTION_SCOPE_EXCEEDED.MCP-työkalut ja -yhteydet
MCP esiintyy kolmessa paikassa, ja ne on helppo sekoittaa keskenään.
Lisäosa voi julkaista MCP-työkaluja määrittelemällä ne kohteessa mcpTools[]: name, description ja inputSchema. Ainoa sääntö, jonka validaattori lisää, on se, että inputSchema ei saa käyttää ylätason oneOf-, allOf- tai anyOf-rakennetta, koska skeeman huipulla oleva yhdistäjä saa jokaisen työkalun tuovan MCP-asiakasohjelman epäonnistumaan virheellä 400. Lisäosa, jonka isolationLevel on 2, suoritetaan mcp_container-muodossa.
Skills Enginen kirjasto on saavutettavissa MCP:n yli. Claude Code ja agentit käyttävät kolmeatoista MCP-työkalua taitojen etsimiseen ja täsmäyttämiseen, niiden suorittamiseen ja suorituksen tallentamiseen sekä niiden luomiseen, tuomiseen tai synkronoimiseen, ja jokainen kutsu suoritetaan sen käynnistäneenä henkilönä hänen sallittujen listansa puitteissa.
Ja tekoälypohjainen koodaustyökalu yhdistää Workbenchin kautta: yksi osoite asennusta kohden, kirjautuminen henkilön selaimen kautta, tunnin voimassa oleva kulkulupa tallennetun avaimen sijaan ja vain ne työkalut, jotka kyseinen henkilö valitsee. Luku 2.26, Rakentaminen tekoälypohjaisilla koodaustyökaluilla, käy tämän läpi.
Liittimet ovat hiljaisempi naapuri. Toimialapaketin tietomallia syötetään vain luku -liittimillä järjestelmiin, kuten vakuutuskannan hallintaan tai korvausjärjestelmään, joista jokaisella on aikataulu ja testipainike. Mitään ei kirjoiteta takaisin lähteeseen.
Omasta haarastasi käyttäjien näytöille
Olitpa millä puolalla tahansa, reitti tuotantoon on sama. Jokainen julkaisu siirtyy kehitystilastasi (dev space) testiympäristöön (staging), sitten pilottiyksikköön ja lopuksi kaikkiin yksiköihin, ja jokaisessa vaiheessa on portit: testit, manifesti, joka ei ole laajentunut, kuivaharjoitus maskatulla kopiolla sekä nimetyt tarkastajat, jotka eivät ole tekijöitä. Ylennys, joka yrittää hypätä vaiheen yli, hylätään virheellä GATE_CANNOT_BE_SKIPPED. Jokainen ympäristö säilyttää edellisen version 30 päivän ajan, ja yhden yksikön palauttaminen aiempaan versioon on tarkastettu muutos, joka vie noin minuutin.
Itse käyttöönotto tapahtuu vain asennuksen julkaisukanavien kautta. Yksiköt valitsevat kanavansa, ja niiden pääkäyttäjä hyväksyy jokaisen siirron. Näet määrät ja virhetasot yksiköittäin Kanavat ja asennukset -sivulla, mutta et koskaan sitä, mitä kukaan teki laajennuksellasi. Luku 2.28, Laajennuksen julkaiseminen, kattaa julkaisupuolen alusta loppuun.
Huomautus versioista
Suurin osa näistä tikapuista on olemassa molemmissa versioissa. Community sisältää asetukset ja Skills Engine -taidot, lisäosat kaikilla tasoilla sekä samat valmiit polut yhdellä palvelimella koodin ollessa omassa Git-palvelussasi. Enterprise lisää ylennyksen kehitystilasta testiympäristön kautta pilottiyksikköön portteineen sekä julkaisijaklusterit ja maskatut kopiot tuotantodatasta. Se lisää myös oman yksityisen katalogisi sekä toimialapaketit. Luku 2.25, Rakentaminen kullekin versiolle, sisältää yksityiskohdat.
Seuraava luku kannattaa lukea ennen kuin kirjoitat lainkaan koodia. Siinä on vähän valintoja ja paljon sääntöjä, ja säännöt ovat samat ensimmäiselle ja tuhannelle laajennukselle.



