ΣύνδεσηΚλείστε μια ενημέρωση

Κεφάλαιο 2.27

Σενάρια δημιουργίας

Ένας οδηγός με δεκατρείς υλοποιήσεις, από μια μεμονωμένη δεξιότητα έως μια παράδοση σε απομονωμένο περιβάλλον (air-gapped). Κάθε συνταγή παρουσιάζει τον στόχο, τα δομικά στοιχεία, τα βήματα και τις εντολές, την πύλη ελέγχου που αποδεικνύει ότι λειτούργησε, καθώς και τι αλλάζει ανά έκδοση και μορφή παράδοσης.

Αυτή η σελίδα μεταφράστηκε με AI από το αγγλικό πρωτότυπο. Εάν οτιδήποτε είναι ασαφές, η αγγλική σελίδα αποτελεί το σημείο αναφοράς. Διαβάστε αυτή τη σελίδα στα αγγλικά

25 λεπτά ανάγνωσης

Αυτές είναι οι συνταγές στις οποίες καταφεύγω όταν κάποιος στην Corrán Orbital, ή σε έναν πελάτη, λέει «θέλουμε το Nexus να κάνει το Χ». Η καθεμία είναι σκόπιμα σύντομη. Το σκεπτικό πίσω από τα βήματα βρίσκεται στα κεφάλαια που προηγούνται: κεφάλαιο 2.20, Skills, και κεφάλαιο 2.21, Το Plugin SDK, που καλύπτει το κιτ ανάπτυξης λογισμικού, έπειτα κεφάλαιο 2.23, Domain packs, και τα τρία κεφάλαια που ακολουθούν για την κατασκευή. Εδώ βρίσκετε τον στόχο, ποια δομικά στοιχεία να χρησιμοποιήσετε, τα βήματα, τις εντολές, την πύλη που σας δείχνει ότι λειτούργησε, καθώς και σημειώσεις για την έκδοση και την παράδοση.

Η πύλη είναι το πιο σημαντικό. Μια συνταγή έχει ολοκληρωθεί όταν η πύλη της είναι πράσινη. Κάθε πύλη σε αυτό το κεφάλαιο είναι κάτι που μπορείτε να εκτελέσετε ή κάτι που η πλατφόρμα εκτελεί για εσάς, και καθεμία τερματίζει με μη μηδενικό κωδικό ή απορρίπτει με κωδικό όταν δεν ικανοποιείται.

Σενάριο Κύριο δομικό στοιχείο Η πύλη που το αποδεικνύει Έκδοση
Ένα νέο skill του Skills Engine Πακέτο SKILL.md skill:validate με μηδέν σφάλματα Community και Enterprise
Ένα skill του manifest με host_callback skills[] του manifest του plugin create-nexus-plugin validate και nexus-gates Community και Enterprise
Επέκταση ενός υπάρχοντος pack pack.json με inherits Έλεγχος πολιτικής lens στην πύλη πιλοτικής φάσης Enterprise και άδεια pack
Ένα νέο pack από την αρχή Domain pack golden path Πύλες staging και πιλοτικής φάσης Enterprise
Ένας σύνδεσμος δεδομένων Skill plugin_queue validate, nexus-gates, απόρριψη εξερχόμενης κίνησης Community και Enterprise
Ένα εργαλείο MCP (Model Context Protocol) mcpTools[] του manifest validate (χωρίς συνδυαστές ανώτατου επιπέδου) Community και Enterprise
Ένα white-label κατάστημα domains και branding του manifest Κανόνας δημόσιας πρόσβασης scope-adherence Enterprise και το πρόσθετο Storefront
Ένα Edge mission pack Mission pack Περιπτώσεις ελέγχου επί του σκάφους, δύο από τρεις υπογραφές Enterprise και το πρόσθετο Nexus Edge
Μια παράδοση σε απομονωμένο περιβάλλον (air-gapped) Σφραγισμένο πακέτο nexus-airgap verify Enterprise
Μια ενότητα μόνο για Enterprise @adverant/nexus-spi Πύλη ορίου άδειας, builds ανά έκδοση Enterprise
Fork ή επέκταση του ανοιχτού πυρήνα Ο πηγαίος κώδικας Community Έλεγχοι, lint και έλεγχος τύπων Community
Μια εφαρμογή cloud της έκδοσης Team Publisher cluster Υπογεγραμμένη έκδοση, αξιολόγηση, παραχώρηση στον πελάτη Team
Ενσωμάτωση μιας υπάρχουσας εσωτερικής εφαρμογής /plugin-create migrate, validate, nexus-gates Community και Enterprise
Ένα δέντρο αποφάσεων που διαβάζεται από πάνω προς τα κάτω. Ο πρώτος ρόμβος ρωτά «Χρειάζεται κώδικα που εκτελείται συνεχώς;». Το «Όχι» οδηγεί σε ρόμβο «Πρόκειται για οδηγίες προς έναν βοηθό;», του οποίου το «Ναι» καταλήγει σε «Δεξιότητα Skills Engine» και το «Όχι» σε «Φακός σε υπάρχον πακέτο». Το «Ναι» οδηγεί σε ρόμβο «Είναι η οπτική ενός κλάδου για την πλατφόρμα;», του οποίου το «Ναι» καταλήγει σε «Πακέτο τομέα (με το plugin του)» και το «Όχι» οδηγεί σε έναν τελευταίο ρόμβο «Πρέπει να παραμείνει κλειστό και αδειοδοτημένο;», που καταλήγει σε «Ενότητα Enterprise» για το «Ναι» και σε «Plugin» για το «Όχι».
Από ποιο δομικό στοιχείο να ξεκινήσετε.

