Versioon 1.0.0-alpha.1uusim
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

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.
- 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.
- Skills Engine'i oskused.
SKILL.mdpakett, 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). - Pistikprogrammid. Teie enda kood, mis on deklareeritud manifestiga ja ehitatud SDK tööriistadega. Pistikprogramm kuulub ühte kolmest tasemest:
skills-only,ui-onlyvõifull-service. - 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.
- Vaated. See, mida üks roll paketi või platvormi sees näeb. Vaade kitsendab baasvaadet ega laienda seda kunagi.
- 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.
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.
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.
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-servicepistikprogrammile 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.
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.
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.



