Zaloguj sięUmów spotkanie

Rozdział 2.27

Scenariusze budowy

Zbiór trzynastu przepisów na budowę rozwiązań – od pojedynczej umiejętności po dostawę do środowiska odizolowanego (air-gapped). Każdy przepis określa cel, elementy składowe, kroki i polecenia, bramkę kontrolną potwierdzającą powodzenie oraz różnice w zależności od edycji i formy dostarczenia.

Ta strona została przetłumaczona przez AI z angielskiego oryginału. W razie jakichkolwiek niejasności wersją wiążącą jest strona w języku angielskim. Przeczytaj tę stronę po angielsku

Czas czytania: 25 min

Oto przepisy, po które sięgam, gdy ktoś w Corrán Orbital lub u klienta mówi „chcemy, aby Nexus robił X”. Każdy z nich jest celowo krótki. Uzasadnienie poszczególnych kroków znajduje się w poprzednich rozdziałach: rozdział 2.20, Skills, oraz rozdział 2.21, The Plugin SDK, który omawia zestaw narzędzi programistycznych, a następnie rozdział 2.23, Domain packs, i trzy kolejne rozdziały poświęcone budowaniu. Tutaj znajdą Państwo cel, elementy składowe, których należy użyć, kroki, polecenia, bramkę potwierdzającą, że wszystko zadziałało, oraz uwagi dotyczące edycji i dostarczania.

Najważniejsza jest bramka. Przepis jest ukończony, gdy jego bramka jest zielona. Każda bramka w tym rozdziale to coś, co mogą Państwo uruchomić, lub coś, co platforma uruchamia za Państwa, i każda z nich kończy się kodem niezerowym lub odmową z kodem, gdy nie jest spełniona.

Scenariusz Główny element składowy Bramka, która to potwierdza Edycja
Nowa umiejętność Skills Engine Pakiet SKILL.md skill:validate bez błędów Community i Enterprise
Umiejętność w manifeście z host_callback Manifest wtyczki skills[] create-nexus-plugin validate oraz nexus-gates Community i Enterprise
Rozszerzanie istniejącego pakietu pack.json z inherits Kontrola zasad soczewek na bramce pilotażowej Enterprise i licencja na pakiet
Nowy pakiet od podstaw Ścieżka wzorcowa pakietu domenowego Bramki stagingowa i pilotażowa Enterprise
Konektor danych Umiejętność plugin_queue validate, nexus-gates, odmowa ruchu wychodzącego Community i Enterprise
Narzędzie MCP (Model Context Protocol) Manifest mcpTools[] validate (bez kombinatorów najwyższego poziomu) Community i Enterprise
Sklep white-label Manifest domains i branding Reguła publiczna scope-adherence Enterprise i dodatek Storefront
Pakiet misji Edge Pakiet misji Przypadki testowe na pokładzie, dwa z trzech podpisów Enterprise i dodatek Nexus Edge
Dostarczanie w środowisku odizolowanym Zapieczętowany pakiet nexus-airgap verify Enterprise
Moduł dostępny tylko w Enterprise @adverant/nexus-spi Bramka linii licencyjnej, kompilacje edycji Enterprise
Rozwidlanie lub rozszerzanie otwartego rdzenia Źródła Community Testy, lint i sprawdzanie typów Community
Aplikacja chmurowa w edycji Team Klaster wydawcy Podpisane wydanie, przegląd, przyznanie klientowi Team
Opakowanie istniejącej aplikacji wewnętrznej /plugin-create migrate, validate, nexus-gates Community i Enterprise
Drzewo decyzyjne czytane od góry do dołu. Pierwszy romb pyta „Czy wymaga stale działającego kodu?”. „Nie” prowadzi do rombu „Czy to instrukcje dla asystenta?”, którego „Tak” kończy się na „Umiejętność Skills Engine”, a „Nie” na „Soczewka na istniejącym pakiecie”. „Tak” prowadzi do rombu „Czy to widok platformy dla jednej branży?”, którego „Tak” kończy się na „Pakiet domenowy (z wtyczką)”, a „Nie” prowadzi do ostatniego rombu „Czy musi pozostać zamknięty i licencjonowany?”, kończącego się na „Moduł Enterprise” dla „Tak” i „Wtyczka” dla „Nie”.
Od którego elementu składowego zacząć.