1. Μια νέα δεξιότητα του Skills Engine

Ο στόχος είναι ένα επαναχρησιμοποιήσιμο κομμάτι οδηγιών που μπορούν να εκτελούν ο βοηθός, οι agents, οι ροές εργασιών και τα εργαλεία προγραμματιστών, όπως ο έλεγχος μιας τελωνειακής δήλωσης βάσει των κανόνων της. Τα δομικά σας στοιχεία είναι ένα πακέτο SKILL.md σε φάκελο με το όνομα του skill, ένα προαιρετικό skill.yaml για εναύσματα και ετικέτες, και ένας προαιρετικός φάκελος scripts/ που συμπεριλαμβάνεται μαζί του.

  1. Δημιουργήστε το skills/<slug>/ και γράψτε το SKILL.md με frontmatter: name (σε kebab-case, ίδιο με το όνομα του φακέλου), description (έως 500 χαρακτήρες), allowed-tools, και προαιρετικά triggers, capabilities και version.
  2. Γράψτε το κυρίως σώμα για το μοντέλο: πότε να χρησιμοποιείται το skill, τα βήματά του, παραδείγματα, και τι δεν πρέπει ποτέ να κάνει.
  3. Προσθέστε περιπτώσεις ελέγχου. Συμπεριλάβετε μία με μια οδηγία φυτεμένη στην είσοδο, την οποία το skill δεν πρέπει να ακολουθήσει.
  4. Επικυρώστε, εξετάστε το σχέδιο μεταφόρτωσης και, στη συνέχεια, μεταφορτώστε.
  5. Δημοσιεύστε. Ένα skill που προσθέτει εργαλείο εγγραφής παραμένει σε αναμονή έως ότου το εγκρίνουν δύο κατονομαζόμενα πρόσωπα με passkeys, και ο προτείνων δεν μπορεί να εγκρίνει τη δική του αλλαγή.
npm run skill:validate skills/check-a-customs-filing
npm run skill:upload skills/check-a-customs-filing --dry-run
npm run skill:upload skills/check-a-customs-filing

Η πύλη είναι το skill:validate, το οποίο πρέπει να αναφέρει μηδέν σφάλματα πριν μπορέσει να δημοσιευθεί οτιδήποτε. Τα σφάλματα που μπλοκάρουν είναι η έλλειψη ονόματος ή περιγραφής και ένα διπλότυπο slug ή τύπος εργασίας. Η μεταφόρτωση περιεχομένου που έχει ήδη δημοσιευθεί επιστρέφει την υπάρχουσα έκδοση (CONTENT_HASH_ALREADY_PUBLISHED), επομένως η μεταφόρτωση μπορεί να επαναληφθεί με ασφάλεια.

Το Community περιλαμβάνει ολόκληρο τον δημιουργό, τη βιβλιοθήκη, τις εκδόσεις, την επαναφορά, την εισαγωγή και τους ελέγχους. Στο Enterprise, η δημοσίευση περνά επιπλέον από shadow και canary: η εγκεκριμένη έκδοση εκτελείται σε shadow, έπειτα για μία μονάδα πίσω από κατονομαζόμενες πύλες, έπειτα για όλους, και σταματά από μόνη της αν μια πύλη δεν ικανοποιείται. Για πελάτη σε απομονωμένο περιβάλλον, τα skills μεταφέρονται προϋπογεγραμμένα μέσα στο σφραγισμένο πακέτο (σενάριο 9).

2. Μια δεξιότητα manifest με host_callback

Ο στόχος είναι ντετερμινιστικός υπολογισμός μέσα στο δικό σας plugin, τον οποίο η πλατφόρμα μπορεί να αναθέσει, όπως το άνοιγμα μιας εγγραφής απόκλισης από μια μέτρηση. Θα χρησιμοποιήσετε μια γραμμή στο skills[] του manifest με το επίπεδο host_callback, και μια διαδρομή /internal στο backend σας που προστατεύεται από το service guard του SDK.

  1. Δηλώστε το skill: id σε lower_snake, tier: "host_callback", ένα classification ίσο ή κάτω από το ανώτατο όριο εμπιστοσύνης του plugin σας, inputSchema, outputSchema και ένα timeoutMs μεταξύ 1 δευτερολέπτου και 6 ωρών.
  2. Συμπληρώστε το hostCallback: το όνομα του δικού σας Service, τη θύρα του, μια σχετική διαδρομή όπως /internal/skills/excursion_open, και τα δύο όρια byte (maxRequestBytes και maxResponseBytes), και tenantHeader: "X-Organization-ID".
  3. Δηλώστε τη διαδρομή στο api.endpoints[] με auth: "service-key" ή auth: "internal", και προστατέψτε τη με requireService ή serviceMiddleware, ποτέ με το guard εμβέλειας χρήστη.
  4. Επικυρώστε, εκτελέστε τις πύλες και αφήστε τη διαδικασία ενσωμάτωσης να συγχρονίσει τα skills με το μητρώο μέσω του compileRegistry. Δεν γράφετε ποτέ SQL μητρώου με το χέρι.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test

