Έκδοση 1.0.0-alpha.1τελευταία
Κεφάλαιο 2.24
Δημιουργία μιας προσαρμοσμένης κάθετης λύσης από την αρχή έως το τέλος
Μια ολοκληρωμένη υλοποίηση του πακέτου τομέα Cold chain, από την πρώτη περιγραφή απαιτήσεων έως την έκδοση που εκτελείται για κάθε μονάδα, με το μοντέλο γνώσης του, τις όψεις, μια δεξιότητα, ένα πλήρες πρόσθετο υπηρεσίας και δείγμα δεδομένων. Έπειτα, πώς να επεκτείνετε ένα πακέτο που υπάρχει ήδη και πώς να προσθέσετε μια όψη σε ένα πακέτο που έχει ήδη διατεθεί.
Αυτή η σελίδα μεταφράστηκε με AI από το αγγλικό πρωτότυπο. Εάν οτιδήποτε είναι ασαφές, η αγγλική σελίδα αποτελεί το σημείο αναφοράς. Διαβάστε αυτή τη σελίδα στα αγγλικά

Είμαι ο Mateo Ruiz, προγραμματιστής στην Corrán Orbital. Το μεγαλύτερο μέρος της εβδομάδας μου το αφιερώνω στο δικό μας λογισμικό ωφέλιμου φορτίου, αλλά αυτό το κεφάλαιο αφορά μια εργασία που κάναμε για έναν πελάτη. Η Larkfield & Vane ασφαλίζει φορτία, και ένα αυξανόμενο μέρος τους ταξιδεύει σε ψυγεία-εμπορευματοκιβώτια. Όταν ένα ψυγείο-εμπορευματοκιβώτιο χάνει την παροχή ρεύματος από την ξηρά στην αποβάθρα, η θερμοκρασία ανεβαίνει, το φορτίο αλλοιώνεται και μια απαίτηση αποζημίωσης ακολουθεί εβδομάδες αργότερα. Η Larkfield ήθελε οι άνθρωποί της να βλέπουν αυτή την αλυσίδα ως ένα ενιαίο σύνολο στο Nexus, από τη βλάβη στην παροχή ρεύματος έως την απαίτηση, με κάθε ρόλο να βλέπει μόνο το δικό του μέρος. Έτσι προέκυψε το πακέτο Cold chain.
Ακολουθεί η κατασκευή με τη σειρά που την κάναμε, με τις οθόνες, τα αρχεία και τις εντολές. Έχω διατηρήσει τα λάθη, επειδή δύο από τις απορρίψεις που συναντήσαμε μας δίδαξαν περισσότερα για την πλατφόρμα από ό,τι η ομαλή πορεία. Το υλικό αναφοράς βρίσκεται στα προηγούμενα κεφάλαια, και παραπέμπω σε αυτά αντί να τα επαναλαμβάνω. Αυτά στα οποία στηρίχθηκα περισσότερο ήταν το κεφάλαιο 2.18, Το μοντέλο επεκτάσεων, και το κεφάλαιο 2.23, Πακέτα τομέα, με το κεφάλαιο 2.21, Το Plugin SDK, ανοιχτό δίπλα τους για το ίδιο το κιτ ανάπτυξης λογισμικού.
Η περιγραφή απαιτήσεων και η κατανομή ρόλων
Η Larkfield μού παραχώρησε θέση προγραμματιστή στον οργανισμό της για όλη τη διάρκεια του έργου. Αυτό έχει σημασία, επειδή ένα ιδιωτικό πακέτο για έναν πελάτη κατασκευάζεται μέσα στην εγκατάσταση αυτού του πελάτη, στους χώρους ανάπτυξης και στους κλάδους δεδομένων του, με τις εγκρίσεις των ανθρώπων του. Ένα πακέτο που προορίζεται για πολλούς πελάτες κατασκευάζεται διαφορετικά, σε cluster εκδότη μόνο με δείγματα δεδομένων, και το κεφάλαιο 2.25, Κατασκευή για κάθε έκδοση, καλύπτει αυτή την περίπτωση.
Οι προδιαγραφές χωρούσαν σε μία σελίδα:
- Ψυγεία-εμπορευματοκιβώτια στην αποβάθρα και σε πλοία: η παροχή ρεύματός τους, οι αποκλίσεις θερμοκρασίας τους και οι απαιτήσεις αποζημίωσης που ακολουθούν.
- Δύο ρόλοι για αρχή: ένας τεχνικός ψυγείων-εμπορευματοκιβωτίων στην αποβάθρα και ένας ελεγκτής ψυχρής αλυσίδας στο γραφείο.
- Ένα πιλοτικό πρόγραμμα που εκτελείται πρώτα στη μονάδα Rotterdam και μεταφέρεται στη συνέχεια στη Felixstowe.
- Τεκμήρια για τρία σύνολα κανόνων: τη συμφωνία ATP για τα ευπαθή τρόφιμα, την ορθή πρακτική διανομής της ΕΕ για τα φάρμακα και τα αρχεία ασφάλειας τροφίμων κατά HACCP (ανάλυση κινδύνων και κρίσιμα σημεία ελέγχου). Οι απαιτήσεις βάσει των κανόνων Hague-Visby χρησιμοποιούν τα ίδια αρχεία αποκλίσεων, οπότε τις σημειώσαμε για μετά το πιλοτικό πρόγραμμα.
Τα πακέτα τομέα είναι δυνατότητα της έκδοσης Enterprise. Η Larkfield χρησιμοποιεί Enterprise, οπότε η διαδρομή πακέτου τομέα ήταν διαθέσιμη για μένα. Στην έκδοση Community, η χρυσή διαδρομή για πακέτο δεν προσφέρεται καθόλου.
Ξεκινήστε από τη βέλτιστη διαδρομή
Όλα ξεκινούν από τη σελίδα Ξεκινήστε κάτι νέο. Προσφέρει έξι χρυσές διαδρομές: plugin, πακέτο τομέα, lens, πλατφόρμα, skill και ροή εργασιών. Η καθεμία δημιουργεί ένα αποθετήριο από ένα πρότυπο με έκδοση, ένα manifest που δηλώνει τι χρειάζεται το στοιχείο, δοκιμές, έναν χώρο ανάπτυξης και κλάδους δεδομένων. Οι ίδιες διαδρομές λειτουργούν στην κονσόλα, στη γραμμή εντολών και από το IDE σας (ολοκληρωμένο περιβάλλον ανάπτυξης), όπου το εργαλείο Workbench nexus.create κάνει την ίδια δουλειά με ένα σχέδιο που επιβεβαιώνετε πρώτα.
nexus create και το καρφιτσωμένο πρότυπό της. Προσέξτε την πλάκα στο κάτω μέρος: το manifest επιβάλλεται, δεν είναι συμβουλευτικό, και μια έκδοση που ζητά περισσότερα παρακρατείται μέχρι να την ελέγξουν δύο άτομα.Ακολουθήσαμε τη διαδρομή πακέτου τομέα από εκείνη τη σελίδα, ονομάζοντας το πακέτο cold-chain και την πρώτη του μονάδα Rotterdam. Το αποτέλεσμα αναφέρει το καρφιτσωμένο πρότυπο, domain-pack@1.6.0, και παραθέτει ό,τι δημιούργησε: το αποθετήριο, ένα manifest που δηλώνει τέσσερα scopes, δύο χώρους αποθήκευσης και καμία εξερχόμενη διεύθυνση, 66 δοκιμές από το πρότυπο, έναν χώρο ανάπτυξης στο Rotterdam, τρεις κλάδους συνθετικών δεδομένων και μια πρόχειρη καταχώριση στον δικό της κατάλογο της Larkfield που μόνο εγώ μπορούσα να δω. Η έκδοση του προτύπου είναι καρφιτσωμένη, και η μεταγενέστερη αναβάθμισή της φτάνει ως ελεγμένη αλλαγή όπως κάθε άλλη, ώστε το πακέτο κανενός να μη μετακινείται κάτω από τα πόδια του επειδή μετακινήθηκε ένα πρότυπο. Παρ' όλα αυτά, χρησιμοποίησα τον οδηγό της κονσόλας για το πρώτο μας πακέτο, επειδή δείχνει το σχέδιο πριν δημιουργήσει οτιδήποτε.
Βήμα 1: ορίστε τον σκοπό του πακέτου
Ο οδηγός Νέο πακέτο τομέα έχει τρία βήματα: πληροφορίες, μοντέλο γνώσης, και έλεγχος και δημιουργία. Το βήμα 1 ζητά τα λίγα στοιχεία που διαμορφώνουν όλα όσα ακολουθούν.
| Πεδίο | Τι καταχωρίσαμε | Σημείωση |
|---|---|---|
| Όνομα | Cold chain | Χρησιμοποιείται για το αποθετήριο και τον κατάλογο |
| Σε τι χρησιμεύει | Ψυγεία-εμπορευματοκιβώτια στην αποβάθρα και σε πλοία: παροχή ρεύματος, αποκλίσεις θερμοκρασίας και οι απαιτήσεις αποζημίωσης που ακολουθούν | |
| Κλάδος | Εφοδιαστική αλυσίδα και ναυτιλία | Βασίζεται στο πακέτο Logistics and maritime |
| Ιδιοκτήτης (Owner) | Το άτομο που το δημιουργεί | Κλειδωμένο στον οδηγό |
| Μονάδες | Rotterdam (πιλοτικό) | Felixstowe μετά το πιλοτικό |
| Πρότυπο | domain-pack@1.6.0 |
Κλειδωμένο· οι αναβαθμίσεις έρχονται ως ελεγμένες αλλαγές |
| Κανόνες που αντιστοιχίζει | Συμφωνία ATP, ορθή πρακτική διανομής της ΕΕ, αρχεία ασφάλειας τροφίμων | Κάθε κανόνας γίνεται μια σελίδα στον χάρτη τεκμηρίων του πακέτου |
Ο βοηθός στο πλαίσιο πρότεινε την τελευταία γραμμή, συμπεριλαμβανομένου του σημείου ότι οι απαιτήσεις για φορτία επαναχρησιμοποιούν τα ίδια αρχεία αποκλίσεων. Μια πλάκα στο κάτω μέρος της σελίδας αναφέρει ότι τίποτα δεν έχει δημιουργηθεί ακόμη. Το αποθετήριο, ο χώρος ανάπτυξης και οι κλάδοι δεδομένων δημιουργούνται μόνο όταν πατήσετε Δημιουργία στο βήμα 3, αφού έχετε δει το σχέδιο. Μπορείτε να αποθηκεύσετε πρόχειρο και να επιστρέψετε.
Βήμα 2: το μοντέλο γνώσης
Το μοντέλο γνώσης είναι το σύνολο των ειδών οντοτήτων που γνωρίζει το πακέτο και του τρόπου με τον οποίο συνδέονται. Το Cold chain ξεκίνησε από το βασικό μοντέλο logistics, logistics-base 4.2, που εισήχθη από το SDK και μας έδωσε πέντε βασικά είδη πάνω στα οποία χτίσαμε (Vessel, Port, Container, Carrier και Shipment). Τα βασικά είδη είναι μόνο για ανάγνωση στον οδηγό. Αν κάποιο χρειάζεται αλλαγή, αλλάζει στο πακέτο στο οποίο ανήκει.
Προσθέσαμε πέντε δικά μας είδη:
| Είδος | Τι είναι | Ιδιότητες |
|---|---|---|
| Reefer unit | Ένα ψυγείο-εμπορευματοκιβώτιο | 9 |
| Vessel call | Ένα πλοίο σε μία θέση πρόσδεσης | 6 |
| Excursion | Μια θερμοκρασία εκτός των ορίων της | 8 |
| Power supply | Ένα σημείο παροχής ρεύματος από την ξηρά ή από το πλοίο | 4 |
| Δήλωση | Χρήματα που ζητούνται για αλλοιωμένο φορτίο | 7 |
Κάθε ιδιότητα κατηγοριοποιείται κατά τη δημιουργία της. Το «Αναφέρθηκε από» σε ένα Excursion είναι προσωπικό. Η «Αξία φορτίου σε κίνδυνο» και το ποσό και ο διακανονισμός μιας απαίτησης είναι εμπορικά. Την πρώτη μέρα αυτό φάνηκε γραφειοκρατία, αλλά μας γλίτωσε δύο φορές αργότερα, επειδή οι κατηγορίες καθορίζουν τι μπορεί να εμφανίσει ένα lens, τι αντικαθιστά ένα αντίγραφο με απόκρυψη και τι αποκρύπτει μια γραμμή καταγραφής.
Δύο από τις σχέσεις μας εκτείνονται στο βασικό μοντέλο: ένα Reefer unit είναι συνδεδεμένο σε ένα Power supply, και ένα Claim παραπέμπει σε ένα Shipment. Το ίδιο το βασικό μοντέλο δεν αλλάζει. Μια ιδιότητα που αποσύρετε παραμένει στην έκδοση 1.0 του μοντέλου και αφαιρείται μόνο σε μεταγενέστερη έκδοση, ώστε τίποτα που ίσχυε για παλαιές εγγραφές να μην πάψει να είναι αναγνώσιμο.
Βήμα 3: έλεγχος και δημιουργία
Το βήμα 3 είναι το σχέδιο. Παραθέτει ό,τι θα δημιουργηθεί, τα scopes που θα δηλώσει το manifest, τους κλάδους δεδομένων και τον χώρο ανάπτυξης. Επιβεβαιώνετε το σχέδιο με το passkey σας, και το σχέδιο λαμβάνει ένα αποτύπωμα. Η δημιουργία στη συνέχεια ακολουθεί ακριβώς αυτό το σχέδιο, ένα βήμα τη φορά, και μπορείτε να σταματήσετε σε οποιοδήποτε βήμα και να κρατήσετε ό,τι έχει δημιουργηθεί.
Το σχέδιο για το Cold chain δήλωνε τέσσερα scopes:
| Scope | Γιατί το χρειάζεται το πακέτο |
|---|---|
| Ανάγνωση τηλεμετρίας ψυγείων-εμπορευματοκιβωτίων | Μετρήσεις ρεύματος και θερμοκρασίας |
| Εγγραφή αποκλίσεων | Καταγράφει μια απόκλιση όταν παραβιάζονται τα όρια |
| Ανάγνωση αποστολών | Συνδέει μια απαίτηση με την αποστολή της |
| Σύνταξη πρόχειρων σημειωμάτων απαιτήσεων | Μόνο πρόχειρα· την αποστολή την κάνει ένα άτομο |
Οι χώροι αποθήκευσής του ήταν ο γράφος και οι εγγραφές. Δεν είχε εξερχόμενες διευθύνσεις και είχε το προφίλ sandbox Standard. Ο χώρος ανάπτυξης συνοδευόταν από 4 πυρήνες, 16 GiB μνήμης και 50 GiB αποθηκευτικού χώρου, δίκτυο κλειστό εκτός από ό,τι δηλώνει το manifest, μόνο υπογεγραμμένα images, και λήξη μετά από 7 ημέρες αδράνειας. Όταν λήξει, ο ορισμός του παραμένει στο αποθετήριο, οπότε τον δημιουργείτε ξανά από εκεί.
Οι τρεις κλάδοι δεδομένων προήλθαν από τη γεννήτρια συνθετικών δεδομένων. Δεν αντιγράφηκαν δεδομένα πελατών. Ένα αντίγραφο του Rotterdam με απόκρυψη απαιτεί τη συγκατάθεση του κατόχου των δεδομένων, που στη Larkfield είναι η Priya Natarajan, και τη ζητάτε ξεχωριστά.
Το manifest του πακέτου
Το αποθετήριο περιέχει το manifest του πακέτου, pack.json. Αναφέρει το όνομα του πακέτου, την έκδοσή του, το πακέτο από το οποίο κληρονομεί (εάν υπάρχει), τα clusters του και τους όρους του. Ένα cluster είναι είτε lens, δηλαδή ό,τι βλέπει ένας ρόλος μέσα στο πακέτο, είτε κοινόχρηστο, που εκτείνεται σε όλα τα lens. Ακολουθεί ο πυρήνας του δικού μας:
{
"id": "cold-chain",
"name": "Cold chain",
"version": "0.4.0",
"clusters": [
{
"id": "CC01",
"kind": "lens",
"name": "Reefer technician",
"seats": "Technicians on the quay",
"purpose": "Which reefers have lost power or warmed up, and what to do next.",
"lexicon": ["cold"],
"menu": [],
"screens": []
},
{
"id": "CC02",
"kind": "lens",
"name": "Cold-chain controller",
"seats": "Controllers in the operations office",
"purpose": "Every excursion from first reading to closed claim, with its evidence.",
"lexicon": ["cold"],
"menu": [],
"screens": []
}
],
"lexicon": {
"core": [],
"cold": [
["excursion", "a time when the temperature left its limits", ""],
["set point", "the temperature a reefer is told to hold", ""],
["shore power", "electricity from the quay rather than the ship", ""]
]
}
}Το λεξικό περιέχει τους όρους του πακέτου με μια απλή επεξήγηση για τον καθένα, αρκετά σύντομη ώστε να διαβάζεται σε κινητό.
Πέρα από το pack.json, το manifest δηλώνει επίσης σε τι μπορεί να έχει πρόσβαση το πακέτο: τα scopes, τους χώρους αποθήκευσης, τις εξερχόμενες διευθύνσεις και το προφίλ sandbox του. Το Nexus παραχωρεί ακριβώς αυτά και τίποτα περισσότερο. Κάθε κλήση εργαλείου ελέγχεται έναντι των δηλωμένων scopes, και μια εξωτερική διεύθυνση αποκλείεται εκτός εάν περιλαμβάνεται στη λίστα. Μπορείτε να διαβάσετε τη δήλωση, καθώς και την αλλαγή σε σχέση με την τελευταία έκδοση, στη σελίδα Manifest και δικαιώματα του πακέτου.
Όψεις: τι βλέπει κάθε ρόλος
Ένα lens μπορεί μόνο να περιορίσει ό,τι δείχνει η βάση του, και αυτός ο ένας κανόνας διαμόρφωσε τον σχεδιασμό μας περισσότερο από οποιονδήποτε άλλον. Ένα lens δείχνει ένα μέρος από όσα δείχνει το βασικό του lens, και τα δικαιώματα εξακολουθούν να προέρχονται από τους ρόλους: ένα lens καθορίζει τι βλέπει ένας ρόλος στο πακέτο, όχι τι επιτρέπεται να κάνει.
Το lens Reefer technician περιορίζει το Operations controller, το βασικό lens που ήδη χρησιμοποιεί η Larkfield για εργασίες logistics. Στο Lens builder επιλέγετε τις κάρτες, τα πεδία και τις ενέργειες που δείχνει το lens. Τα στοιχεία που δεν δείχνει η βάση είναι κλειδωμένα.
| Μέρος | Το Reefer technician δείχνει | Εκτός |
|---|---|---|
| Κάρτες | Ψυγεία-εμπορευματοκιβώτια στην αποβάθρα, ανοιχτές αποκλίσεις, σημεία παροχής ρεύματος, σημερινές προσεγγίσεις πλοίων | Οτιδήποτε σχετικό με απαιτήσεις |
| Πεδία | Κατάσταση ρεύματος, τιμή ρύθμισης, τελευταία μέτρηση, υψηλότερη θερμοκρασία | Ποσό απαίτησης (δεν υπάρχει στο βασικό lens), προσωπικά πεδία (απενεργοποιημένα από προεπιλογή) |
| Ενέργειες | Καταγραφή αιτίας απόκλισης, αίτημα ελέγχου ρεύματος | Αλλαγή τιμής ρύθμισης και κλείσιμο απόκλισης (μόνο ελεγκτές), σύνταξη πρόχειρου σημειώματος απαίτησης |
Προσπάθησα παρ' όλα αυτά να προσθέσω το ποσό απαίτησης στο lens του τεχνικού, επειδή ένας τεχνικός το είχε ζητήσει. Το builder αρνήθηκε με LENS_CANNOT_WIDEN και δεν αποθήκευσε τίποτα. Δεν υπάρχει λύση παράκαμψης μέσα στο lens: ο δρόμος είναι ένα lens σε ευρύτερη βάση, ένα διαφορετικό αίτημα για το οποίο αποφασίζει ο διαχειριστής του οργανισμού. Το αφήσαμε εκτός.
Η απόκρυψη ενός στοιχείου σε ένα lens δεν το αφαιρεί από το Nexus. Σημαίνει ότι αυτός ο ρόλος δεν το βλέπει. Το builder δείχνει πόσα άτομα θα φτάσει ένα lens στο πιλοτικό πρόγραμμα (29, στη δική μας περίπτωση) και τηρεί αρχείο κάθε Προσθήκης, Αλλαγής και Απόσυρσης. Ένα lens ορίζεται μία φορά για τον οργανισμό και παραχωρείται ανά μονάδα σε έναν ρόλο πλατφόρμας, ώστε το ίδιο lens Reefer technician να μπορεί να δοθεί στους τεχνικούς του Rotterdam αυτόν τον μήνα και της Felixstowe τον επόμενο.
Μια δεξιότητα για τη σύνταξη σημειώσεων αξιώσεων
Οι ελεγκτές ήθελαν ένα πρώτο προσχέδιο του σημειώματος που αποστέλλεται σε έναν ιδιοκτήτη φορτίου μετά από μια απόκλιση. Αυτό είναι γλωσσική εργασία, οπότε εκτελείται σε μοντέλο, και το ερώτημα ήταν πού να τοποθετηθεί.
Υπάρχουν δύο είδη skill στο Nexus, και η διαφορά έχει σημασία εδώ. Ένα manifest skill είναι μια τυποποιημένη γραμμή στο skills[] ενός plugin, που αποστέλλεται για εκτέλεση από την πλατφόρμα. Ένα skill του Skills Engine είναι ένα πακέτο SKILL.md στη βιβλιοθήκη skills του οργανισμού, το οποίο εκτελούν με τον ίδιο τρόπο οι agents, τα κουμπιά AI (τεχνητής νοημοσύνης), οι ροές εργασιών και τα εργαλεία ανάπτυξης. Το Κεφάλαιο 2.20, Skills, καλύπτει και τα δύο.
Το επίπεδο εμπιστοσύνης του plugin μας είναι community, και ένα community plugin μπορεί να δηλώνει μόνο manifest skills που δεν απευθύνονται σε μοντέλο (host_callback και plugin_queue). Τα δύο επίπεδα που απευθύνονται στο AI Provider Router, tool_using και llm_only, απαιτούν εμπιστοσύνη core ή verified. Έτσι, η σύνταξη σημειωμάτων απαιτήσεων έγινε skill του Skills Engine, και ο router επιλέγει το μοντέλο από τη δική της δεξαμενή της Larkfield:
---
name: draft-claim-note
description: Draft a note to a cargo owner about one reefer excursion, from the excursion record and its readings. Drafts only; a person reviews and sends.
allowed-tools: Read, Grep
triggers:
- /draft-claim-note
capabilities:
- name: draft_note
description: Write a first draft for one excursion
version: 1.0.0
---
# Draft a claim note
Use this when a controller asks for a note about one excursion.
## Steps
1. Read the excursion: unit, start, length, highest temperature and cause.
2. Read the shipment it belongs to, for the cargo owner's name.
3. Write four short paragraphs: what happened, when, what the readings show, what happens next.
4. Never state a claim amount. Never send anything.Το πακέτο βρίσκεται στο skills/draft-claim-note/ στο αποθετήριο, με το όνομα του φακέλου ίδιο με το όνομα του skill. Το επικυρώσαμε και το ανεβάσαμε από το τερματικό:
npm run skill:validate skills/draft-claim-note
npm run skill:upload skills/draft-claim-note --dry-run
npm run skill:upload skills/draft-claim-noteΑν ανεβάσετε το ίδιο περιεχόμενο δύο φορές, επιστρέφεται η υπάρχουσα έκδοση αντί για νέα (CONTENT_HASH_ALREADY_PUBLISHED), οπότε η επανάληψη της μεταφόρτωσης είναι ασφαλής. Πριν κυκλοφορήσει μια έκδοση, το Skills Engine εκτελεί τις περιπτώσεις δοκιμών της, μια δοκιμαστική εκτέλεση σε σκιώδη λειτουργία σε προηγούμενες εργασίες και μια τυφλή αξιολόγηση από μοντέλο άλλης εταιρείας, με τον χρόνο και το κόστος κάθε εκτέλεσης.
Το πλήρες πρόσθετο υπηρεσίας
Το πακέτο χρειαζόταν επίσης κώδικα που εκτελείται συνεχώς: έναν αναγνώστη για τη ροή τηλεμετρίας των ψυγείων-εμπορευματοκιβωτίων και έναν εγγραφέα που ανοίγει εγγραφή απόκλισης όταν μια μέτρηση παραβιάζει τα όριά της. Τέτοιος κώδικας ανήκει σε ένα πλήρες plugin υπηρεσίας, και τον δημιουργήσαμε με την εντολή του ίδιου του SDK, η οποία γράφει ολόκληρο το δέντρο αναφοράς με αντικατεστημένο το όνομα:
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold cold-chain --tier full-service
cd cold-chain
npm install
npm ci
npm run typecheck && npm test && npm run build
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Το SDK εγκαθίσταται από το https://registry.adverant.ai/npm/ με το pull token από τη σελίδα Pull tokens και εντολές εγκατάστασης του λογαριασμού σας Adverant. Κάντε commit το package-lock.json που γράφει η πρώτη εγκατάσταση· η δημιουργία του image εκτελεί npm ci και αρνείται να προχωρήσει χωρίς αυτό.
Ακολουθεί το τμήμα του nexus.manifest.json μας που διαφέρει από το πρότυπο. Δεν είναι ολόκληρο το αρχείο: τα μπλοκ description, author, license, runtime, backend και frontend του σκελετού παραμένουν ως έχουν, και ο validator απορρίπτει ένα manifest πλήρους υπηρεσίας χωρίς αυτά. Οι τρεις προτάσεις architecture είναι ο κανόνας που επαναλαμβάνει κάθε plugin, και ο validator ελέγχει τη διατύπωση. Το UNO στην πρώτη είναι η μηχανή ροών εργασιών:
{
"manifestVersion": "2",
"name": "cold-chain",
"displayName": "Cold chain",
"version": "0.4.0",
"tier": "full-service",
"trust": "community",
"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": {
"version": "1",
"basePath": "/",
"endpoints": [
{ "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
{ "method": "GET", "path": "/api/excursions", "summary": "List the unit's excursions", "auth": "scope", "right": "excursion.read", "needsUnit": true },
{ "method": "POST", "path": "/api/excursions", "summary": "Record an excursion", "auth": "scope", "right": "excursion.create", "needsUnit": true },
{ "method": "POST", "path": "/internal/skills/excursion_open", "summary": "host_callback receiver the platform POSTs to", "auth": "internal" }
]
},
"rights": {
"excursion.read": { "summary": "Read the unit's excursions.", "roles": ["owner", "admin", "member", "viewer"] },
"excursion.create": { "summary": "Record an excursion.", "roles": ["owner", "admin", "member"] }
},
"skills": [
{
"id": "excursion_open",
"displayName": "Open an excursion",
"description": "Open an excursion record when a reading breaks its set point limits. No model; runs in the plugin's own backend.",
"tier": "host_callback",
"classification": "tenant",
"dataResidency": "eu",
"inputSchema": { "type": "object", "properties": { "readingId": { "type": "string" } }, "required": ["readingId"] },
"outputSchema": { "type": "object", "properties": { "opened": { "type": "boolean" } }, "required": ["opened"] },
"hostCallback": {
"service": "cold-chain",
"port": 8080,
"path": "/internal/skills/excursion_open",
"maxRequestBytes": 65536,
"maxResponseBytes": 16384,
"tenantHeader": "X-Organization-ID"
},
"timeoutMs": 10000
}
],
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}
}Το excursion_open είναι ένα skill του manifest με το επίπεδο host_callback: η πλατφόρμα αποστέλλει την είσοδο στο δικό μας Service, μέσα στο namespace μας, και ποτέ σε host που ορίζουμε εμείς. Η διαδρομή του παραλήπτη δηλώνεται auth: internal και προστατεύεται με το serviceMiddleware του SDK, τη μορφή Express του μηχανισμού προστασίας, η οποία απορρίπτει ένα token κλήσης που έχει εκδοθεί για οποιοδήποτε άλλο plugin, οργανισμό, skill ή διαδρομή. Το classification του είναι tenant, που αποτελεί το ανώτατο όριο για ένα plugin της κοινότητας. Το Κεφάλαιο 2.27, Σενάρια κατασκευής, παρουσιάζει αναλυτικά ένα skill host_callback ξεχωριστά.
Δύο συνήθειες από αυτό το στάδιο αξίζει να υιοθετήσετε. Κάθε πίνακας φέρει organization_id, owner_user_id και business_unit_id από την πρώτη μετάπτωση, επειδή η προσθήκη ενός άξονα αργότερα αποτελεί μετάπτωση πάνω σε ζωντανές γραμμές. Επίσης, εκτελούσαμε το nexus-gates τοπικά πριν από κάθε push, καθώς είναι η ίδια εντολή που εκτελεί το pipeline· μια εκτέλεση που δεν εξέτασε τίποτα τερματίζει με 2 και το αναφέρει. Το Κεφάλαιο 2.19, Οι κανόνες που κληρονομεί κάθε επέκταση, παραθέτει τις πύλες ελέγχου.
Δείγμα δεδομένων για δοκιμές
Η σελίδα Δείγματα δεδομένων για δοκιμές προσφέρει τρία είδη κλάδων:
| Είδος | Τι περιέχει | Ποιος συναινεί |
|---|---|---|
| Συνθετικά | Δεδομένα που παράγονται από πλήθη και μορφές που ορίζετε εσείς· τίποτα δεν προέρχεται από πραγματική μονάδα | Κανείς· είναι δικά σας |
| Αντίγραφο με απόκρυψη | Αντίγραφο μιας μονάδας με τα προσωπικά, ευαίσθητα και εμπορικά πεδία αντικατεστημένα | Ο κάτοχος των δεδομένων (Priya Natarajan για το Rotterdam) |
| Μόνο σχήμα | Η δομή των αποθηκών δεδομένων, χωρίς γραμμές | Κανείς· για μεταπτώσεις |
Δημιουργήσαμε μια πολυάσχολη εβδομάδα: περίπου 7 αποκλίσεις ανά 100 ψυκτικά εμπορευματοκιβώτια, όπως είναι ένας πολυάσχολος Αύγουστος στο Rotterdam. Οι ασυνήθιστες περιπτώσεις είχαν μεγαλύτερη σημασία από τον όγκο. Ζητήσαμε απώλεια ρεύματος κατά την εκφόρτωση, μια πόρτα που έμεινε ανοιχτή, ένα κενό στις μετρήσεις αισθητήρα και δύο απαιτήσεις για μία απόκλιση. Η σελίδα μπορεί να προτείνει ασυνήθιστες περιπτώσεις από τις αιτίες αποκλίσεων στο μοντέλο γνώσης, ποτέ από πραγματικές εγγραφές.
Κάθε σύνολο πληθών και μορφών αποθηκεύεται ως seed, όπως το cold-chain-busy-01, μαζί με το αποτύπωμά του. Το ίδιο seed δίνει τα ίδια δεδομένα, οπότε κάθε εκτέλεση δοκιμών σε κάθε κλάδο βλέπει την ίδια εβδομάδα. Αυτό έκανε τις 66 δοκιμές μας επαναλήψιμες.
Ένας κλάδος διαρκεί 72 ώρες από προεπιλογή και 14 ημέρες το πολύ. Ζήτησα να κρατήσουμε τον πολυάσχολο κλάδο μας για 30 ημέρες κατά τη διάρκεια μιας μακράς αναθεώρησης, και η σελίδα το απέρριψε με BRANCH_LIFE_EXCEEDED. Η λύση είναι αυτή που προτείνει η πινακίδα: κρατήστε το seed και δημιουργήστε έναν νέο κλάδο από αυτό όταν τον χρειαστείτε. Ένα αντίγραφο με απόκρυψη ακολουθεί τα ίδια όρια, και το αίτημά του περιλαμβάνει αιτιολόγηση και διάρκεια έως 14 ημέρες.
Προεπισκόπηση μιας όψης ως συγκεκριμένο πρόσωπο
Πριν το δει οποιοσδήποτε στο Rotterdam, εξετάσαμε το Cold chain όπως θα το έβλεπαν εκείνοι. Η Προεπισκόπηση φακού ως συγκεκριμένο πρόσωπο αποδίδει το πακέτο ακριβώς όπως το βλέπει ένας επιλεγμένος ρόλος, σε έναν κλάδο δεδομένων, μέσα σε ένα πλαίσιο προεπισκόπησης με διακεκομμένη γραμμή.
Τρεις κανόνες καθιστούν τις προεπισκοπήσεις ασφαλείς για ελεύθερη χρήση. Μια προεπισκόπηση χρησιμοποιεί κλάδο δεδομένων, ποτέ τη ζωντανή μονάδα. Τα δικά σας δικαιώματα δεν διαρρέουν σε αυτήν, οπότε βλέπετε ό,τι βλέπει ο ρόλος και όχι ό,τι μπορείτε να δείτε εσείς. Και λήγει μετά από 30 λεπτά. Η στόχευση μιας προεπισκόπησης σε ζωντανή μονάδα απορρίπτεται με CONNECTION_SCOPE_EXCEEDED· αν χρειάζεστε πραγματικές μορφές δεδομένων, ζητήστε από τον κάτοχο των δεδομένων ένα αντίγραφο με απόκρυψη και κάντε προεπισκόπηση σε αυτό.
Στην προεπισκόπηση εντοπίσαμε ένα πραγματικό σφάλμα. Το διάγραμμα θερμοκρασίας στην προβολή του τεχνικού έδειχνε το σημείο ρύθμισης, ενώ οι αλλαγές του σημείου ρύθμισης προορίζονταν μόνο για τους ελεγκτές. Το διάγραμμα ήταν εντάξει· το κουμπί επεξεργασίας από κάτω του δεν ήταν. Η έκδοση 0.3.2 απέκρυψε τις αλλαγές του σημείου ρύθμισης από τους τεχνικούς, και η προεπισκόπηση είναι το σημείο όπου το εντοπίσαμε.
Αλλαγή του μοντέλου γνώσης μετά τη διάθεσή του
Στην έκδοση 0.4.0 χρειαζόμασταν ένα είδος Inspection για τις επιθεωρήσεις πριν από το ταξίδι, και η σχέση «Excursion caused Claim» διαβαζόταν καλύτερα ως «Excursion led to Claim». Η μετάβαση του μοντέλου από 1.3 σε 1.4 είναι αλλαγή του μοντέλου γνώσης, και η σελίδα Αλλαγές μοντέλου γνώσης εμφανίζει τις διαφορές της, τι θα επηρεάσει και σε ποιο στάδιο βρίσκεται.
Η αλλαγή διακινείται ως αίτημα αλλαγής γράφου. Η δοκιμαστική εκτέλεσή της μετρά τι θα επηρεάσει στο αντίγραφο με απόκρυψη του Rotterdam, ως πλήθη: για εμάς, 1.284 συνδέσεις μετονομάστηκαν και τίποτα δεν αφαιρέθηκε. Δύο αναθεωρητές την εγκρίνουν, και το pipeline την εφαρμόζει στο staging και έπειτα στην πιλοτική μονάδα. Κανείς δεν γράφει χειροκίνητα στον κοινόχρηστο γράφο· μια τέτοια απόπειρα απορρίπτεται και καταγράφεται. Τρεις αποθηκευμένες ερωτήσεις χρησιμοποιούσαν τη λέξη «caused», και η αλλαγή περιλάμβανε αυτόματη αναδιατύπωση για καθεμία, την οποία παρέθετε η σελίδα. Τα φίλτρα των φακών δεν άλλαξαν, επειδή και οι δύο φακοί εξακολουθούσαν μόνο να περιορίζουν.
Προώθηση στην παραγωγή
Κάθε έκδοση ακολουθεί μία διαδρομή: χώρος ανάπτυξης, staging, πιλοτική μονάδα, και στη συνέχεια όλες οι μονάδες. Κάθε βήμα έχει πύλες ελέγχου, και τίποτα δεν παρακάμπτει καμία.
| Προς | Πύλες ελέγχου |
|---|---|
| Staging | Όλες οι δοκιμές επιτυχείς· έλεγχοι ποιότητας· manifest αμετάβλητο ή η διεύρυνση αποδεκτή· υπογεγραμμένο image |
| Πιλοτική μονάδα (Rotterdam) | Δοκιμαστική εκτέλεση αλλαγής μοντέλου στο αντίγραφο με απόκρυψη χωρίς σφάλματα· έλεγχος πολιτικής στους κανόνες φακών και εμβέλειας· δύο αναθεωρητές που δεν είναι ο συντάκτης, ο ένας εκ των οποίων ο κάτοχος των δεδομένων |
| Όλες οι μονάδες | 14 ημέρες στην πιλοτική μονάδα· σφάλματα κάτω από 1 στα 1.000, μετρημένα στην πιλοτική μονάδα· κάθε διαχειριστής μονάδας συναινεί για τη μονάδα του· δύο αναθεωρητές που δεν είναι ο συντάκτης |
Δοκίμασα τη συντόμευση μία φορά, μια Παρασκευή, για μια διόρθωση μίας γραμμής: προώθηση του 0.4.0-dev από τον χώρο ανάπτυξής μου σε όλες τις μονάδες. Απορρίφθηκε με GATE_CANNOT_BE_SKIPPED, και δεν προωθήθηκε τίποτα. Η πινακίδα σάς λέει να προωθήσετε στο επόμενο βήμα, και αυτή είναι η μόνη απάντηση που υπάρχει.
Η ίδια η αναθεώρηση έκδοσης, τα στοιχεία που διαβάζει ένας δεύτερος αναθεωρητής και τα κανάλια που επιλέγουν οι μονάδες, περιγράφονται στο κεφάλαιο 2.28, Έκδοση της επέκτασής σας. Δύο στοιχεία από αυτό ανήκουν εδώ, επειδή διαμορφώνουν τον τρόπο που σχεδιάζετε μια κάθετη λύση. Ο συντάκτης δεν μετρά ποτέ ως αναθεωρητής, οπότε μια ομάδα δύο ατόμων χρειάζεται ένα τρίτο άτομο για κάθε έκδοση. Και κάθε περιβάλλον διατηρεί την προηγούμενη έκδοση για 30 ημέρες, οπότε η επαναφορά είναι μια αναθεωρημένη αλλαγή που το pipeline εκτελεί σε περίπου ένα λεπτό.
Επέκταση ενός πακέτου που υπάρχει ήδη
Δεν ξεκινά κάθε κάθετη λύση από το μηδέν. Ένα πακέτο μπορεί να κληρονομεί από άλλο και να προσθέτει μόνο ό,τι διαφέρει. Το πακέτο Banking and payments, το οποίο χρησιμοποιεί η Larchmont Bank, είναι το σαφέστερο παράδειγμα στον κατάλογο. Το manifest του ξεκινά ως εξής:
{
"id": "fintech",
"name": "Banking and payments",
"version": "0.1",
"inherits": "insurance",
"clusters": [
{
"id": "FL01",
"kind": "lens",
"name": "Lending decisions",
"seats": "Credit analysts, underwriters of loans, credit committee",
"purpose": "Whether to lend, how much, at what price, and writing down why.",
"lexicon": ["fin"],
"menu": [],
"screens": []
}
],
"lexicon": {
"core": [],
"fin": [
["APR", "the yearly cost of borrowing, fees included", "exact"],
["mandate", "the most one person may lend alone", ""]
]
}
}Το inherits ονομάζει το πακέτο στο οποίο βασίζεται. Το Banking and payments διατηρεί τη δομή του πακέτου Insurance, τις κοινόχρηστες ομάδες συνομιλιών του και τους βασικούς όρους του, και προσθέτει τρεις δικούς του φακούς: Lending decisions, Card disputes και My account. Το τρίτο στοιχείο κάθε καταχώρισης του λεξικού είναι exact για έναν όρο που πρέπει να εμφανίζεται όπως είναι γραμμένος, όπως APR (ετήσιο πραγματικό επιτόκιο), αντί να αναδιατυπώνεται.
Ορισμένα πράγματα δεν μπορούν να γίνουν μέσω κληρονομικότητας. Ένα πακέτο δεν αλλάζει ποτέ το κέλυφος, τα στοιχεία διεπαφής ή τους κανόνες γραφής, οπότε ένα θυγατρικό πακέτο δεν μπορεί να αλλάξει την εμφάνιση της κονσόλας. Ένα κανονιστικό πλαίσιο που χρειάζονται πολλά πακέτα είναι ένας κοινόχρηστος φακός αντί για αντίγραφο σε καθένα: το μητρώο εξωτερικευμένης τεχνολογίας εξυπηρετεί τόσο το Insurance όσο και το Banking and payments. Αν το θυγατρικό σας πακέτο χρειάζεται έναν φακό που υπάρχει ήδη ως κοινόχρηστος, χρησιμοποιήστε τον αντί να σχεδιάσετε δικό σας.
Η αδειοδότηση ακολουθεί την κληρονομικότητα. Ένα πακέτο αδειοδοτείται επιπλέον του Enterprise και μπορεί να απαιτεί πρόσθετα, και το έγγραφο άδειας περιλαμβάνει αυτές τις εξαρτήσεις. Το Insurance απαιτεί Decision rooms και σφραγισμένες εγγραφές, οπότε ένας πελάτης που αδειοδοτεί ένα πακέτο που το κληρονομεί χρειάζεται επίσης αυτό το πρόσθετο, και η κονσόλα αρνείται να εκδώσει άδεια που το παραλείπει. Οι οθόνες κινητού ενός πακέτου απαιτούν επίσης το πρόσθετο Mobile apps. Ελέγξτε την αλυσίδα απαιτήσεων πριν υποσχεθείτε σε έναν πελάτη μια ημερομηνία.
Προσθήκη μιας όψης σε ένα πακέτο που έχει διατεθεί
Η μικρότερη εργασία κάθετης λύσης είναι ένας νέος φακός σε ένα πακέτο που δεν γράψατε εσείς. Έξι μήνες μετά την έναρξη του πιλοτικού, η ομάδα ναυτιλιακών απαιτήσεων της Larkfield ήθελε δικό της φακό μέσα στο Cold chain: αποκλίσεις και απαιτήσεις, χωρίς σημεία τροφοδοσίας, χωρίς σημεία ρύθμισης. Δεν αγγίξαμε τον κώδικα του πακέτου. Ένας φακός είναι μια γραμμή στο μητρώο φακών του οργανισμού, που ανήκει στο πακέτο, οπότε τον ξεκινήσαμε από τη χρυσή διαδρομή φακού στη σελίδα Ξεκινήστε κάτι νέο και τον διαμορφώσαμε στο Εργαλείο δημιουργίας φακών με βάση τον φακό Cold-chain controller. Ισχύει ο ίδιος κανόνας με πριν: ο νέος φακός μπορεί να κρύψει ό,τι δείχνει η βάση του και δεν μπορεί ποτέ να δείξει περισσότερα. Ορίζεται μία φορά για τον οργανισμό και εκχωρείται σε έναν ρόλο πλατφόρμας σε κάθε μονάδα. Μια εκχώρηση ανακαλείται, δεν διαγράφεται ποτέ, και η εκ νέου παροχή του φακού δημιουργεί νέα εκχώρηση, ώστε να παραμένει αναγνώσιμο ποιος είχε ποιον φακό και πότε. Το μητρώο μετρά πόσα άτομα είχαν έναν φακό κάθε μήνα, ποτέ ποιοι.
Η σελίδα Φακοί και ποιος τους βλέπει εμφανίζει το αποτέλεσμα ως πίνακα φακών ανά μονάδα και ρόλο, με τις επιλογές Προσθήκη, Αλλαγή και Ανάκληση σε κάθε κελί. Κάντε προεπισκόπηση του νέου φακού ως συγκεκριμένο πρόσωπο πριν τον εκχωρήσετε, ακριβώς όπως παραπάνω.
Τι κόστισε, με ειλικρίνεια
Ένα πακέτο αγγίζει τις εγγραφές ενός πελάτη, οπότε η πλατφόρμα κάνει σκόπιμα ορισμένες διαδικασίες αργές, και θα πρέπει να τις προβλέψετε από την πρώτη ημέρα.
- Ένα αντίγραφο με απόκρυψη απαιτεί κάθε φορά τη συναίνεση του κατόχου των δεδομένων. Το δικό μας χρειάστηκε μία ημέρα για να φτάσει την πρώτη φορά, επειδή η Priya ήθελε πρώτα να διαβάσει το μοντέλο γνώσης. Ξεκινήστε με συνθετικά δεδομένα και ζητήστε το νωρίς.
- Ο συντάκτης δεν μπορεί να εγκρίνει τη δική του έκδοση, και τα αιτήματα λήγουν μετά από 3 ημέρες. Αν οι αναθεωρητές σας είναι απασχολημένοι, η έκδοσή σας περιμένει.
- Μια έκδοση που ζητά περισσότερα από την προηγούμενη, όπως αποστολή email ή μία εξωτερική διεύθυνση, παρακρατείται έως ότου δύο αναθεωρητές αποδεχτούν το διευρυμένο manifest. Το Κεφάλαιο 2.28, Έκδοση της επέκτασής σας, παρουσιάζει τη σελίδα Manifest και δικαιώματα που σας ενημερώνει πριν το ζητήσετε.
- Ένας φακός δεν μπορεί να δείξει ό,τι κρύβει ο φακός βάσης του. Αν ένας ρόλος χρειάζεται πράγματι περισσότερα, αυτό είναι θέμα συζήτησης με τον διαχειριστή του οργανισμού, όχι μια ρύθμιση.
Κανένα από αυτά δεν μας εμπόδισε δεύτερη φορά. Η δεύτερη έκδοση του Cold chain χρειάστηκε μία εβδομάδα από το πρώτο commit έως την πιλοτική μονάδα του Rotterdam, κυρίως για την εκτέλεση των 66 δοκιμών σε τρεις κλάδους και για την ανάγνωση των στοιχείων από δύο άτομα.