1. Nowa umiejętność Skills Engine

Celem jest wielokrotnego użytku instrukcja, którą mogą uruchamiać asystent, agenci, przepływy pracy i narzędzia programistyczne, na przykład sprawdzanie zgłoszenia celnego pod kątem obowiązujących reguł. Elementami składowymi są pakiet SKILL.md w folderze nazwanym tak jak umiejętność, opcjonalny plik skill.yaml dla wyzwalaczy i tagów oraz opcjonalny folder scripts/ dołączony do pakietu.

  1. Utwórz skills/<slug>/ i napisz SKILL.md z frontmatterem: name (kebab-case, równe nazwie folderu), description (do 500 znaków), allowed-tools oraz opcjonalnie triggers, capabilities i version.
  2. Napisz treść dla modelu: kiedy używać umiejętności, jej kroki, przykłady oraz czego nigdy nie wolno jej robić.
  3. Dodaj przypadki testowe. Uwzględnij jeden z instrukcją podłożoną w danych wejściowych, której umiejętność nie może wykonać.
  4. Zweryfikuj, przejrzyj plan przesyłania, a następnie prześlij.
  5. Opublikuj. Umiejętność dodająca narzędzie zapisu jest wstrzymywana, dopóki dwie wskazane osoby nie zatwierdzą jej kluczami dostępu, a proponujący nie może zatwierdzić własnej zmiany.
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

Bramką jest skill:validate, które musi zgłosić zero błędów, zanim cokolwiek zostanie opublikowane. Błędy blokujące to brak nazwy lub opisu oraz zduplikowany slug lub typ zadania. Przesłanie treści, która jest już opublikowana, zwraca istniejącą wersję (CONTENT_HASH_ALREADY_PUBLISHED), więc przesyłanie można bezpiecznie powtarzać.

Community otrzymuje cały kreator, bibliotekę, wersje, przywracanie poprzednich wersji, import i testy. W Enterprise publikacja przechodzi dodatkowo przez tryb cienia i canary: zatwierdzona wersja działa w trybie cienia, następnie w jednej jednostce za wskazanymi bramkami, a potem dla wszystkich, i zatrzymuje się sama, jeśli bramka nie zostanie spełniona. U klienta w środowisku odizolowanym umiejętności są przenoszone wstępnie podpisane wewnątrz zapieczętowanego pakietu (scenariusz 9).

2. Umiejętność manifestu z host_callback

Celem są deterministyczne obliczenia we własnej wtyczce, które platforma może zlecać, na przykład otwarcie rekordu przekroczenia na podstawie odczytu. Użyją Państwo wiersza w skills[] manifestu z poziomem host_callback oraz trasy /internal w swoim backendzie, chronionej strażnikiem usług SDK.

  1. Zadeklaruj umiejętność: id w lower_snake, tier: "host_callback", classification na poziomie zaufania wtyczki lub poniżej, inputSchema, outputSchema oraz timeoutMs od 1 sekundy do 6 godzin.
  2. Wypełnij hostCallback: nazwę własnej usługi (Service), jej port, ścieżkę względną, taką jak /internal/skills/excursion_open, oba limity bajtów (maxRequestBytes i maxResponseBytes) oraz tenantHeader: "X-Organization-ID".
  3. Zadeklaruj trasę w api.endpoints[] z auth: "service-key" lub auth: "internal" i chroń ją za pomocą requireService lub serviceMiddleware, nigdy strażnikiem zakresu użytkownika.
  4. Zweryfikuj, uruchom bramki i pozwól, aby proces wdrażania zsynchronizował umiejętności z rejestrem za pomocą compileRegistry. Nigdy nie piszesz ręcznie SQL do rejestru.
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 stosuje własne reguły synchronizacji rejestru, zanim cokolwiek zostanie zsynchronizowane, a każda odmowa zawiera kod odbiorcy. Ścieżka ze schematem, // lub ukośnikiem odwrotnym jest odrzucana jako pochodząca z innego źródła. Brak limitu bajtów to ENDPOINT_BYTE_CAP_REQUIRED, pole z innego poziomu to FIELD_NOT_FOR_TIER, a limit czasu spoza zakresu to TIMEOUT_OUT_OF_BOUNDS. Następnie nexus-gates sprawdza, czy trasa /internal ma strażnika usług i jest zadeklarowana jako internal lub service-key. Ta para bramek stanowi dowód.

