Logi sisseBroneerige tutvustus

Peatükk 2.18

Laiendusmudel

Kuus viisi Nexuse laiendamiseks seadistusest kuni valdkonnapaketini, igaühe piirid ning kuidas usaldus- ja isolatsioonitasemed määravad, kus teie kood töötab. Lugege see läbi enne tarkvaraarenduskomplekti (SDK) avamist.

Selle lehe tõlkis AI ingliskeelsest originaalist. Kui miski jääb ebaselgeks, võtke aluseks ingliskeelne leht. Lugege seda lehte inglise keeles

16 minutit lugemist

Esimene asi, mille ma ettevõttes Corrán Orbital Nexuse peale ehitasin, ei olnud pistikprogramm. Meie lennudünaamika meeskond soovis, et assistent vastaks küsimusele „millised maajaama ülelennud me kaotame, kui Svalbardi antenn läheb hooldusesse?“ iga kord samal kujul: kõigepealt ülelendude tabel ja selle all kulu kontaktminutites. Veetsin pool päeva tarkvaraarenduskomplekti (SDK) lugedes, enne kui kolleeg juhtis tähelepanu sellele, et mul on tegelikult vaja oskust: kausta, milles on SKILL.md, mis on laaditud üles Skills Engine'isse ja avaldatud pärast seda, kui selle testid on läbitud ja ülevaataja on selle heaks kiitnud. Selleks kulus 40 minutit.

Kaks pistikprogrammi ja üks valdkonnapakett hiljem on see endiselt esimene nõuanne, mida ma annan. Nexuse laiendamiseks on kuus viisi ja need paiknevad pingutuse redelil. Odavad redelipulgad teevad rohkem, kui inimesed ootavad, ja kallitega kaasnevad kohustused, mida on lihtne alahinnata. See peatükk laotab selle redeli teie ette. Valige madalaim pulk, mis töö ära teeb. Järgmised peatükid käsitlevad igaüht neist süvitsi: peatükk 2.19, Reeglid, mille iga laiendus pärib; peatükk 2.20, Oskused; peatükk 2.21, Pistikprogrammide SDK; peatükk 2.22, Pistikprogrammide käituskeskkond; ja peatükk 2.23, Valdkonnapaketid.

Kuus ehitusplokki

Siin on need järjekorras, milles peaksite neid kaaluma.

  1. Seaded ja poliitikad. Need on väärtused, mille administraator määrab konsoolis organisatsiooni, üksuse või ühe isiku jaoks litsentsiga lubatud piires. Te ei kirjuta üldse koodi.
  2. Skills Engine'i oskused. SKILL.md pakett, mis sisaldab juhiseid ja tööriistu, mida oskus võib välja kutsuda, koos valikuliste failide ja skriptidega. Assistent, agendid, töövood ja ekraanidel olevad AI (tehisintellekti) nupud käitavad kõik samu oskusi ning seda teeb ka teie IDE (integreeritud arenduskeskkond).
  3. Pistikprogrammid. Teie enda kood, mis on deklareeritud manifestiga ja ehitatud SDK tööriistadega. Pistikprogramm kuulub ühte kolmest tasemest: skills-only, ui-only või full-service.
  4. Valdkonnapaketid. Ühe tegevusala vaated ja mallid, selle oskused ja teadmusmudel, konnektorid ja telefoniekraanid, mis on litsentsitud tervikuna. Adverant tarnib neid kümme; te võite ehitada ka enda oma.
  5. Vaated. See, mida üks roll paketi või platvormi sees näeb. Vaade kitsendab baasvaadet ega laienda seda kunagi.
  6. MCP-ühendused ja konnektorid. Mudeli kontekstiprotokolli (MCP) tööriistad, mida pistikprogramm avaldab või mille kaudu AI-põhine kodeerimistööriist ühendub, ning kirjutuskaitstud konnektorid, mis toovad kirjeid sisse süsteemidest, mida te juba kasutate.

