Έκδοση 1.0.0-alpha.1τελευταία
Κεφάλαιο 2.21
Το Plugin SDK
Εγκατάσταση του Plugin SDK (κιτ ανάπτυξης λογισμικού), τα εργαλεία γραμμής εντολών του, μια περιήγηση στο πρότυπο πλήρους υπηρεσίας, το manifest έκδοσης v2 πεδίο προς πεδίο, και οι είκοσι δύο πύλες που διασφαλίζουν ότι ένα πρόσθετο τηρεί τους κανόνες.
Αυτή η σελίδα μεταφράστηκε με AI από το αγγλικό πρωτότυπο. Εάν οτιδήποτε είναι ασαφές, η αγγλική σελίδα αποτελεί το σημείο αναφοράς. Διαβάστε αυτή τη σελίδα στα αγγλικά

Το δεύτερο πρόσθετό μου χρειάστηκε το ένα τρίτο του χρόνου του πρώτου, και σχεδόν όλη η εξοικονόμηση οφειλόταν στο SDK (κιτ ανάπτυξης λογισμικού). Την πρώτη φορά, έγραψα έναν έλεγχο εμβέλειας, έναν φορτωτή παραμέτρων και έναν εκτελεστή μετεγκατάστασης, και ένας αξιολογητής τα επέστρεψε όλα πίσω. Τη δεύτερη φορά, εκτέλεσα μία εντολή δημιουργίας σκελετού (scaffold), διέγραψα την ενδεικτική δεξιότητα ανάλυσης συναισθήματος και αφιέρωσα τις μέρες μου στις εγγραφές ελέγχου ανωμαλιών που πραγματικά χρειαζόταν η ομάδα δυναμικής πτήσης μας.
Το @adverant-nexus/plugin-sdk είναι ένα ενιαίο πακέτο npm. Περιέχει το σχήμα του manifest v2 και τους επικυρωτές που το διαβάζουν (definePlugin, defineSkill), τις λειτουργικές μονάδες χρόνου εκτέλεσης που εισάγει το πρόσθετό σας για την εμβέλεια, τη βάση δεδομένων, την αποστολή (dispatch) και τα υπόλοιπα, βοηθητικά εργαλεία δοκιμών, τις πύλες συμμόρφωσης και τα εργαλεία γραμμής εντολών. Αυτό το κεφάλαιο καλύπτει την εγκατάστασή του, τα εργαλεία, το πρότυπο, το manifest και τις πύλες. Το Κεφάλαιο 2.22, Ο χρόνος εκτέλεσης προσθέτου, καλύπτει τις λειτουργικές μονάδες χρόνου εκτέλεσης στον εκτελούμενο κώδικά σας.
Εγκατάσταση
Το πακέτο προέρχεται από το μητρώο της Adverant στο https://registry.adverant.ai/npm/, ποτέ από το δημόσιο μητρώο npm, και χρειάζεστε το διακριτικό ανάκτησης (pull token) από τη σελίδα «Διακριτικά ανάκτησης και εντολές εγκατάστασης» του λογαριασμού σας. Κατευθύνετε την εμβέλεια @adverant-nexus στο μητρώο μέσα στο .npmrc του αποθετηρίου σας:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
Το <pull-token> είναι το διακριτικό από τη σελίδα του λογαριασμού σας. Σε μια διοχέτευση (pipeline), περάστε το από ένα μυστικό (secret) και μην το υποβάλετε (commit) ποτέ· το Dockerfile του προτύπου αρνείται να εκτελέσει τη δόμηση χωρίς αυτό και διαγράφει το .npmrc από το στάδιο δόμησης μόλις εκτελεστεί το npm ci, ώστε το διακριτικό να μην περιλαμβάνεται ποτέ σε μια εικόνα.
Στη συνέχεια, κλειδώστε την ακριβή έκδοση:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Υποβάλετε (commit) το package-lock.json κατά την πρώτη εγκατάσταση. Η δόμηση εικόνας του προτύπου εκτελεί το npm ci και αρνείται να καταφύγει στο npm install: το αρχείο κλειδώματος (lockfile) αποτελεί το συμβόλαιο. Η ελάχιστη απαίτηση του ίδιου του SDK είναι το Node 18· το πρότυπο στοχεύει στο Node 20.
Τα εργαλεία γραμμής εντολών παρέχονται μέσα στο πακέτο, επομένως κάθε εντολή σε αυτή την τεκμηρίωση κατονομάζει το πακέτο και την έκδοσή του με npx -p. Από μόνο του, το npx create-nexus-plugin αναζητείται στο δημόσιο μητρώο, και αυτό το όνομα δεν αντιστοιχεί σε αυτό το πακέτο.
Τα εργαλεία γραμμής εντολών
| Εργαλείο | Τι κάνει |
|---|---|
create-nexus-plugin |
Δημιουργεί τον σκελετό ενός προσθέτου, επικυρώνει ένα manifest, μετεγκαθιστά ένα manifest v1 σε v2 και αποδίδει τον οδηγό καταναλωτή για τον προγραμματιστή frontend σας |
nexus-tenancy |
Αποδίδει την SQL πολυμισθωτικότητας (tenancy) του σχήματός σας από το manifest: ρόλους, εκχωρήσεις (grants), το πρότυπο ασφάλειας σε επίπεδο γραμμής (row-level security) και τους πίνακες γράφου |
nexus-migrate |
Εφαρμόζει τις μετεγκαταστάσεις σας: προβλέπει τους ρόλους μία φορά και, στη συνέχεια, εκτελεί κάθε αριθμημένο αρχείο με τον ρόλο μετεγκαταστάτη (migrator) |
nexus-gates |
Εκτελεί κάθε πύλη συμμόρφωσης, καθώς και τον αυτοέλεγχο κάθε πύλης |
Το create-nexus-plugin δεν πραγματοποιεί καμία κλήση δικτύου και δεν φορτώνει απομακρυσμένο κώδικα. Εκτελεί τους ίδιους επικυρωτές εντός διεργασίας που εκτελεί και η ενσωμάτωση (onboarding) της πλατφόρμας, ώστε να μην υπάρχει καμία απόκλιση μεταξύ του «επικυρώθηκε στο μηχάνημά μου» και του «η πλατφόρμα το αποδέχτηκε».
| Εντολή | Σημαίες | Τι κάνει | Κωδικοί εξόδου |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Γράφει έναν νέο κατάλογο προσθέτου· το --print εκτυπώνει μόνο το manifest |
0 εγγράφηκε · 1 άρνηση αντικατάστασης · 2 εσφαλμένη χρήση |
validate <file> |
Επικυρώνει ένα nexus.manifest.json, ή μια λειτουργική μονάδα .ts ή .js που εξάγει ένα τέτοιο αρχείο |
0 έγκυρο · 1 μη έγκυρο ή μη αναγνώσιμο · 2 εσφαλμένη χρήση | |
migrate <file> |
--write |
Αναβαθμίζει ένα manifest v1 σε v2 και το εκτυπώνει, ή το γράφει επιτόπου | 0 · 1 · 2, όπως παραπάνω |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Αποδίδει τον οδηγό καταναλωτή από το manifest και το αφηγηματικό σας κείμενο· το --check το συγκρίνει με το υποβληθέν αντίγραφο και δεν γράφει τίποτα |
0 · 1 απόκλιση ή παράβαση ελέγχου κώδικα (lint) · 2 εσφαλμένη χρήση |
help |
Εκτυπώνει οδηγίες χρήσης | 0 |
Δημιουργία σκελετού (Scaffolding) και τα τρία επίπεδα
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-serviceΤο --tier έχει ως προεπιλογή το full-service. Το εργαλείο δημιουργίας σκελετού αρνείται να γράψει σε έναν κατάλογο που υπάρχει ήδη, και το manifest που γράφει περνάει ήδη την επικύρωση· δεν παράγει ποτέ ένα μη έγκυρο manifest.
Επιλέξτε τη βαθμίδα ανάλογα με το τι διαθέτει το πρόσθετό σας.
| Βαθμίδα | Διαθέτει | Πρέπει να δηλώνει |
|---|---|---|
skills-only |
Δεξιότητες manifest και τίποτα άλλο | Το skills[], με τουλάχιστον μία καταχώριση |
ui-only |
Μια επιφάνεια frontend μέσα στο κέλυφος | frontend |
full-service |
Ένα backend και ένα frontend, συνήθως με το δικό του σχήμα | Τα backend και frontend· και επειδή διαθέτει backend, το runtime.healthCheck |
Αν δεν είστε βέβαιοι, δημιουργήστε τον σκελετό με full-service και διαγράψτε ό,τι δεν χρειάζεστε. Η αντίστροφη πορεία σημαίνει ότι θα πρέπει να γράψετε μόνοι σας τα μέρη που θα σας είχε δώσει το πρότυπο.
Περιήγηση στο πρότυπο πλήρους υπηρεσίας
Το πρότυπο είναι το πρόσθετο αναφοράς, δομημένο σύμφωνα με το αυστηρό μοτίβο που προϋποθέτει κάθε επόμενο κεφάλαιο. Κλωνοποιήστε τη δομή του, όχι την ενδεικτική λογική του.
| Διαδρομή | Τι είναι |
|---|---|
nexus.manifest.json |
Το manifest v2: οι τρεις νόμοι επαναδιατυπωμένοι, ο πίνακας διαδρομών και το μητρώο δικαιωμάτων του |
src/config.ts |
Ο φορτωτής παραμέτρων. Μία προδιαγραφή, που διαβάζεται μία φορά, με συλλογή κάθε προβλήματος προτού η διεργασία αρνηθεί να εκκινήσει |
src/scope.ts |
Το μοναδικό αρχείο που μετατρέπει ένα αίτημα σε εμβέλεια (scope), με τον αυστηρό επαληθευτή διακριτικών του SDK και δύο καθεστώτα: το διακριτικό κομιστή (bearer token) ενός προσώπου και την κλήση υπηρεσίας της πλατφόρμας |
src/db.ts |
Κάθε εντολή συνθέτει το tenantFence() και εκτελείται εντός του withScopedTx |
src/uno.ts |
Το μοναδικό αρχείο αποστολής (dispatch): ένα URL, ένας πελάτης, μια κλειστή λίστα επιτρεπομένων |
src/routes/*.ts |
Το health (ανώνυμο, ακριβής διαδρομή), οι διαδρομές /api (με εμβέλεια) και η επανάκληση /internal (προστατευμένη από υπηρεσία) |
src/skills/sentiment.ts |
Μια ντετερμινιστική δεξιότητα host_callback· αντικαταστήστε το λεξικό με τη δική σας λογική |
src/server.ts |
Η ρίζα σύνθεσης: εγκαθιστά το καθολικό αρνήσεων μία φορά, αναμένει τη βάση δεδομένων (με χρονικό όριο) και, στη συνέχεια, εκτελεί τους ελέγχους απομόνωσης και καθολικού προτού ξεκινήσει την ακρόαση |
migrations/000_tenancy.sql |
Αποδίδεται από το nexus-tenancy render κατά τον χρόνο δημιουργίας του σκελετού: ρόλοι, σχήμα, το πρότυπο ασφάλειας σε επίπεδο γραμμής |
migrations/001_init.sql |
Δύο πίνακες με σύνθετο κλειδί όπου προηγείται ο μισθωτής και ένα σύνθετο ξένο κλειδί που φέρει τον μισθωτή |
migrations/002_refusal_ledger.sql |
Ο πίνακας στον οποίο γράφει το καθολικό αρνήσεων |
scripts/ci/required-env |
Εκτυπώνει τα ονόματα των μεταβλητών περιβάλλοντος που απαιτούνται για την εκκίνηση ως JSON |
scripts/ci/shadow-migrate-*.sh |
Η δοκιμαστική εκτέλεση (dry run) μετεγκατάστασης της διοχέτευσης, μέσω του nexus-migrate |
gates/ |
Ο κατάλογος εξαιρέσεων των πυλών: κενός, που είναι η σωστή κατάσταση για ένα νέο πρόσθετο |
test/ |
Δοκιμές για την εμβέλεια, τις διαδρομές, τη βάση δεδομένων, την αποστολή και την εκκίνηση, με τα ομοιώματα εμβέλειας (scope doubles) που εγχέει κάθε δοκιμή |
Dockerfile |
Μια εικόνα χωρίς δικαιώματα root (αναγνωριστικό χρήστη 10001) με τις μετεγκαταστάσεις μέσα σε αυτήν |
Ορισμένα από αυτά τα αρχεία αξίζουν μια πιο προσεκτική ματιά.
Το src/config.ts ακολουθεί δύο κανόνες. Συλλέγει κάθε πρόβλημα προτού προκαλέσει εξαίρεση, ώστε μία επανεκκίνηση να κατονομάζει και τις πέντε μεταβλητές που λείπουν, αντί για πέντε επανεκκινήσεις που κατονομάζουν από μία η καθεμία. Επίσης, ορίζει μια προεπιλεγμένη τιμή μόνο όταν μια λανθασμένη τιμή δεν μπορεί να οδηγήσει σε μια σιωπηλή λανθασμένη απάντηση: το PORT μπορεί να έχει ως προεπιλογή το 8080, επειδή μια λανθασμένη θύρα αποτυγχάνει εμφανώς κατά τη δέσμευση (bind), ενώ τα DATABASE_URL και UNO_DISPATCH_URL είναι υποχρεωτικά και πρέπει να είναι διευθύνσεις εντός συστάδας. Μια δημόσια διεύθυνση απορρίπτεται κατά την εκκίνηση.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Η δοκιμή του ίδιου του προτύπου εκτελεί αυτό το αρχείο και συγκρίνει την έξοδό του με τα ονόματα που η προδιαγραφή παραμέτρων χαρακτηρίζει ως υποχρεωτικά, επομένως η προσθήκη μιας υποχρεωτικής μεταβλητής χωρίς την ενημέρωση της λίστας προκαλεί αποτυχία στο npm test.
Το src/server.ts δεν ξεκινά την ακρόαση μέχρι να απαντήσει η βάση δεδομένων, και περιορίζει την αναμονή στα 120 δευτερόλεπτα, καταγράφοντας κάθε αποτυχημένη προσπάθεια μαζί με την αιτία της. Στη συνέχεια, αποδεικνύει, με τη σειρά, ότι ο ρόλος εφαρμογής δεν μπορεί να επαναδεσμεύσει τον μισθωτή και ότι κάθε πίνακας υπόκειται υποχρεωτικά σε ασφάλεια σε επίπεδο γραμμής, ότι η δεξαμενή (pool) κάθε pod χωράει στο όριο συνδέσεων του ρόλου και ότι ο πίνακας του καθολικού αρνήσεων μπορεί να δεχτεί μια γραμμή. Μια άρνηση από οποιοδήποτε από τα τρία εκτυπώνεται ολόκληρη και η διεργασία τερματίζεται με κωδικό 2.
Το manifest έκδοσης v2, πεδίο προς πεδίο
Το manifest είναι το αναγνώσιμο από μηχανή συμβόλαιο του προσθέτου με την πλατφόρμα. Επικυρώνεται όταν το συντάσσετε, όταν η πλατφόρμα το ενσωματώνει και, στη συνέχεια, αδιαλείπτως. Το σχήμα είναι additionalProperties: false σε κάθε επίπεδο: αν το πρόσθετό σας έχει μια ενότητα, υπάρχει μια ιδιότητα γι' αυτήν, και ένα αδήλωτο κλειδί απορρίπτεται. Η λύση είναι πάντα η χρήση της σωστής προαιρετικής ιδιότητας.
Ο υποχρεωτικός πυρήνας
| Πεδίο | Κανόνας |
|---|---|
manifestVersion |
Ακριβώς "2". Ένα έγγραφο v1 μετεγκαθίσταται, δεν επανεπικυρώνεται ποτέ επιτόπου |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, το πολύ 64 χαρακτήρες. Το αναγνωριστικό προσθέτου που χρησιμοποιείται στην εγγραφή, στην ονοματοθεσία αποστολής (dispatch namespacing) και στις γραμμές με εμβέλεια μισθωτή. Ένα πρόσθετο που δηλώνει δεξιότητες χρειάζεται επίσης ένα όνομα χωρίς τελεία και χωρίς ψηφίο στην αρχή |
displayName |
1 έως 120 χαρακτήρες |
version |
Σημασιολογική έκδοση (semantic version)· η δική σας αλυσίδα κυκλοφοριών |
description, author, license |
Τουλάχιστον ένας χαρακτήρας το καθένα |
tier |
skills-only, ui-only ή full-service |
trust |
core, verified, community ή untrusted |
runtime |
Υποχρεωτικά: executionMode, isolationLevel (1 έως 4), entrypoint. Προαιρετικά: nodeVersion, healthCheck, readinessCheck, livenessCheck, καθένα από τα οποία είναι μια διαδρομή που ξεκινά με /. Η κατάσταση λειτουργίας προκύπτει από το επίπεδο: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai και deploy, οι τρεις νόμοι της πλατφόρμας επαναδιατυπωμένοι. Ο επικυρωτής επιβάλλει την ακριβή διατύπωση |
Για ένα πρόσθετο που δημιουργείτε για τη δική σας εγκατάσταση, οι τρεις προτάσεις διατυπώνονται ως εξής. Η πρόταση ai καλύπτει την τεχνητή νοημοσύνη (AI) και είναι το σημείο όπου δηλώνεται ότι το πρόσθετο δεν διατηρεί διαπιστευτήρια μοντέλων.
"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."
}Ο πίνακας διαδρομών: api και rights
Το api χρειάζεται τα version και basePath, και προαιρετικά τα websocket (path, auth) και endpoints[]. Ο πίνακας διαδρομών είναι η ισχυρότερη ιδέα στο σχήμα: μια πύλη τον συγκρίνει (diff) με τις διαδρομές που πραγματικά καταχωρίζει ο κώδικάς σας, και προς τις δύο κατευθύνσεις, ώστε το manifest να είναι ένα ελέγξιμο συμβόλαιο και όχι απλή τεκμηρίωση.
Κάθε τελικό σημείο χρειάζεται method (GET, POST, PUT, PATCH ή DELETE) και path. Τα υπόλοιπα:
| Πεδίο | Τι αναφέρει |
|---|---|
auth |
Μία από πέντε κλάσεις: scope (διαδρομή προσώπου, πίσω από τον φρουρό εμβέλειας), service-key και internal (από διακομιστή σε διακομιστή, ποτέ προσβάσιμες από πρόγραμμα περιήγησης), public (πάντοτε και μόνο ακριβής διαδρομή με allowAnonymous) και device (μηχανή με δικό της διαπιστευτήριο, πίσω από τον φρουρό συσκευής) |
right |
Υποχρεωτικό σε κάθε διαδρομή που εξυπηρετεί ο φρουρός εμβέλειας, και απορρίπτεται σε οποιαδήποτε άλλη: το όνομα ενός δικαιώματος στο μητρώο rights |
needsUnit |
Η διαδρομή αρνείται την εξυπηρέτηση όταν δεν μπορεί να επιλυθεί η μονάδα του καλούντος |
allowAnonymous |
Λίστα επιτρεπομένων μόνο με ακριβή αντιστοίχιση. Ένας κανόνας προθέματος είναι ο τρόπος με τον οποίο το /health-of-tenant-42 καταλήγει να είναι δημόσιο |
group, serves, screens |
Κάτω από ένα μπλοκ release: η ομάδα δυνατοτήτων που εξυπηρετεί η διαδρομή, τι απαντά όταν η αδειοδοτημένη λειτουργία αυτής της ομάδας είναι κλειδωμένη (data, teaser, sighting ή ask), και οι οθόνες που εξυπηρετεί |
query |
required (κάθε όνομα με μια ενδεικτική τιμή) και allowed: οι παράμετροι ερωτήματος που διαβάζει η διαδρομή |
body |
example: ένα ενδεικτικό σώμα (body) μιας διαδρομής εγγραφής, το οποίο αποδέχεται ο δικός της επικυρωτής. Ποτέ σε GET |
Το rights είναι το μητρώο που κατονομάζουν αυτές οι διαδρομές. Κάθε δικαίωμα έχει roles (το ανώτατο όριο) και προαιρετικά summary, never (ρόλους που δεν επιτρέπεται ποτέ να το ασκήσουν, ανεξάρτητα από το τι άλλο κατέχουν), barred (τα λόγια του ίδιου του προϊόντος για την άρνηση ενός ρόλου never), seat (απαιτείται επίσης μια ενεργή θέση), self (το κατέχει κάθε επαληθευμένο πρόσωπο, για δικαιώματα επί της δικής του συνεδρίας), grants (οι κάτοχοι εκχωρούν θέσεις· το πολύ ένα δικαίωμα το δηλώνει αυτό), licence (μια αδειοδοτημένη λειτουργία που πρέπει να περιλαμβάνει η άδεια του οργανισμού) installation (κατέχεται μόνο από τους διαχειριστές της ίδιας της εγκατάστασης) και platform (κατέχεται μόνο από τους διαχειριστές πλατφόρμας της Adverant· δεν κατονομάζει ρόλους). Τα ονόματα δικαιωμάτων περιέχουν τουλάχιστον μία τελεία: 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 απορρίπτει μια διαδρομή εμβέλειας χωρίς δικαίωμα (ENDPOINT_RIGHT_MISSING), ένα δικαίωμα που λείπει από το μητρώο (ENDPOINT_RIGHT_NOT_REGISTERED) και ένα δικαίωμα σε μια διαδρομή που δεν εξυπηρετείται από κανέναν φρουρό (ENDPOINT_RIGHT_UNGUARDED). Απορρίπτει επίσης ένα μητρώο που αντιφάσκει με τον εαυτό του, καθώς και δύο διαφορετικές γραφές της ίδιας διαδρομής (:id και :recordId) ως DUPLICATE_ENDPOINT.
Τα δεδομένα σας: databases, schema και db
Το schema είναι το μοναδικό σχήμα Postgres που ανήκει στο πρόσθετο. Τα public, plugins, auth και nexus απαγορεύονται, και αν το databases[] κατονομάζει επίσης ένα σχήμα Postgres, τα δύο πρέπει να ταιριάζουν.
Το databases[] δηλώνει κάθε αποθήκη δεδομένων ανά μηχανή: postgresql (schema, tables, migrations και granted, τους πίνακες που ένας άλλος οργανισμός μπορεί να διαβάσει βάσει μιας καταγεγραμμένης εκχώρησης), neo4j (schemas), qdrant (collections) ή redis (purpose).
Το db διατηρεί τα όρια συνεδρίας για κάθε σύνδεση που ανοίγει το πρόσθετο, τα οποία δηλώνονται εδώ αντί να ενσωματώνονται στον κώδικα, ώστε να μπορούν να τα διαβάσουν τόσο ένας αξιολογητής όσο και η ανάπτυξη (deployment):
| Πεδίο | Τι οριοθετεί |
|---|---|
maxConnections |
Τη δεξαμενή (pool) ανά αντίγραφο (replica) |
pods |
Τον μέγιστο αριθμό pods που διατηρούν δεξαμενή ταυτόχρονα, δηλαδή τα αντίγραφα συν την υπέρβαση (surge) μιας κυλιόμενης ενημέρωσης. Το όριο συνδέσεων κάθε ρόλου αποδίδεται ως maxConnections × pods· αν το παραλείψετε, το definePlugin προειδοποιεί με DB_PODS_UNDECLARED |
statementTimeoutMs |
Μία εντολή (statement) |
idleInTransactionTimeoutMs |
Μια ανοιχτή συναλλαγή που δεν εκτελεί τίποτα |
workMemKB |
Έναν κόμβο ταξινόμησης ή κατακερματισμού, ανά κόμβο, όχι ανά ερώτημα |
piiMask[] |
Καταχωρίσεις table.column που περιέχουν προσωπικά δεδομένα, τα οποία αποκρύπτονται (masked) στην ελεγχόμενη κονσόλα SQL και στα αρχεία καταγραφής |
Δεξιότητες και εργαλεία: skills, mcpTools, entitlements
Το skills[] περιέχει δεξιότητες manifest· το κεφάλαιο 2.20, Δεξιότητες, καλύπτει τα πεδία και τις βαθμίδες τους. Το mcpTools[] περιέχει τα εργαλεία MCP (Model Context Protocol) που δημοσιεύει το πρόσθετο, καθένα από τα οποία αποτελείται από ένα name, ένα description και ένα inputSchema χωρίς oneOf, allOf ή anyOf ανωτάτου επιπέδου.
Το entitlements απαιτεί το featureIdPattern και δέχεται τα alwaysOn[], source και store. Το μοτίβο κατονομάζει τον χώρο ονομάτων στον οποίο βρίσκονται τα αναγνωριστικά των λειτουργιών σας, που κατά σύμβαση είναι το name του προσθέτου συν ένα τμήμα που συμπληρώνει ο κώδικάς σας ανά επιφάνεια. Το alwaysOn[] είναι η σύντομη, ακριβής λίστα που πρέπει να απαντά ακόμη και όταν δεν μπορεί να ληφθεί απόφαση δικαιώματος χρήσης (entitlement): υγεία, ετοιμότητα, σύνδεση και οι ρυθμίσεις που χρειάζεται ένας διαχειριστής για να επιδιορθώσει το δικαίωμα χρήσης.
Έλεγχος αλλαγών: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Οι εγκρίσεις καταμετρώνται σε διακριτά πρόσωπα, και το πρόσωπο που πρότεινε την αλλαγή δεν είναι ποτέ ένα από αυτά· χωρίς και τις δύο αυτές προϋποθέσεις, οι «δύο εγκρίσεις» καταλήγουν να είναι ένα πρόσωπο που κάνει κλικ δύο φορές. Το enabled: true απαιτεί το classes, και κάθε κλάση που κατονομάζεται χρειάζεται τον δικό της αριθμό. Μια κλάση που παραλείπετε παραμένει μη ελεγχόμενη, κάτι που αποτελεί μια θεμιτή επιλογή την οποία το σχήμα σάς υποχρεώνει να καταγράψετε.
Ποιοι είστε: domains, branding, routing
Το domains[] (καθένα με primary και aliases[]· το domain είναι η μορφή ενός τομέα) απαριθμεί πού απαντά το πρόσθετο. Το branding απαιτεί το appName και δέχεται τα tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId και gaId. Οτιδήποτε βρίσκεται στο branding είναι δημόσιο: η σελίδα σύνδεσης το διαβάζει προτού οποιοσδήποτε αποκτήσει διαπιστευτήριο, επομένως δεν περιέχει ποτέ μυστικό ή εσωτερική διεύθυνση. Το routing (type, gateway, virtualService) προορίζεται για πρόσθετα που περιγράφουν τη δική τους δρομολόγηση.
Διαστασιολόγηση και τα υπόλοιπα
Το resources απαιτεί τα cpuMillicores (10 έως 64.000) και memoryMB (16 έως 262.144), και δέχεται τα diskGB, timeoutMs, port και wsPort. Το backend περιέχει τα port, healthPath, apiPrefix, framework και platformClients[], τους πελάτες SDK που εισάγει ονομαστικά το backend σας. Η λίστα είναι κλειστή, και μια πύλη την ελέγχει σε σχέση με τις εισαγωγές σας. Το σχήμα επιτρέπει δεκατέσσερα ονόματα: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin και uno, συν ένα για τον πελάτη που απαντά σε αρνήσεις δικαιωμάτων χρήσης πλάνου, το οποίο διατηρεί εσωτερικό όνομα. Ο πελάτης δικαιωμάτων χρήσης λειτουργιών, runtime/entitlements, δεν είναι ένα από αυτά και δεν μπαίνει ποτέ στη λίστα, επειδή το μπλοκ entitlements σας τον δηλώνει ήδη, και ένα backend που τον εισάγει χωρίς μπλοκ entitlements αποτυγχάνει στην ίδια πύλη. Το frontend περιέχει τα basePath, mountPath και framework. Το nexus περιέχει τα minVersion, maxVersion, capabilities[] και permissions[].
Τα υπόλοιπα μπλοκ υπάρχουν το καθένα για μία συγκεκριμένη εργασία:
| Μπλοκ | Για |
|---|---|
settings |
Τις ρυθμίσεις σας στο κοινόχρηστο πλαίσιο: groups και keys, ορισμένες στα επίπεδα που κατονομάζει η καθεμία |
people |
sweep (service, port): τα μέλη του οργανισμού, συγχρονισμένα από την υπηρεσία ταυτότητας, με τις θέσεις να απενεργοποιούνται όταν κάποιος αποχωρεί |
ontology |
entityTypes και relationshipTypes: τον τυποποιημένο γράφο που διατηρείται στο δικό σας σχήμα |
release |
groups και frame: τις ομάδες δυνατοτήτων στις οποίες κλιμακώνονται οι διαδρομές σας, οι οποίες κυκλοφορούν πρώτα ως έκδοση canary |
cells[] |
Ένα πρόσθετο που αποτελείται από πολλά αναπτύξιμα στοιχεία (deployables): name, kind, entrypoint, port, wsPort το καθένα |
pricing |
model, currency, tiers[] για την καταχώρισή σας στον κατάλογο |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Ποιος το δημοσιεύει και πού βρίσκεται ο κώδικάς του |
metrics, atlas |
Τα δύο σκόπιμα ανοιχτά αντικείμενα, για τα δικά σας ονόματα μετρικών και τη δημιουργία εγγράφων αρχιτεκτονικής |
Τι δεν μπορεί να εκφράσει το σχήμα
Το JSON Schema καθορίζει τη δομή· το definePlugin προσθέτει τους κανόνες που δεν μπορεί να εκφράσει ένα σχήμα. Το classification μιας δεξιότητας δεν μπορεί να υπερβαίνει το ανώτατο όριο εμπιστοσύνης. Μόνο τα πρόσθετα core και verified επιτρέπεται να δηλώνουν δεξιότητες tool_using και llm_only. Κάθε δηλωμένη διαδρομή πρέπει να είναι σχετική και της ίδιας προέλευσης (same-origin), χωρίς σχήμα (scheme), χωρίς // και χωρίς ανάστροφη κάθετο, επειδή ο αναλυτής URL συμπτύσσει το \ σε / και το /\evil.example/x επιλύεται ως διασταυρούμενης προέλευσης (cross-origin). Κάθε κανόνας που εφαρμόζει ο συγχρονισμός μητρώου σε μια δεξιότητα εφαρμόζεται πρώτα εδώ, με τον κωδικό του ίδιου του συγχρονισμού, ώστε το validate και ο συγχρονισμός να κατονομάζουν έναν παραβιασμένο κανόνα με τον ίδιο τρόπο.
Επικύρωση και μετάβαση από την έκδοση 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
Μια αποτυχία εκτυπώνει την ακριβή διαδρομή και, για έναν κανόνα συγχρονισμού, πρώτα τον κωδικό. Κάντε το άγκιστρο υποβολής (commit hook).
Ένα manifest v1 αναβαθμίζεται μηχανικά. Το migrate προσθέτει τις τρεις προτάσεις των νόμων, μετακινεί το domain στο domains[] και αρνείται να επινοήσει ένα σημείο εισόδου που δεν είχατε. Επικυρώνει το αποτέλεσμα προτού εκτυπώσει ή γράψει οτιδήποτε, ώστε μια μετεγκατάσταση να μην μεταφέρει ποτέ μια αποτυχία από το εργαλείο στο αποθετήριό σας.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeΔιαβάστε τις διαφορές (diff) προτού τις υποβάλετε. Οι προτάσεις των νόμων που προσθέτει έχουν τη διατύπωση που επιβάλλει ο επικυρωτής· για τη δική σας εγκατάσταση, ορίστε το deploy στην πρόταση που παρουσιάστηκε νωρίτερα.
Απόδοση της πολυμίσθωσης (tenancy) και προετοιμασία των ρόλων
Δεν γράφετε ποτέ με το χέρι τις εκχωρήσεις ρόλων ή το πρότυπο ασφάλειας σε επίπεδο γραμμής. Το nexus-tenancy render τα γράφει από τα schema και db του manifest:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlΤο αποδιδόμενο αρχείο δημιουργεί πέντε ρόλους για το σχήμα, καθέναν με όσα δεν πρέπει να κατέχει: έναν μετεγκαταστάτη (migrator) που μπορεί μόνο να γίνει ο κάτοχος (owner), έναν κάτοχο που δεν μπορεί να συνδεθεί, έναν ρόλο εφαρμογής για τη διαδρομή αιτημάτων, έναν ρόλο αναφορών που βλέπει μόνο συγκεντρωτικά στοιχεία και έναν ρόλο καθολικού που μπορεί μόνο να προσθέτει εγγραφές (append). Κανένας ρόλος δεν κατέχει το BYPASSRLS. Ο μόνος τρόπος δέσμευσης ενός μισθωτή είναι μία συνάρτηση βάσης δεδομένων, και το set_config ανακαλείται από κάθε ρόλο εκτός από τον κάτοχο.
Ένα εφαρμοσμένο αρχείο πολυμισθωτικότητας δεν τροποποιείται ποτέ. Μια αλλαγή αποτελεί αναθεώρηση με το δικό της αρχείο αριθμού 0, και η θέση ανάγνωσης για εκχωρήσεις μεταξύ οργανισμών έρχεται με αυτόν τον τρόπο, ως αναθεώρηση 2. Το --graph αποδίδει τους δύο πίνακες του τυποποιημένου γράφου που δηλώνει το ontology σας ως την επόμενη αριθμημένη μετεγκατάστασή σας.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --graph --out migrations/001_graph.sqlΤο αρχείο πολυμισθωτικότητας δημιουργεί αυτούς ακριβώς τους ρόλους με τους οποίους συνδέεται ο εκτελεστής, επομένως εφαρμόζεται από τον κάτοχο της βάσης δεδομένων με το 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> είναι μια συμβολοσειρά σύνδεσης για τον κάτοχο της βάσης δεδομένων, και το <dir> είναι ένας ιδιωτικός κατάλογος. Η πρόβλεψη (provision) εφαρμόζει το βασικό αρχείο πολυμισθωτικότητας και κάθε αναθεώρηση με τη σειρά, γράφει τα migrator.url και app.url (καθώς και το seat.url μόλις υπάρξει η αναθεώρηση 2) στο <dir> με δικαιώματα 0600, και δεν εκτυπώνει τίποτα απόρρητο. Ορίζει το όριο συνδέσεων κάθε ρόλου από το db.maxConnections × db.pods σε κάθε εκτέλεση. Μια εκ νέου εκτέλεση διατηρεί τους υπάρχοντες κωδικούς πρόσβασης εκτός αν το ζητήσετε: το --passwords <dir> τους ορίζει από αρχεία και το --rotate <roles> δίνει στους κατονομαζόμενους ρόλους νέους κωδικούς. Μετατρέψτε τα αρχεία σε μυστικά (secrets) της ανάπτυξής σας.
Μετά από αυτό, η εφαρμογή συνδέεται με τη συμβολοσειρά σύνδεσης του μετεγκαταστάτη που έγραψε η πρόβλεψη:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonΕκτελεί τα αρχεία από το 001 και μετά ως ο μετεγκαταστάτης, κάθε αρχείο υπό το SET ROLE <schema>_owner, με μία συναλλαγή ανά αρχείο. Διατηρεί ένα καθολικό, το <schema>.schema_migrations, με το άθροισμα ελέγχου (checksum) κάθε αρχείου· ένα εφαρμοσμένο αρχείο του οποίου τα byte άλλαξαν απορρίπτεται ονομαστικά (CHECKSUM_DRIFT), δεν επανεκτελείται ποτέ και δεν παραλείπεται ποτέ. Κάθε εκκρεμές αρχείο αναλύεται με την πραγματική γραμματική της Postgres προτού εκτελεστεί το πρώτο, ώστε μια άρνηση να αφήνει τη βάση δεδομένων ανέπαφη. Η μοναδική κεφαλίδα που μπορεί να φέρει ένα αρχείο είναι η -- nexus-migration: transaction=file|per-statement, με προαιρετικά χρονικά όρια κλειδώματος και εντολής· το per-statement προορίζεται για το CREATE INDEX CONCURRENTLY.
Οι πύλες
Το nexus-gates εκτελεί είκοσι δύο πύλες. Καθεμία κωδικοποιεί μία κλάση ελαττώματος ώστε να μην μπορεί να κυκλοφορήσει δεύτερη φορά, και καθεμία διαθέτει έναν αυτοέλεγχο που αποδεικνύει ότι αποτυγχάνει σε ένα σενάριο δοκιμής (fixture) κατασκευασμένο για να την ενεργοποιήσει. Εκτελέστε τες προτού κάνετε προώθηση (push):
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Πύλη | Τι εντοπίζει |
|---|---|
scope-adherence |
Μια διαδρομή /api χωρίς τον φρουρό εμβέλειας· μια ανώνυμη διαδρομή που δεν είναι ακριβής δηλωμένη διαδρομή· μια διαδρομή συσκευής χωρίς τον φρουρό συσκευής, ή με έναν φρουρό προσώπου δίπλα της |
one-fence |
Ένα κατηγόρημα (predicate) μισθωτή ορισμένο οπουδήποτε αλλού εκτός από ένα μοναδικό σημείο, συμπεριλαμβανομένου ενός χειροκίνητα γραμμένου φράχτη θέσης ή εκχώρησης |
sql-fence |
Μια εντολή που διαβάζει ή ενημερώνει έναν πίνακα με εμβέλεια χωρίς τον φράχτη, σε οποιονδήποτε στόχο FROM, JOIN, USING ή UPDATE |
migrations-are-scoped |
Έναν πίνακα από τον οποίο λείπει ένας άξονας, ένα σύνθετο κλειδί όπου προηγείται ο μισθωτής, ένα ξένο κλειδί που φέρει τον μισθωτή ή η στήλη επίδειξης (demo) |
migrations-commit-what-they-open |
Μια μετεγκατάσταση της οποίας το πλήθος BEGIN δεν ταιριάζει με το πλήθος των COMMIT και ROLLBACK της |
no-direct-compute |
Μια απευθείας κλήση σε πάροχο μοντέλου, μηχανή, ουρά ή κεντρικό υπολογιστή ροής εργασιών· έναν δεύτερο αναγνώστη του URL αποστολής |
no-credentials |
Ένα διαπιστευτήριο παρόχου μοντέλου αναγνώσιμο στο αποθετήριο ή στο περιβάλλον |
crud-adherence |
Μια διαδρομή μεταβολής δεδομένων της οποίας ο έλεγχος δικαιωμάτων δεν κατονομάζει τίποτα στο μητρώο |
blocked-backends |
Μια διαδρομή που ούτε εξυπηρετείται, ούτε αποκλείεται ονομαστικά, ούτε απορρίπτεται από τον νόμο, ούτε ανήκει αλλού |
every-test-runs |
Δοκιμές στις οποίες δεν φτάνει ποτέ το μοτίβο glob της δέσμης ενεργειών δοκιμών |
tiles-are-invariant |
Ένα προσωρινά αποθηκευμένο σημείο σύνδεσης (seam) αμετάβλητο ως προς τον μισθωτή, το οποίο διαβάζει μια τιμή μισθωτή ή παρακάμπτει τον έλεγχο ταυτότητας |
api-contract |
Μια καταχωρισμένη διαδρομή που δεν δηλώνει το manifest, ή μια δηλωμένη διαδρομή που ο κώδικας δεν καταχωρίζει ποτέ |
rls-present |
Έναν πίνακα χωρίς επιβεβλημένη ασφάλεια σε επίπεδο γραμμής· μια συνάρτηση SECURITY DEFINER χωρίς κλειδωμένο search_path |
no-set-config |
Κώδικα προσθέτου που δεσμεύει ο ίδιος τη ρύθμιση μισθωτή |
db-role-honest |
Μια διαδρομή αιτήματος που συνδέεται ως ο κάτοχος ή ο μετεγκαταστάτης, ή που ζητά SUPERUSER ή BYPASSRLS |
platform-clients |
Έναν πελάτη SDK που εισάγεται αλλά δεν αναφέρεται στο backend.platformClients, ή που αναφέρεται αλλά δεν εισάγεται ποτέ |
rights-register |
Μια διαδρομή εμβέλειας χωρίς δηλωμένο δικαίωμα· έναν έλεγχο δικαιωμάτων εκτός του μητρώου |
refusal-ledger |
Έναν δηλωμένο πίνακα αρνήσεων χωρίς εγκατεστημένο καθολικό, ή ένα σώμα άρνησης που αποστέλλεται παρακάμπτοντάς το |
grants-declared |
Έναν εκχωρημένο πίνακα που δεν δηλώνει το manifest· προνόμια θέσης ανάγνωσης που έχουν δοθεί χειροκίνητα |
people-declared |
Ένα μπλοκ people χωρίς τη διαδρομή εκκαθάρισης (sweep), τον φρουρό και τους πίνακές του |
functions-closure |
Ένα πρόσθετο Azure Functions του οποίου οι εξυπηρετούμενες διαδρομές και οι δηλωμένες διαδρομές διαφωνούν |
declared-input |
Μια λίστα παραμέτρων ερωτήματος ενός χειριστή (handler) που δεν ταιριάζει με το δηλωμένο query της διαδρομής |
Ο κατάλογος gates/ περιέχει τα πέντε αρχεία εξαιρέσεων που μπορεί να διαβάσει μια πύλη (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json και invariant-seams.json), με μία αιτιολογία ανά καταχώριση. Μια κενή αιτιολογία λογίζεται ως μη καταχώριση, και μια καταχώριση που κατονομάζει κάτι που δεν υπάρχει πλέον προκαλεί αποτυχία στην πύλη. Μπορείτε επίσης να τοποθετήσετε εκεί τις δικές σας λειτουργικές μονάδες πυλών, και το nexus-gates τις εντοπίζει μαζί με τις ενσωματωμένες.
Η διοχέτευση (pipeline) του προτύπου
Το πρότυπο δεν περιλαμβάνει καμία χειροκίνητα γραμμένη ροή εργασιών. Η παραμετροποίηση της διοχέτευσής του κατονομάζει το Dockerfile, το μοναδικό όρισμα δόμησης (το διακριτικό μητρώου), τη δοκιμαστική εκτέλεση μετεγκατάστασης και τον έλεγχο εκκίνησης (boot probe), καθώς και την πύλη που εκτελεί η ουρά συγχώνευσης (merge queue). Η σειρά είναι αυτή ακριβώς με την οποία θα θέλατε να συμβεί μια ενδεχόμενη αποτυχία.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, το οποίο είναι τοcreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, το οποίο είναι τοnexus-gates --self-testnode scripts/ci/required-env
Δύο ακόμη έλεγχοι εκτελούνται γύρω από το image. Η δοκιμαστική εκτέλεση μετεγκατάστασης εφαρμόζει κάθε αρχείο σε μια προσωρινή βάση Postgres προτού μπορέσει να κυκλοφορήσει το image, με τον ίδιο runner που χρησιμοποιεί το περιβάλλον παραγωγής: το nexus-migrate provision μία φορά ως superuser και έπειτα κάθε αριθμημένο αρχείο ως migrator. Ο έλεγχος εκκίνησης ξεκινά το κατασκευασμένο image με το δικό του entrypoint και κάθε μεταβλητή που εκτυπώνει το required-env, στοχεύοντας σε υποκατάστατα που δέχονται συνδέσεις και δεν απαντούν ποτέ. Ο διακομιστής αναμένει τη βάση δεδομένων, εντός του καθορισμένου χρονικού παραθύρου του, και αυτή η αναμονή αποτελεί το σήμα επιτυχίας· ένας φορτωτής ρυθμίσεων που αρνείται να εκκινήσει προκαλεί αποτυχία του build εκεί και όχι στην παραγωγή.
Τι κοστίζει
Το SDK παίρνει αποφάσεις αντί για εσάς, και ορισμένες από αυτές θα τις είχατε πάρει διαφορετικά. Το manifest απορρίπτει κλειδιά που δεν αναγνωρίζει, ο πίνακας δρομολόγησης πρέπει να ταιριάζει απόλυτα με τον κώδικά σας, οι ρόλοι της βάσης δεδομένων δεν σχεδιάζονται από εσάς και οι πύλες ελέγχου απορρίπτουν ένα build αν λείπει κάποιο δικαίωμα σε μια ανάγνωση. Στο πρώτο μου plugin πέρασα μια μέρα διαφωνώντας με το api-contract για μια διαδρομή που είχα καταχωρίσει και είχα ξεχάσει να δηλώσω. Είχε δίκιο· η διαδρομή ήταν απροστάτευτη. Να περιμένετε ότι το πρώτο plugin θα σας φανεί αργό και ότι το δεύτερο θα χρειαστεί το ένα τρίτο του χρόνου.