Synchronizacja jest deklaratywna. Za każdym razem przesyłaj pełny zestaw umiejętności, ponieważ pominięta umiejętność zostaje wyłączona, i przerywaj krok wdrożenia przy każdym statusie innym niż 200. W Enterprise synchronizacja wtyczki jest sprawdzana w całości: jeśli jedna umiejętność narusza regułę, żadna część tej synchronizacji nie zostaje przyjęta (PLUGIN_SYNC_ALL_OR_NOTHING), a poprzednia wersja nadal działa. Wtyczka o zaufaniu community nie może używać poziomów, które docierają do modelu, tool_using i llm_only; wymagają one zaufania core lub verified.

Wtyczki i synchronizacja MCP
Wtyczki i synchronizacja MCP
Wtyczki dostarczające umiejętności i to, pod kątem czego sprawdzono każdą synchronizację. Proszę zwrócić uwagę na wtyczkę, której synchronizacja została odrzucona w całości, ponieważ jedna z jej pięciu umiejętności używała poziomu, który może hostować tylko platforma, podczas gdy jej poprzednia wersja nadal działała.

3. Rozszerzanie istniejącego pakietu

Celem jest nowa branża lub podbranża, która wykorzystuje większość istniejącego pakietu, na przykład kredyty i spory kartowe oparte na strukturze pakietu Insurance. Elementem składowym jest pack.json, który wskazuje swój pakiet nadrzędny w inherits i dodaje tylko własne klastry soczewek i słownictwo.

  1. Rozpocznij pakiet ścieżką wzorcową pakietu domenowego, a następnie ustaw inherits na identyfikator pakietu nadrzędnego.
  2. Dodaj własne klastry lens, każdy z jego stanowiskami, celem i odwołaniem do leksykonu.
  3. Dodaj swoje słowa do leksykonu, każde z prostym objaśnieniem. Oznacz termin jako exact tam, gdzie musi być wyświetlany w niezmienionej postaci.
  4. Używaj ponownie wspólnych soczewek zamiast tworzyć własne: reżim potrzebny kilku pakietom, taki jak rejestr outsourcowanych technologii, to jedna wspólna soczewka.
  5. Sprawdź łańcuch licencji. Pakiet dziedziczy wymagania dotyczące dodatków po pakiecie nadrzędnym.
  6. Wyświetl podgląd każdej soczewki z perspektywy danej osoby w gałęzi syntetycznej.
{ "id": "fintech", "name": "Banking and payments", "version": "0.1", "inherits": "insurance" }

Dowodem jest kontrola zasad na bramce pilotażowej, która potwierdza, że każda soczewka jedynie zawęża swoją bazę i domyślnie ukrywa pola osobowe. Soczewka, która próbuje pokazać to, co ukrywa jej baza, jest odrzucana z kodem LENS_CANNOT_WIDEN. Po stronie licencji konsola odmawia wydania licencji na Państwa pakiet bez dodatków wymaganych przez pakiet nadrzędny; pakiet Insurance wymaga pokojów decyzyjnych i zapieczętowanych rekordów.

Pakiety domenowe są dostępne w Enterprise i licencjonowane osobno dla każdego pakietu. Ekrany telefoniczne pakietu wymagają także dodatku Mobile apps. Pakiet podrzędny nie może zmieniać powłoki, komponentów ani zasad redakcyjnych.

4. Nowy pakiet od podstaw