Kahte mõistet kiputakse üle koormama, seega täpsustan need kohe. Skills Engine'i oskus on SKILL.md pakett teegis. Manifesti oskus on tüpiseeritud rida pistikprogrammi skills[] massiivis, mis kompileeritakse platvormi oskuste registrisse ja käitatakse läbi UNO, mis on töövoomootor. Mõlemat nimetatakse ekraanil oskusteks. Neid kirjutatakse ja hallatakse erinevalt ning käesolev dokumentatsioon ütleb alati täpselt, kumba silmas peetakse.

Alusta midagi uut
Alusta midagi uut
„Alusta midagi uut“ pakub kuut kuldset teekonda, üks iga laiendusetüübi kohta. Igaüks neist loob versioonitud mallist hoidla koos manifestiga, mis deklareerib vajaliku, ning seadistab testid, arendusruumi ja andmeharud.

Mida igaüks saab teha ja mida mitte

Tabel on lühiversioon. Lisasin veeru „Mida see ei saa teha“ meelega: iga piirang on disaini omadus ja igaüks neist on mind millegi eest päästnud.

Ehitusplokk Mida see saab teha Mida see ei saa teha Kes selle loob
Seade või poliitika Muuta funktsiooni käitumist mis tahes tasemel organisatsioonist kuni ühe isikuni; lukustada väärtust; delegeerida seda allapoole; küsida muudatuse jaoks teise isiku kinnitust Lisada ekraani või marsruuti, salvestada uut tabelit või alustada uut tüüpi tööd Administraator, konsoolis
Skills Engine'i oskus Anda assistendile ja agentidele, töövoogudele ja AI-nuppudele korratav viis ühe töö tegemiseks koos oma juhiste ja testjuhtudega Hoida mandaati; kutsuda välja tööriista väljaspool seda käitava isiku lubatud nimekirja (SKILL_CANNOT_WIDEN_TOOLS); minna avalikuks ilma testide ja heakskiiduta Igaüks, kellel on vastav õigus, loojas või oma IDE-s
Pistikprogramm, skills-only Avaldada manifesti oskusi, mis töötavad platvormil: hosti tagasihelistamised, järjekorratööd, loendi kaardistamised ning usaldustasemel core või verified ka mudelipõhised oskused Serveerida oma lehti Arendaja, SDK-ga
Pistikprogramm, ui-only Lisada kesta sisse kasutajaliidese pinna Salvestada oma andmeid või käitada arvutusi Arendaja, SDK-ga
Pistikprogramm, full-service Oma tausta- ja esirakendus, Postgresi skeem, õigustega marsruuditabel ning oskused ja MCP-tööriistad Kutsuda välja mudelipakkujat; hoida mudeli võtit; lugeda teise organisatsiooni ridu, välja arvatud registreeritud loa kaudu; käitada arvutusi väljaspool UNO suunamist Arendaja, SDK-ga
Valdkonnapakett Tuua tegevusala vaated ja mallid, selle oskused ja töövood, teadmusmudeli, tõendite kaardi ja telefoniekraanid üksustesse, mille administraator valib Muuta kesta või selle komponente või kirjutamisreegleid; töötada ilma, et organisatsiooni litsents seda sisaldaks Adverant või teie enda arendajad Enterprise'is
Vaade Valida kaardid ja väljad, mida üks roll paketi või platvormi sees näeb, ning toimingud, mida see pakub Näidata midagi, mida selle baasvaade peidab (LENS_CANNOT_WIDEN); muuta seda, mida roll tohib teha Paketi autor ehitab selle; administraator annab selle üksuse kaupa
MCP-tööriistad ja konnektorid Teha pistikprogrammi tööriistad kättesaadavaks agentidele ja kodeerimistööriistadele; lugeda kirjeid poliitikasüsteemist või telemeetriaarhiivist teadmusmudelisse Kirjutada konnektori kaudu tagasi lähtesüsteemi; tegutseda väljaspool sisselogitud isiku enda õigusi Arendaja deklareerib MCP-tööriistad; administraator seadistab konnektorid

Mõned neist lahtritest väärivad veel üht lauset.

Seaded on raamistik ja iga pistikprogramm kasutab sedasama. Pistikprogramm, mis deklareerib oma manifestis settings ploki, saab tasemed (platvorm, organisatsioon, pakett, üksus, grupp, hoidla, isik), lukustused ja delegeerimise, muudatuste logi ja teise isiku heakskiidu – seda kõike ilma seadete tabelit kirjutamata. Seetõttu piisab sageli kõige odavamast redelipulgast: kui soovitud käitumine on juba olemas ja vajab Rotterdami üksuse jaoks lihtsalt teistsugust väärtust, on tegu seadega.