Το validate εφαρμόζει τους ίδιους τους κανόνες του συγχρονισμού μητρώου πριν συγχρονιστεί οτιδήποτε, και καθεμία απόρριψη φέρει τον κωδικό του παραλήπτη. Μια διαδρομή με σχήμα, // ή ανάστροφη κάθετο απορρίπτεται ως διαφορετικής προέλευσης. Ένα όριο byte που λείπει είναι ENDPOINT_BYTE_CAP_REQUIRED, ένα πεδίο από άλλο επίπεδο είναι FIELD_NOT_FOR_TIER, και ένα χρονικό όριο εκτός εύρους είναι TIMEOUT_OUT_OF_BOUNDS. Στη συνέχεια, το nexus-gates ελέγχει ότι η διαδρομή /internal φέρει το service guard και είναι δηλωμένη ως internal ή service-key. Αυτό το ζεύγος πυλών είναι η απόδειξη.

Ο συγχρονισμός είναι δηλωτικός. Αποστέλλετε ολόκληρο το σύνολο των skills κάθε φορά, επειδή ένα skill που παραλείπετε απενεργοποιείται, και κάντε το βήμα ανάπτυξης να αποτυγχάνει σε οποιαδήποτε κατάσταση εκτός από 200. Στο Enterprise, ο συγχρονισμός ενός plugin ελέγχεται ως σύνολο: αν ένα skill παραβιάζει έναν κανόνα, τίποτα από αυτόν τον συγχρονισμό δεν γίνεται δεκτό (PLUGIN_SYNC_ALL_OR_NOTHING) και η προηγούμενη έκδοση συνεχίζει να εκτελείται. Ένα plugin με εμπιστοσύνη community δεν μπορεί να χρησιμοποιήσει τα επίπεδα που φτάνουν σε μοντέλο, tool_using και llm_only· αυτά απαιτούν εμπιστοσύνη core ή verified.

Πρόσθετα και συγχρονισμός MCP
Πρόσθετα και συγχρονισμός MCP
Plugins που φέρνουν skills, και για τι ελέγχθηκε κάθε συγχρονισμός. Προσέξτε το plugin του οποίου ο συγχρονισμός απορρίφθηκε ολόκληρος επειδή ένα από τα πέντε skills του χρησιμοποίησε επίπεδο που μόνο η πλατφόρμα μπορεί να φιλοξενήσει, ενώ η προηγούμενη έκδοσή του συνέχισε να εκτελείται.

3. Επέκταση ενός υπάρχοντος πακέτου

Ο στόχος είναι ένας νέος κλάδος ή υποκλάδος που επαναχρησιμοποιεί το μεγαλύτερο μέρος ενός υπάρχοντος pack, όπως οι δανειοδοτήσεις και οι αμφισβητήσεις καρτών πάνω στη δομή του pack Ασφαλίσεων. Το δομικό στοιχείο είναι ένα pack.json που κατονομάζει τον γονέα του στο inherits και προσθέτει μόνο τα δικά του συμπλέγματα lens και λέξεις.

  1. Ξεκινήστε το pack με το domain pack golden path και, στη συνέχεια, ορίστε το inherits στο id του γονικού pack.
  2. Προσθέστε τα δικά σας συμπλέγματα lens, το καθένα με τις θέσεις, τον σκοπό και την αναφορά λεξικού του.
  3. Προσθέστε τις λέξεις σας στο λεξικό με μια απλή επεξήγηση για την καθεμία. Επισημάνετε έναν όρο ως exact όπου πρέπει να εμφανίζεται όπως είναι γραμμένος.
  4. Επαναχρησιμοποιήστε κοινά lenses αντί να σχεδιάζετε δικά σας: ένα κανονιστικό καθεστώς που χρειάζονται πολλά packs, όπως ένα μητρώο τεχνολογίας σε εξωτερική ανάθεση, είναι ένα κοινό lens.
  5. Ελέγξτε την αλυσίδα αδειών. Το pack σας κληρονομεί τις απαιτήσεις πρόσθετων του γονέα του.
  6. Κάντε προεπισκόπηση κάθε lens ως συγκεκριμένο πρόσωπο σε έναν συνθετικό κλάδο.
{ "id": "fintech", "name": "Banking and payments", "version": "0.1", "inherits": "insurance" }

Η απόδειξη είναι ο έλεγχος πολιτικής της πύλης πιλοτικής φάσης, ο οποίος επιβεβαιώνει ότι κάθε lens μόνο περιορίζει τη βάση του και διατηρεί τα προσωπικά πεδία απενεργοποιημένα από προεπιλογή. Ένα lens που επιχειρεί να εμφανίσει ό,τι κρύβει η βάση του απορρίπτεται με LENS_CANNOT_WIDEN. Όσον αφορά τις άδειες, η κονσόλα αρνείται να εκδώσει άδεια για το pack σας χωρίς τα πρόσθετα που χρειάζεται ο γονέας του· το pack Ασφαλίσεων χρειάζεται Decision rooms και σφραγισμένες εγγραφές.

Τα domain packs είναι Enterprise και αδειοδοτούνται ανά pack. Οι οθόνες κινητού ενός pack απαιτούν επίσης το πρόσθετο Mobile apps. Ένα θυγατρικό pack δεν μπορεί να αλλάξει το κέλυφος, τα στοιχεία ή τους κανόνες γραφής.

4. Ένα νέο πακέτο από την αρχή

