IdħolIbbukkja laqgħa informattiva

Kapitlu 2.21

Il-Plugin SDK

L-installazzjoni tal-Plugin SDK (software development kit), l-għodod tal-linja tal-kmand tiegħu, dawra mal-mudell ta' servizz sħiħ, il-manifest v2 qasam b'qasam, u t-tnejn u għoxrin gate li jżommu plugin mar-regoli.

Din il-paġna ġiet tradotta bl-IA mill-oriġinal bl-Ingliż. Jekk xi ħaġa mhijiex ċara, il-paġna bl-Ingliż hija r-referenza. Aqra din il-paġna bl-Ingliż

22 minuti qari

It-tieni plugin tiegħi ħa terz tal-ħin tal-ewwel wieħed, u kważi l-iffrankar kollu kien minħabba l-SDK (software development kit). L-ewwel darba, ktibt verifika tal-ambitu, loader tal-konfigurazzjoni u runner tal-migrazzjonijiet, u reviżur bagħathomli lura lkoll. It-tieni darba, ħaddimt kmand wieħed ta' scaffold, ħassart is-skill tal-kampjun tas-sentiment, u qattajt il-jiem tiegħi fuq ir-rekords tar-reviżjoni tal-anomaliji li t-tim tagħna tad-dinamika tat-titjir verament kellu bżonn.

@adverant-nexus/plugin-sdk huwa pakkett npm wieħed. Fih l-iskema tal-manifest v2 u l-validaturi li jaqrawha (definePlugin, defineSkill), il-moduli runtime li l-plugin tagħkom jimporta għall-ambitu, id-database, id-dispatch u l-bqija, helpers tat-testijiet, il-gates tal-konformità, u l-għodod tal-linja tal-kmand. Dan il-kapitlu jkopri l-installazzjoni tiegħu, l-għodod, it-template, il-manifest u l-gates. Il-Kapitlu 2.22, Ir-runtime tal-plugin, ikopri l-moduli runtime fil-kodiċi tagħkom waqt li jkun qed jaħdem.

Kif tinstallah

Il-pakkett jiġi mir-reġistru ta' Adverant f'https://registry.adverant.ai/npm/, qatt mir-reġistru pubbliku ta' npm, u għandkom bżonn il-pull token mill-paġna "Pull tokens u kmandi tal-installazzjoni" tal-kont tagħkom. Ipponta l-ambitu @adverant-nexus lejn ir-reġistru fil-.npmrc tar-repożitorju tagħkom:

@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>

<pull-token> huwa t-token mill-paġna tal-kont tagħkom. F'pipeline, għaddewh minn secret u qatt tagħmlulu commit; id-Dockerfile tat-template jirrifjuta li jibni mingħajru u jħassar .npmrc mill-istadju tal-bini ladarba npm ci ikun ħadem, sabiex it-token qatt ma jinħareġ f'immaġni.

Imbagħad iffissaw il-verżjoni eżattament:

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

Agħmlu commit ta' package-lock.json fl-ewwel installazzjoni. Il-bini tal-immaġni tat-template iħaddem npm ci u jirrifjuta li jerġa' lura għal npm install: il-lockfile huwa l-kuntratt. Il-minimu tal-SDK innifsu huwa Node 18; it-template jimmira għal Node 20.

L-għodod tal-linja tal-kmand jiġu ġewwa l-pakkett, għalhekk kull kmand f'din id-dokumentazzjoni jsemmi l-pakkett u l-verżjoni tiegħu b'npx -p. Waħdu, npx create-nexus-plugin jinfittex fir-reġistru pubbliku, u dak l-isem mhuwiex dan il-pakkett.

L-għodod tal-linja tal-kmand

Għodda X'jagħmel
create-nexus-plugin Joħloq l-iskeletru ta' plugin, jivvalida manifest, jemigra manifest v1 għal v2, u joħroġ il-gwida tal-konsumatur għall-iżviluppatur tal-frontend tagħkom
nexus-tenancy Joħroġ l-SQL tat-tenancy tal-iskema tagħkom mill-manifest: ir-rwoli, il-grants, it-template tas-sigurtà fil-livell tar-ringiela, u t-tabelli tal-graff
nexus-migrate Japplika l-migrazzjonijiet tagħkom: jipprovdi r-rwoli darba, imbagħad iħaddem kull fajl numerat bħala r-rwol tal-migratur
nexus-gates Iħaddem kull gate tal-konformità, u t-test awtomatiku ta' kull gate