Skills Engine'i oskus töötab kasutaja nimel. See ei hoia kunagi võtit ning pääseb ligi ainult tööriistadele, mis on selle käivitaja lubatud nimekirjas, ja saab lugeda ainult seda, mida see isik tohib avada. Oskust, mis lisab kirjutava tööriista, hoitakse kinni, kuni kaks inimest selle heaks kiidavad, seejärel läheb see avalikuks varirežiimis, siis kanaarilinnu-režiimis ja seejärel kõigile.

skills-only pistikprogramm on keskmine redelipulk. Seda on vaja siis, kui tööks on teie enda kood: deterministlik arvutus, järjekorratööline, loendi hargnev töötlemine. Platvorm kutsub välja teie koodi; teie kood ei kutsu kunagi välja mudelit.

full-service pistikprogramm on väike toode. Sellele kuulub Postgresi skeem, õiguste registriga marsruuditabel, esirakendus, andmebaasi rollide komplekt ja kõik isoleerimiskohustused, mis on toodud peatükis 2.19, Reeglid, mille iga laiendus pärib. See on õige vastus sagedamini, kui kardetakse, ja vale vastus sagedamini, kui loodetakse.

Millist mul vaja on?

Alustage selle tabeli ülaosast ja peatuge esimesel real, mis sobib.

Te soovite… Kasutage Miks mitte midagi kergemat
Muuta väärtust või limiiti või seda, kes tohib midagi teha Seade või poliitika Midagi kergemat pole olemas
Panna assistent tegema ühte tööd iga kord samamoodi Skills Engine'i oskus Seade ei saa sisaldada juhiseid
Panna ekraanile „AI-nupp“, mis seda tööd käitab Nupuga seotud Skills Engine'i oskus Nupp käitab ainult oskusi; pole midagi ehitada
Lasta AI-põhisel kodeerimistööriistal Nexusega ühendust võtta MCP-ühendus läbi Workbenchi Pole midagi kirjutada; isik logib sisse oma brauseri kaudu
Lugeda kirjeid olemasolevast süsteemist teadmusmudelisse Kirjutuskaitstud konnektor Konnektor ei kirjuta midagi tagasi, seega ei kaasne sellega kirjutamisriski
Käitada teie enda deterministlikku koodi platvormi ajakava järgi skills-only pistikprogramm koos host_callback või plugin_queue oskusega Skills Engine'i oskus ei saa käitada teie koodi
Lisada kesta sisse üks või kaks ekraani ui-only pistikprogramm Ainult pistikprogrammid lisavad ekraane
Hoida oma kirjeid enda marsruutide ja õiguste taga full-service pistikprogramm Ainult sellel tasemel on oma skeem
Anda ühele rollile kitsam vaade tegevusala ekraanidest Vaade olemasoleval paketil Vaade on andmed, mitte kood
Tuua tegevusala teadmusmudel ja vaated koos telefoniekraanidega mitmesse üksusesse Valdkonnapakett Pistikprogrammil üksi pole vaateid ega litsentsiväravat

Ettevõttes Corrán Orbital jäi ülelendude planeerimise küsimus Skills Engine'i oskuseks. Orbiidi prognoosimine, mida see vajab, sai skills-only pistikprogrammiks ühe host_callback oskusega, kuna numbriline töö on meie oma ja peab andma kaks korda sama vastuse. Meie anomaaliate ülevaatamise nõukogust sai full-service pistikprogramm, sest see peab oma arvestust selle üle, kes millist telemeetria kõrvalekallet vaatas ja mida nad otsustasid. Pakett tuli viimasena, kui teine üksus soovis sedasama.

Kuidas osad omavahel kombineeruvad

