Verżjoni 1.0.0-alpha.1l-aħħar
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ż

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.0Agħ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 --writeAqraw 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.sqlIl-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.sqlIl-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.jsonIħ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.
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.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, li huwacreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, li huwanexus-gates --self-testnode 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.
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.