create-nexus-plugin ma jagħmel l-ebda sejħa tan-netwerk u ma jtella' l-ebda kodiċi remot. Iħaddem l-istess validaturi in-process li jħaddem l-onboarding tal-pjattaforma, għalhekk ma hemm l-ebda diskrepanza bejn "ġie vvalidat fuq il-magna tiegħi" u "il-pjattaforma aċċettatu".

Verb Flags X'jagħmel Kodiċijiet tal-ħruġ
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Jikteb direttorju ġdid tal-plugin; --print jistampa l-manifest biss 0 miktub · 1 irrifjuta li jikteb fuqu · 2 użu ħażin
validate <file> Jivvalida nexus.manifest.json, jew modulu .ts jew .js li jesporta wieħed 0 validu · 1 invalidu jew ma jinqarax · 2 użu ħażin
migrate <file> --write Itella' manifest v1 għal v2 u jistampah, jew jiktbu f'postu 0 · 1 · 2, bħal hawn fuq
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Joħroġ il-gwida tal-konsumatur mill-manifest u min-narrattiva tagħkom; --check iqabbel mal-kopja li saritilha commit u ma jikteb xejn 0 · 1 diskrepanza jew offiża tal-lint · 2 użu ħażin
help Jistampa l-użu 0

Scaffolding, u t-tliet saffi

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service

--tier awtomatikament ikun full-service. L-iscaffolder jirrifjuta li jikteb f'direttorju li jeżisti, u l-manifest li jikteb diġà jgħaddi mill-validazzjoni; qatt ma joħroġ wieħed invalidu.

Agħżlu l-livell skont x'għandu l-plugin tagħkom.

Livell Għandu Irid jiddikjara
skills-only Skills tal-manifest u xejn aktar skills[], b'tal-inqas entrata waħda
ui-only Wiċċ tal-frontend ġewwa l-shell frontend
full-service Backend u frontend, normalment bl-iskema tiegħu backend u frontend; u peress li għandu backend, runtime.healthCheck

Jekk m'intomx ċerti, agħmlu scaffold ta' full-service u ħassru dak li m'għandkomx bżonn. Li tmorru fid-direzzjoni l-oħra jfisser li tiktbu l-partijiet li t-template kien jagħtikom.

Dawra mal-mudell ta' servizz sħiħ

It-template huwa l-plugin ta' referenza, mibni skont il-mudell strett li kull kapitlu sussegwenti jassumi. Ikkupjaw il-forma tiegħu, mhux il-loġika tal-kampjun tiegħu.

