Leagan 1.0.0-alpha.1is déanaí
Caibidil 2.21
An SDK Breiseán
An SDK Breiseán (trealamh forbartha bogearraí) a shuiteáil, a uirlisí líne ordaithe, turas ar an teimpléad lán-seirbhíse, an follas v2 réimse ar réimse, agus na dhá gheata is fiche a choinníonn breiseán leis na rialacha.
d'aistrigh AI an leathanach seo ón mbunleagan Béarla. Má tá aon rud doiléir, is é an leathanach Béarla an tagairt. Léigh an leathanach seo i mBéarla

Ghlac mo dhara breiseán an tríú cuid den am a ghlac mo chéad cheann, agus ba é an SDK (trealamh forbartha bogearraí) a thug beagnach an coigilteas ar fad. An chéad uair, scríobh mé seiceáil raoin, lódálaí cumraíochta agus reathaí imirce, agus sheol athbhreithneoir gach ceann acu ar ais. An dara huair, rith mé ordú creatlaithe amháin, scrios mé an scil sheintiminte samplach, agus chaith mé mo laethanta ar na taifid athbhreithnithe aimhrialtachtaí a bhí de dhíth go fírinneach ar ár bhfoireann dinimic eitilte.
Is pacáiste npm amháin é @adverant-nexus/plugin-sdk. Tá ann scéimre an fhorógra v2 agus na bailíochtóirí a léann é (definePlugin, defineSkill), na modúil rith-ama a iompórtálann do bhreiseán le haghaidh raoin, bunachar sonraí, seolta agus na nithe eile, cúntóirí tástála, na geataí cloíte, agus na huirlisí líne ordaithe. Clúdaíonn an chaibidil seo a shuiteáil, na huirlisí, an teimpléad, an forógra agus na geataí. Clúdaíonn Caibidil 2.22, Rith-am an bhreiseáin, na modúil rith-ama i do chód atá ag rith.
É a shuiteáil
Tagann an pacáiste ó chlárlann Adverant ag https://registry.adverant.ai/npm/, agus ní thagann sé riamh ón gclárlann phoiblí npm, agus teastaíonn an comhartha tarraingthe ón leathanach "Comharthaí tarraingthe agus orduithe suiteála" i do chuntas. Dírigh an raon @adverant-nexus ar an gclárlann in .npmrc do stórais:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
Is é <pull-token> an comhartha ó leathanach do chuntais. I bpíblíne, tabhair isteach é ó rún agus ná déan é a thiomantas riamh; diúltaíonn Dockerfile an teimpléid tógáil gan é agus scriosann sé .npmrc ón gcéim tógála a luaithe a bheidh npm ci rite, ionas nach seoltar an comhartha riamh in íomhá.
Ansin pionnáil an leagan go beacht:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Déan package-lock.json a thiomantas ar an gcéad suiteáil. Ritheann tógáil íomhá an teimpléid npm ci agus diúltaíonn sí titim siar ar npm install: is é an comhad glasála an conradh. Is é Node 18 an t-íosleibhéal atá ag an SDK féin; díríonn an teimpléad ar Node 20.
Seoltar na huirlisí líne ordaithe taobh istigh den phacáiste, mar sin ainmníonn gach ordú sa doiciméadú seo an pacáiste agus a leagan le npx -p. Leis féin, lorgaítear npx create-nexus-plugin ar an gclárlann phoiblí, agus ní don phacáiste seo an t-ainm sin.
Na huirlisí líne ordaithe
| Uirlis | An méid a dhéanann sé |
|---|---|
create-nexus-plugin |
Cruthaíonn sé creatlach breiseáin, bailíochtaíonn sé forógra, imirceann sé forógra v1 go v2, agus rindreálann sé treoir an tomhaltóra do d'fhorbróir taobh tosaigh |
nexus-tenancy |
Rindreálann sé SQL tionóntachta do scéimre ón bhforógra: róil, deontais, teimpléad na slándála ar leibhéal na ró, agus na táblaí graif |
nexus-migrate |
Cuireann sé d'imirceanna i bhfeidhm: soláthraíonn sé na róil uair amháin, ansin ritheann sé gach comhad uimhrithe mar ról an imirceora |
nexus-gates |
Ritheann sé gach geata cloíte, agus féintástáil gach geata |
Ní dhéanann create-nexus-plugin aon ghlao líonra agus ní lódálann sé aon chód cianda. Ritheann sé na bailíochtóirí céanna laistigh den phróiseas a ritheann ionduchtú an ardáin, mar sin níl aon difríocht idir "bhailíochtaigh sé ar mo ríomhaire" agus "ghlac an t-ardán leis".
| Briathar | Bratacha | An méid a dhéanann sé | Cóid scoir |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Scríobhann sé eolaire breiseáin nua; ní phriontálann --print ach an forógra |
0 scríofa · 1 diúltaíodh forscríobh · 2 droch-úsáid |
validate <file> |
Bailíochtaíonn sé nexus.manifest.json, nó modúl .ts nó .js a easpórtálann ceann |
0 bailí · 1 neamhbhailí nó doléite · 2 droch-úsáid | |
migrate <file> |
--write |
Ardaíonn sé forógra v1 go v2 agus priontálann sé é, nó scríobhann sé ina áit é | 0 · 1 · 2, mar atá thuas |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Rindreálann sé treoir an tomhaltóra ón bhforógra agus ó do insint; déanann --check comparáid leis an gcóip thiomanta agus ní scríobhann sé faic |
0 · 1 difríocht nó ciontóir lint · 2 droch-úsáid |
help |
Priontálann sé an úsáid | 0 |
Scafall, agus na trí shraith
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-serviceIs é full-service an réamhshocrú do --tier. Diúltaíonn an creatlaitheoir scríobh isteach in eolaire atá ann cheana, agus téann an forógra a scríobhann sé tríd an mbailíochtú cheana féin; ní eisíonn sé ceann neamhbhailí riamh.
Roghnaigh an leibhéal de réir a bhfuil ag do bhreiseán.
| Sraith | Tá aige | Caithfidh sé a dhearbhú |
|---|---|---|
skills-only |
Scileanna forógra agus faic eile | skills[], le hiontráil amháin ar a laghad |
ui-only |
Dromchla taobh tosaigh taobh istigh den bhlaosc | frontend |
full-service |
Taobh cúil agus taobh tosaigh, de ghnáth lena scéimre féin | backend agus frontend; agus toisc go bhfuil taobh cúil aige, runtime.healthCheck |
Mura bhfuil tú cinnte, cruthaigh creatlach full-service agus scrios a bhfuil gan ghá duit. Má théann tú an bealach eile, caithfidh tú na codanna a thabharfadh an teimpléad duit a scríobh.
Turas ar an teimpléad lán-seirbhíse
Is é an teimpléad an breiseán tagartha, tógtha de réir an phatrúin dhian a nglacann gach caibidil ina dhiaidh seo leis. Clónáil a chruth, ní a loighic shamplach.
| Cosán | Cad é féin |
|---|---|
nexus.manifest.json |
An forógra v2: na trí dhlí athráite, an tábla bealaí agus a chlár ceart |
src/config.ts |
An lódálaí cumraíochta. Sonraíocht amháin, léite uair amháin, gach fadhb bailithe sula ndiúltaíonn an próiseas tosú |
src/scope.ts |
An t-aon chomhad a iompaíonn iarratas ina raon, le fíoraitheoir comharthaí dian an SDK agus dhá réimeas: comhartha iompróra duine agus glao seirbhíse an ardáin |
src/db.ts |
Comhdhéanann gach ráiteas tenantFence() agus ritheann sé taobh istigh de withScopedTx |
src/uno.ts |
An t-aon chomhad seolta: URL amháin, cliant amháin, liosta ceadaithe dúnta |
src/routes/*.ts |
health (gan ainm, cosán beacht), na bealaí /api (faoi raon) agus an t-aisghlao /internal (faoi chosaint seirbhíse) |
src/skills/sentiment.ts |
Scil chinntitheach host_callback; cuir do loighic féin in ionad an fhoclóra |
src/server.ts |
An fhréamh chomhdhéanta: suiteálann sí an mórleabhar diúltuithe uair amháin, fanann sí leis an mbunachar sonraí (teorannaithe), ansin ritheann sí na seiceálacha leithlisithe agus mórleabhair sula n-éisteann sí |
migrations/000_tenancy.sql |
Rindreáilte ag nexus-tenancy render le linn an chreatlaithe: róil, scéimre, teimpléad na slándála ar leibhéal na ró |
migrations/001_init.sql |
Dhá thábla le heochair ilchodach a bhfuil an tionónta ar tosach inti agus eochair eachtrach ilchodach a iompraíonn an tionónta |
migrations/002_refusal_ledger.sql |
An tábla a scríobhann an mórleabhar diúltuithe |
scripts/ci/required-env |
Priontálann sé ainmneacha na n-athróg timpeallachta atá riachtanach le tosú, mar JSON |
scripts/ci/shadow-migrate-*.sh |
Triail thirim imirce na píblíne, trí nexus-migrate |
gates/ |
Eolaire díolúintí na ngeataí: folamh, arb é an staid cheart do bhreiseán nua |
test/ |
Tástálacha do raon, bealaí, bunachar sonraí, seoladh agus an tosú, leis na dúbailtí raoin a instealltar i ngach tástáil |
Dockerfile |
Íomhá neamhfhréimhe (aitheantas úsáideora 10001) leis na himirceanna taobh istigh di |
Is fiú féachaint níos géire ar chuid de na comhaid sin.
Leanann src/config.ts dhá riail. Bailíonn sé gach fadhb sula gcaitheann sé earráid, mar sin ainmníonn atosú amháin na cúig athróg ar fad atá in easnamh in ionad cúig atosú a ainmníonn ceann an ceann. Agus ní thugann sé luach réamhshocraithe ach amháin nuair nach féidir le luach mícheart freagra mícheart ciúin a thabhairt: is féidir 8080 a bheith mar réamhshocrú ag PORT, mar go dteipeann an ceangal go sofheicthe le port mícheart, ach tá DATABASE_URL agus UNO_DISPATCH_URL riachtanach agus caithfidh siad a bheith ina seoltaí laistigh den bhraisle. Diúltaítear do sheoladh poiblí ag am tosaithe.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Ritheann tástáil an teimpléid féin an comhad sin agus cuireann sí a aschur i gcomparáid leis na hainmneacha a mharcálann sonraíocht na cumraíochta mar riachtanach, mar sin má chuirtear athróg riachtanach leis gan an liosta a nuashonrú, teipeann npm test.
Ní éisteann src/server.ts go dtí go bhfreagraíonn an bunachar sonraí, agus cuireann sé teorainn 120 soicind leis an bhfanacht, ag logáil gach iarracht a theip lena cúis. Ansin cruthaíonn sé, in ord, nach féidir le ról an fheidhmchláir an tionónta a athcheangal agus go bhfuil gach tábla faoi éigean na slándála ar leibhéal na ró, go luíonn linn gach poda laistigh de theorainn nasc an róil, agus gur féidir le tábla an mhórleabhair diúltuithe ró a ghlacadh. Priontáiltear diúltú ó cheann ar bith den trí cinn ina iomláine agus scoireann an próiseas le 2.
An follas v2, réimse ar réimse
Is é an forógra conradh inléite ag meaisín an bhreiseáin leis an ardán. Bailíochtaítear é nuair a scríobhann tú é, nuair a ionduchtaíonn an t-ardán é agus go leanúnach ina dhiaidh sin. Is é additionalProperties: false an scéimre ar gach leibhéal: má tá rannán ag do bhreiseán, tá airí ann dó, agus diúltaítear d'eochair neamhdhearbhaithe. Is é an réiteach i gcónaí an t-airí roghnach ceart a úsáid.
An croí riachtanach
| Réimse | Riail |
|---|---|
manifestVersion |
Go díreach "2". Déantar doiciméad v1 a imirce, agus ní athbhailíochtaítear riamh ina áit é |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, 64 carachtar ar a mhéad. An t-aitheantas breiseáin a úsáidtear i gclárú, i spás ainmneacha seolta agus i sraitheanna faoi raon tionónta. Teastaíonn ainm gan ponc agus gan digit tosaigh freisin ó bhreiseán a dhearbhaíonn scileanna |
displayName |
1 go 120 carachtar |
version |
Leagan séimeantach; do thraein eisiúna féin |
description, author, license |
Carachtar amháin ar a laghad an ceann |
tier |
skills-only, ui-only nó full-service |
trust |
core, verified, community nó untrusted |
runtime |
Riachtanach: executionMode, isolationLevel (1 go 4), entrypoint. Roghnach: nodeVersion, healthCheck, readinessCheck, livenessCheck, gach ceann acu ina chosán a thosaíonn le /. Díorthaítear an mód ón leibhéal: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai agus deploy, trí dhlí an ardáin athráite. Socraíonn an bailíochtóir an fhoclaíocht |
Maidir le breiseán a thógann tú do do shuiteáil féin, seo mar a léann na trí abairt. Clúdaíonn an abairt ai an intleacht shaorga (AI) agus is ann a deirtear nach gcoinníonn an breiseán aon dintiúir samhla.
"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."
}An tábla bealaí: api agus rights
Teastaíonn version agus basePath ó api, agus go roghnach websocket (path, auth) agus endpoints[]. Is é an tábla bealaí an smaoineamh is láidre sa scéimre: déanann geata difríocht idir é agus na bealaí a chláraíonn do chód i ndáiríre, sa dá threo, mar sin is conradh insheiceáilte é an forógra agus ní doiciméadú.
Teastaíonn method (GET, POST, PUT, PATCH nó DELETE) agus path ó gach críochphointe. An chuid eile:
| Réimse | An méid a deir sé |
|---|---|
auth |
Ceann de chúig aicme: scope (bealach duine, taobh thiar den gharda raoin), service-key agus internal (freastalaí go freastalaí, ní bhíonn siad inrochtana ó bhrabhsálaí riamh), public (cosán beacht le allowAnonymous i gcónaí), agus device (meaisín a bhfuil a dhintiúr féin aige, taobh thiar de gharda an ghléis) |
right |
Riachtanach ar gach bealach a bhfreastalaíonn an garda raoin air, agus diúltaithe ar aon cheann eile: ainm cirt sa chlár rights |
needsUnit |
Diúltaíonn an bealach nuair nach féidir aonad an ghlaoiteora a réiteach |
allowAnonymous |
Liosta ceadaithe meaitseála beaichte amháin. Is trí riail réimíre a éiríonn /health-of-tenant-42 poiblí |
group, serves, screens |
Faoi bhloc release: an grúpa cumais a bhfreastalaíonn an bealach air, an freagra a thugann sé nuair atá gné cheadúnaithe an ghrúpa sin faoi ghlas (data, teaser, sighting nó ask), agus na scáileáin a bhfreastalaíonn sé orthu |
query |
required (gach ainm le luach samplach) agus allowed: na paraiméadair iarratais a léann an bealach |
body |
example: corp samplach bealaigh scríofa, ceann a nglacann a bhailíochtóir féin leis. Ní úsáidtear riamh ar GET é |
Is é rights an clár a ainmníonn na bealaí sin. Tá roles (an uasteorainn) ag gach ceart agus go roghnach summary, never (róil nach bhféadfaidh é a fheidhmiú riamh, is cuma cad eile atá acu), barred (focail an táirge féin chun ról never a dhiúltú), seat (teastaíonn suíochán beo freisin), self (tá sé ag gach duine fíoraithe, le haghaidh ceart ar a seisiún féin), grants (deonaíonn sealbhóirí suíocháin; deir ceart amháin é seo ar a mhéad), licence (gné cheadúnaithe a chaithfidh a bheith ar cheadúnas na heagraíochta) installation (níl sé ach ag riarthóirí na suiteála féin) agus platform (níl sé ach ag riarthóirí ardáin Adverant; ní ainmníonn sé aon róil). Tá ponc amháin ar a laghad in ainmneacha ceart: 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"] }
}Diúltaíonn definePlugin do bhealach raoin gan aon cheart (ENDPOINT_RIGHT_MISSING), do cheart nach bhfuil sa chlár (ENDPOINT_RIGHT_NOT_REGISTERED) agus do cheart ar bhealach nach bhfreastalaíonn aon gharda air (ENDPOINT_RIGHT_UNGUARDED). Diúltaíonn sé freisin do chlár a bhréagnaíonn é féin, agus do dhá litriú ar bhealach amháin (:id agus :recordId) mar DUPLICATE_ENDPOINT.
Do shonraí: databases, schema agus db
Is é schema an t-aon scéimre Postgres atá ag an mbreiseán. Tá cosc ar public, plugins, auth agus nexus, agus má ainmníonn databases[] scéimre Postgres freisin caithfidh an dá cheann a bheith mar a chéile.
Dearbhaíonn databases[] gach stór de réir innill: postgresql (schema, tables, migrations, agus granted, na táblaí a fhéadfaidh eagraíocht eile a léamh faoi dheontas taifeadta), neo4j (schemas), qdrant (collections) nó redis (purpose).
Coinníonn db teorainneacha an tseisiúin do gach nasc a osclaíonn an breiseán, dearbhaithe anseo seachas códaithe ionas gur féidir le hathbhreithneoir agus leis an imscaradh araon iad a léamh:
| Réimse | Cad a theorannaíonn sé |
|---|---|
maxConnections |
An linn in aghaidh an mhacasamhail |
pods |
An líon is mó pod a bhfuil linn acu ag an am céanna, macasamhla móide borradh nuashonraithe rollaigh. Rindreáiltear teorainn nasc gach róil mar maxConnections × pods; fág ar lár é agus tugann definePlugin rabhadh DB_PODS_UNDECLARED |
statementTimeoutMs |
Ráiteas amháin |
idleInTransactionTimeoutMs |
Idirbheart oscailte nach bhfuil ag rith faic |
workMemKB |
Nód sórtála nó haiseála amháin, in aghaidh an nóid, ní in aghaidh an iarratais |
piiMask[] |
Iontrálacha table.column a bhfuil sonraí pearsanta iontu, maisceáilte sa chonsól SQL rialaithe agus i logaí |
Scileanna agus uirlisí: skills, mcpTools, entitlements
Coinníonn skills[] scileanna forógra; clúdaíonn caibidil 2.20, Scileanna, a réimsí agus a leibhéil. Coinníonn mcpTools[] na huirlisí MCP (Model Context Protocol) a fhoilsíonn an breiseán, gach ceann acu ina name, description agus inputSchema gan aon oneOf, allOf nó anyOf ag an mbarrleibhéal.
Teastaíonn featureIdPattern ó entitlements agus glacann sé le alwaysOn[], source agus store. Ainmníonn an patrún an spás ainmneacha ina bhfuil aitheantais do ghnéithe, de réir gnáis name an bhreiseáin móide deighleog amháin a líonann do chód in aghaidh an dromchla. Is é alwaysOn[] an liosta gearr beacht a chaithfidh freagairt fiú nuair nach féidir breithiúnas teidlíochta a fháil: sláinte, ullmhacht, síniú isteach, agus na socruithe a theastaíonn ó riarthóir chun an teidlíocht a dheisiú.
Rialú athruithe: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Comhairtear formheasanna i ndaoine ar leith, agus ní bhíonn an duine a mhol an t-athrú ina measc riamh; gan an dá leath, is ionann "dhá fhormheas" agus duine amháin ag cliceáil faoi dhó. Teastaíonn classes ó enabled: true, agus teastaíonn a chomhaireamh féin ó gach aicme a ainmnítear. Ní rialaítear aicme a fhágann tú ar lár, rogha dhlisteanach a chuireann an scéimre iallach ort a scríobh síos.
Cé thú féin: domains, branding, routing
Liostaíonn domains[] (gach ceann primary agus aliases[]; is é domain an fhoirm aon-fhearainn) cá bhfreagraíonn an breiseán. Teastaíonn appName ó branding agus glacann sé le tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId agus gaId. Tá gach rud in branding poiblí: léann an leathanach sínithe isteach é sula mbíonn dintiúr ag aon duine, mar sin ní choinníonn sé rún ná seoladh inmheánach riamh. Tá routing (type, gateway, virtualService) ann do bhreiseáin a chuireann síos ar a ródú féin.
Toisiú agus an chuid eile
Éilíonn resources cpuMillicores (10 go 64,000) agus memoryMB (16 go 262,144), agus glacann sé le diskGB, timeoutMs, port agus wsPort. Tá port, healthPath, apiPrefix, framework agus platformClients[] in backend, na cliaint SDK a iompórtálann d'inneall cúil de réir ainm. Tá an liosta dúnta, agus seiceálann geata é i gcoinne d'iompórtálacha. Ceadaíonn an scéimre ceithre ainm déag: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin agus uno, móide ceann amháin don chliant a fhreagraíonn diúltuithe teidlíochta plean, a choinníonn ainm inmheánach. Ní ceann acu sin an cliant teidlíochta gné, runtime/entitlements, agus ní théann sé ar an liosta riamh, mar go bhfógraíonn do bhloc entitlements cheana féin é, agus teipeann inneall cúil a iompórtálann é gan bhloc entitlements ar an ngeata céanna. Tá basePath, mountPath agus framework in frontend. Tá minVersion, maxVersion, capabilities[] agus permissions[] in nexus.
Tá gach ceann de na bloic eile ann do phost amháin:
| Bloc | Le haghaidh |
|---|---|
settings |
Do shocruithe ar an gcreat comhroinnte: groups agus keys, socraithe ag na leibhéil a ainmníonn gach ceann acu |
people |
sweep (service, port): baill na heagraíochta, sioncronaithe ón tseirbhís aitheantais, le suíocháin múchta nuair a fhágann duine |
ontology |
entityTypes agus relationshipTypes: an graf clóscríofa a choinnítear i do scéimre féin |
release |
groups agus frame: na grúpaí cumais ina gcuirtear do bhealaí ar stáitse, scaoilte ar dtús mar canary |
cells[] |
Breiseán atá comhdhéanta de roinnt aonad imscartha: name, kind, entrypoint, port, wsPort do gach ceann |
pricing |
model, currency, tiers[] do do liostú sa chatalóg |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Cé a fhoilsíonn é agus cá bhfuil a chód |
metrics, atlas |
An dá réad atá oscailte d'aon ghnó, do d'ainmneacha méadrachta féin agus do ghiniúint doiciméid ailtireachta |
An méid nach féidir leis an scéimre a rá
Socraíonn an JSON Schema an cruth; cuireann definePlugin na rialacha leis nach féidir le scéimre a chur in iúl. Ní féidir le classification scile dul thar an uasteorainn iontaoibhe. Ní féidir ach le breiseáin core agus verified scileanna tool_using agus llm_only a fhógairt. Ní mór do gach cosán fógartha a bheith coibhneasta agus ón mbunús céanna, gan scéim, gan // agus gan cúlslais, mar go n-athraíonn an parsálaí URL \ go / agus go réitíonn /\evil.example/x chuig bunús eile. Cuirtear gach riail a chuireann sioncronú na clárlainne i bhfeidhm ar scil i bhfeidhm anseo ar dtús, le cód an tsioncronaithe féin, ionas go n-ainmníonn validate agus an sioncronú riail bhriste ar an mbealach céanna.
Ag bailíochtú, agus ag bogadh ó 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
Priontálann teip an cosán beacht agus, i gcás riail sioncronaithe, an cód ar dtús. Déan crúca tiomantais de.
Ardaítear forógra v1 go meicniúil. Cuireann migrate na trí abairt dlí leis, bogann sé domain go domains[] agus diúltaíonn sé pointe iontrála nach raibh agat a chumadh. Bailíochtaíonn sé an toradh sula bpriontálann nó sula scríobhann sé aon rud, ionas nach mbogann imirce teip ón uirlis isteach i do stór riamh.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeLéigh an diff sula ndéanann tú é a thiomantú. Is iad na habairtí dlí a chuireann sé leis an fhoclaíocht a shocraíonn an bailíochtóir; do do shuiteáil féin, socraigh deploy chuig an abairt a taispeánadh níos luaithe.
An tionóntacht a rindreáil, agus na róil a sholáthar
Ní scríobhann tú do dheontais ról ná an teimpléad slándála ar leibhéal na sraithe de láimh riamh. Scríobhann nexus-tenancy render iad ó schema agus db an fhorógra:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlCruthaíonn an comhad rindreáilte cúig ról don scéimre, gach ceann acu leis an méid nach ceadmhach dó a shealbhú: imirceoir nach féidir leis ach a bheith ina úinéir, úinéir nach féidir leis logáil isteach, ról feidhmchláir do chosán an iarratais, ról tuairisce nach bhfeiceann ach comhiomláin, agus ról mórleabhair nach féidir leis ach iontrálacha a chur leis. Níl BYPASSRLS ag aon ról. Is é feidhm bunachar sonraí amháin an t-aon bhealach chun tionónta a cheangal, agus cúlghairtear set_config ó gach ról ach amháin an t-úinéir.
Ní chuirtear comhad tionóntachta feidhmithe in eagar riamh. Is athbhreithniú é athrú lena chomhad uimhir-0 féin, agus is ar an mbealach sin a thagann an suíochán léite do dheontais traseagraíochta, mar athbhreithniú 2. Rindreálann --graph dhá thábla an ghraif chlóscríofa a fhógraíonn do ontology mar d'imirce uimhrithe eile.
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.sqlCruthaíonn an comhad tionóntachta na róil chéanna a nascann an reathaí leo, mar sin is é úinéir an bhunachair sonraí a chuireann i bhfeidhm é le nexus-migrate provision:
DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir>Is teaghrán ceangail d'úinéir an bhunachair sonraí é <database-owner-url>, agus is comhadlann phríobháideach é <dir>. Cuireann Provision an bunchomhad tionóntachta agus gach athbhreithniú i bhfeidhm in ord, scríobhann sé migrator.url agus app.url (agus seat.url nuair a bhíonn athbhreithniú 2 ann) isteach in <dir> le mód 0600, agus ní phriontálann sé aon rud rúnda. Socraíonn sé teorainn cheangail gach róil ó db.maxConnections × db.pods ar gach rith. Coinníonn athrith na pasfhocail atá ann cheana mura n-iarrann tú a mhalairt: socraíonn --passwords <dir> iad ó chomhaid agus tugann --rotate <roles> cinn nua do na róil ainmnithe. Déan rúin d'imscaradh de na comhaid.
Ina dhiaidh sin, nascann an fheidhmiú le teaghrán ceangail an imirceora a scríobh provision:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonRitheann sé comhaid 001 ar aghaidh mar an t-imirceoir, gach comhad faoi SET ROLE <schema>_owner, idirbheart amháin in aghaidh an chomhaid. Coinníonn sé mórleabhar, <schema>.schema_migrations, le suim sheiceála gach comhaid; diúltaítear de réir ainm do chomhad feidhmithe a bhfuil a bhearta athraithe (CHECKSUM_DRIFT), ní athritear é riamh agus ní scipeáiltear é riamh. Parsáiltear gach comhad ar feitheamh leis an bhfíorghramadach Postgres sula ritheann an chéad cheann, ionas go bhfágann diúltú an bunachar sonraí gan teagmháil. Is é -- nexus-migration: transaction=file|per-statement an t-aon cheanntásc is féidir le comhad a iompar, le teorainneacha ama roghnacha glais agus ráitis; is le haghaidh CREATE INDEX CONCURRENTLY atá per-statement.
Na geataí
Ritheann nexus-gates dhá gheata is fiche. Ionchódaíonn gach ceann acu aicme amháin locht ionas nach féidir é a sheoladh faoi dhó, agus tá féintástáil ag gach ceann a chruthaíonn go dteipeann air ar dhaingneán a tógadh chun é a thuisliú. Rith iad sula mbrúnn tú:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Geata | Cad a aimsíonn sé |
|---|---|
scope-adherence |
Bealach /api gan an garda raoin; cosán gan ainm nach cosán fógartha beacht é; bealach gléis gan garda an ghléis, nó le garda duine in aice leis |
one-fence |
Preideacáid tionónta sainithe in aon áit seachas áit amháin, lena n-áirítear fál suíocháin nó deontais a rinneadh de láimh |
sql-fence |
Ráiteas a léann nó a nuashonraíonn tábla raoin gan an fál, in aon sprioc FROM, JOIN, USING nó UPDATE |
migrations-are-scoped |
Tábla a bhfuil ais, eochair chomhchodach a thosaíonn le tionónta, eochair eachtrach a iompraíonn tionónta nó an colún taispeána in easnamh air |
migrations-commit-what-they-open |
Imirce nach dtagann a líon BEGIN lena líon COMMIT agus ROLLBACK |
no-direct-compute |
Glao díreach ar sholáthraí samhla, inneall, scuaine nó óstach sreafa oibre; dara léitheoir den URL seolta |
no-credentials |
Dintiúr soláthraí samhla is féidir a léamh sa stór nó sa timpeallacht |
crud-adherence |
Bealach athraithe nach n-ainmníonn a sheiceáil cheart aon rud sa chlár |
blocked-backends |
Bealach nach bhfreastalaítear air, nach bhfuil bactha de réir ainm, nach ndiúltaítear dó de réir dlí agus nach le háit eile é |
every-test-runs |
Tástálacha nach sroicheann glob na scripte tástála riamh |
tiles-are-invariant |
Uaim taiscthe atá neamhathraitheach ó thaobh tionónta de a léann luach tionónta nó a scipeálann fíordheimhniú |
api-contract |
Bealach cláraithe nach bhfógraíonn an forógra, nó ceann fógartha nach gcláraíonn an cód riamh |
rls-present |
Tábla gan slándáil éigeantach ar leibhéal na sraithe; feidhm SECURITY DEFINER gan search_path socraithe |
no-set-config |
Cód breiseáin a cheanglaíonn an socrú tionónta é féin |
db-role-honest |
Cosán iarratais a nascann mar an t-úinéir nó an t-imirceoir, nó a iarrann SUPERUSER nó BYPASSRLS |
platform-clients |
Cliant SDK a iompórtáiltear ach nach bhfuil liostaithe in backend.platformClients, nó atá liostaithe ach nach n-iompórtáiltear riamh |
rights-register |
Bealach raoin gan ceart fógartha; seiceáil cheart in aice leis an gclár |
refusal-ledger |
Tábla diúltaithe fógartha gan mórleabhar suiteáilte, nó corp diúltaithe a sheoltar timpeall air |
grants-declared |
Tábla deonaithe nach bhfógraíonn an forógra; pribhléidí suíocháin léite a thugtar amach de láimh |
people-declared |
Bloc people gan a bhealach scuabtha, a gharda agus a tháblaí |
functions-closure |
Breiseán Azure Functions nach dtagann a bhealaí freastalaithe agus a bhealaí fógartha le chéile |
declared-input |
Liosta paraiméadar fiosrúcháin láimhseálaí nach dtagann le query fógartha an bhealaigh |
Tá na cúig chomhad díolúine is féidir le geata a léamh sa chomhadlann gates/ (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json agus invariant-seams.json), cúis amháin in aghaidh na hiontrála. Ní áirítear cúis bhán mar iontráil, agus teipeann an geata ar iontráil a ainmníonn rud nach bhfuil ann a thuilleadh. Is féidir leat do mhodúil gheata féin a chur ann freisin, agus piocann nexus-gates suas iad in aice leis na cinn ionsuite.
Píblíne an teimpléid
Ní sheolann an teimpléad aon sreabhadh oibre lámhscríofa. Ainmníonn a chumraíocht phíblíne an Dockerfile, an t-aon argóint tógála (comhartha na clárlainne), triail imirce, an tóireadóir tosaithe, agus an geata a ritheann an scuaine chumaisc. Is é an t-ord an t-ord ina mbeadh fonn ort teip.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, arb écreate-nexus-plugin validate nexus.manifest.jsonénpm run gates, arb énexus-gates --self-testénode scripts/ci/required-env
Ritheann dhá sheiceáil eile timpeall na híomhá. Cuireann an triail imirce gach comhad i bhfeidhm ar Postgres indiúscartha sular féidir an íomhá a scaoileadh, leis an reathaí céanna a úsáideann an táirgeadh: nexus-migrate provision uair amháin mar an sárúsáideoir, ansin gach comhad uimhrithe mar an t-imirceoir. Tosaíonn an tóireadóir tosaithe an íomhá thógtha lena pointe iontrála féin agus le gach athróg a phriontálann required-env, dírithe ar ionadaithe a ghlacann le naisc agus nach bhfreagraíonn riamh. Fanann an freastalaí ar an mbunachar sonraí, laistigh dá fhuinneog theoranta, agus is é an feitheamh sin comhartha an phas; teipeann ar an tógáil ansin de bharr lódálaí cumraíochta a dhiúltaíonn tosú, agus ní sa táirgeadh.
Cad a chosnaíonn sé
Baineann an SDK cinntí díot, agus bheadh cuid acu déanta go difriúil agat. Diúltaíonn an forógra d'eochracha nach bhfuil aithne aige orthu, caithfidh an tábla bealaí teacht go beacht le do chód, ní fútsa atá sé na róil bhunachar sonraí a dhearadh, agus teipeann na geataí ar thógáil mar gheall ar cheart in easnamh ar léamh. Ar mo chéad bhreiseán chaith mé lá ag argóint le api-contract faoi bhealach a chláraigh mé agus a ndearna mé dearmad é a fhógairt. Bhí an ceart aige; bhí an bealach gan garda. Bí ag súil go mbraithfidh an chéad bhreiseán mall, agus bí ag súil go dtógfaidh an dara ceann trian den am.