Ο στόχος είναι η οπτική ενός κλάδου για το Nexus: το μοντέλο γνώσης του, τα lenses για κάθε ρόλο, τα τεκμήρια που απαιτούν οι κανόνες του, και το plugin που διατηρεί τα δεδομένα του ενημερωμένα. Το Κεφάλαιο 2.24, Κατασκευή ενός προσαρμοσμένου κάθετου κλάδου από άκρη σε άκρη, περιγράφει αυτή την κατασκευή πλήρως· εδώ είναι η σύντομη μορφή.

  1. Εκτελέστε το domain pack golden path και περιγράψτε το pack: σκοπό, μονάδες, το βασικό μοντέλο και τους κανόνες που αντιστοιχίζει.
  2. Δημιουργήστε το μοντέλο γνώσης πάνω σε ένα βασικό μοντέλο και ταξινομήστε κάθε ιδιότητα καθώς την προσθέτετε.
  3. Διαβάστε το σχέδιο, επιβεβαιώστε το αποτύπωμά του με το passkey σας και δημιουργήστε.
  4. Διαμορφώστε τα lenses στο Lens builder, καθένα περιορίζοντας ένα βασικό lens.
  5. Γράψτε το plugin και όποια skills του Skills Engine χρειάζεται το pack.
  6. Δημιουργήστε συνθετικά δεδομένα με seed, που περιλαμβάνουν τις ασυνήθιστες περιπτώσεις που σας ενδιαφέρουν, και κάντε προεπισκόπηση κάθε lens ως συγκεκριμένο πρόσωπο.
  7. Προωθήστε από τον χώρο ανάπτυξης στο staging, σε μια πιλοτική μονάδα και, στη συνέχεια, σε όλες τις μονάδες.

Η απόδειξη είναι οι πύλες προώθησης: όλοι οι έλεγχοι επιτυχείς στους συνθετικούς κλάδους για την είσοδο στο staging, έπειτα δύο αξιολογητές που δεν είναι ο συντάκτης, έπειτα 14 ημέρες στην πιλοτική φάση με σφάλματα κάτω από 1 στα 1.000. Κανένα βήμα δεν μπορεί να παραλειφθεί (GATE_CANNOT_BE_SKIPPED). Τα packs είναι Enterprise. Στο Community το domain pack golden path δεν προσφέρεται.

5. Ένας σύνδεσμος δεδομένων

Ο στόχος είναι δεδομένα από ένα εξωτερικό σύστημα να ρέουν στους δικούς σας πίνακες του plugin βάσει χρονοδιαγράμματος, όπως συμβάντα πύλης από ένα σύστημα λειτουργίας τερματικού σταθμού. Τα δομικά στοιχεία είναι ένα skill plugin_queue, ένας worker που αντλεί από την ουρά σας, ένα migration για τον πίνακα προορισμού, και μια εξερχόμενη διεύθυνση δηλωμένη στο manifest.

  1. Δηλώστε ένα skill plugin_queue με queueName γραμμένο ως <plugin name>.<name>. Δεν επιτρέπεται άνω και κάτω τελεία, και το όνομα πρέπει να βρίσκεται στο manifest, επειδή ο orchestrator τοποθετεί στοιχεία απευθείας στην ουρά του.
  2. Γράψτε τον worker που αντλεί από την ουρά και καλεί το εξωτερικό σύστημα.
  3. Δηλώστε τη διεύθυνση του εξωτερικού συστήματος ως εξερχόμενη διεύθυνση. Οτιδήποτε δεν περιλαμβάνεται στη λίστα αποκλείεται.
  4. Αποθηκεύστε ό,τι φτάνει στο δικό σας σχήμα, με organization_id, owner_user_id και business_unit_id σε κάθε γραμμή.
  5. Διαβάστε το διαπιστευτήριο του εξωτερικού συστήματος με το όνομά του από το περιβάλλον, και καταχωρίστε τη μεταβλητή στο scripts/ci/required-env.
  6. Αναθέστε τις αντλήσεις μέσω του UNO, της μηχανής ροών εργασιών, ποτέ με χρονοδιακόπτη που καλεί απευθείας τις μηχανές.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --only no-credentials --only no-direct-compute --only migrations-are-scoped
node scripts/ci/required-env

Το validate ελέγχει το όνομα της ουράς και το χρονικό όριο βάσει των κανόνων του συγχρονισμού μητρώου. Οι τρεις πύλες αποδεικνύουν ότι δεν υπάρχει διαπιστευτήριο μοντέλου, ούτε άμεσος υπολογισμός, και ότι ο πίνακας έχει σωστή εμβέλεια. Εκτελέστε το πλήρες nexus-gates πριν κάνετε push, καθώς το --only περιορίζει την εκτέλεση και το αναφέρει στη σύνοψή του. Κατά την εκτέλεση, μια κλήση σε διεύθυνση που δεν δήλωσε το manifest σταματά στο όριο με EGRESS_NOT_DECLARED.

Οι ίδιοι οι σύνδεσμοι της πλατφόρμας προς μονάδες αποθήκευσης, wikis, αποθήκες αλληλογραφίας και παλαιά συστήματα, με καταγραφή αλλαγών και γενεαλογία δεδομένων, παρέχονται με το πρόσθετο Data connectors. Ένας σύνδεσμος που κατασκευάζετε μόνοι σας είναι plugin και λειτουργεί σε οποιαδήποτε έκδοση. Η προσθήκη εξερχόμενης διεύθυνσης σε μεταγενέστερη έκδοση αποτελεί διεύρυνση, η οποία παραμένει σε αναμονή έως ότου την αποδεχτούν δύο αξιολογητές.

6. Ένα εργαλείο MCP