Passaġġ X'inhu
nexus.manifest.json Il-manifest v2: it-tliet liġijiet iddikjarati mill-ġdid, it-tabella tar-rotot u r-reġistru tad-drittijiet tagħha
src/config.ts Il-loader tal-konfigurazzjoni. Speċifikazzjoni waħda, tinqara darba, kull problema tinġabar qabel ma l-proċess jirrifjuta li jibda
src/scope.ts L-uniku fajl li jbiddel talba f'ambitu, bil-verifikatur strett tat-tokens tal-SDK u żewġ reġimi: il-bearer token ta' persuna u s-sejħa tas-servizz tal-pjattaforma
src/db.ts Kull dikjarazzjoni tikkomponi tenantFence() u taħdem ġewwa withScopedTx
src/uno.ts L-uniku fajl tad-dispatch: URL wieħed, klijent wieħed, allow-list magħluqa
src/routes/*.ts health (anonima, path eżatt), ir-rotot /api (b'ambitu) u l-callback /internal (protett mis-servizz)
src/skills/sentiment.ts Skill deterministiku host_callback; ibdlu l-lessiku bil-loġika tagħkom
src/server.ts L-għerq tal-kompożizzjoni: jinstalla r-reġistru tar-rifjuti darba, jistenna d-database (b'limitu), imbagħad iħaddem il-verifiki tal-iżolament u tar-reġistru qabel ma jibda jisma'
migrations/000_tenancy.sql Prodott minn nexus-tenancy render fil-ħin tal-scaffold: ir-rwoli, l-iskema, it-template tas-sigurtà fil-livell tar-ringiela
migrations/001_init.sql Żewġ tabelli b'ċavetta komposta li tibda bit-tenant u foreign key komposta li ġġorr it-tenant
migrations/002_refusal_ledger.sql It-tabella li fiha jikteb ir-reġistru tar-rifjuti
scripts/ci/required-env Jistampa l-ismijiet tal-varjabbli tal-ambjent meħtieġa għall-bidu bħala JSON
scripts/ci/shadow-migrate-*.sh Il-prova tal-migrazzjoni tal-pipeline, permezz ta' nexus-migrate
gates/ Id-direttorju tal-eżenzjonijiet tal-gates: vojt, li huwa l-istat korrett għal plugin ġdid
test/ Testijiet għall-ambitu, ir-rotot, id-database, id-dispatch u l-bidu, bid-doubles tal-ambitu li kull test jinjetta
Dockerfile Immaġni mhux root (ID tal-utent 10001) bil-migrazzjonijiet ġewwa fiha

Ftit minn dawk il-fajls jistħoqqilhom ħarsa aktar mill-qrib.

src/config.ts isegwi żewġ regoli. Jiġbor kull problema qabel ma jitfa' eċċezzjoni, sabiex restart wieħed isemmi l-ħames varjabbli nieqsa kollha minflok ħames restarts li jsemmu waħda kull darba. U jagħti valur awtomatiku biss meta valur ħażin ma jistax jipproduċi tweġiba ħażina b'mod sieket: PORT jista' jkun awtomatikament 8080, għax port ħażin ifalli l-bind b'mod viżibbli, filwaqt li DATABASE_URL u UNO_DISPATCH_URL huma meħtieġa u jridu jkunu indirizzi ġewwa l-cluster. Wieħed pubbliku jiġi rrifjutat fil-bidu.

node scripts/ci/required-env
["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]

It-test tat-template stess iħaddem dak il-fajl u jqabbel l-output tiegħu mal-ismijiet li l-ispeċifikazzjoni tal-konfigurazzjoni timmarka bħala meħtieġa, għalhekk iż-żieda ta' varjabbli meħtieġa mingħajr ma taġġornaw il-lista tfalli npm test.

src/server.ts ma jibdiex jisma' sakemm id-database ma twieġibx, u jillimita l-istennija għal 120 sekonda, b'reġistrazzjoni ta' kull tentattiv falliti flimkien mal-kawża tiegħu. Imbagħad jipprova, f'ordni, li r-rwol tal-app ma jistax jerġa' jorbot it-tenant u li kull tabella hija sfurzata taħt is-sigurtà fil-livell tar-ringiela, li l-pool ta' kull pod jidħol fil-limitu tal-konnessjonijiet tar-rwol, u li t-tabella tar-reġistru tar-rifjuti tista' tieħu ringiela. Rifjut minn kwalunkwe wieħed mit-tlieta jiġi stampat kollu u l-proċess joħroġ b'2.

Il-manifest v2, qasam b'qasam

Il-manifest huwa l-kuntratt tal-plugin mal-pjattaforma li jinqara mill-magna. Jiġi vvalidat meta tiktbuh, meta l-pjattaforma tagħmillu onboarding u kontinwament wara dan. L-iskema hija additionalProperties: false f'kull livell: jekk il-plugin tagħkom għandu sezzjoni, hemm proprjetà għaliha, u ċavetta mhux iddikjarata tiġi rrifjutata. Is-soluzzjoni dejjem hija li tużaw il-proprjetà fakultattiva t-tajba.

Il-qalba meħtieġa

Qasam Regola
manifestVersion Eżattament "2". Dokument v1 jiġi emigrat, qatt ma jerġa' jiġi vvalidat f'postu
name ^[a-z0-9]+([-.][a-z0-9]+)*$, massimu ta' 64 karattru. L-id tal-plugin użat fir-reġistrazzjoni, fin-namespacing tad-dispatch u fir-ringieli b'ambitu tat-tenant. Plugin li jiddikjara skills jeħtieġ ukoll isem mingħajr punt u li ma jibdiex b'ċifra
displayName Minn 1 sa 120 karattru
version Verżjoni semantika; iċ-ċiklu tar-rilaxxi tagħkom
description, author, license Tal-inqas karattru wieħed kull wieħed
tier skills-only, ui-only jew full-service
trust core, verified, community jew untrusted
runtime Meħtieġa: executionMode, isolationLevel (minn 1 sa 4), entrypoint. Fakultattivi: nodeVersion, healthCheck, readinessCheck, livenessCheck, kull wieħed path li jibda b'/. Il-modalità tiġi dedotta mil-livell: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai u deploy, it-tliet liġijiet tal-pjattaforma ddikjarati mill-ġdid. Il-validatur jiffissa l-kliem

Għal plugin li tibnu għall-installazzjoni tagħkom, it-tliet sentenzi jaqraw kif ġej. Is-sentenza ai tkopri l-intelliġenza artifiċjali (IA) u hija l-post fejn tgħidu li l-plugin ma jżomm l-ebda kredenzjali tal-mudelli.

"architecture": {
  "compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
  "ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
  "deploy": "Deploy is through the installation's release channels only."
}

It-tabella tar-rotot: api u rights

api jeħtieġ version u basePath, u fakultattivament websocket (path, auth) u endpoints[]. It-tabella tar-rotot hija l-aktar idea b'saħħitha fl-iskema: gate iqabbilha mar-rotot li l-kodiċi tagħkom verament jirreġistra, fiż-żewġ direzzjonijiet, sabiex il-manifest ikun kuntratt li jista' jiġi vverifikat u mhux dokumentazzjoni.

Kull endpoint jeħtieġ method (GET, POST, PUT, PATCH jew DELETE) u path. Il-bqija:

Qasam X'jgħid
auth Waħda minn ħames klassijiet: scope (rotta ta' persuna, wara l-gwardja tal-ambitu), service-key u internal (minn server għal server, qatt aċċessibbli minn browser), public (dejjem path eżatt biss b'allowAnonymous), u device (magna bil-kredenzjali tagħha, wara l-gwardja tal-apparat)
right Meħtieġ fuq kull rotta li sservi l-gwardja tal-ambitu, u rrifjutat fuq kwalunkwe oħra: l-isem ta' dritt fir-reġistru rights
needsUnit Ir-rotta tirrifjuta meta l-unità ta' min qed jagħmel is-sejħa ma tistax tiġi riżolta
allowAnonymous Allow-list b'qbil eżatt biss. Regola ta' prefiss hija kif /health-of-tenant-42 jispiċċa pubbliku
group, serves, screens Taħt blokk release: il-grupp tal-kapaċitajiet li sservi r-rotta, x'twieġeb meta l-funzjoni liċenzjata ta' dak il-grupp tkun imsakkra (data, teaser, sighting jew ask), u l-iskrins li sservi
query required (kull isem b'valur ta' eżempju) u allowed: il-parametri tal-query li taqra r-rotta
body example: body ta' eżempju ta' rotta tal-kitba, wieħed li l-validatur tagħha stess jaċċetta. Qatt fuq GET

rights huwa r-reġistru li jsemmu dawk ir-rotot. Kull dritt għandu roles (il-limitu massimu) u fakultattivament summary, never (rwoli li qatt ma jistgħu jeżerċitawh, ikun x'ikun li għandhom ukoll), barred (il-kliem tal-prodott stess biex jirrifjuta rwol never), seat (hija meħtieġa wkoll sedja attiva), self (kull persuna vverifikata għandha, għal drittijiet fuq is-sessjoni tagħha stess), grants (dawk li għandhom jagħtu sedji; massimu ta' dritt wieħed jgħid hekk), licence (funzjoni liċenzjata li l-liċenzja tal-organizzazzjoni trid iġġorr) installation (miżmum biss mill-amministraturi tal-installazzjoni stess) u platform (miżmum biss mill-amministraturi tal-pjattaforma ta' Adverant; ma jsemmi l-ebda rwol). L-ismijiet tad-drittijiet għandhom tal-inqas punt wieħed: project.read, money.pay.

"api": {
  "version": "1",
  "basePath": "/",
  "endpoints": [
    { "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
    { "method": "GET", "path": "/api/projects", "summary": "List the caller's projects", "auth": "scope", "right": "project.read" },
    { "method": "POST", "path": "/api/projects", "summary": "Create a project", "auth": "scope", "right": "project.create" },
    { "method": "POST", "path": "/internal/skills/sentiment_score", "summary": "host_callback receiver", "auth": "service-key" }
  ]
},
"rights": {
  "project.read": { "summary": "Read the organisation's projects.", "roles": ["owner", "admin", "member", "viewer"] },
  "project.create": { "summary": "Open a project.", "roles": ["owner", "admin", "member"] }
}

definePlugin jirrifjuta rotta tal-ambitu mingħajr dritt (ENDPOINT_RIGHT_MISSING), dritt li r-reġistru m'għandux (ENDPOINT_RIGHT_NOT_REGISTERED) u dritt fuq rotta li l-ebda gwardja ma sservi (ENDPOINT_RIGHT_UNGUARDED). Jirrifjuta wkoll reġistru li jikkontradixxi lilu nnifsu, u żewġ ortografiji ta' rotta waħda (:id u :recordId) bħala DUPLICATE_ENDPOINT.

Id-data tagħkom: databases, schema u db

schema hija l-iskema waħda ta' Postgres li l-plugin għandu. public, plugins, auth u nexus huma pprojbiti, u jekk databases[] isemmi wkoll skema ta' Postgres it-tnejn iridu jaqblu.

databases[] jiddikjara kull store skont il-magna: postgresql (schema, tables, migrations, u granted, it-tabelli li organizzazzjoni oħra tista' taqra taħt grant irreġistrat), neo4j (schemas), qdrant (collections) jew redis (purpose).

db fih il-limiti tas-sessjoni għal kull konnessjoni li jiftaħ il-plugin, iddikjarati hawn minflok ikkodifikati sabiex kemm reviżur kif ukoll id-deployment ikunu jistgħu jaqrawhom:

Qasam X'jillimita
maxConnections Il-pool għal kull replika
pods L-akbar numru ta' pods li jżommu pool fl-istess ħin, ir-repliki flimkien mas-surge ta' rolling update. Il-limitu tal-konnessjonijiet ta' kull rwol jinħareġ bħala maxConnections × pods; jekk tħalluh barra definePlugin iwissi DB_PODS_UNDECLARED
statementTimeoutMs Dikjarazzjoni waħda
idleInTransactionTimeoutMs Transazzjoni miftuħa li mhi qed tħaddem xejn
workMemKB Node wieħed ta' sort jew hash, għal kull node, mhux għal kull query
piiMask[] Entrati table.column li fihom data personali, moħbija fil-console SQL regolata u fil-logs

Skills u għodod: skills, mcpTools, entitlements

skills[] fih is-skills tal-manifest; il-kapitlu 2.20, Skills, ikopri l-oqsma u l-livelli tagħhom. mcpTools[] fih l-għodod MCP (Model Context Protocol) li jippubblika l-plugin, kull waħda name, description u inputSchema mingħajr oneOf, allOf jew anyOf fil-livell ta' fuq.

entitlements jeħtieġ featureIdPattern u jaċċetta alwaysOn[], source u store. Il-mudell isemmi n-namespace li fih jinsabu l-ids tal-funzjonijiet tagħkom, konvenzjonalment il-name tal-plugin flimkien ma' segment wieħed li l-kodiċi tagħkom jimla għal kull wiċċ. alwaysOn[] hija l-lista qasira u eżatta li trid twieġeb anki meta ma jista' jinkiseb l-ebda verdett dwar l-intitolament: is-saħħa, il-prontezza, l-aċċess, u s-settings li amministratur jeħtieġ biex isewwi l-intitolament.

Kontroll tal-bidliet: changePolicy

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

L-approvazzjonijiet jingħaddu f'persuni distinti, u l-persuna li pproponiet il-bidla qatt ma tkun waħda minnhom; mingħajr iż-żewġ nofsijiet, "żewġ approvazzjonijiet" isiru persuna waħda tikklikkja darbtejn. enabled: true jeħtieġ classes, u kull klassi msemmija teħtieġ l-għadd tagħha. Klassi li tħalluha barra ma tkunx regolata, li hija għażla leġittima li l-iskema ġġegħelkom tniżżlu bil-miktub.

Min intom: domains, branding, routing

domains[] (kull wieħed primary u aliases[]; domain hija l-forma b'dominju wieħed) jelenka fejn iwieġeb il-plugin. branding jeħtieġ appName u jaċċetta tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId u gaId. Kollox f'branding huwa pubbliku: il-paġna tal-aċċess taqrah qabel ma xi ħadd ikollu kredenzjali, għalhekk qatt ma fih secret jew indirizz intern. routing (type, gateway, virtualService) huwa għal plugins li jiddeskrivu r-routing tagħhom stess.

Id-daqs u l-bqija

resources jeħtieġ cpuMillicores (10 sa 64,000) u memoryMB (16 sa 262,144), u jaċċetta diskGB, timeoutMs, port u wsPort. backend fih port, healthPath, apiPrefix, framework u platformClients[], il-klijenti tal-SDK li l-backend tagħkom jimporta bl-isem. Il-lista hija magħluqa, u gate jiċċekkjaha mal-importazzjonijiet tagħkom. L-iskema tippermetti erbatax-il isem: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin u uno, flimkien ma' wieħed għall-klijent li jwieġeb ir-rifjuti tad-drittijiet tal-pjan, li jżomm isem intern. Il-klijent tad-drittijiet tal-karatteristiċi, runtime/entitlements, mhuwiex wieħed minnhom u qatt ma jidħol fil-lista, għax il-blokk entitlements tagħkom diġà jiddikjarah, u backend li jimportah mingħajr blokk entitlements ifalli l-istess gate. frontend fih basePath, mountPath u framework. nexus fih minVersion, maxVersion, capabilities[] u permissions[].

Il-blokki li jifdal kull wieħed jeżisti għal xogħol wieħed:

Blokk Għal
settings L-issettjar tagħkom fuq il-qafas komuni: groups u keys, issettjati fil-livelli li jsemmi kull wieħed
people sweep (service, port): il-membri tal-organizzazzjoni, sinkronizzati mis-servizz tal-identità, bis-siġġijiet jintfew meta xi ħadd jitlaq
ontology entityTypes u relationshipTypes: il-graff tipizzat miżmum fl-iskema tagħkom stess
release groups u frame: il-gruppi ta' kapaċitajiet li fihom ir-rotot tagħkom jiġu stadjati, rilaxxati l-ewwel bħala canary
cells[] Plugin li huwa diversi deployables: name, kind, entrypoint, port, wsPort għal kull wieħed
pricing model, currency, tiers[] għall-elenkar tagħkom fil-katalgu
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Min jippubblikah u fejn jinsab il-kodiċi tiegħu
metrics, atlas Iż-żewġ oġġetti miftuħa apposta, għall-ismijiet tal-metriċi tagħkom stess u għall-ġenerazzjoni tad-dokumentazzjoni tal-arkitettura

Dak li l-iskema ma tistax tgħid

Il-JSON Schema tiddetermina l-forma; definePlugin iżid ir-regoli li skema ma tistax tesprimi. Il-classification ta' skill ma jistax jaqbeż il-limitu massimu tal-fiduċja. Plugins core u verified biss jistgħu jiddikjaraw skills tool_using u llm_only. Kull mogħdija ddikjarata trid tkun relattiva u tal-istess oriġini, mingħajr skema, mingħajr // u mingħajr backslash, għax il-parser tal-URL jibdel \ f'/ u /\evil.example/x jirrisolvi lejn oriġini oħra. Kull regola li s-sinkronizzazzjoni tar-reġistru tapplika għal skill tiġi applikata hawn l-ewwel, bil-kodiċi tas-sinkronizzazzjoni stess, sabiex validate u s-sinkronizzazzjoni jsemmu regola miksura bl-istess mod.

Validazzjoni, u ċaqliq minn v1

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
✔ anomaly-review@0.3.0 · tier=full-service · trust=community · skills=1 · mcpTools=0

Falliment jistampa l-mogħdija preċiża u, għal regola tas-sinkronizzazzjoni, il-kodiċi l-ewwel. Agħmluh commit hook.

Manifest v1 jiġi aġġornat b'mod mekkaniku. migrate iżid it-tliet sentenzi tal-liġi, iċaqlaq domain għal domains[] u jirrifjuta li jivvinta entrypoint li ma kellkomx. Jivvalida r-riżultat qabel ma jistampa jew jikteb xi ħaġa, sabiex migrazzjoni qatt ma ċċaqlaq falliment mill-għodda għar-repożitorju tagħkom.

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --write

Aqraw id-diff qabel ma tagħmlulu commit. Is-sentenzi tal-liġi li jżid huma l-kliem li l-validatur jiffissa; għall-installazzjoni tagħkom stess, issettjaw deploy għas-sentenza murija qabel.

Rendering tat-tenancy, u proviżjonament tar-rwoli

Qatt ma tiktbu bl-idejn l-għotjiet tar-rwoli jew il-mudell tas-sigurtà fil-livell tar-ringiela. nexus-tenancy render jiktibhom mill-schema u db tal-manifest:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sql

Il-fajl iġġenerat joħloq ħames rwoli għall-iskema, kull wieħed b'dak li m'għandux iżomm: migrator li jista' biss isir is-sid, sid li ma jistax jidħol, rwol tal-app għall-mogħdija tat-talbiet, rwol tar-rapporti li jara biss aggregati, u rwol tal-ledger li jista' biss iżid. L-ebda rwol ma għandu BYPASSRLS. L-uniku mod biex jintrabat tenant huwa funzjoni waħda tad-database, u set_config huwa revokat minn kull rwol ħlief is-sid.

Fajl tat-tenancy applikat qatt ma jiġi editjat. Bidla hija reviżjoni bil-fajl numru 0 tagħha stess, u s-siġġu tal-qari għall-għotjiet bejn organizzazzjonijiet jasal b'dak il-mod, bħala reviżjoni 2. --graph jiġġenera ż-żewġ tabelli tal-graff tipizzat li jiddikjara l-ontology tagħkom bħala l-migrazzjoni nnumerata li jmiss tagħkom.

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --graph --out migrations/001_graph.sql

Il-fajl tat-tenancy joħloq l-istess rwoli li bihom jikkonnettja r-runner, għalhekk jiġi applikat mis-sid tad-database b'nexus-migrate provision:

DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir>

<database-owner-url> huwa connection string għas-sid tad-database, u <dir> huwa direttorju privat. Provision japplika l-fajl bażi tat-tenancy u kull reviżjoni f'ordni, jikteb migrator.url u app.url (u seat.url ladarba teżisti r-reviżjoni 2) f'<dir> bil-mode 0600, u ma jistampa xejn sigriet. F'kull eżekuzzjoni jissettja l-limitu tal-konnessjonijiet ta' kull rwol minn db.maxConnections × db.pods. Eżekuzzjoni mill-ġdid iżżomm il-passwords eżistenti sakemm ma titolbux: --passwords <dir> jissettjahom minn fajls u --rotate <roles> jagħti passwords ġodda lir-rwoli msemmija. Ibdlu l-fajls f'sigrieti tad-deployment tagħkom.

Wara dan, l-applikazzjoni tikkonnettja bil-connection string tal-migrator li kiteb provision:

DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.json

Iħaddem il-fajls minn 001 'il quddiem bħala l-migrator, kull fajl taħt SET ROLE <schema>_owner, transazzjoni waħda għal kull fajl. Iżomm ledger, <schema>.schema_migrations, bil-checksum ta' kull fajl; fajl applikat li l-bytes tiegħu nbidlu jiġi rifjutat bl-isem (CHECKSUM_DRIFT), qatt ma jerġa' jitħaddem u qatt ma jinqabeż. Kull fajl pendenti jiġi analizzat bil-grammatika reali ta' Postgres qabel ma jitħaddem l-ewwel wieħed, sabiex rifjut iħalli d-database mhux mittiefsa. L-unika header li fajl jista' jkollu hija -- nexus-migration: transaction=file|per-statement, b'timeouts fakultattivi għal-lock u għall-istqarrija; per-statement huwa għal CREATE INDEX CONCURRENTLY.

Il-gates

nexus-gates iħaddem tnejn u għoxrin gate. Kull wieħed jikkodifika klassi waħda ta' difett sabiex ma tkunx tista' tiġi rilaxxata darbtejn, u kull wieħed għandu awtotest li jipprova li jfalli fuq fixture mibni apposta biex iqanqlu. Ħaddmuhom qabel ma tagħmlu push:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Gate Dak li jaqbad
scope-adherence Rotta /api mingħajr il-guard tal-ambitu; mogħdija anonima li mhijiex waħda eżatta ddikjarata; rotta tal-apparat mingħajr il-guard tal-apparat, jew bil-guard ta' persuna maġenbha
one-fence Predikat tat-tenant definit kullimkien ħlief f'post wieħed, inkluż ċint tas-siġġijiet jew tal-għotjiet magħmul bl-idejn
sql-fence Stqarrija li taqra jew taġġorna tabella b'ambitu mingħajr iċ-ċint, fi kwalunkwe mira FROM, JOIN, USING jew UPDATE
migrations-are-scoped Tabella nieqsa minn assi, ċavetta komposta li tibda bit-tenant, foreign key li ġġorr it-tenant jew il-kolonna demo
migrations-commit-what-they-open Migrazzjoni li l-għadd ta' BEGIN tagħha ma jaqbilx mal-għadd ta' COMMIT u ROLLBACK tagħha
no-direct-compute Sejħa diretta lil fornitur ta' mudelli, engine, kju jew host tal-workflows; qarrej ieħor tal-URL tad-dispatch
no-credentials Kredenzjali ta' fornitur ta' mudelli li tista' tinqara fir-repożitorju jew fl-ambjent
crud-adherence Rotta li tbiddel li l-verifika tad-drittijiet tagħha ma ssemmi xejn fir-reġistru
blocked-backends Rotta li la hi servuta, la mblukkata bl-isem, la rrifjutata mil-liġi u lanqas proprjetà ta' xi mkien ieħor
every-test-runs Testijiet li l-glob tal-iskript tat-testijiet qatt ma jilħaq
tiles-are-invariant Seam fil-cache invarjanti għat-tenant li jaqra valur tat-tenant jew jaqbeż l-awtentikazzjoni
api-contract Rotta rreġistrata li l-manifest ma jiddikjarahiex, jew waħda ddikjarata li l-kodiċi qatt ma jirreġistra
rls-present Tabella mingħajr sigurtà furzata fil-livell tar-ringiela; funzjoni SECURITY DEFINER mingħajr search_path iffissat
no-set-config Kodiċi tal-plugin li jorbot l-issettjar tat-tenant huwa stess
db-role-honest Mogħdija tat-talbiet li tikkonnettja bħala s-sid jew il-migrator, jew li titlob SUPERUSER jew BYPASSRLS
platform-clients Klijent tal-SDK importat iżda mhux elenkat f'backend.platformClients, jew elenkat iżda qatt ma ġie importat
rights-register Rotta tal-ambitu mingħajr dritt iddikjarat; verifika tad-drittijiet barra mir-reġistru
refusal-ledger Tabella tar-rifjuti ddikjarata mingħajr ledger installat, jew korp ta' rifjut mibgħut evitah
grants-declared Tabella mogħtija li l-manifest ma jiddikjarahiex; privileġġi tas-siġġu tal-qari mogħtija bl-idejn
people-declared Blokk people mingħajr ir-rotta tas-sweep, il-guard u t-tabelli tiegħu
functions-closure Plugin ta' Azure Functions li r-rotot servuti u r-rotot iddikjarati tiegħu ma jaqblux
declared-input Lista tal-parametri tal-query ta' handler li ma taqbilx mal-query iddikjarat tar-rotta

Id-direttorju gates/ fih il-ħames fajls tal-eżenzjonijiet li gate jista' jaqra (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json u invariant-seams.json), raġuni waħda għal kull entrata. Raġuni vojta titqies bħala l-ebda entrata, u entrata li ssemmi xi ħaġa li m'għadhiex teżisti tfalli l-gate. Tistgħu wkoll tpoġġu hemm il-moduli tal-gates tagħkom stess, u nexus-gates jiġborhom flimkien ma' dawk integrati.

Kompatibbiltà
Kompatibbiltà
Il-Kompatibbiltà turi liema verżjoni tal-SDK taħdem ma' liema verżjoni tal-pjattaforma, minn eżekuzzjonijiet ta' kull lejl tal-quickstart. Par mhux ittestjat jgħid hekk, u par li jfalli jsemmi l-bidla li kissritu.

Il-pipeline tal-mudell

Il-mudell ma jinkludi l-ebda workflow miktub bl-idejn. Il-konfigurazzjoni tal-pipeline tiegħu ssemmi d-Dockerfile, l-uniku argument tal-build (it-token tar-reġistru), id-dry run tal-migrazzjoni u l-boot probe, u l-gate li jħaddem il-merge queue. L-ordni hija l-ordni li fiha tixtiequ tfallu.

  1. npm ci
  2. npm run typecheck
  3. npm run build
  4. npm test
  5. npm run validate:manifest, li huwa create-nexus-plugin validate nexus.manifest.json
  6. npm run gates, li huwa nexus-gates --self-test
  7. node scripts/ci/required-env

Żewġ verifiki oħra jitħaddmu madwar l-immaġni. Id-dry run tal-migrazzjoni japplika kull fajl għal Postgres temporanju qabel ma l-immaġni tkun tista' tiġi rilaxxata, bl-istess runner li juża l-ambjent tal-produzzjoni: nexus-migrate provision darba bħala s-superuser, imbagħad kull fajl innumerat bħala l-migrator. Il-boot probe jibda l-immaġni mibnija bl-entrypoint tagħha stess u b'kull varjabbli li jistampa required-env, diretti lejn sostituti li jaċċettaw konnessjonijiet u qatt ma jwieġbu. Is-server jistenna d-database, fi ħdan it-tieqa limitata tiegħu, u dak l-istennija huwa s-sinjal tas-suċċess; loader tal-konfigurazzjoni li jirrifjuta li jibda jfalli l-build hemmhekk u mhux fil-produzzjoni.

Il-bini fuq Community
Il-bini fuq Community
Fuq Community, żviluppatur jieħu l-istess golden paths, dev space u data branches fuq server wieħed, bil-kodiċi fil-host tal-Git tiegħu stess. L-istaging, il-pilot units u kopji maskrati ta' data ħajja jiġu ma' Enterprise.

Kemm jiswa

L-SDK jieħu deċiżjonijiet minflokkom, u xi wħud minnhom kontu tieħduhom b'mod differenti. Il-manifest jirrifjuta ċwievet li ma jafx, it-tabella tar-rotot trid taqbel eżatt mal-kodiċi tagħkom, ir-rwoli tad-database mhumiex tagħkom biex tfassluhom, u l-gates ifallu build minħabba dritt nieqes fuq qari. Fl-ewwel plugin tiegħi qattajt ġurnata nargumenta ma' api-contract dwar rotta li kont irreġistrajt u nsejt niddikjara. Kellu raġun; ir-rotta ma kellhiex guard. Stennew li l-ewwel plugin iħossu bil-mod, u stennew li t-tieni wieħed jieħu terz tal-ħin.