Celem jest widok Nexus dla jednej branży: jej model wiedzy, soczewki dla każdej roli, dowody wymagane przez jej przepisy oraz wtyczka utrzymująca aktualność jej danych. Rozdział 2.24, Building a custom vertical end to end, omawia tę budowę w całości; tutaj przedstawiamy wersję skróconą.

  1. Uruchom ścieżkę wzorcową pakietu domenowego i opisz pakiet: cel, jednostki, model bazowy i przepisy, które odwzorowuje.
  2. Zbuduj model wiedzy na modelu bazowym i klasyfikuj każdą właściwość w momencie jej dodawania.
  3. Przeczytaj plan, potwierdź jego odcisk kluczem dostępu i utwórz.
  4. Kształtuj soczewki w Lens builder, przy czym każda zawęża soczewkę bazową.
  5. Napisz wtyczkę oraz wszelkie umiejętności Skills Engine potrzebne pakietowi.
  6. Wygeneruj syntetyczne dane z ziarnem, zawierające nietypowe przypadki, na których Państwu zależy, i wyświetl podgląd każdej soczewki jako konkretna osoba.
  7. Promuj z przestrzeni deweloperskiej do stagingu, do jednostki pilotażowej, a następnie do wszystkich jednostek.

Dowodem są bramki promocji: wszystkie testy zaliczone na gałęziach syntetycznych przed stagingiem, następnie dwóch recenzentów niebędących autorem, a potem 14 dni pilotażu z błędami poniżej 1 na 1000. Żadnego kroku nie można pominąć (GATE_CANNOT_BE_SKIPPED). Pakiety są dostępne w Enterprise. W Community ścieżka wzorcowa pakietu domenowego nie jest oferowana.

5. Konektor danych

Celem jest przepływ danych z zewnętrznego systemu do własnych tabel wtyczki zgodnie z harmonogramem, na przykład zdarzeń bramowych z systemu operacyjnego terminalu. Elementami składowymi są umiejętność plugin_queue, worker pobierający z kolejki, migracja tabeli docelowej oraz adres wychodzący zadeklarowany w manifeście.

  1. Zadeklaruj umiejętność plugin_queue z queueName zapisanym jako <plugin name>.<name>. Dwukropek jest niedozwolony, a nazwa musi znajdować się w manifeście, ponieważ orkiestrator dodaje zadania bezpośrednio do tej kolejki.
  2. Napisz worker, który pobiera z kolejki i wywołuje zewnętrzny system.
  3. Zadeklaruj adres zewnętrznego systemu jako adres wychodzący. Wszystko, czego nie wymieniono, jest blokowane.
  4. Przechowuj otrzymane dane we własnym schemacie, z organization_id, owner_user_id i business_unit_id w każdym wierszu.
  5. Odczytuj poświadczenia zewnętrznego systemu po nazwie ze środowiska i wymień zmienną w scripts/ci/required-env.
  6. Zlecaj pobieranie za pośrednictwem UNO, silnika przepływów pracy, nigdy za pomocą timera wywołującego silniki bezpośrednio.
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 sprawdza nazwę kolejki i limit czasu pod kątem reguł synchronizacji rejestru. Trzy bramki dowodzą braku poświadczeń modelu, braku bezpośrednich obliczeń oraz prawidłowo ograniczonej tabeli. Przed wypchnięciem uruchom pełne nexus-gates, ponieważ --only zawęża przebieg i informuje o tym w podsumowaniu. W czasie działania wywołanie adresu, którego manifest nie zadeklarował, jest zatrzymywane na brzegu z kodem EGRESS_NOT_DECLARED.

Własne konektory platformy do dysków, wiki, magazynów poczty i systemów starszego typu, z przechwytywaniem zmian i pochodzeniem danych, są dostępne w dodatku Data connectors. Konektor zbudowany samodzielnie jest wtyczką i działa w każdej edycji. Dodanie adresu wychodzącego w późniejszym wydaniu stanowi poszerzenie i jest wstrzymywane, dopóki dwóch recenzentów go nie zaakceptuje.