Ο στόχος είναι ένα εργαλείο που μπορούν να καλούν το Claude Code, οι agents και άλλοι πελάτες MCP (Model Context Protocol), όπως η αναζήτηση του ιστορικού επιθεωρήσεων ενός πλοίου. Το δομικό στοιχείο είναι μια καταχώριση στο mcpTools[] του manifest, με name, description και inputSchema.

  1. Δώστε όνομα στο εργαλείο και περιγράψτε το με απλά λόγια. Η περιγραφή είναι αυτό που διαβάζει ένα μοντέλο για να αποφασίσει αν θα το καλέσει.
  2. Γράψτε το inputSchema ως ένα σχήμα αντικειμένου. Μην τοποθετείτε oneOf, allOf ή anyOf στο ανώτατο επίπεδό του.
  3. Διατηρήστε τη διαδρομή που εξυπηρετεί το εργαλείο πίσω από το guard εμβέλειας, όπως κάθε άλλη διαδρομή /api, ώστε η μίσθωση (tenancy) να προέρχεται από το token του καλούντος.
  4. Επικυρώστε το manifest.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json

Η απόδειξη είναι το validate: ένας συνδυαστής ανώτατου επιπέδου απορρίπτεται κατά τη σύνταξη, επειδή κατά την εκτέλεση θα έκανε το εργαλείο να αποτυγχάνει για κάθε MCP subagent που το εισάγει, και το εργαλείο θα υπήρχε χωρίς κανείς να μπορεί να το καλέσει.

Στο Enterprise, κάθε εργαλείο που μπορεί να καλέσει ένα IDE (ολοκληρωμένο περιβάλλον ανάπτυξης) εμφανίζεται στον κατάλογο εργαλείων του Workbench με το επίπεδό του, το αν αλλάζει δεδομένα, ένα καρφιτσωμένο αποτύπωμα και τους ρόλους που μπορούν να το χρησιμοποιούν. Αν η περιγραφή του εργαλείου σας αλλάξει σε νέα έκδοση, ο κατάλογος κρατά το εργαλείο σε αναμονή έως ότου ένα πρόσωπο εξετάσει την αλλαγή. Αυτό είναι σκόπιμο: μια αλλαγμένη περιγραφή είναι ο τρόπος με τον οποίο ένα εργαλείο μπορεί να αρχίσει να ζητά από ένα μοντέλο κάτι που δεν θα έπρεπε. Μια κλήση σε οτιδήποτε εκτός της άδειας πρόσβασης του καλούντος απορρίπτεται με CONNECTION_SCOPE_EXCEEDED.

7. Ένα κατάστημα white-label

Ο στόχος είναι μια εφαρμογή που χρησιμοποιούν οι πελάτες του πελάτη σας, στον τομέα του πελάτη και με τη δική του επωνυμία, χωρίς κανένα ίχνος της Adverant. Τα δομικά στοιχεία είναι τα μπλοκ domains και branding του manifest, οι βοηθητικές συναρτήσεις σύνδεσης του SDK, και το πρόσθετο Storefront / white-label του πελάτη.

  1. Τοποθετήστε τον τομέα του πελάτη στο domains[] ως primary, με τυχόν aliases.
  2. Συμπληρώστε το branding: appName, tagline, primaryColor, accentColor, ένα passkeyRpId ίσο με τον τομέα, και oauthClientRef.
  3. Συνδέστε τους χρήστες μέσω των βοηθητικών συναρτήσεων σύνδεσης του SDK, και δηλώστε ακριβώς τις δύο δημόσιες διαδρομές τους, με auth: "public" και allowAnonymous: true.
  4. Στείλτε κάθε κλήση του frontend μέσω του proxy λίστας επιτρεπόμενων του backend for frontend. Μην τοποθετείτε ποτέ διεύθυνση υπηρεσίας στον client.
  5. Αφήστε τις πληρωμές στον διαχειριστή του πελάτη, ο οποίος συνδέει πύλες πληρωμών και ρυθμίζει το επώνυμο checkout.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --only scope-adherence --only api-contract

Η απόδειξη είναι το scope-adherence. Επιτρέπει μια μη προστατευμένη διαδρομή /api μόνο όταν το manifest δηλώνει τη συγκεκριμένη μέθοδο και διαδρομή ως δημόσια και η διαδρομή είναι μία από τις διαδρομές σύνδεσης· οποιαδήποτε άλλη δήλωση δημόσιας πρόσβασης αποτυγχάνει και κατονομάζει τις δύο επιτρεπόμενες διαδρομές. Στη συνέχεια, το api-contract συγκρίνει τις δηλωμένες διαδρομές με τις πραγματικές και προς τις δύο κατευθύνσεις. Το definePlugin απορρίπτει επίσης ένα frontend.basePath που δεν είναι σχετική διαδρομή ίδιας προέλευσης.

Το white-label είναι το πρόσθετο Storefront / white-label στο Enterprise, το οποίο παρέχει επίσης άδεια για πληρωμές. Τα στοιχεία καρτών δεν περνούν ποτέ από το Nexus. Ο διαχειριστής του πελάτη είναι κάτοχος της επωνυμίας και η πλατφόρμα την προσδιορίζει από τον οργανισμό και όχι από τον κώδικά σας.

8. Ένα πακέτο αποστολής Edge

