Leagan 1.0.0-alpha.1is déanaí
Caibidil 2.22
Am rite an bhreiseáin
Na modúil SDK (trealamh forbartha bogearraí) ar a ritheann do bhreiseán, ón ngarda scóipe agus an fál bunachair shonraí go seoladh UNO, léamh bealaigh an AI (intleacht shaorga) agus seiceálacha ceadúnais. Ansin tástáil i gcoinne bunachar sonraí fíor, clárú do scileanna agus bordáil.
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

Is é leath rite-ama an SDK (trealamh forbartha bogearraí) tacar modúl faoi @adverant-nexus/plugin-sdk/runtime/*, mar aon le cúntóirí tástála faoi testing/*. Iompórtálann tú iad; ní athchuireann tú i bhfeidhm iad. Sin an smaoineamh ar fad, agus thóg sé athbhreithniú amháin a diúltaíodh dom sular ghlac mé dáiríre leis: líne amháin a bhí i nóta an athbhreithneora ar an seiceáil scóipe a scríobh mé de láimh i mo chéad bhreiseán, "tá sé seo ag an SDK cheana féin, agus glacann do cheannsa le comhartha dúshláin MFA (fíordheimhniú ilfhachtóireach) mar sheisiún".
Leanann an chaibidil seo iarratas trí bhreiseán atá ag rith, mar a nascann an teimpléad lánseirbhíse é: garda an scóipe, fál an bhunachair sonraí, an t-aon trasnú amháin a cheadaítear, seoladh trí UNO, léamh bhealach AI (intleacht shaorga) agus na seiceálacha ceadúnais. Ansin pléann sé tástáil, clárú scileanna do mhanifeisto, agus na céimeanna ionduchtaithe.
Scóip: garda amháin in aghaidh an chreata
Iompraíonn gach bealach /api garda an scóipe. Fíoraíonn sé an comhartha iompróra, réitíonn sé na trí ais (tionónta, úinéir, aonad) uaidh, diúltaíonn sé do chorp a ainmníonn tionónta, cuireann sé ceart an bhealaigh ó chlár an mhanifeisto i bhfeidhm, agus ansin amháin a ligeann sé don láimhseálaí rith. Seolann an SDK cuibheoir amháin in aghaidh an chreata, iad go léir ó @adverant-nexus/plugin-sdk/runtime/scope agus iad go léir ag glacadh na roghanna céanna.
| Creat | Cuibheoir |
|---|---|
| Express | scopeMiddleware |
| Fastify | requireScope, mar preHandler |
| Next | withScope, ag timfhilleadh an láimhseálaí; ní insítear a bhealach do láimhseálaí Next, mar sin glacann withScope é mar thríú argóint |
Seo nascadh Express an teimpléid, giorraithe. Is leis an SDK an fíoraitheoir, agus coinníonn sé an comhartha le formáid seisiúin na seirbhíse aitheantais: HS256 amháin; iss, exp, iat agus jti riachtanach; saolré uair an chloig ar a mhéad; agus ní ghlactar le dúshlán MFA, pearsanú ná comhartha acmhainne OAuth (an caighdeán oscailte d'údarú tarmligthe) mar sheisiún.
import { platformAccessTokenVerifier } from "@adverant-nexus/plugin-sdk/runtime/platform-token";
import { scopeMiddleware } from "@adverant-nexus/plugin-sdk/runtime/scope";
const requireScope = scopeMiddleware({
verify: platformAccessTokenVerifier(config.PLATFORM_JWT_SECRET),
rights: { manifest },
});
router.get("/api/projects", requireScope, async (req, res) => {
res.json({ projects: await db.listProjects(scopeOf(req)) });
});Cuireann garda na gceart ceart bealaigh i bhfeidhm i gceithre chéim. Diúltaíonn ról atá i liosta never an chirt le AUTHORITY_EXCEEDED agus na focail barred, agus ní ardaíonn suíochán ar bith é. Ligeann ról in roles isteach, le suíochán beo freisin nuair a deir an ceart seat: true. Seachas sin, ligeann suíochán beo a iompraíonn an ceart isteach. Seachas sin, diúltaítear don iarratas AUTHORITY_EXCEEDED, ag ainmniú na ndaoine a d'fhéadfadh suíochán a dheonú. Tabhair stór don gharda (rights: { manifest, store: { pool, schema } }) agus léann sé suíocháin faoi scóip an ghlaoiteora féin; teastaíonn léitheoir ceadúnais freisin ó cheart a ainmníonn licence, a phléitear thíos.
Laistigh de láimhseálaí, is é scopeOf(req) an t-aon bhealach chun an scóip réitithe a léamh, agus caitheann sé earráid mura ndearna an garda rith. Freagraíonn garda a cláraíodh ar réimír, a ritheann sula meaitseálann bealach ar bith, 500 MIDDLEWARE_ORDERING_ERROR; freagraíonn bealach a chláraíonn do chód nach bhfógraíonn an manifeisto 500 UNHANDLED_ERROR. Teipeann an dá cheann dúnta.
Úsáideann bealaí /internal an teimpléid, a ghlaonn an t-ardán, an córas eile. Seiceálann garda na seirbhíse X-Service-Key in am tairiseach agus tógann sé an tionónta ó X-Organization-ID an ardáin, ag diúltú do MISSING_SERVICE_KEY, INVALID_SERVICE_KEY nó MISSING_ORG_ID_HEADER. Don chomhartha sínithe in aghaidh an ghlao ón ardán, tá requireService (Fastify) agus serviceMiddleware (Express) ag an SDK, a sheiceálann freisin cén scil agus cén bealach dar mionnaíodh an comhartha agus a dhiúltaíonn do chomhartha a úsáidtear faoi dhó.
Fál an bhunachair sonraí: tenantFence agus withScopedTx
Cumann gach ráiteas i gcoinne tábla scóipthe an fál agus ritheann sé laistigh d'idirbheart scóipthe:
import { withScopedTx } from "@adverant-nexus/plugin-sdk/runtime/db";
import { tenantFence } from "@adverant-nexus/plugin-sdk/runtime/fence";
async function listProjects(scope: ResolvedScope) {
// Projects are owner-private inside the organisation, so the owner axis is passed explicitly.
const f = tenantFence(scope, { alias: "p", owner: scope.owner });
const r = await withScopedTx(pool, scope, { schema: SCHEMA }, (db) =>
db.query(`SELECT p.* FROM anomaly_review.reviews p WHERE ${f.where} ORDER BY p.created_at DESC`, f.params),
);
return r.rows;
}Tógann tenantFence(scope, options) an preideacáid agus a paraiméadair ó scóip réitithe. Tabhair owner do tháblaí pearsanta; fág amach é d'fhoirgintí eagraíochta ina bhfuil an t-úinéir mar phromhadh tionscnaimh. Nuair atá paraiméadair ag an ráiteas cheana féin, insíonn startIndex don fhál cén áit ar cheart tosú ag uimhriú. Ní ghlacann ionsá na haiseanna mar ionchur riamh: scríobhann sé scope.tenant, scope.owner agus scope.unit ón scóip.
Ceanglaíonn withScopedTx na trí ais ar fad d'idirbheart amháin trí fheidhm cheangail amháin an scéimre, agus ansin ritheann sé d'aisghlaoch. Ardaíonn an dara ceangal san idirbheart céanna SCOPE_ALREADY_BOUND (500: cheangail do chód faoi dhó; ní dhearna an glaoiteoir aon ní mícheart). Ardaíonn tionónta nó úinéir atá as láthair nó nialasach SCOPE_PREDICATE_INVALID (403). Tá an socrú áitiúil don idirbheart, mar sin ní féidir le nasc comhthiomsaithe tionónta amháin a iompar isteach san chéad iarratas eile.
Clúdaíonn dhá cheann gaolmhara na cásanna nach iarratas duine iad. Ceanglaíonn withTenantScopedTx tionónta agus aonad gan úinéir, do shraitheanna a léann meaisín (clár na ngléasanna), agus diúltaíonn sé do scóip a iompraíonn úinéir. Cuireann maintenanceScope(reason) iallach ar oibríocht ar fud na heagraíochta a rá os ard cad é féin sula n-osclóidh idirbheart an úinéara. Is dhá mheicníocht d'aon dlí amháin iad fál an chóid agus slándáil éigeantach ar leibhéal na sraithe; diúltaíonn an seiceáil tosaithe éisteacht go dtí go gcruthaíonn an bunachar sonraí go seasann an dara ceann (DB_ROLE_BYPASSES_ISOLATION murach sin).
Is ró é gach diúltú
Suiteálann an teimpléad píosa amháin eile de mheánearraí, uair amháin, idir parsálaí an choirp agus na ródairí: mórleabhar na ndiúltuithe.
import { recordRefusals } from "@adverant-nexus/plugin-sdk/runtime/refusal-ledger";
app.use(express.json({ limit: "256kb" }));
app.use(recordRefusals({ pool, schema: SCHEMA }));Timfhilleann sé an freagra ionas go scríobhtar gach diúltú a léann duine, cibé ó gharda na gceart, ó láimhseálaí nó ó stór, chuig tábla refusal do scéimre laistigh d'idirbheart scóipthe an duine sin féin sula seoltar an corp. Ní scríobhann 401 gan ainm aon ní. Mura féidir an tsraith a scríobh, is é UNHANDLED_ERROR an freagra: ní sheoltar "ní hea" nach féidir leis an táirge a thaifeadadh amhail is dá bhféadfaí. Ritheann an tosú assertRefusalLedger chun a sheiceáil gur féidir leis an tábla sraith an mhórleabhair a ghlacadh, agus is féidir le stór noteSubject({ recordId, isDemo }) a ghlaoch ionas go n-ainmníonn gach diúltú an taifead a raibh sé faoi. Nuair a fhiafraíonn custaiméir cén fáth ar diúltaíodh do dhuine Dé Máirt seo caite, is fiosrúchán an freagra, ní buille faoi thuairim.
An t-aon trasnú amháin: deontas inléite amháin taifeadta
Nuair a dhéanann duine de do chustaiméirí obair do dhuine eile agus gur féidir leis an duine eile í a iniúchadh, tá bealach ceadaithe amháin trasna na teorann. Taifeadann an eagraíocht a bhfuil na sraitheanna aici deontas. Ligeann eagraíocht an léitheora duine isteach trí shuíochán a iompraíonn an ceart granted.read, ar gá dó owner agus admin a ainmniú in never. Ritheann an léamh mar shéú ról bunachair sonraí, an suíochán léite, nach féidir leis ach na táblaí a liostaíonn databases[].granted a roghnú:
const r = await withSeatTx({ app: appPool, seat: seatPool }, seatsOf(req), { holder, grantId }, { schema: "anomaly_review" }, (db) => {
const f = grantFence(db.seat, { alias: "r" });
return db.query(`SELECT r.review_id FROM anomaly_review.reviews r WHERE ${f.where}`, f.params);
});
if (!r.ok) return res.status(r.status).json(r.refusal);Scríobhann withSeatTx an amharc i dtionónta an léitheora féin ar dtús, ansin ceanglaíonn sé an suíochán léite leis an deontas, rud a scríobhann an amharc i dtionónta an tsealbhóra. Seiceálann polasaí an bhunachair sonraí féin go n-ainmníonn an deontas eagraíocht an léitheora, go gclúdaíonn sé an tábla, go bhfuil sé tosaithe, nach bhfuil sé críochnaithe agus nár tarraingíodh siar é, agus gur scríobh an t-idirbheart seo a amharc. Ní fheiceann léamh a scipeálann an amharc aon ní. Ag an tosú, seiceálann assertSeatAtBoot(seatPool, schema) gur an suíochán agus gan aon ní eile é an comhthiomsú a osclaíodh ó seat.url, agus diúltaíonn sé le DB_SEAT_ROLE_INVALID murach sin.
Seoladh trí UNO
Téann gach ríomh trí chliant amháin, a tógadh i gcomhad amháin, le liosta ceadaithe dúnta:
import { UnoClient } from "@adverant-nexus/plugin-sdk/runtime/uno";
/** The namespaced job types this surface may dispatch. Closed; edit in code. */
export const DISPATCHABLE = Object.freeze([`${manifest.name}.sentiment_score`] as const);
export function createUno(deps: UnoDeps): UnoClient {
return new UnoClient({
baseUrl: deps.dispatchUrl,
serviceKey: deps.serviceKey,
callerService: manifest.name,
dispatchable: DISPATCHABLE,
});
}Is tairiseach ar leibhéal an mhodúil an liosta ceadaithe d'aon ghnó. Dá bhféadfadh oibreoir é a leathnú ón gcumraíocht, bheadh an bealach ina sheachfhreastalaí seolta don chlár ar fad. Dearbhaíonn tástáil an teimpléid féin go n-ainmníonn an liosta go díreach na cineálacha jab a dtiomsaíonn an manifeisto chucu.
An clúdach
Iompraíonn seoladh sé réimse ag a chroílár riachtanach. Líonann an cliant an tionónta agus an gníomhaí ón scóip fhíoraithe, riamh ón iarratas:
| Réimse | An méid atá ann |
|---|---|
jobType |
An cineál jab ainmspásáilte, <plugin name>.<skill id> |
organizationId |
An tionónta, ón scóip |
userId |
An gníomhaí, ón scóip, le haghaidh iniúchta agus billeála |
inputParams |
Ionchur na scile. Ní iompraíonn sé aitheantas tionónta riamh; diúltaítear ag an seoladh do cheann a iompraíonn |
priority |
critical, high, normal nó low |
pluginId |
name do mhanifeisto. Fógraíonn gach seoladh an breiseán ónar tháinig sé |
Áirítear ar na réimsí roghnacha correlationId (UUID (aitheantóir uathúil uilíoch), nó mionnaítear ceann nua) agus callbackUrl, a theastaíonn ó scil plugin_queue ionas go mbeidh a fhios ag an oibrí cá bpostálfaidh sé a thoradh.
const accepted = await uno.dispatch(scope, {
jobType: DISPATCHABLE[0],
inputParams: { text: text.body },
priority: "normal",
pluginId: manifest.name,
correlationId: crypto.randomUUID(),
});
if (!accepted.ok) return res.status(statusFor(accepted.refusal.code)).json(accepted.refusal);
res.status(202).json(accepted.value);202, ansin vótaíocht
Cuirtear gach seoladh sa scuaine. Is é 202 le haitheantóirí (jobId, runId, traceId, status) an freagra i gcónaí, riamh toradh. Tagann an toradh ó vótaíocht an jab nó ó d'aisghlaoch. Léann uno.peek(jobId, { scope }) é uair amháin agus vótálann awaitJob go stádas deiridh; seolann an dá cheann an tionónta ón scóip fhíoraithe, agus seiceálann an dá cheann organization_id na sraithe a fhilltear i gcoinne thionónta an ghlaoiteora ar do thaobh féin den ghlao líonra, ag diúltú do mhímheaitseáil le SCOPE_REFUSED.
Léigh sraith an rite ina litriú féin. Deir freagra an tseolta jobId; deir an tsraith job_id, organization_id agus plugin_id. Is iad result, error, error_code agus error_troubleshooting colúin an toraidh agus na teipe. Is stádais deiridh iad completed agus failed. Tagann timed_out, cancelled agus system_failure ón mbainteoir agus féadfaidh toradh déanach iad a cheartú fós. Diúltaíonn cliant a mheasann aon cheann díobh sin a bheith doparsáilte do shraitheanna a scríobhann an t-ardán gach lá.
An coinneáil faofa
Coinnítear ag an seoladh scil manifeisto a fhógraíonn approval. Deir an 202 ansin status: "awaiting_approval" agus iompraíonn sé waitpointId, leis an gcúis a thug an manifeisto. Fanann an rith coinnithe go dtí go dtugann duine ainmnithe rialú air. Seolann uno.approve agus uno.resolveWaitpoint an tionónta agus an glaoiteoir mar an gníomhaí, agus diúltaítear do rialú ó dhuine seachas an glaoiteoir fíoraithe. Scaoileann faomhadh an jab uair amháin agus ritheann sé seiceálacha an tseolta arís; cuireann diúltú deireadh leis failed. Diúltaítear do dhara rialú, agus do rialú tar éis don choinneáil dul in éag freisin. Má theastaíonn ó do tháirge gur duine difriúil ón moltóir an faomhóir, cuir é sin i bhfeidhm sa bhealach a thugann an rialú: taifeadann an t-ardán an bheirt.
Taispeáin jab coinnithe mar jab coinnithe. Ná hinis do dhuine gur scaoil a chlic é go dtí go ndeir sraith an rite amhlaidh.
AI: mianta ar an ró scile, agus léamh amháin
Ní ghlaonn do bhreiseán ar mhúnla riamh. Nuair a theastaíonn ceann ó scil manifeisto (llm_only nó tool_using, ag muinín core nó verified), cuireann tú roghanna in iúl ar a sraith sa chlár, agus cinneann an ródaire ó chomhthiomsú na heagraíochta féin:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"capabilityProfile": { "needsToolUse": true, "dataResidency": "eu_only" }
}
}Is mianta iad preferredProvider agus preferredModel nach n-urramaíonn an ródaire ach amháin nuair atá an soláthraí sin cumasaithe agus dintiúir aige ag an eagraíocht. Scagann capabilityProfile agus ní roghnaíonn sé riamh; is srian docht é a dataResidency (eu_only, us_only nó any) a shásaíonn an ródaire nó a ndiúltaíonn sé dó. Is ceart iad go léir a fhágáil amach de ghnáth. Tá modelOverride ann don scil annamh a dteastaíonn múnla beacht amháin uaithi, agus fágann sé na mianta in aice leis gan éifeacht; sheachnóinn é mura bhfuil an scil gan bhrí ar aon mhúnla eile.
Nuair is gá do chomhéadan a thaispeáint cén múnla a d'úsáidfeadh an ródaire, léigh é, ná tuar é:
import { createAIRouteClient } from "@adverant-nexus/plugin-sdk/runtime/ai-route";Is é createAIRouteClient(...).effectiveRoute() an t-aon léamh ceadaithe de Ródaire Soláthraithe AI. Glacann sé seoladh an gheata, iompróir an ghlaoiteora féin agus slug d'ardáin, agus ní sheolann sé aon iarratas AI. Freagraíonn sé an soláthraí agus an múnla, na soláthraithe a cheadaíonn an polasaí, agus an ritheann an críochphointe roghnaithe local nó external. Nuair nach bhfuil an bealach inúsáidte, freagraíonn sé diúltú an ródaire i bhfocail (NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE nó NO_MODEL_FOR_ROLE_AND_PROVIDER, leis an réiteach), riamh múnla réamhshocraithe. Taispeáin an diúltú sin don duine; cumraíocht a eagraíochta féin atá ag labhairt.
Seiceálacha ceadúnais
Seiceálann trí mheicníocht an ceadúnú, ag trí ghráinneacht.
Ceart a ainmníonn ceadúnas. An ceann is simplí. Sa mhanifeisto, iompraíonn ceart licence: "<feature>", agus fiafraíonn an garda den tseirbhís aitheantais an iompraíonn ceadúnas na heagraíochta é, le comhartha an ghlaoiteora féin, sula léitear ról ar bith. Tóg an garda le léitheoir:
import { createLicenceReader } from "@adverant-nexus/plugin-sdk/runtime/licence";
const requireScope = scopeMiddleware({
verify,
rights: { manifest, store: { pool, schema: SCHEMA }, licence: createLicenceReader({ baseUrl: config.NEXUS_AUTH_URL }) },
});Diúltaíonn ceadúnas nach n-iompraíonn an ghné do gach duine le LICENCE_LOCKED, ag ainmniú cad a iompraíonn í agus ag rá gur féidir le húinéirí agus le riarthóirí na heagraíochta í a chasadh air. Diúltaíonn ceadúnas nach féidir a léamh UNHANDLED_ERROR: ní fhreastalaítear riamh ar ghné faoi ghlas toisc go raibh an ceadúnas as raon. Cuimhnítear ar fhreagraí ar feadh 30 soicind in aghaidh na heagraíochta agus na gné.
Geata an táirge. Fiafraíonn createProductGate({ baseUrl, product }) ó runtime/product-gate den seiceáil teidlíochta an bhfuil do tháirge ag eagraíocht an ghlaoiteora ar chor ar bith, agus ritheann a middleware() tar éis gharda an scóipe. Is é ENTITLEMENT_DENIED breithiúnas diúltach; is é ENTITLEMENT_UNREACHABLE seiceáil nach féidir teacht uirthi, agus ní mheasann an geata ceann acu mar an ceann eile riamh.
An doiciméad ceadúnais féin. Úsáideann cód nach mór dó cinneadh a dhéanamh dó féin ón gceadúnas sínithe, amhail modúl dúnta pacáiste fearainn, verifyLicenceDocument(docText, opts) ó runtime/licence-document. Feidhm íon atá ann: gan glao líonra, gan athróg timpeallachta, gan chomhad. Seiceálann sé an dá shíniú i gcoinne na bhfréamhacha muiníne a iompraíonn an tógáil agus freagraíonn sé staid (VALID, WARN, GRACE, RESTRICT, TERMINATE nó ABSENT) leis na deontais, na breiseáin agus na pacáistí fearainn. Deir licenceAllows(verdict, featureGroup, action, tenantId?) ansin an bhfuil cead agat use nó provision faoi ghrúpa. Ceadaíonn RESTRICT use agus freagraíonn sé provision le LICENCE_LOCKED, ionas go leanann obair atá ag rith ar aghaidh agus nach dtosaíonn aon ní nua.
Tástáil
Taispeánann tástálacha an teimpléid an patrún; seo iad na huirlisí atá taobh thiar de.
Bréagáin scóipe. Tóg an dúblach scóipe réitithe uair amháin, in test/scope-fakes.ts, agus instealladh é i ngach áit, na cásanna easpacha san áireamh: gan aonad, gan chomhartha, comhartha le heagraíocht nialasach. Is iad conairí an diúltaithe an táirge.
Iompar seolta bréige. Glacann UnoClient fetch, now agus sleep, ionas nach mbaineann tástáil aonaid leis an líonra riamh. Dearbhaigh réimsí an chlúdaigh, cruth 202, an suirbhéireacht stádais arís agus arís eile go dtí sraith deiridh lena organization_id, agus go gcaitear amach sraith do thionónta eile.
Postgres fíor. Cruthaíonn feidhm fiosrúcháin bhréige teaghrán SQL. Ní féidir léi a chruthú go seasann an tslándáil éigeantach ar leibhéal na sraithe ná go gcuirtear na comhaid i bhfeidhm in ord mar a dhéanann an t-imirceoir. Tosaíonn testing/ephemeral-postgres freastalaí indiúscartha agus ritheann sé an nexus-migrate céanna a ritheann an táirgeadh:
import { EPHEMERAL_REMEDY, migrated, startEphemeralPostgres } from "@adverant-nexus/plugin-sdk/testing/ephemeral-postgres";
const pg = await startEphemeralPostgres(); // null off CI: skip each case by name with EPHEMERAL_REMEDY
const db = migrated(pg!, "plugin_test", { root }); // provision as the superuser, then every file as the migrator
// connect as db.appUrl and run the boot checks the server runsLasmuigh de CI (comhtháthú leanúnach), scipeálann meaisín nach bhfuil freastalaí Postgres air gach cás bunachar sonraí de réir ainm, mar aon leis an leigheas, agus ní bhíonn sé glas riamh. In CI, teipeann ar an tsraith tástálacha mar gheall ar an easpa chéanna (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI), mar is geata glas nár thomhais aon rud é tástáil slándála ar leibhéal na sraithe a scipeáladh. Fanann an freastalaí suas le 180 soicind le tosú, agus stopann faireoir é nuair a imíonn próiseas na tástála.
An úim aonraithe. Léann runIsolationHarness(target) ó testing/isolation-harness gach bealach a fheistíonn d'aip agus ionsaíonn sé gach ceann acu mar riarthóir eagraíochta eile agus mar chomhghleacaí. Ansin ionsaíonn sé arís agus fál an chóid bainte, fál an bhunachair sonraí bainte, agus an dá cheann bainte. Ní bhíonn bealach PROVEN ach amháin nuair a theipeann ar an ionsaí agus ceachtar fál i bhfeidhm agus nuair a shroicheann sé sonraí an íospartaigh agus an dá cheann bainte, ionas go mbeidh a fhios agaibh gur féidir leis an tástáil sceitheadh a fheiceáil ar chor ar bith. Seolann sé an fiosrúchán dearbhaithe agus an corp samplach atá ag gach bealach, ionas go sroichtear fiú bealach a dhiúltaíonn d'iarratas folamh. Socraigh ledgerOf(report) i dtástáil agus teip ar defectsOf(report).
Clárú: ó fhollas go clárlann scileanna
Sroicheann scileanna bhur léiriúcháin clárlann na scileanna ar aon bhealach amháin:
manifest.skills[] → compileRegistry(manifest) → POST /api/v1/plugins/sync
Iompaíonn compileRegistry léiriúchán bailíochtaithe ina chorp nexus.plugin-sync/v1. Déanann an teimpléad é ag am iompórtála, ionas go dteipeann ar an tógáil má tá léiriúchán neamhbhailí:
import { compileRegistry, definePlugin } from "@adverant-nexus/plugin-sdk";
export const manifest = definePlugin(raw);
export const registryPayload = compileRegistry(manifest);{
"contract": "nexus.plugin-sync/v1",
"pluginId": "anomaly-review",
"version": "0.3.0",
"skills": [ { "job_type": "anomaly-review.excursion_summary", "tier": "host_callback", "classification": "tenant" } ]
}Is sioncrónú dearbhach é: seol an tacar scileanna iomlán gach uair, agus díchumasaítear scil a fágadh amach, agus coinnítear a stair. Tá sé dian: diúltaítear do réimse anaithnid, do réimse de shraith eile nó do null, tagann gach sárú ar ais le chéile in aon 400 SYNC_CONTRACT_VIOLATION amháin, agus ní scríobhtar aon rud fad is atá ceann ann. Agus scríobhann sé sraith chláraithe amháin in aghaidh na scile, eochraithe ar an gcineál poist ainmspásáilte, ina bhfuil gach colún a léann an seoltóir, ionas gur féidir an scil a rith a luaithe a fhreagraíonn an sioncrónú 200.
Is é an breiseán an glaoiteoir fíordheimhnithe, ní réimse coirp riamh. Glaoigh ar an sioncrónú ó ualach oibre an bhreiseáin féin thar mTLS (TLS frithpháirteach: Transport Layer Security le teastas ag an dá cheann). Léann an Skills Engine teastas cliaint bhur n-ualaigh oibre, a n-ainmníonn a aitheantas SPIFFE (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>) an t-ainmspás agus an cuntas seirbhíse, agus lorgaíonn sé an breiseán agus an eagraíocht úinéireachta atá taifeadta don ainmspás sin. Caithfidh pluginId an choirp a bheith comhionann; is seiceáil é, ní roghnóir. Scríobhtar gach sraith leis an mbreiseán agus leis an eagraíocht sin.
| Stádas | Cód | Brí |
|---|---|---|
| 200 | {contract, pluginId, version, created, updated, unchanged, disabled, skills} |
|
| 400 | SYNC_CONTRACT_VIOLATION |
Gach sárú liostaithe in violations[]; ní scríobhtar aon rud |
| 401 | UNAUTHORIZED |
Eochair seirbhíse lochtach nó in easnamh |
| 401 | CALLER_IDENTITY_UNVERIFIED |
Níl aitheantas cliaint inléite ann |
| 403 | DELIVERY_IDENTITY_MISSING |
Ní bhaineann an t-ainmspás glaoiteach le haon bhreiseán |
| 403 | PLUGIN_ID_MISMATCH |
Ainmníonn an corp breiseán eile |
| 409 | REGISTRY_CONFLICT |
Is le háit eile cineál poist nó cláraíodh é lasmuigh den sioncrónú; ní scríobhtar aon rud |
Cuir teip ar bhur gcéim imscartha ar aon stádas seachas 200. Ní chiallaíonn aon stádas eile go bhfuil bhur scileanna cláraithe.
Bordáil
Ritheann an ionduchtú mar dheich gcéim in ord, agus is féidir gach ceann acu a athrith, a chealú nó a rolladh siar ina aonar:
- Clónáil an stór agus bailíochtaigh é.
- Parsáil an léiriúchán.
- Scan é le haghaidh fadhbanna slándála.
- Tóg an íomhá.
- Brúigh í chuig clárlann na suiteála.
- Socraigh a hainmneacha fearainn.
- Imscar í, trí chainéil eisiúna na suiteála.
- Fan leis an tseiceáil sláinte.
- Cláraigh an breiseán.
- Cuir an forbróir ar an eolas.
Roimh imscaradh, ritheann cúig sheiceáil chomhréireachta i gcoinne an léiriúcháin agus na híomhá tógtha: parsáiltear an léiriúchán agus tá a réimsí riachtanacha ann; is bealach fíor cláraithe é gach bealach dearbhaithe; is leis an mbreiseán a scéimre agus ní scríobhann sé aon rud lasmuigh de; tá iarratais acmhainní dearbhaithe agus laistigh de theorainneacha; agus tá láimhseálaí sláinte oibre ag an íomhá. Ritheann breiseán a chláraíonn é féin ag am tosaithe an conradh céanna faoina údarás féin, ionas go mbíonn na seiceálacha ina CI aige seachas ag an bpíblíne. Ní ghiorraíonn sé an t-ionduchtú ceann a scipeáil; bogann sé an teip go dtí am rite.
Freastalaítear an brandáil i bhur léiriúchán gan fíordheimhniú de réir fearainn, mar teastaíonn sí ón leathanach sínithe isteach sula mbíonn dintiúr ag aon duine. Caithigí le gach rud in branding mar rud poiblí.
GATE_CANNOT_BE_SKIPPED.Cad nach ndéanfaidh an t-am rite duit
Coinníonn an t-am rite an líne ar aonrú, ar sheoladh agus ar rochtain ar mhúnlaí. Ní cheartóidh sé loighic bhur dtáirge, agus ní dhéanfaidh sé fiosrúchán mall tapa: ritheann gach ráiteas laistigh d'idirbheart faoi cheangal leis na teorainneacha ama a dhearbhaíonn bloc db bhur léiriúcháin, agus cealaítear ráiteas a sháraíonn statementTimeoutMs seachas fanacht leis. Ceap méid bhur bhfiosrúchán dá réir sin. Agus cuireann an coinneáil faofa, an suíochán léite agus léitheoir an cheadúnais go léir babhta nó idirbheart breise leis. Ar mo bhreiseán athbhreithnithe aimhrialtachtaí, chuir seiceáil an cheadúnais cúpla milleasoicind le gach iarratas go dtí gur théigh a chuimhne 30 soicind, rud ba phraghas cóir é as gan gné faoi ghlas a sheirbheáil riamh.