6. Narzędzie MCP

Celem jest narzędzie, które mogą wywoływać Claude Code, agenci i inni klienci MCP (Model Context Protocol), na przykład wyszukiwanie historii inspekcji statku. Elementem składowym jest wpis w mcpTools[] manifestu, z name, description i inputSchema.

  1. Nazwij narzędzie i opisz je prostym językiem. Opis jest tym, co odczytuje model, aby zdecydować, czy je wywołać.
  2. Napisz inputSchema jako jeden schemat obiektu. Nie umieszczaj oneOf, allOf ani anyOf na jego najwyższym poziomie.
  3. Utrzymuj trasę obsługującą narzędzie za strażnikiem zakresu, jak każdą inną trasę /api, aby dzierżawa wynikała z tokenu wywołującego.
  4. Zweryfikuj manifest.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json

Dowodem jest validate: kombinator najwyższego poziomu jest odrzucany na etapie tworzenia, ponieważ w czasie działania spowodowałby awarię narzędzia dla każdego subagenta MCP, który je importuje, a narzędzie istniałoby, lecz nikt nie mógłby go wywołać.

W Enterprise każde narzędzie, które może wywołać IDE (zintegrowane środowisko programistyczne), jest wymienione w katalogu narzędzi Workbench wraz z jego poziomem, informacją, czy wprowadza zmiany, przypiętym odciskiem oraz rolami, które mogą z niego korzystać. Jeśli opis narzędzia zmieni się w nowym wydaniu, katalog wstrzymuje narzędzie do czasu przeglądu zmiany przez człowieka. Jest to zamierzone: zmieniony opis to sposób, w jaki narzędzie może zacząć prosić model o coś, czego nie powinno. Wywołanie czegokolwiek spoza przepustki wywołującego jest odrzucane z kodem CONNECTION_SCOPE_EXCEEDED.

7. Witryna white-label

Celem jest aplikacja używana przez klientów Państwa klienta, w domenie klienta i w jego marce, bez śladu Adverant. Elementami składowymi są bloki domains i branding manifestu, pomocnicze funkcje logowania SDK oraz dodatek Storefront / white-label klienta.

  1. Umieść domenę klienta w domains[] jako primary, wraz z ewentualnymi aliases.
  2. Wypełnij branding: appName, tagline, primaryColor, accentColor, passkeyRpId równe domenie oraz oauthClientRef.
  3. Loguj użytkowników za pomocą pomocniczych funkcji logowania SDK i zadeklaruj dokładnie ich dwie publiczne trasy, z auth: "public" i allowAnonymous: true.
  4. Kieruj każde wywołanie frontendu przez proxy z listą dozwolonych w warstwie backend for frontend. Nigdy nie umieszczaj adresu usługi w kliencie.
  5. Płatności pozostaw administratorowi klienta, który podłącza bramki płatności i konfiguruje markowy proces realizacji zamówienia.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --only scope-adherence --only api-contract

Dowodem jest scope-adherence. Dopuszcza ono niechronioną trasę /api tylko wtedy, gdy manifest deklaruje tę dokładną metodę i ścieżkę jako publiczne, a ścieżka jest jedną z tras logowania; każda inna deklaracja publiczna kończy się niepowodzeniem i podaje dwie dozwolone ścieżki. api-contract następnie porównuje zadeklarowane trasy z rzeczywistymi w obu kierunkach. definePlugin odrzuca także frontend.basePath, które nie jest względną ścieżką z tego samego źródła.

White-label to dodatek Storefront / white-label w edycji Enterprise, który obejmuje również licencję na płatności. Dane kart nigdy nie trafiają do Nexus. Marka należy do administratora klienta, a platforma ustala ją na podstawie organizacji, a nie Państwa kodu.

8. Pakiet misji Edge