Ο στόχος είναι μια νέα ή ενημερωμένη αποστολή για δορυφόρο ή drone που εκτελεί το Nexus Edge, όπως η προσθήκη ενός προσαρμογέα εντοπισμού πλοίων σε μια αποστολή θαλάσσιας επιτήρησης. Το δομικό στοιχείο είναι ένα πακέτο αποστολής, που δημιουργείται και υπογράφεται στο έδαφος.

  1. Ξεκινήστε από το τρέχον πακέτο στη σελίδα Δημιουργία πακέτου αποστολής, η οποία συντάσσει τη νέα έκδοση από την παλιά και επισημαίνει κάθε αλλαγή.
  2. Αλλάξτε μόνο ό,τι χρειάζεται η αποστολή. Διατηρήστε σταθερά τα μεγάλα μέρη, το γλωσσικό μοντέλο και την οντολογία, όταν είναι δυνατό.
  3. Ελέγξτε τον πίνακα τοποθέτησης σε κάθε βήμα υποβάθμισης, ώστε κάθε πλακέτα να εξακολουθεί να επαρκεί για ό,τι εκτελεί.
  4. Εκτελέστε τις ενσωματωμένες δοκιμαστικές περιπτώσεις του πακέτου σε πάγκο δοκιμών με τις ίδιες πλακέτες.
  5. Στείλτε το για υπογραφή: απαιτούνται δύο από τις τρεις υπογραφές.
  6. Κυκλοφορήστε το σε μία πλατφόρμα. Τοποθετείται στην αδρανή υποδοχή και ενεργοποιείται μόνο αφού οι δοκιμαστικές του περιπτώσεις περάσουν επί του σκάφους.
  7. Επεκτείνετε τη διάθεση στην επόμενη πλατφόρμα μετά από μία εβδομάδα χωρίς προβλήματα.
Πακέτα αποστολής
Πακέτα αποστολής
Η βιβλιοθήκη πακέτων αποστολής, με το περιεχόμενο κάθε πακέτου και τις πλατφόρμες που το εκτελούν. Προσέξτε την παλαιότερη έκδοση που διατηρείται επί του σκάφους για επαναφορά, καθώς και τον αριθμό των δοκιμαστικών περιπτώσεων που πρέπει να περάσει κάθε πακέτο στο υλικό του.

Δεν υπάρχουν εντολές σε αυτή τη συνταγή· γίνεται στις σελίδες Nexus Edge της κονσόλας. Η απόδειξη είναι οι δοκιμαστικές περιπτώσεις επί του σκάφους, οι οποίες πρέπει όλες να περάσουν πριν ενεργοποιηθεί το πακέτο, και οι δύο υπογραφές. Αν μια δοκιμή αποτύχει επί του σκάφους, η πλατφόρμα παραμένει στο προηγούμενο πακέτο της και η αποτυχία μεταδίδεται στην επόμενη διέλευση. Η εγκατάσταση πακέτου σε υλικό για το οποίο δεν έχει ελεγχθεί απορρίπτεται με PACK_NOT_CHECKED_FOR_HARDWARE.

Το Nexus Edge είναι πρόσθετο, με άδεια ανά πλατφόρμα ή ανά στόλο. Τα πακέτα παραμένουν έγκυρα όσο μια πλατφόρμα είναι εκτός επικοινωνίας. Η ζεύξη ανόδου είναι στενή, οπότε σχεδιάστε τα μεγέθη με βάση αυτήν: η δική μας έκδοση 1.5 ήταν 412 MB, έναντι 9.8 GB για πακέτο με νέο γλωσσικό μοντέλο.

9. Μια παράδοση σε πελάτη με απομονωμένο περιβάλλον (air-gapped)

Ο στόχος είναι η εγκατάσταση του plugin ή του πακέτου σας σε εγκατάσταση πελάτη χωρίς δίκτυο. Τα δομικά στοιχεία είναι ένα σφραγισμένο bundle από το @adverant/nexus-sovereign, το κλειδί υπογραφής εκδόσεών σας και τα κανάλια εκδόσεων του ίδιου του πελάτη.

  1. Δημιουργήστε το plugin και τις εικόνες του ακριβώς όπως για συνδεδεμένο πελάτη, με όλους τους ελέγχους επιτυχείς.
  2. Δημιουργήστε ένα σφραγισμένο bundle με το προφίλ airgap, που περιέχει τις εικόνες, τις μεταφορές δεδομένων (migrations), τις προϋπογεγραμμένες δεξιότητες και ένα SBOM (κατάλογο υλικών λογισμικού) με τις άδειες χρήσης.
  3. Υπογράψτε το με το κλειδί εκδόσεων Ed25519 σας.
  4. Επαληθεύστε το μόνοι σας σε καθαρό μηχάνημα.
  5. Στείλτε το bundle σε φυσικό μέσο και στείλτε το δημόσιο κλειδί σας και το SHA-256 του bundle από ξεχωριστή οδό.
  6. Ο χειριστής του πελάτη επαληθεύει το bundle με το κλειδί σας και, στη συνέχεια, εισάγει την έκδοση μέσω των δικών του καναλιών εκδόσεων.
nexus-airgap bundle
nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgap

Το nexus-airgap bundle δημιουργεί το bundle από τη διαμόρφωση bundle σας. Η απόδειξη είναι το nexus-airgap verify από την πλευρά του πελάτη. Υπολογίζει εκ νέου το hash κάθε αρχείου, απορρίπτει κάθε αρχείο που δεν αναφέρεται στο manifest, απαιτεί έμπιστο υπογράφοντα και απορρίπτει bundle του οποίου η λίστα επιτρεπόμενων δικτύων δεν είναι κενή. Ένα τροποποιημένο αρχείο αποτυγχάνει με BUNDLE_INTEGRITY_VIOLATION. Κανείς δεν πρέπει ποτέ να απενεργοποιεί τον αυστηρό έλεγχο για να το παρακάμψει.

