Version 1.0.0-alpha.1aktuell
Kapitel 2.22
Die Plugin-Laufzeitumgebung
Die SDK-Module (Software Development Kit), auf denen Ihr Plugin läuft, vom Scope Guard und der Datenbank-Abgrenzung bis zum UNO-Dispatch, dem Auslesen der KI-Route (künstliche Intelligenz) und Lizenzprüfungen. Anschließend das Testen gegen eine echte Datenbank, das Registrieren Ihrer Skills und das Onboarding.
Diese Seite wurde mithilfe von KI aus dem englischen Original übersetzt. Bei Unklarheiten gilt die englische Seite als Referenz. Diese Seite auf Englisch lesen

Die Laufzeithälfte des SDK (Software Development Kit) besteht aus einer Reihe von Modulen unter @adverant-nexus/plugin-sdk/runtime/* sowie Test-Helfern unter testing/*. Sie importieren sie; Sie implementieren sie nicht neu. Das ist die Grundidee, und es brauchte ein abgelehntes Review, bis ich sie ernst nahm: Die Anmerkung des Prüfers zur selbst geschriebenen Bereichsprüfung meines ersten Plugins bestand aus einer einzigen Zeile: „Das SDK hat das bereits, und Ihre akzeptiert ein MFA-Challenge-Token (Multi-Faktor-Authentifizierung) als Sitzung.“
Dieses Kapitel verfolgt eine Anfrage durch ein laufendes Plugin, so wie die Full-Service-Vorlage sie verdrahtet: den Bereichswächter (Scope Guard), die Datenbankbegrenzung (Database Fence), den einzigen erlaubten Grenzübertritt, den Versand (Dispatch) über UNO, das Auslesen der KI-Route (Künstliche Intelligenz) und die Lizenzprüfungen. Anschließend behandelt es das Testen, das Registrieren Ihrer Manifest-Skills und die Onboarding-Schritte.
Scope: Ein Guard pro Framework
Jede /api-Route trägt den Bereichswächter. Er überprüft das Bearer-Token, löst daraus die drei Achsen (Mandant, Eigentümer, Einheit) auf, lehnt einen Body ab, der einen Mandanten nennt, wendet das Recht der Route aus dem Register des Manifests an und lässt erst dann den Handler laufen. Das SDK liefert einen Adapter pro Framework, alle aus @adverant-nexus/plugin-sdk/runtime/scope und alle mit denselben Optionen.
| Framework | Adapter |
|---|---|
| Express | scopeMiddleware |
| Fastify | requireScope, als preHandler |
| Next | withScope, umschließt den Handler; einem Next-Handler wird seine Route nicht mitgeteilt, daher nimmt withScope sie als drittes Argument entgegen |
Hier ist die Express-Verdrahtung der Vorlage in gekürzter Form. Der Prüfer (Verifier) stammt aus dem SDK und verpflichtet das Token auf das Sitzungsformat des Identitätsdienstes: nur HS256; iss, exp, iat und jti erforderlich; eine Lebensdauer von höchstens einer Stunde; und kein MFA-Challenge-, Impersonation- oder OAuth-Ressourcen-Token (der offene Standard für delegierte Autorisierung) wird als Sitzung zugelassen.
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)) });
});Der Rechtewächter (Rights Guard) wendet das Recht einer Route in vier Schritten an. Eine Rolle in der never-Liste des Rechts lehnt mit AUTHORITY_EXCEEDED und dem Wortlaut aus barred ab, und kein Platz (Seat) hebt dies auf. Eine Rolle in roles gewährt Zutritt, zusammen mit einem aktiven Platz, wenn das Recht seat: true vorgibt. Andernfalls gewährt ein aktiver Platz, der das Recht trägt, Zutritt. Andernfalls wird die Anfrage mit AUTHORITY_EXCEEDED abgelehnt, wobei die Personen genannt werden, die einen Platz vergeben könnten. Geben Sie dem Wächter einen Speicher (rights: { manifest, store: { pool, schema } }), und er liest Plätze unter dem eigenen Bereich des Aufrufers aus; ein Recht, das ein licence nennt, benötigt außerdem einen Lizenzleser, der weiter unten behandelt wird.
Innerhalb eines Handlers ist scopeOf(req) der einzige Weg, den aufgelösten Bereich auszulesen, und es wirft einen Fehler, wenn der Wächter nicht gelaufen ist. Ein auf einem Präfix registrierter Wächter, der läuft, bevor eine Route gepasst hat, antwortet mit 500 MIDDLEWARE_ORDERING_ERROR; eine von Ihrem Code registrierte Route, die das Manifest nicht deklariert, antwortet mit 500 UNHANDLED_ERROR. Beide schlagen sicher geschlossen fehl (Fail Closed).
Die /internal-Routen der Vorlage, die von der Plattform aufgerufen werden, nutzen das andere Regime. Der Dienstwächter (Service Guard) prüft X-Service-Key in konstanter Zeit und übernimmt den Mandanten aus X-Organization-ID der Plattform, wobei er MISSING_SERVICE_KEY, INVALID_SERVICE_KEY oder MISSING_ORG_ID_HEADER ablehnt. Für das signierte Pro-Aufruf-Token der Plattform bietet das SDK requireService (Fastify) und serviceMiddleware (Express), die außerdem prüfen, für welchen Skill und welche Route das Token geprägt wurde, und ein doppelt verwendetes Token ablehnen.
Die Datenbankbegrenzung: tenantFence und withScopedTx
Jede Anweisung gegen eine bereichsgebundene Tabelle setzt die Begrenzung zusammen und läuft innerhalb einer bereichsgebundenen Transaktion:
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;
}tenantFence(scope, options) erstellt das Prädikat und seine Parameter aus einem aufgelösten Bereich. Übergeben Sie owner für persönliche Tabellen; lassen Sie es weg für Organisationsartefakte, bei denen der Eigentümer die Herkunft angibt. Wenn die Anweisung bereits Parameter hat, teilt startIndex der Begrenzung mit, ab wo nummeriert werden soll. Ein Insert nimmt niemals die Achsen als Eingabe entgegen: Es schreibt scope.tenant, scope.owner und scope.unit aus dem Bereich.
withScopedTx bindet alle drei Achsen für eine Transaktion über die eine Bind-Funktion des Schemas und führt dann Ihren Callback aus. Ein zweites Binden in derselben Transaktion löst SCOPE_ALREADY_BOUND aus (500: Ihr Code hat zweimal gebunden; der Aufrufer hat nichts falsch gemacht). Ein fehlender oder auf null gesetzter Mandant oder Eigentümer löst SCOPE_PREDICATE_INVALID aus (403). Die Einstellung ist transaktionslokal, sodass eine gepoolte Verbindung keinen Mandanten in die nächste Anfrage verschleppen kann.
Zwei Geschwisterfunktionen decken die Fälle ab, die keine Anfrage einer Person sind. withTenantScopedTx bindet Mandant und Einheit ohne Eigentümer, für Zeilen, die eine Maschine liest (die Geräteregistrierung), und lehnt einen Bereich ab, der einen Eigentümer trägt. maintenanceScope(reason) zwingt eine organisationsweite Operation dazu, offen auszusprechen, was sie ist, bevor sich die Transaktion des Eigentümers öffnet. Die Code-Begrenzung und die erzwungene Sicherheit auf Zeilenebene (Row-Level Security) sind zwei Mechanismen für ein Gesetz; die Boot-Prüfung lässt den Server erst dann Verbindungen annehmen, wenn die Datenbank nachweist, dass der zweite greift (andernfalls DB_ROLE_BYPASSES_ISOLATION).
Jede Ablehnung ist eine Zeile
Die Vorlage installiert einmalig ein weiteres Stück Middleware zwischen dem Body-Parser und den Routern: das Ablehnungsbuch (Refusal Ledger).
import { recordRefusals } from "@adverant-nexus/plugin-sdk/runtime/refusal-ledger";
app.use(express.json({ limit: "256kb" }));
app.use(recordRefusals({ pool, schema: SCHEMA }));Es umschließt die Antwort, sodass jede Ablehnung, die eine Person liest – ob vom Rechtewächter, einem Handler oder einem Speicher –, innerhalb der eigenen bereichsgebundenen Transaktion dieser Person in die Tabelle refusal Ihres Schemas geschrieben wird, bevor der Body gesendet wird. Ein anonymes 401 schreibt nichts. Wenn die Zeile nicht geschrieben werden kann, wird die Antwort zu UNHANDLED_ERROR: Ein „Nein“, das das Produkt nicht aufzeichnen kann, wird nicht so gesendet, als wäre es aufgezeichnet worden. Der Bootvorgang führt assertRefusalLedger aus, um zu prüfen, ob die Tabelle die Zeile des Buchs aufnehmen kann, und ein Speicher kann noteSubject({ recordId, isDemo }) aufrufen, damit jede Ablehnung den Datensatz nennt, um den es ging. Wenn ein Kunde fragt, warum jemand letzten Dienstag abgewiesen wurde, ist die Antwort eine Abfrage, keine Vermutung.
Der einzige Übergang: Eine protokollierte Lese-Berechtigung
Wenn einer Ihrer Kunden für einen anderen arbeitet und der andere dies einsehen darf, gibt es einen genehmigten Weg über die Grenze. Die Organisation, die die Zeilen hält, zeichnet eine Freigabe (Grant) auf. Die Organisation des Lesers lässt eine Person über einen Platz zu, der das Recht granted.read trägt, welches owner und admin in never nennen muss. Der Lesevorgang läuft als sechste Datenbankrolle, der Leseplatz (Read Seat), der nur die Tabellen abfragen (SELECT) kann, die databases[].granted auflistet:
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);withSeatTx schreibt den Einblick (Look) zuerst im eigenen Mandanten des Lesers und bindet dann den Leseplatz an die Freigabe, was den Einblick im Mandanten des Inhabers schreibt. Die eigene Richtlinie der Datenbank prüft, ob die Freigabe die Organisation des Lesers nennt, die Tabelle abdeckt, begonnen hat, nicht geendet hat und nicht zurückgezogen wurde, und ob diese Transaktion ihren Einblick geschrieben hat. Ein Lesevorgang, der den Einblick überspringt, sieht nichts. Beim Booten prüft assertSeatAtBoot(seatPool, schema), ob der aus seat.url geöffnete Pool wirklich der Platz ist und nichts weiter, und lehnt andernfalls mit DB_SEAT_ROLE_INVALID ab.
Dispatch über UNO
Alle Rechenoperationen laufen über einen einzigen Client, der in einer Datei mit einer geschlossenen Positivliste (Allow-List) erstellt wird:
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,
});
}Die Positivliste ist absichtlich eine Konstante auf Modulebene. Wenn ein Betreiber sie über die Konfiguration erweitern könnte, würde die Route zu einem Versand-Proxy für die gesamte Registrierung werden. Der eigene Test der Vorlage stellt sicher, dass die Liste genau die Job-Typen nennt, zu denen das Manifest kompiliert wird.
Der Umschlag (Envelope)
Ein Versand trägt in seinem erforderlichen Kern sechs Felder. Der Client füllt den Mandanten und den Akteur aus dem überprüften Bereich aus, niemals aus der Anfrage:
| Feld | Inhalt |
|---|---|
jobType |
Der mit Namensraum versehene Job-Typ, <plugin name>.<skill id> |
organizationId |
Der Mandant, aus dem Bereich |
userId |
Der Akteur, aus dem Bereich, für Audit und Abrechnung |
inputParams |
Die Eingabe des Skills. Sie trägt niemals eine Mandanten-ID; eine Eingabe, die dies tut, wird beim Versand abgelehnt |
priority |
critical, high, normal oder low |
pluginId |
Ihr Manifest-name. Jeder Versand deklariert sein Ursprungs-Plugin |
Zu den optionalen Feldern gehören correlationId (eine UUID (Universally Unique Identifier), oder es wird eine neue geprägt) und callbackUrl, das ein plugin_queue-Skill benötigt, damit der Worker weiß, wohin er sein Ergebnis senden soll.
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, dann Polling
Jeder Versand wird in eine Warteschlange eingereiht. Die Antwort ist immer 202 mit Kennungen (jobId, runId, traceId, status), niemals ein Ergebnis. Das Ergebnis stammt aus dem regelmäßigen Abfragen (Polling) des Jobs oder aus Ihrem Callback. uno.peek(jobId, { scope }) liest es einmalig aus und awaitJob fragt regelmäßig bis zu einem Endstatus ab; beide senden den Mandanten aus dem überprüften Bereich, und beide prüfen die organization_id der zurückgegebenen Zeile gegen den Mandanten des Aufrufers auf Ihrer Seite des Netzwerkaufrufs und lehnen eine Abweichung mit SCOPE_REFUSED ab.
Lesen Sie die Ausführungszeile (Run Row) in ihrer eigenen Schreibweise. Die Versandantwort lautet jobId; die Zeile lautet job_id, organization_id und plugin_id. Die Ergebnis- und Fehlerspalten sind result, error, error_code und error_troubleshooting. completed und failed sind Endzustände. timed_out, cancelled und system_failure stammen vom Reaper, und ein verspätetes Ergebnis kann sie noch korrigieren. Ein Client, der eines davon als nicht analysierbar behandelt, lehnt Zeilen ab, die die Plattform jeden Tag schreibt.
Der Genehmigungsstopp (Approval Hold)
Ein Manifest-Skill, der approval deklariert, wird beim Versand angehalten. Das 202 lautet dann status: "awaiting_approval" und trägt eine waitpointId mit der Begründung, die das Manifest angegeben hat. Die Ausführung bleibt angehalten, bis eine benannte Person darüber entscheidet. uno.approve und uno.resolveWaitpoint senden den Mandanten und den Aufrufer als Akteur, und eine Entscheidung durch jemand anderen als den überprüften Aufrufer wird abgelehnt. Eine Genehmigung gibt den Job einmalig frei und führt die Versandprüfungen erneut durch; eine Ablehnung beendet ihn mit failed. Eine zweite Entscheidung wird abgelehnt, ebenso eine Entscheidung nach Ablauf des Stopps. Wenn Ihr Produkt erfordert, dass der Genehmiger eine andere Person als der Antragsteller ist, setzen Sie dies in der Route durch, die entscheidet: Die Plattform zeichnet beide auf.
Stellen Sie einen angehaltenen Job als angehalten dar. Sagen Sie einer Person nicht, dass ihr Klick ihn freigegeben hat, bevor die Ausführungszeile dies besagt.
KI: Wünsche in der Skill-Zeile und ein Lesevorgang
Ihr Plugin ruft niemals ein Modell auf. Wenn ein Manifest-Skill eines benötigt (llm_only oder tool_using, auf Vertrauensstufe core oder verified), drücken Sie Präferenzen in seiner Registrierungszeile aus, und der Router entscheidet aus dem eigenen Pool der Organisation:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"capabilityProfile": { "needsToolUse": true, "dataResidency": "eu_only" }
}
}preferredProvider und preferredModel sind Wünsche, die der Router nur berücksichtigt, wenn die Organisation diesen Anbieter aktiviert und mit Zugangsdaten versehen hat. capabilityProfile filtert und wählt niemals aus; sein dataResidency (eu_only, us_only oder any) ist eine harte Einschränkung, die der Router erfüllt oder ablehnt. Alle wegzulassen, ist normalerweise richtig. modelOverride existiert für den seltenen Skill, der ein genaues Modell benötigt, und macht die Wünsche daneben wirkungslos; ich würde es vermeiden, es sei denn, der Skill ist auf jedem anderen Modell sinnlos.
Wenn Ihre Oberfläche anzeigen muss, welches Modell der Router verwenden würde, lesen Sie es aus, sagen Sie es nicht voraus:
import { createAIRouteClient } from "@adverant-nexus/plugin-sdk/runtime/ai-route";createAIRouteClient(...).effectiveRoute() ist der einzige genehmigte Lesevorgang des AI Provider Routers. Er nimmt die Adresse des Gateways, den eigenen Bearer des Aufrufers und den Slug Ihrer Plattform entgegen und sendet keine KI-Anfrage. Er liefert den Anbieter und das Modell, die von der Richtlinie erlaubten Anbieter sowie die Angabe, ob der gewählte Endpunkt local oder external läuft. Wenn die Route nicht nutzbar ist, liefert er die Ablehnung des Routers im Wortlaut (NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE oder NO_MODEL_FOR_ROLE_AND_PROVIDER, mit der Abhilfemaßnahme), niemals ein Standardmodell. Zeigen Sie diese Ablehnung der Person an; hier spricht die Konfiguration ihrer Organisation.
Lizenzprüfungen
Drei Mechanismen prüfen die Lizenzierung, auf drei Granularitätsstufen.
Ein Recht, das eine Lizenz nennt. Das Einfachste. Im Manifest trägt ein Recht licence: "<feature>", und der Wächter fragt den Identitätsdienst mit dem eigenen Token des Aufrufers, ob die Lizenz der Organisation es enthält, bevor irgendeine Rolle gelesen wird. Erstellen Sie den Wächter mit einem Leser:
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 }) },
});Eine Lizenz, die die Funktion nicht enthält, lehnt jeden mit LICENCE_LOCKED ab, nennt, was sie enthält, und besagt, dass die Eigentümer und Administratoren der Organisation sie aktivieren können. Eine Lizenz, die nicht gelesen werden kann, lehnt mit UNHANDLED_ERROR ab: Eine gesperrte Funktion wird niemals bereitgestellt, nur weil die Lizenz nicht erreichbar war. Antworten werden für 30 Sekunden pro Organisation und Funktion gespeichert.
Das Produkt-Gate. createProductGate({ baseUrl, product }) aus runtime/product-gate fragt die Berechtigungsprüfung, ob die Organisation des Aufrufers Ihr Produkt überhaupt besitzt, und sein middleware() läuft nach dem Bereichswächter. Ein negatives Urteil ist ENTITLEMENT_DENIED; eine Prüfung, die nicht erreicht werden kann, ist ENTITLEMENT_UNREACHABLE, und das Gate behandelt niemals das eine wie das andere.
Das Lizenzdokument selbst. Code, der anhand der signierten Lizenz selbst entscheiden muss, wie etwa das geschlossene Modul eines Domain-Packs, verwendet verifyLicenceDocument(docText, opts) aus runtime/licence-document. Es ist eine reine Funktion (Pure Function): kein Netzwerkaufruf, keine Umgebungsvariable, keine Datei. Sie prüft beide Signaturen gegen die Vertrauensanker (Trust Roots), die der Build mitbringt, und antwortet mit einem Status (VALID, WARN, GRACE, RESTRICT, TERMINATE oder ABSENT) samt den Freigaben, Add-ons und Domain-Packs. licenceAllows(verdict, featureGroup, action, tenantId?) besagt dann, ob Sie unter einer Gruppe use oder provision dürfen. RESTRICT erlaubt use und beantwortet provision mit LICENCE_LOCKED, sodass laufende Arbeiten fortgesetzt werden und nichts Neues startet.
Testen
Die Tests der Vorlage zeigen das Muster; dies sind die Werkzeuge dahinter.
Bereichs-Attrappen (Scope Fakes). Erstellen Sie das Test-Double für den aufgelösten Bereich einmalig in test/scope-fakes.ts und injizieren Sie es überall, einschließlich der Negativfälle: keine Einheit, kein Token, ein Token mit einer Null-Organisation. Die Ablehnungspfade sind das Produkt.
Ein gefälschter Versandtransport. UnoClient nimmt fetch, now und sleep entgegen, sodass ein Unit-Test niemals das Netzwerk berührt. Überprüfen Sie (Assert) die Felder des Umschlags, die Form von 202, das Polling bis zu einer Endzeile mit ihrem organization_id und dass eine Zeile für einen anderen Mandanten verworfen wird.
Ein echtes Postgres. Eine gefälschte Abfragefunktion beweist einen SQL-String. Sie kann nicht beweisen, dass die erzwungene Sicherheit auf Zeilenebene greift oder dass die Dateien durch den Migrator in der richtigen Reihenfolge angewendet werden. testing/ephemeral-postgres startet einen Wegwerf-Server und führt dieselben nexus-migrate aus, die auch in der Produktion laufen:
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 runsAußerhalb von CI (Continuous Integration) überspringt eine Maschine ohne Postgres-Server jeden Datenbankfall namentlich mit Angabe der Abhilfe, niemals grün. In CI lässt dasselbe Fehlen die Suite fehlschlagen (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI), da ein übersprungener Test für Sicherheit auf Zeilenebene ein grünes Gate ist, das nichts gemessen hat. Der Server wartet bis zu 180 Sekunden auf den Start, und ein Watchdog stoppt ihn, wenn der Testprozess beendet wird.
Das Isolations-Testgerüst. runIsolationHarness(target) aus testing/isolation-harness liest jede Route, die Ihre App einbindet, und greift jede einzelne als Administrator einer anderen Organisation und als Kollege an. Dann greift es erneut an, wobei die Code-Begrenzung entfernt wird, die Datenbankbegrenzung entfernt wird und schließlich beide. Eine Route ist nur dann PROVEN, wenn der Angriff fehlschlägt, solange eine der beiden Begrenzungen aktiv ist, und die Daten des Opfers erreicht, wenn beide entfernt sind – so wissen Sie, dass der Test ein Leck überhaupt erkennen kann. Es sendet die deklarierte Abfrage und den Beispiel-Body jeder Route, sodass auch eine Route erreicht wird, die eine leere Anfrage ablehnt. Fixieren Sie ledgerOf(report) in einem Test und lassen Sie ihn bei defectsOf(report) fehlschlagen.
Registrierung: Vom Manifest zur Skill-Registry
Ihre Manifest-Skills erreichen die Skill-Registrierung über einen einzigen Pfad:
manifest.skills[] → compileRegistry(manifest) → POST /api/v1/plugins/sync
compileRegistry verwandelt ein validiertes Manifest in den nexus.plugin-sync/v1-Body. Die Vorlage tut dies beim Import, sodass ein ungültiges Manifest den Build fehlschlagen lässt:
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" } ]
}Die Synchronisierung ist deklarativ: Senden Sie jedes Mal das gesamte Skill-Set; ein ausgelassener Skill wird deaktiviert, wobei seine Historie erhalten bleibt. Sie ist strikt: Ein unbekanntes Feld, ein Feld einer anderen Stufe oder ein null wird abgelehnt, alle Verstöße kommen zusammen in einem 400 SYNC_CONTRACT_VIOLATION zurück, und es wird nichts geschrieben, solange einer vorliegt. Und sie schreibt eine Registrierungszeile pro Skill, geschlüsselt nach dem mit Namensraum versehenen Job-Typ, die jede Spalte enthält, die der Dispatcher liest, sodass der Skill in dem Moment ausführbar ist, in dem die Synchronisierung mit 200 antwortet.
Das Plugin ist der authentifizierte Aufrufer, niemals ein Body-Feld. Rufen Sie die Synchronisierung aus der eigenen Workload Ihres Plugins über mTLS auf (Mutual TLS: Transport Layer Security mit einem Zertifikat auf beiden Seiten). Die Skills Engine liest das Client-Zertifikat Ihrer Workload, dessen SPIFFE-Identität (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>) den Namespace und das Service-Konto nennt, und schlägt das Plugin sowie die besitzende Organisation nach, die für diesen Namespace aufgezeichnet sind. Die pluginId des Bodys muss übereinstimmen; es ist eine Prüfung, kein Selektor. Jede Zeile wird mit diesem Plugin und dieser Organisation geschrieben.
| Status | Code | Bedeutung |
|---|---|---|
| 200 | {contract, pluginId, version, created, updated, unchanged, disabled, skills} |
|
| 400 | SYNC_CONTRACT_VIOLATION |
Jeder Verstoß in violations[] aufgelistet; nichts geschrieben |
| 401 | UNAUTHORIZED |
Ungültiger oder fehlender Dienstschlüssel |
| 401 | CALLER_IDENTITY_UNVERIFIED |
Keine lesbare Client-Identität |
| 403 | DELIVERY_IDENTITY_MISSING |
Der aufrufende Namespace gehört zu keinem Plugin |
| 403 | PLUGIN_ID_MISMATCH |
Der Body nennt ein anderes Plugin |
| 409 | REGISTRY_CONFLICT |
Ein Job-Typ gehört einer anderen Stelle oder wurde außerhalb der Synchronisierung registriert; nichts geschrieben |
Lassen Sie Ihren Bereitstellungsschritt (Deploy) bei jedem anderen Status als 200 fehlschlagen. Kein anderer Status bedeutet, dass Ihre Skills registriert sind.
Onboarding
Das Onboarding läuft in zehn geordneten Schritten ab, von denen jeder einzeln erneut ausgeführt, abgebrochen oder zurückgerollt werden kann:
- Das Repository klonen und validieren.
- Das Manifest parsen.
- Es auf Sicherheitsprobleme scannen.
- Das Image bauen.
- Es in die Registrierung der Installation pushen.
- Seine Domainnamen einrichten.
- Es über die Release-Kanäle der Installation bereitstellen (deployen).
- Auf die Zustandsprüfung (Health Check) warten.
- Das Plugin registrieren.
- Den Entwickler benachrichtigen.
Vor der Bereitstellung laufen fünf Konformitätsprüfungen gegen das Manifest und das gebaute Image: Das Manifest lässt sich parsen und enthält seine Pflichtfelder; jede deklarierte Route ist eine echte registrierte Route; das Plugin besitzt sein Schema und schreibt nichts außerhalb davon; Ressourcenanforderungen sind deklariert und liegen innerhalb der Grenzen; und das Image verfügt über einen funktionierenden Health-Handler. Ein Plugin, das sich beim Booten selbst registriert, führt denselben Vertrag unter seiner eigenen Autorität aus, sodass die Prüfungen zu seiner eigenen CI statt zu derjenigen der Pipeline werden. Einen Schritt zu überspringen, verkürzt das Onboarding nicht; es verlagert den Fehler in die Laufzeit.
Das Branding in Ihrem Manifest wird ohne Authentifizierung nach Domain ausgeliefert, da die Anmeldeseite es benötigt, bevor jemand Zugangsdaten hat. Behandeln Sie alles in branding als öffentlich.
GATE_CANNOT_BE_SKIPPED abgelehnt.Was die Laufzeitumgebung nicht für Sie übernimmt
Die Laufzeitumgebung hält die Linie bei Isolation, Versand und Modellzugriff. Sie wird Ihre Produktlogik nicht richtig machen, und sie wird eine langsame Abfrage nicht schnell machen: Jede Anweisung läuft innerhalb einer gebundenen Transaktion mit den Zeitüberschreitungen (Timeouts), die der db-Block Ihres Manifests deklariert, und eine Anweisung, die statementTimeoutMs überschreitet, wird abgebrochen, nicht abgewartet. Dimensionieren Sie Ihre Abfragen entsprechend. Zudem fügen der Genehmigungsstopp, der Leseplatz und der Lizenzleser jeweils einen Roundtrip oder eine Transaktion hinzu. Bei meinem Plugin zur Anomalieprüfung fügte die Lizenzprüfung pro Anfrage einige Millisekunden hinzu, bis ihr 30-Sekunden-Speicher aufgewärmt war – ein fairer Preis dafür, niemals eine gesperrte Funktion bereitzustellen.