Celem jest nowa lub zaktualizowana misja dla satelity lub drona z Nexus Edge, na przykład dodanie adaptera wykrywania statków do misji obserwacji morskiej. Elementem składowym jest pakiet misji, budowany i podpisywany na ziemi.

  1. Należy zacząć od bieżącego pakietu na stronie Budowanie pakietu misji, która tworzy szkic nowej wersji na podstawie starej i oznacza każdą zmianę.
  2. Należy zmieniać tylko to, czego wymaga misja. W miarę możliwości duże elementy, model językowy i ontologię, należy pozostawić bez zmian.
  3. Należy sprawdzić tabelę rozmieszczenia na każdym etapie degradacji, aby każda płytka nadal mieściła to, co uruchamia.
  4. Należy uruchomić pokładowe przypadki testowe pakietu na stanowisku testowym z tymi samymi płytkami.
  5. Należy przesłać pakiet do podpisu: wymagane są dwa z trzech podpisów.
  6. Należy wydać pakiet na jedną platformę. Trafia on do nieaktywnego slotu i jest włączany dopiero po pomyślnym przejściu przypadków testowych na pokładzie.
  7. Wdrożenie na kolejną platformę należy przeprowadzić po tygodniu bez problemów.
Pakiety misji
Pakiety misji
Biblioteka pakietów misji, z zawartością każdego pakietu i platformami, na których działa. Proszę zwrócić uwagę na starszą wersję przechowywaną na pokładzie na wypadek powrotu oraz na liczbę przypadków testowych, które każdy pakiet musi przejść na swoim sprzęcie.

W tym przepisie nie ma poleceń; wszystko wykonuje się na stronach Nexus Edge w konsoli. Dowodem są pokładowe przypadki testowe, które muszą zakończyć się powodzeniem przed włączeniem pakietu, oraz dwa podpisy. Jeśli test na pokładzie się nie powiedzie, platforma pozostaje przy poprzednim pakiecie, a informacja o błędzie zostaje przesłana podczas następnego przelotu. Instalacja pakietu na sprzęcie, dla którego nie został sprawdzony, jest odrzucana z kodem PACK_NOT_CHECKED_FOR_HARDWARE.

Nexus Edge jest dodatkiem licencjonowanym na platformę lub na flotę. Pakiety pozostają ważne, gdy platforma jest poza zasięgiem łączności. Łącze w górę jest wąskie, dlatego rozmiary należy planować z jego uwzględnieniem: nasze wydanie 1.5 miało 412 MB, wobec 9.8 GB pakietu z nowym modelem językowym.

9. Dostawa do środowiska odizolowanego (air-gapped) klienta

Celem jest Państwa wtyczka lub pakiet zainstalowany w lokalizacji klienta bez dostępu do sieci. Elementami składowymi są zapieczętowany pakiet z @adverant/nexus-sovereign, Państwa klucz do podpisywania wydań oraz własne kanały wydań klienta.

  1. Należy zbudować wtyczkę i jej obrazy dokładnie tak jak dla klienta z dostępem do sieci, przy czym wszystkie bramki muszą być zielone.
  2. Należy utworzyć zapieczętowany pakiet z profilem airgap, zawierający obrazy, migracje, wstępnie podpisane umiejętności oraz SBOM (wykaz składników oprogramowania) z licencjami.
  3. Należy go podpisać kluczem wydań Ed25519.
  4. Należy go samodzielnie zweryfikować na czystej maszynie.
  5. Pakiet należy przesłać na nośniku, a klucz publiczny i skrót SHA-256 pakietu inną drogą.
  6. Operator klienta weryfikuje pakiet Państwa kluczem, a następnie wprowadza wydanie przez własne kanały wydań.
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 buduje pakiet na podstawie Państwa konfiguracji pakietu. Dowodem jest nexus-airgap verify po stronie klienta. Polecenie ponownie oblicza skrót każdego pliku, odrzuca każdy plik niewymieniony w manifeście, wymaga zaufanego sygnatariusza i odrzuca pakiet, którego lista dozwolonych adresów sieciowych nie jest pusta. Zmieniony plik powoduje błąd BUNDLE_INTEGRITY_VIOLATION. Nikt nie powinien nigdy wyłączać ścisłej weryfikacji, aby go obejść.