Οι απομονωμένες (air-gapped) εγκαταστάσεις ανήκουν στο Enterprise. Τίποτα στο bundle δεν επιτρέπεται να ανακτά οτιδήποτε κατά την εγκατάσταση, και ένα μοντέλο που χρειάζεται το plugin προέρχεται από τον δικό του διακομιστή μοντέλων του πελάτη μέσω του AI (τεχνητής νοημοσύνης) Provider Router.

10. Μια λειτουργική μονάδα αποκλειστικά για την έκδοση Enterprise

Ο στόχος είναι μια κλειστή, αδειοδοτημένη δυνατότητα που συνδέεται στον ανοιχτό πυρήνα, όπως ένα ίχνος ελέγχου μακράς διατήρησης που πωλείται μόνο σε πελάτες Enterprise. Το δομικό στοιχείο είναι το πακέτο διεπαφής @adverant/nexus-spi και τίποτα άλλο από το Community.

  1. Διατηρήστε στο αποθετήριό σας ένα αντίγραφο του δημιουργημένου πακέτου διεπαφής, καρφιτσωμένο σε επίπεδο byte, ως τοπικό πακέτο file:, με το καρφίτσωμα SHA256SUMS.
  2. Γράψτε ένα RouteModule (ή ένα ScreenModule για οθόνες κονσόλας) βάσει αυτού, με την ομάδα λειτουργιών που εξυπηρετεί.
  3. Εκτελέστε κάθε διαδρομή πίσω από το ctx.requireScope και ελέγξτε την εξουσιοδότηση της ίδιας της ενότητας πριν απαντήσετε.
  4. Απορρίψτε με LICENCE_LOCKED όταν ο οργανισμός δεν δικαιούται και εμφανίστε την προεπισκόπηση της λειτουργίας, ποτέ τα δεδομένα της.
  5. Τηρήστε στο αποθετήριο τη γραμμή αδειοδότησης και, στη συνέχεια, δημιουργήστε το συνθεμένο δέντρο κάθε έκδοσης.
npm ci
npm test
npm run build

Η απόδειξη είναι ο κανόνας της γραμμής αδειοδότησης: καμία εισαγωγή από εμβέλεια Community εκτός από το πακέτο διεπαφής, καμία σχετική εισαγωγή εκτός του αποθετηρίου και καμία εξάρτηση file:, link: ή workspace: εκτός αυτού. Στη συνέχεια, οι τρεις παραπάνω εντολές πρέπει να περνούν σε κάθε συνθεμένο δέντρο έκδοσης, όχι μόνο στο δέντρο εργασίας σας. Το Κεφάλαιο 2.25, Δημιουργία για κάθε έκδοση, περιέχει τον σκελετό της ενότητας.

Μια ενότητα φορτώνεται σε μια υπηρεσία Community κατά την εκκίνηση, σε εγκαταστάσεις των οποίων η άδεια περιλαμβάνει την ομάδα λειτουργιών της. Χωρίς αυτή την εξουσιοδότηση αρνείται, οπότε η ίδια έκδοση διατίθεται παντού και δεν κάνει τίποτα όπου δεν έχει άδεια.

11. Διακλάδωση (forking) ή επέκταση του ανοιχτού πυρήνα

Ο στόχος είναι μια αλλαγή στο ίδιο το Community, που διατηρείται στο fork σας ή συνεισφέρεται πίσω. Το δομικό στοιχείο είναι ο πηγαίος κώδικας του Community υπό την Apache License, Version 2.0.

  1. Κάντε fork το αποθετήριο και δημιουργήστε κλάδο από το main.
  2. Προτιμήστε ένα plugin ή μια δεξιότητα, αν αυτό που θέλετε μπορεί να υλοποιηθεί έτσι. Μια αλλαγή στον πυρήνα είναι δική σας ευθύνη να τη συντηρείτε σε κάθε έκδοση.
  3. Κάντε την αλλαγή με δοκιμές που αποτυγχάνουν χωρίς αυτήν.
  4. Εκτελέστε τους ελέγχους που εκτελεί το έργο πριν προτείνετε οτιδήποτε.
  5. Διατηρήστε το αρχείο NOTICE και μη χρησιμοποιείτε τα ονόματα ή τα εμπορικά σήματα της Adverant πέρα από την αναφορά της προέλευσης της εργασίας.
git checkout -b feature/your-change
npm test
npm run lint
npm run typecheck

Η απόδειξη είναι η επιτυχία αυτών των τριών ελέγχων, καθώς και η τεκμηρίωση ότι κάθε νέα δοκιμή αποτύγχανε πριν από την αλλαγή σας. Διατηρήστε αληθή στο fork σας μία ιδιότητα του ανοιχτού πυρήνα: το Community εκτελεί έναν agent από άκρη σε άκρη σε τοπικό μοντέλο χωρίς κλειδί και χωρίς δίκτυο. Μια αλλαγή που το παραβιάζει αυτό παραβιάζει ό,τι καθιστά το Community αυτόνομα χρησιμοποιήσιμο.

Αυτό αφορά μόνο το Community. Οτιδήποτε πρέπει να παραμείνει κλειστό ανήκει αντί αυτού σε μια ενότητα Enterprise (σενάριο 10), ώστε η γραμμή αδειοδότησης να παραμένει σε σημείο που ο καθένας μπορεί να υποδείξει.

12. Μια εφαρμογή cloud για την έκδοση Team