Ehitusplokid liituvad suunaga alt üles. Valdkonnapakett on kõige selgem näide, sest see on teiste kogum pluss litsentsivärav:

  • teadmusmudel, tegevusalale teadaolevad nähtused ja nendevahelised seosed, mis on sageli ehitatud teise paketi baasmudelile;
  • vaated, üks iga rolli kohta, millest igaüks kitsendab baasvaadet;
  • mallid ja töövood ning Skills Engine'i oskused, mida need välja kutsuvad;
  • pistikprogrammid seal, kus pakett vajab oma koodi;
  • kirjutuskaitstud konnektorid süsteemidesse, mis juba hoiavad kirjeid;
  • mobiilne ülekattekiht, mis ütleb, millised kaardid ja sisestusetapid ilmuvad telefonides;
  • ja õigus: funktsioonigrupid, mida litsents peab sisaldama, enne kui midagi sellest sisse lülitub.
Joonistage horisontaalsete ribade virn. Allosas on „Nexuse põhifunktsioonid“ (assistent, failid, mälu, tööd) ja selle kõrval „UNO suunamine“ ning „AI Provider Router“. Selle kohal on riba „Pistikprogrammid“ kahe kastiga, „skills-only“ ja „full-service“, ning riba „Skills Engine'i oskused“. Nende kohal on lai kast „Valdkonnapakett“, mis sisaldab nelja väiksemat kasti: „Teadmusmudel“, „Vaated“, „Mallid ja töövood“, „Mobiilne ülekattekiht“. Paketist vasakul on kast „Kirjutuskaitstud konnektorid“, kust läheb nool kasti „Teadmusmudel“. Kõige peal on kolm üksuse kasti („Rotterdam“, „Felixstowe“, „Peakontor“), kuhu suunduvad paketist alla nooled sildiga „vaade antud rolli kaupa“. Paketi serval oleval tabalukul on silt „licence: domain_packs“.
Kuidas valdkonnapakett koondab teisi ehitusplokke.

Miski sellest pole rakendusepõhine taristu. Pakett ei tarni oma isoleerimiskoodi, mudeliklienti ega litsentsikontrolli: see pärib need platvormilt. See on järgmise peatüki teema ja põhjus, miks panga ja sadama paketi autorid kirjutavad täpselt sama palju turvakoodi – see tähendab null rida.

Valdkonnapaketid
Valdkonnapaketid (Domain packs)
Valdkonnapakettide lehel on loetletud kõik kümme paketti koos sellega, mida igaüks vajab ja kus see töötab. Pakett, mida litsents ei sisalda, jääb nimekirja hallina koos infoga, mida see vajaks.

Usaldustasemed

Iga pistikprogramm deklareerib oma manifestis trust taseme. Usaldus ei ole värav, millest SDK saaks end mööda rääkida. See on nõuandev metaandmestik, mida platvorm loeb, et otsustada, kui isoleeritult pistikprogrammi panused töötavad ja kui tundlikke andmeid selle oskused võivad puudutada. Reaalajas väravad (klassifikatsioon ja asukoht, eksport ja kulutused) jäävad täpselt sinna, kus nad on.

Usaldus Kellele see on mõeldud Isoleerituse hoiak Klassifikatsiooni ülempiir
core Esimese osapoole kood, mis tarnitakse koos platvormiga none: sama päritolu, lisaisolatsioon puudub restricted
verified Ülevaadatud kolmas osapool, kinnitatud avaldaja same-origin pind, vahendatud oskused restricted
community Ülevaatamata kolmas osapool; uue pistikprogrammi vaikeväärtus sandboxed pind, vahendatud oskused tenant
untrusted Kõik, mis pärineb tundmatust allikast strict: liivakastis pind, ainult vahendatud oskused, hosti usaldus puudub public

Sellest tabelist tuleneb kaks reeglit ja create-nexus-plugin validate jõustab mõlemad enne, kui midagi ehitatakse.

Esiteks, oskuse classification ei tohi ületada selle pistikprogrammi ülempiiri. Klassifikatsioonid reastuvad: public, seejärel tenant, seejärel restricted. community pistikprogramm, mis deklareerib restricted oskuse, ei kompileeru.