Instalacje odizolowane od sieci są dostępne w edycji Enterprise. Żaden element pakietu nie może niczego pobierać podczas instalacji, a model potrzebny wtyczce pochodzi z własnego serwera modeli klienta za pośrednictwem AI (sztucznej inteligencji) Provider Router.

10. Moduł wyłącznie dla edycji Enterprise

Celem jest zamknięta, licencjonowana funkcja dołączana do otwartego rdzenia, na przykład dziennik audytu z długim okresem przechowywania sprzedawany wyłącznie klientom Enterprise. Elementem składowym jest pakiet interfejsów @adverant/nexus-spi i nic poza nim z Community.

  1. Należy przechowywać w repozytorium kopię zbudowanego pakietu interfejsów przypiętą co do bajtu jako lokalny pakiet file:, wraz z przypięciem SHA256SUMS.
  2. Należy napisać na jego podstawie RouteModule (lub ScreenModule dla ekranów konsoli), wraz z obsługiwaną grupą funkcji.
  3. Każdą trasę należy uruchamiać za ctx.requireScope i przed udzieleniem odpowiedzi sprawdzać uprawnienie modułu.
  4. Gdy organizacja nie ma uprawnień, należy odmówić z kodem LICENCE_LOCKED i wyświetlić zapowiedź funkcji, nigdy jej danych.
  5. Należy utrzymać repozytorium w granicach licencji, a następnie zbudować złożone drzewo każdej edycji.
npm ci
npm test
npm run build

Dowodem jest reguła granicy licencji: brak importów z zakresu Community poza pakietem interfejsów, brak importów względnych spoza repozytorium oraz brak zależności file:, link: lub workspace: poza nim. Następnie trzy powyższe polecenia muszą zakończyć się powodzeniem w złożonym drzewie każdej edycji, a nie tylko w Państwa drzewie roboczym. Rozdział 2.25, Budowanie dla każdej edycji, zawiera szkielet modułu.

Moduł ładuje się do usługi Community przy uruchomieniu w instalacjach, których licencja obejmuje jego grupę funkcji. Bez tego uprawnienia odmawia działania, dzięki czemu ta sama kompilacja trafia wszędzie i nic nie robi tam, gdzie nie jest licencjonowana.

11. Rozwidlenie (fork) lub rozszerzanie otwartego rdzenia

Celem jest zmiana w samym Community, utrzymywana w Państwa forku lub przekazana do projektu. Elementem składowym jest kod źródłowy Community na licencji Apache License, Version 2.0.

  1. Należy utworzyć fork repozytorium i gałąź od main.
  2. Jeśli to, czego Państwo potrzebują, może być wtyczką lub umiejętnością, należy wybrać to rozwiązanie. Zmianę w rdzeniu muszą Państwo utrzymywać przy każdym wydaniu.
  3. Należy wprowadzić zmianę wraz z testami, które bez niej kończą się niepowodzeniem.
  4. Przed zaproponowaniem czegokolwiek należy uruchomić testy, które uruchamia projekt.
  5. Należy zachować plik NOTICE i nie używać nazw ani znaków towarowych Adverant poza wskazaniem pochodzenia pracy.
git checkout -b feature/your-change
npm test
npm run lint
npm run typecheck

Dowodem jest pomyślne przejście tych trzech testów oraz potwierdzenie, że każdy nowy test kończył się niepowodzeniem przed Państwa zmianą. W forku należy zachować jedną właściwość otwartego rdzenia: Community uruchamia agenta od początku do końca na lokalnym modelu, bez klucza i bez sieci. Zmiana, która to narusza, niszczy to, co sprawia, że Community można używać samodzielnie.

Dotyczy to wyłącznie Community. Wszystko, co musi pozostać zamknięte, należy zamiast tego umieścić w module Enterprise (scenariusz 10), aby granica licencji pozostała w miejscu, które każdy może wskazać.

12. Aplikacja chmurowa w edycji Team