Ο στόχος είναι μια εφαρμογή που μπορούν να εγκαταστήσουν οι πελάτες Team. Το Team εκτελείται μόνο στο Adverant cloud, οπότε η εφαρμογή φτάνει σε αυτούς μόνο μέσω του καταλόγου. Τα δομικά στοιχεία είναι ένα plugin και ένα publisher cluster: το δικό σας εικονικό cluster στο Adverant cloud με δείγματα δεδομένων.

  1. Δημιουργήστε και δοκιμάστε στο publisher cluster, μόνο με δείγματα δεδομένων.
  2. Δηλώστε στο manifest της εφαρμογής όλα όσα χρειάζεται και τίποτα περισσότερο.
  3. Κυκλοφορήστε την υπογεγραμμένη, για έλεγχο από την Adverant και καταχώριση στον κατάλογο.
  4. Κάθε πελάτης την εγκαθιστά, εκχωρώντας κάθε δηλωμένη εμβέλεια ανά μονάδα.

Η απόδειξη αποτελείται από δύο μέρη. Η υπογεγραμμένη, ελεγμένη έκδοση σάς εισάγει στον κατάλογο. Στη συνέχεια, η εξουσιοδότηση του πελάτη καθορίζει σε τι μπορεί να έχει πρόσβαση η εφαρμογή στην εγκατάστασή του, και κάθε κλήση που δεν δηλώθηκε απορρίπτεται με CONNECTION_SCOPE_EXCEEDED. Μπορείτε να προσθέσετε μια εμβέλεια που λείπει μόνο σε νέα έκδοση την οποία ελέγχει ο πελάτης.

Εγκατάσταση προσθέτου τρίτου μέρους
Εγκατάσταση προσθέτου τρίτου μέρους
Ένας διαχειριστής εγκαθιστά ένα plugin τρίτου, εκχωρώντας κάθε δηλωμένη εμβέλεια ανά μονάδα και παραλείποντας μία. Η εικόνα δείχνει μια κλήση που το plugin δεν δήλωσε ποτέ, η οποία απορρίπτεται.

Ένα publisher cluster δεν έχει διαδρομή προς κανέναν πελάτη, και η αίτηση για δεδομένα πελάτη εκεί απορρίπτεται με TENANT_BOUNDARY. Οι πελάτες μπορούν να μοιράζονται μαζί σας αποτελέσματα δοκιμών, ποτέ τα δεδομένα τους. Το Team περιλαμβάνει τη δυνατότητα λειτουργιών ροών εργασίας, οπότε αν η εφαρμογή σας περιλαμβάνει ροές εργασίας, οι πελάτες Team μπορούν να τις προωθούν μεταξύ περιβαλλόντων οι ίδιοι.

13. Ενσωμάτωση μιας υπάρχουσας εσωτερικής εφαρμογής ως προσθέτου

Ο στόχος είναι μια εφαρμογή που ήδη εκτελεί η εταιρεία σας, η οποία εισάγεται στο Nexus ώστε να κληρονομήσει τη σύνδεση, την απομόνωση και τη διακυβέρνηση. Τα δομικά στοιχεία είναι η δεξιότητα /plugin-create για το πρώτο προσχέδιο, και τα εργαλεία manifest και οι έλεγχοι του SDK για την ολοκλήρωσή του.

  1. Εκτελέστε το /plugin-create με το αποθετήριο. Αναλύει τον κώδικα και επιλέγει στρατηγική περιτύλιξης, και στη συνέχεια δημιουργεί το backend, τις μεταφορές δεδομένων (migrations), τη διεπαφή χρήστη (UI), το manifest και τις δοκιμές.
  2. Αναβαθμίστε το manifest στη σύμβαση v2. Το migrate προσθέτει τις τρεις προτάσεις κανόνων και μετακινεί το domain στο domains[], και αρνείται να επινοήσει σημείο εισόδου.
  3. Αντικαταστήστε κάθε τιμή tenant που διαβάζει το περιτύλιγμα από κεφαλίδες με τον φύλακα εμβέλειας του SDK.
  4. Προσθέστε τα organization_id, owner_user_id και business_unit_id σε κάθε πίνακα, με πρωτεύοντα κλειδιά που ξεκινούν από τον tenant.
  5. Δηλώστε κάθε διαδρομή με το δικαίωμά της και εγκαταστήστε το μητρώο απορρίψεων.
  6. Εκτελέστε τους ελέγχους μέχρι να είναι όλοι επιτυχείς.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --write
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test

Η απόδειξη είναι η έξοδος του nexus-gates με 0, με τα scope-adherence, one-fence, migrations-are-scoped, crud-adherence και api-contract να περνούν όλα. Αναμένετε η πρώτη εκτέλεση να αποτύχει στους περισσότερους· η δική μας ανέφερε κάθε διαδρομή ως χωρίς εμβέλεια, επειδή το προσχέδιο εμπιστευόταν κεφαλίδες που μπορούσε να ορίσει το πρόγραμμα περιήγησης. Οι έλεγχοι δεν διαθέτουν διακόπτη αυτόματης διόρθωσης, σκόπιμα.

Οι περιτυλιγμένες εφαρμογές λειτουργούν σε οποιαδήποτε έκδοση. Η ανάπτυξη γίνεται μόνο μέσω των καναλιών εκδόσεων της εγκατάστασης, οπότε αγνοήστε τυχόν αρχεία ανάπτυξης που έγραψε το προσχέδιο. Η εργασία απομόνωσης είναι εκεί όπου αναλώνεται ο χρόνος: υπολογίστε ημέρες για μια πραγματική εφαρμογή, όχι ώρες.