Teiseks, ainult core ja verified pistikprogrammid võivad deklareerida oskusi, mis ulatuvad AI Provider Routerini. Need on tool_using ja llm_only tasemed. community või untrusted pistikprogramm vahendab deterministlikku tööd (host_callback, plugin_queue ja map nende üle) ning palub platvormil teha kõike, mis vajab mudelit. Minu esimene pistikprogramm oli community ja ma kaotasin terve pärastlõuna, püüdes deklareerida llm_only kokkuvõtteoskust, enne kui mõistsin, et keeldumine oligi asja mõte.

Kui jätate trust vahele, käsitleb SDK pistikprogrammi kui community. Vahelejäetud väli ei saa kunagi tähendada edutamist.

Isolatsioonitasemed 1 kuni 4

Usaldusest eraldi ütleb manifesti runtime plokk, kuidas pistikprogramm töötab. isolationLevel on täisarv vahemikus 1 kuni 4 ja täitmisrežiim tuleneb sellest. Te ei vali neid kahte teineteisest sõltumatult: validaator tuletab ühe teisest ja lükkab tagasi manifesti, mille paar ei klapi.

isolationLevel executionMode Mida see tähendab
1 external_https Pistikprogramm töötab väljaspool paigaldust ja sellega võetakse ühendust HTTPS-i kaudu
2 mcp_container Konteiner, mis teeb kättesaadavaks MCP-tööriistad
3 hardened_docker Tugevdatud konteiner pistikprogrammi enda pod'ides; malli vaikeväärtus
4 firecracker Mikro-VM, kõige tugevam eraldatus
"runtime": {
  "nodeVersion": "20",
  "executionMode": "hardened_docker",
  "isolationLevel": 3,
  "entrypoint": "dist/server.js",
  "healthCheck": "/health"
}

entrypoint on nõutav. Sisenemispunktid on tarnitud artefaktid ja neid ei hangita kunagi käitusajal: SDK-l puudub dünaamilise importimise või kauglaadimise teekond täielikult, seega pannakse usaldus kirja ja seda kontrollitakse üks kord, misjärel see külmutatakse ega laadita kunagi alla.

Millega te igal astmel nõustute

Iga seadetest kõrgemal asuva redelipulga ülalpidamine maksab midagi. Siin on see, mida igaüks neist teile maksma läheb.

  • Skills Engine'i oskus vajab testjuhte, ülevaatajat, kes ei ole teie, ja versiooniajalugu, mille kohta teilt küsitakse, kui see valesti käitub. Samu baite ei avaldata kunagi kaks korda (CONTENT_HASH_ALREADY_PUBLISHED), nii et „laadi see lihtsalt uuesti üles“ ei ole lahendus.
  • Pistikprogramm vajab manifesti, mille marsruuditabel ühtib mõlemas suunas marsruutidega, mida teie kood registreerib. Marsruut, mis eksisteerib, kuid pole deklareeritud, on vastavusviga, nagu ka deklareeritud marsruut, mida kood kunagi ei registreeri.
  • full-service pistikprogrammile kuulub skeem viie andmebaasi rolliga, igal tabelil pealesunnitud reataseme turvalisusega ja alglaadimisega, mis keeldub kuulamast, kuni andmebaas tõestab, et tõke peab. Samuti kordab see oma manifestis sõna-sõnalt üle kolm platvormi seadust.
  • Valdkonnapakett on litsentsitud. See lülitub sisse üks üksus korraga, pilootprojekti kaudu, ja organisatsiooni litsents peab seda sisaldama. Teie ei saa otsustada, et kliendil on see olemas.
  • Vaade saab ainult vähemaks võtta. Kui roll peab nägema rohkem, peab muutuma baasvaade, mis tähendab vestlust sellega, kellele see baas kuulub.

Ühegi sellise kulu üle ei saa rakenduse kaupa läbi rääkida, mis ongi kompromiss. Te loobute esimese pistikprogrammi puhul osast vabadusest ja saate selle iga järgmise puhul tagasi.

Kolmanda osapoole pistikprogrammi paigaldamine
Kolmanda osapoole pistikprogrammi paigaldamine
Kolmanda osapoole pistikprogrammi paigaldamine toimib nagu rakenduse load. Iga ulatus, mille selle manifest deklareerib, antakse või jäetakse andmata üksuse kaupa ning väljakutse millelegi, mida see ei deklareerinud, lükatakse tagasi veaga CONNECTION_SCOPE_EXCEEDED.