Celem jest aplikacja, którą mogą zainstalować klienci Team. Team działa wyłącznie w chmurze Adverant, więc aplikacja dociera do nich tylko przez katalog. Elementami składowymi są wtyczka i klaster wydawcy: Państwa własny klaster wirtualny w chmurze Adverant z przykładowymi danymi.

  1. Należy budować i testować w klastrze wydawcy, wyłącznie na przykładowych danych.
  2. W manifeście należy zadeklarować wszystko, czego aplikacja potrzebuje, i nic ponadto.
  3. Należy wydać aplikację podpisaną, do przeglądu przez Adverant i umieszczenia w katalogu.
  4. Każdy klient ją instaluje, przyznając każdy zadeklarowany zakres jednostka po jednostce.

Dowód składa się z dwóch części. Podpisane, sprawdzone wydanie zapewnia miejsce w katalogu. Następnie uprawnienie przyznane przez klienta decyduje, do czego aplikacja ma dostęp w jego lokalizacji, a każde niezadeklarowane wywołanie jest odrzucane z kodem CONNECTION_SCOPE_EXCEEDED. Brakujący zakres można dodać tylko w nowym wydaniu, które klient sprawdzi.

Zainstaluj wtyczkę zewnętrzną
Zainstaluj wtyczkę zewnętrzną
Administrator instaluje wtyczkę innego dostawcy, przyznając każdy zadeklarowany zakres dla poszczególnych jednostek i pomijając jeden. Panel pokazuje odrzucone wywołanie, którego wtyczka nigdy nie zadeklarowała.

Klaster wydawcy nie ma połączenia z żadnym klientem, a żądanie danych klienta w nim jest odrzucane z kodem TENANT_BOUNDARY. Klienci mogą udostępniać Państwu wyniki testów, ale nigdy swoich danych. Team obejmuje funkcję operacji na przepływach pracy, więc jeśli aplikacja zawiera przepływy pracy, klienci Team mogą samodzielnie przenosić je między środowiskami.

13. Opakowanie istniejącej aplikacji wewnętrznej jako wtyczki

Celem jest aplikacja, którą Państwa firma już eksploatuje, przeniesiona do Nexus, aby przejęła logowanie, izolację i nadzór. Elementami składowymi są umiejętność /plugin-create do pierwszego szkicu oraz narzędzia manifestu i bramki SDK do jego dokończenia.

  1. Należy uruchomić /plugin-create z repozytorium. Analizuje ono kod i wybiera strategię opakowania, a następnie generuje backend, migracje, interfejs użytkownika (UI), manifest i testy.
  2. Należy podnieść manifest do kontraktu v2. migrate dodaje trzy zdania reguł i przenosi domain do domains[], a przy tym odmawia wymyślenia punktu wejścia.
  3. Każdą wartość dzierżawcy, którą opakowanie odczytuje z nagłówków, należy zastąpić strażnikiem zakresu z SDK.
  4. Do każdej tabeli należy dodać organization_id, owner_user_id i business_unit_id, z kluczami głównymi zaczynającymi się od dzierżawcy.
  5. Należy zadeklarować każdą trasę z jej uprawnieniem i zainstalować rejestr odmów.
  6. Należy uruchamiać bramki, aż będą zielone.
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

Dowodem jest zakończenie nexus-gates kodem 0, przy pomyślnym przejściu scope-adherence, one-fence, migrations-are-scoped, crud-adherence i api-contract. Należy się spodziewać, że pierwsze uruchomienie nie przejdzie większości z nich; u nas każda trasa została zgłoszona jako pozbawiona zakresu, ponieważ szkic ufał nagłówkom, które może ustawić przeglądarka. Bramki celowo nie mają przełącznika naprawy.

Opakowane aplikacje działają w każdej edycji. Wdrożenie odbywa się wyłącznie przez kanały wydań instalacji, dlatego należy zignorować wszelkie pliki wdrożeniowe utworzone przez szkic. Najwięcej czasu zajmuje praca nad izolacją: w przypadku rzeczywistej aplikacji należy planować dni, a nie godziny.