MCP-tööriistad ja ühendused

MCP ilmub kolmes kohas ja neid on lihtne segamini ajada.

Pistikprogramm saab avaldada MCP-tööriistu, deklareerides need mcpTools[] sees: name, description ja inputSchema. Ainus reegel, mille validaator lisab, on see, et inputSchema ei tohi kasutada ülemise taseme oneOf, allOf ega anyOf, sest skeemi tipus olev kombinaator paneb iga tööriista importiva MCP-kliendi ebaõnnestuma veaga 400. Pistikprogramm tasemel isolationLevel 2 töötab kui mcp_container.

Skills Engine'i teek on kättesaadav MCP kaudu. Claude Code ja agendid kasutavad kolmeteistkümmet MCP-tööriista, et leida ja sobitada oskusi, neid käitada ja käitamist salvestada ning neid luua, importida või sünkroonida, kusjuures iga väljakutse töötab selle algatanud isiku nimel, tema lubatud nimekirja piires.

Ja AI-põhine kodeerimistööriist ühendub läbi Workbenchi: üks aadress paigalduse kohta, sisselogimine isiku brauseri kaudu, ühetunnine luba salvestatud võtme asemel ja ainult need tööriistad, mille see isik ära märgib. Peatükk 2.26, Ehitamine AI-põhiste kodeerimistööriistadega, käib selle üksikasjalikult läbi.

Konnektorid on vaiksem naaber. Valdkonnapaketi teadmusmudelit toidavad kirjutuskaitstud konnektorid süsteemidesse, nagu poliisihaldus või kahjukäsitlussüsteem, millest igaühel on ajakava ja testinupp. Lähtesüsteemi ei kirjutata midagi tagasi.

Pistikprogrammid ja MCP sünkroonimine
Pistikprogrammid ja MCP sünkroonimine
Pistikprogrammid ja MCP sünkroonimine näitab, millised pistikprogrammid toovad kaasa oskusi, millised sünkroonimised lükati täielikult tagasi, ning kolmeteistkümmet MCP-tööriista, mida Claude Code ja agendid teeki jõudmiseks kasutavad.

Teie koodiharust inimeste ekraanidele

Olenemata sellest, millisel redelipulgal te olete, on tee tootmiskeskkonda sama. Iga väljalase liigub teie arendusruumist testimiskeskkonda, seejärel pilootüksusesse ja siis kõikidesse üksustesse, ning igal sammul on väravad: testid, manifest, mis pole laienenud, proovikäivitus maskeeritud koopial ja nimelised ülevaatajad, kes ei ole autorid. Edutamine, mis püüab sammu vahele jätta, lükatakse tagasi veaga GATE_CANNOT_BE_SKIPPED. Iga keskkond hoiab eelmist versiooni 30 päeva ja ühe üksuse tagasipööramine on ülevaadatud muudatus, mis võtab aega umbes minuti.

Juurutamine ise käib ainult läbi paigalduse väljalaskekanalite. Üksused valivad oma kanali ja nende administraator nõustub iga liikumisega. Kanalite ja paigalduste lehel näete arve ja veamäärasid üksuse kohta, kuid mitte kunagi seda, mida keegi teie laiendusega tegi. Peatükk 2.28, Laienduse väljaandmine, katab väljalaske poole algusest lõpuni.

Märkus väljaannete kohta

Suurem osa sellest redelist on olemas mõlemas väljaandes. Community saab seaded ja Skills Engine'i oskused, pistikprogrammid igal tasemel ja samad kuldsed teekonnad ühes serveris koos koodiga teie enda Giti hostis. Enterprise lisab edutamise arendusruumist läbi testimiskeskkonna pilootüksusesse koos selle väravatega, pluss avaldaja klastrid ja reaalajas andmete maskeeritud koopiad. Samuti lisab see teie enda privaatse kataloogi ja valdkonnapaketid. Peatükk 2.25, Ehitamine iga väljaande jaoks, sisaldab üksikasju.

Järgmine peatükk on see, mida tuleks lugeda enne mis tahes koodi kirjutamist. Selles on vähe valikuid ja palju reegleid ning reeglid on samad nii esimese kui ka tuhandenda laienduse jaoks.