Wersja 1.0.0-alpha.1najnowsza
Rozdział 2.18
Model rozszerzeń
Sześć sposobów na rozszerzenie systemu Nexus – od pojedynczego ustawienia po pakiet domenowy – ograniczenia każdego z nich oraz sposób, w jaki poziomy zaufania i izolacji decydują o miejscu wykonania kodu. Przeczytaj ten rozdział przed otwarciem pakietu SDK (software development kit).
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

Pierwszą rzeczą, którą zbudowałem w systemie Nexus w firmie Corrán Orbital, nie była wtyczka. Nasz zespół ds. dynamiki lotu chciał, aby asystent za każdym razem w tym samym formacie odpowiadał na pytanie „które przeloty nad stacjami naziemnymi stracimy, jeśli antena na Svalbardzie zostanie wyłączona w celu konserwacji?” – najpierw wyświetlając tabelę przelotów, a pod spodem koszt w minutach łączności. Spędziłem pół dnia na czytaniu dokumentacji pakietu SDK (Software Development Kit), zanim kolega zwrócił mi uwagę, że tak naprawdę potrzebuję umiejętności: folderu z plikiem SKILL.md, przesłanego do Skills Engine i opublikowanego po przejściu testów oraz zatwierdzeniu przez recenzenta. Zajęło to czterdzieści minut.
Dwie wtyczki i jeden pakiet domenowy później, to wciąż pierwsza rada, jakiej udzielam. Nexus oferuje sześć sposobów na rozbudowę, które układają się w drabinę nakładu pracy. Niższe, mniej kosztowne szczeble pozwalają na więcej, niż można się spodziewać, a te wyższe wiążą się ze zobowiązaniami, które łatwo zbagatelizować. Ten rozdział przedstawia całą drabinę. Proszę wybrać najniższy szczebel, który spełni Państwa zadanie. Kolejne rozdziały omawiają szczegółowo każdy z nich: rozdział 2.19, Zasady dziedziczone przez każde rozszerzenie; rozdział 2.20, Umiejętności; rozdział 2.21, Pakiet SDK wtyczek; rozdział 2.22, Środowisko uruchomieniowe wtyczek; oraz rozdział 2.23, Pakiety domenowe.
Sześć elementów składowych
Oto one w kolejności, w jakiej należy je rozważać.
- Ustawienia i polityki. Są to wartości, które administrator ustala w konsoli dla organizacji, jednostki lub jednej osoby, w ramach tego, na co pozwala licencja. Nie trzeba pisać żadnego kodu.
- Umiejętności Skills Engine. Pakiet
SKILL.mdzawierający instrukcje i narzędzia, które dana umiejętność może wywoływać, wraz z opcjonalnymi plikami i skryptami obok niego. Asystent, agenci, przepływy pracy oraz przyciski AI (sztucznej inteligencji) na ekranach uruchamiają te same umiejętności – podobnie jak Państwa zintegrowane środowisko programistyczne (IDE). - Wtyczki. Państwa własny kod, zadeklarowany w manifeście i zbudowany za pomocą narzędzi pakietu SDK. Wtyczka występuje na jednym z trzech poziomów:
skills-only,ui-onlylubfull-service. - Pakiety domenowe. Soczewki i szablony dla danej branży, jej umiejętności i model wiedzy, konektory oraz ekrany na telefony, licencjonowane jako całość. Adverant dostarcza ich dziesięć; mogą Państwo również zbudować własne.
- Soczewki. To, co dana rola widzi wewnątrz pakietu lub platformy. Soczewka zawęża soczewkę bazową i nigdy jej nie rozszerza.
- Połączenia i konektory MCP. Narzędzia protokołu Model Context Protocol (MCP) publikowane przez wtyczkę lub te, przez które łączy się narzędzie programistyczne AI, a także konektory tylko do odczytu, które pobierają rekordy z już używanych przez Państwa systemów.
Dwa pojęcia bywają nadużywane, dlatego wyjaśnię je teraz. Umiejętność Skills Engine to pakiet SKILL.md w bibliotece. Umiejętność manifestu to typowany wiersz w tablicy skills[] wtyczki, kompilowany do rejestru umiejętności platformy i uruchamiany przez UNO, silnik przepływu pracy. Na ekranie obie nazywane są umiejętnościami. Są jednak pisane i zarządzane w inny sposób, a niniejsza dokumentacja zawsze precyzuje, o którą z nich chodzi.
Co potrafi każdy z nich, a czego nie
Tabela stanowi wersję skróconą. Celowo umieściłem w niej kolumnę „Czego nie potrafi”: każde ograniczenie wynika z założeń projektowych i każde z nich uchroniło mnie przed problemami.
| Element konstrukcyjny | Co potrafi | Czego nie potrafi | Kto go tworzy |
|---|---|---|---|
| Ustawienie lub polityka | Zmienić sposób działania funkcji na dowolnym poziomie – od organizacji po pojedynczą osobę; zablokować wartość; oddelegować ją niżej; wymagać zatwierdzenia zmiany przez drugą osobę | Dodać ekranu ani ścieżki (route), zapisać nowej tabeli ani rozpocząć nowego rodzaju pracy | Administrator, w konsoli |
| Umiejętność Skills Engine | Zapewnić asystentowi, agentom, przepływom pracy i przyciskom AI powtarzalny sposób wykonywania jednego zadania, z własnymi instrukcjami i przypadkami testowymi | Przechowywać poświadczeń; wywołać narzędzia spoza listy dozwolonych dla osoby uruchamiającej (SKILL_CANNOT_WIDEN_TOOLS); wejść w życie bez testów i zatwierdzenia |
Każdy z odpowiednim uprawnieniem, w kreatorze lub ze swojego IDE |
Wtyczka, skills-only |
Publikować umiejętności manifestu działające na platformie: wywołania zwrotne hosta, zadania w kolejce, mapowania na liście oraz, przy poziomie zaufania core lub verified, umiejętności oparte na modelach |
Serwować własnych stron | Programista, za pomocą pakietu SDK |
Wtyczka, ui-only |
Dodać interfejs frontendowy wewnątrz powłoki | Przechowywać własnych danych ani uruchamiać obliczeń | Programista, za pomocą pakietu SDK |
Wtyczka, full-service |
Własny backend i frontend, schemat Postgres, tabelę ścieżek (route table) z uprawnieniami oraz umiejętności i narzędzia MCP | Wywołać dostawcy modelu; przechowywać klucza modelu; odczytać wierszy innej organizacji (z wyjątkiem zarejestrowanego nadania uprawnień); uruchamiać obliczeń poza dyspozytorem UNO | Programista, za pomocą pakietu SDK |
| Pakiet domenowy | Dostarczyć branżowe soczewki i szablony, umiejętności i przepływy pracy, model wiedzy, mapę dowodów oraz ekrany na telefony do jednostek wybranych przez administratora | Zmienić powłoki lub jej komponentów ani zasad pisania; działać bez odpowiedniego wpisu w licencji organizacji | Adverant lub Państwa właśni programiści w edycji Enterprise |
| Soczewka | Wybrać karty i pola widoczne dla jednej roli w ramach pakietu lub platformy oraz oferowane przez nią akcje | Pokazać czegokolwiek, co ukrywa jej soczewka bazowa (LENS_CANNOT_WIDEN); zmienić tego, co dana rola może robić |
Tworzy ją autor pakietu; administrator przyznaje ją dla poszczególnych jednostek |
| Narzędzia i konektory MCP | Udostępniać narzędzia wtyczki agentom i narzędziom programistycznym; odczytywać rekordy z systemu obsługi polis lub archiwum telemetrii do modelu wiedzy | Zapisywać danych z powrotem do systemu źródłowego przez konektor; działać poza uprawnieniami zalogowanej osoby | Programista deklaruje narzędzia MCP; administrator konfiguruje konektory |
Kilka z tych komórek zasługuje na dodatkowe zdanie wyjaśnienia.
Ustawienia to framework, z którego korzysta każda wtyczka. Wtyczka deklarująca blok settings w swoim manifeście otrzymuje poziomy (platforma, organizacja, pakiet, jednostka, grupa, repozytorium, osoba), blokady i delegowanie, dziennik zmian oraz zatwierdzanie przez drugą osobę – wszystko to bez konieczności pisania tabeli ustawień. Dlatego najtańszy szczebel często wystarcza: jeśli pożądane zachowanie już istnieje i wymaga jedynie innej wartości dla jednostki Rotterdam, jest to ustawienie.
Umiejętność Skills Engine działa w imieniu danej osoby. Nigdy nie przechowuje klucza, ma dostęp wyłącznie do narzędzi z listy dozwolonych osoby, która ją uruchamia, i może odczytać tylko to, co ta osoba ma prawo otworzyć. Umiejętność dodająca narzędzie dokonujące zapisu jest wstrzymywana do czasu zatwierdzenia przez dwie osoby, a następnie wdrażana w trybie cienia (shadow), potem kanarkowym (canary), a na końcu dla wszystkich.
Wtyczka skills-only to środkowy szczebel. Jest potrzebna, gdy zadanie wymaga Państwa własnego kodu: deterministycznych obliczeń, procesu obsługującego kolejkę (queue worker) czy równoległego przetwarzania listy (fan-out). Platforma wywołuje Państwa kod; Państwa kod nigdy nie wywołuje modelu.
Wtyczka full-service to mały produkt. Posiada własny schemat Postgres, tabelę ścieżek z rejestrem uprawnień, frontend, zestaw ról bazy danych oraz wszystkie zobowiązania dotyczące izolacji opisane w rozdziale 2.19, Zasady dziedziczone przez każde rozszerzenie. Jest właściwym rozwiązaniem częściej, niż ludzie się obawiają, i niewłaściwym częściej, niż mają nadzieję.
Którego elementu potrzebuję?
Proszę zacząć od góry tej tabeli i zatrzymać się na pierwszym pasującym wierszu.
| Chcą Państwo… | Należy użyć | Dlaczego nie czegoś lżejszego |
|---|---|---|
| Zmienić wartość, limit lub to, kto może coś zrobić | Ustawienia lub polityki | Nic lżejszego nie istnieje |
| Sprawić, by asystent wykonywał jedno zadanie za każdym razem w ten sam sposób | Umiejętności Skills Engine | Ustawienie nie może zawierać instrukcji |
| Umieścić na ekranie „przycisk AI” uruchamiający to zadanie | Umiejętności Skills Engine powiązanej z przyciskiem | Przycisk uruchamia tylko umiejętności; nie trzeba niczego budować |
| Pozwolić narzędziu programistycznemu AI na dostęp do systemu Nexus | Połączenia MCP przez Workbench | Nie trzeba nic pisać; osoba loguje się przez przeglądarkę |
| Odczytać rekordy z istniejącego systemu do modelu wiedzy | Konektora tylko do odczytu | Konektor niczego nie zapisuje z powrotem, więc nie niesie ryzyka związanego z zapisem |
| Uruchamiać własny kod deterministyczny zgodnie z harmonogramem platformy | Wtyczki skills-only z umiejętnością host_callback lub plugin_queue |
Umiejętność Skills Engine nie może uruchamiać Państwa kodu |
| Dodać jeden lub dwa ekrany wewnątrz powłoki | Wtyczki ui-only |
Tylko wtyczki dodają ekrany |
| Przechowywać własne rekordy za własnymi ścieżkami i uprawnieniami | Wtyczki full-service |
Tylko ten poziom posiada własny schemat |
| Zapewnić jednej roli węższy widok ekranów branżowych | Soczewki na istniejącym pakiecie | Soczewka to dane, a nie kod |
| Wdrożyć branżowy model wiedzy i soczewki wraz z ekranami na telefony w kilku jednostkach | Pakietu domenowego | Sama wtyczka nie posiada soczewek ani bramki licencyjnej |
W Corrán Orbital pytanie dotyczące planowania przelotów pozostało umiejętnością Skills Engine. Potrzebna do tego propagacja orbity stała się wtyczką skills-only z jedną umiejętnością host_callback, ponieważ obliczenia numeryczne są nasze i muszą dawać ten sam wynik przy powtórzeniu. Nasza komisja ds. przeglądu anomalii stała się wtyczką full-service, ponieważ prowadzi własne rejestry tego, kto analizował które odchylenie telemetryczne i jaką podjął decyzję. Pakiet pojawił się na końcu, gdy druga jednostka potrzebowała tego samego rozwiązania.
Jak elementy łączą się ze sobą
Elementy konstrukcyjne łączą się w większe całości. Pakiet domenowy jest najjaśniejszym przykładem, ponieważ stanowi zestaw pozostałych elementów wzbogacony o bramkę licencyjną:
- model wiedzy, czyli rodzaje pojęć znanych w danej branży i powiązania między nimi, często budowany na bazie modelu z innego pakietu;
- soczewki, po jednej dla każdej roli, z których każda zawęża soczewkę bazową;
- szablony i przepływy pracy oraz wywoływane przez nie umiejętności Skills Engine;
- wtyczki tam, gdzie pakiet wymaga własnego kodu;
- konektory tylko do odczytu łączące z systemami, które już przechowują rekordy;
- nakładka mobilna określająca, które karty i kroki wprowadzania danych pojawiają się na telefonach;
- oraz uprawnienia (entitlement): grupy funkcji, które musi obejmować licencja, zanim cokolwiek z tego zostanie włączone.
Nic z tego nie wymaga tworzenia infrastruktury dla każdej aplikacji z osobna. Pakiet nie zawiera własnego kodu izolacji, klienta modelu ani mechanizmu sprawdzania licencji – dziedziczy je z platformy. Jest to tematem kolejnego rozdziału i powodem, dla którego autor pakietu w banku i autor w porcie piszą dokładnie tyle samo kodu bezpieczeństwa, czyli zero.
Poziomy zaufania
Każda wtyczka deklaruje w swoim manifeście poziom zaufania (trust). Zaufanie to nie bramka, którą pakiet SDK może ominąć. To metadane doradcze, które platforma odczytuje, aby zdecydować, z jakim stopniem izolacji działają elementy wtyczki i jak bardzo wrażliwych danych mogą dotykać jej umiejętności. Aktywne bramki (klasyfikacja i rezydencja danych, eksport oraz wydatki) pozostają dokładnie na swoich miejscach.
| Poziom zaufania | Dla kogo jest przeznaczony | Tryb izolacji | Pułap klasyfikacji |
|---|---|---|---|
core |
Kod własny dostarczany wraz z platformą | none: to samo pochodzenie (same-origin), brak dodatkowej izolacji |
restricted |
verified |
Zweryfikowany podmiot zewnętrzny, potwierdzony wydawca | Powierzchnia same-origin, umiejętności pośredniczone (brokered) |
restricted |
community |
Niezweryfikowany podmiot zewnętrzny; wartość domyślna dla nowej wtyczki | Powierzchnia sandboxed, umiejętności pośredniczone (brokered) |
tenant |
untrusted |
Wszystko z nieznanego źródła | strict: powierzchnia w piaskownicy (sandbox), wyłącznie umiejętności pośredniczone, brak zaufania hosta |
public |
Z tej tabeli wynikają dwie zasady, a create-nexus-plugin validate egzekwuje obie, zanim cokolwiek zostanie zbudowane.
Po pierwsze, parametr classification umiejętności nie może przekroczyć pułapu swojej wtyczki. Klasyfikacje uszeregowane są w kolejności: public, następnie tenant, a potem restricted. Wtyczka o poziomie community, która deklaruje umiejętność restricted, nie zostanie zbudowana.
Po drugie, tylko wtyczki core i verified mogą deklarować umiejętności sięgające do AI Provider Router. Są to poziomy tool_using oraz llm_only. Wtyczka community lub untrusted pośredniczy w pracy deterministycznej (host_callback, plugin_queue oraz map na nich oparte) i zleca platformie wykonanie wszystkiego, co wymaga modelu. Moja pierwsza wtyczka miała poziom community i straciłem całe popołudnie, próbując zadeklarować umiejętność podsumowującą llm_only, zanim zrozumiałem, że ta odmowa była celowa.
W przypadku pominięcia trust, pakiet SDK traktuje wtyczkę jako community. Pominięte pole nigdy nie może skutkować podwyższeniem uprawnień.
Poziomy izolacji od 1 do 4
Niezależnie od poziomu zaufania, blok runtime manifestu określa sposób działania wtyczki. isolationLevel to liczba całkowita od 1 do 4, z której wynika tryb wykonania. Nie wybiera się ich niezależnie: walidator wyprowadza jedną wartość z drugiej i odrzuca manifest, w którym ta para jest niespójna.
isolationLevel |
executionMode |
Co to oznacza |
|---|---|---|
| 1 | external_https |
Wtyczka działa poza instalacją i komunikacja z nią odbywa się przez HTTPS |
| 2 | mcp_container |
Kontener udostępniający narzędzia MCP |
| 3 | hardened_docker |
Utwardzony (hardened) kontener we własnych podach wtyczki; ustawienie domyślne szablonu |
| 4 | firecracker |
Mikromaszyna wirtualna (microVM), najsilniejsza separacja |
"runtime": {
"nodeVersion": "20",
"executionMode": "hardened_docker",
"isolationLevel": 3,
"entrypoint": "dist/server.js",
"healthCheck": "/health"
}Pole entrypoint jest wymagane. Punkty wejścia (entrypoints) są dostarczanymi artefaktami i nigdy nie są pobierane w czasie wykonywania: pakiet SDK w ogóle nie posiada ścieżki dynamicznego importu ani zdalnego ładowania, dzięki czemu poziom zaufania jest zapisywany, sprawdzany raz, a następnie zamrażany – nigdy nie jest pobierany z sieci.
Zobowiązania na poszczególnych poziomach
Utrzymanie każdego szczebla powyżej ustawień wiąże się z pewnym kosztem. Oto co kosztuje każdy z nich.
- Umiejętność Skills Engine wymaga przypadków testowych, recenzenta (którym nie są Państwo) oraz historii wersji, o którą zostaną Państwo zapytani, gdy umiejętność zadziała nieprawidłowo. Te same bajty nigdy nie są publikowane dwukrotnie (
CONTENT_HASH_ALREADY_PUBLISHED), więc „po prostu prześlij to ponownie” nie rozwiąże problemu. - Wtyczka wymaga manifestu, którego tabela ścieżek odpowiada ścieżkom rejestrowanym przez Państwa kod, w obu kierunkach. Ścieżka, która istnieje, ale nie została zadeklarowana, oznacza błąd zgodności – podobnie jak zadeklarowana ścieżka, której kod nigdy nie rejestruje.
- Wtyczka
full-serviceposiada własny schemat z pięcioma rolami bazy danych, zabezpieczeniami na poziomie wiersza (row-level security) wymuszonymi dla każdej tabeli oraz procesem startowym, który odmawia nasłuchiwania, dopóki baza danych nie udowodni, że bariera ochronna działa. W swoim manifeście powtarza również słowo w słowo trzy prawa platformy. - Pakiet domenowy jest licencjonowany. Włącza się go po jednej jednostce naraz, poprzez wdrożenie pilotażowe, a licencja organizacji musi go obejmować. Nie mogą Państwo sami zadecydować, że klient go posiada.
- Soczewka może jedynie odejmować elementy. Jeśli dana rola musi widzieć więcej, zmianie musi ulec soczewka bazowa, co wymaga rozmowy z właścicielem tej bazy.
Żadnego z tych kosztów nie można negocjować dla pojedynczej aplikacji – na tym polega kompromis. Rezygnują Państwo z części swobody przy pierwszej wtyczce, aby odzyskać ją przy każdej kolejnej.
CONNECTION_SCOPE_EXCEEDED.Narzędzia i połączenia MCP
Protokół MCP pojawia się w trzech miejscach, które łatwo ze sobą pomylić.
Wtyczka może publikować narzędzia MCP, deklarując je w mcpTools[]: name, description oraz inputSchema. Jedyną zasadą dodawaną przez walidator jest to, że inputSchema nie może używać na najwyższym poziomie oneOf, allOf ani anyOf, ponieważ kombinator na szczycie schematu powoduje, że każdy klient MCP importujący narzędzie zwraca błąd 400. Wtyczka o isolationLevel równym 2 działa jako mcp_container.
Biblioteka Skills Engine jest dostępna przez MCP. Claude Code oraz agenci używają trzynastu narzędzi MCP do wyszukiwania i dopasowywania umiejętności, uruchamiania ich i rejestrowania przebiegu, a także tworzenia, importowania lub synchronizowania – przy czym każde wywołanie działa w imieniu osoby, która je zainicjowała, w ramach jej listy dozwolonych.
Natomiast narzędzie programistyczne AI łączy się przez Workbench: jeden adres na instalację, logowanie przez przeglądarkę danej osoby, jednogodzinna przepustka zamiast zapisanego klucza oraz dostęp wyłącznie do narzędzi zaznaczonych przez tę osobę. Szczegółowo omawia to rozdział 2.26, Budowanie za pomocą narzędzi programistycznych AI.
Konektory to spokojniejszy sąsiad. Model wiedzy pakietu domenowego jest zasilany przez konektory tylko do odczytu z systemów takich jak administracja polisami czy system roszczeń, z których każdy posiada własny harmonogram i przycisk testowy. Nic nie jest zapisywane z powrotem do źródła.
Z Twojej gałęzi kodu na ekrany użytkowników
Niezależnie od wybranego szczebla, droga na produkcję jest taka sama. Każde wydanie przechodzi z przestrzeni deweloperskiej na środowisko staging, następnie do jednostki pilotażowej, a potem do wszystkich jednostek. Każdy krok posiada bramki kontrolne: testy, manifest, który nie został rozszerzony, próbne uruchomienie (dry run) na zamaskowanej kopii danych oraz wyznaczonych recenzentów niebędących autorami. Próba promocji z pominięciem kroku zostaje odrzucona z błędem GATE_CANNOT_BE_SKIPPED. Każde środowisko zachowuje poprzednią wersję przez 30 dni, a wycofanie zmian w jednej jednostce to podlegająca przeglądowi operacja, która zajmuje około minuty.
Samo wdrożenie odbywa się wyłącznie za pośrednictwem kanałów wydawniczych danej instalacji. Jednostki wybierają swój kanał, a ich administrator wyraża zgodę na każde przeniesienie. Na stronie Kanały i instalacje widzą Państwo liczby i wskaźniki błędów dla poszczególnych jednostek, ale nigdy to, co ktokolwiek zrobił za pomocą Państwa rozszerzenia. Rozdział 2.28, Wydawanie rozszerzenia, omawia proces wydawniczy od początku do końca.
Uwaga dotycząca edycji
Większość tej drabiny istnieje w obu edycjach. Edycja Community otrzymuje ustawienia i umiejętności Skills Engine, wtyczki na każdym poziomie oraz te same sprawdzone ścieżki (golden paths) na jednym serwerze z kodem na Państwa własnym hoście Git. Edycja Enterprise dodaje promocję z przestrzeni deweloperskiej przez staging do jednostki pilotażowej wraz z jej bramkami, a także klastry wydawców i zamaskowane kopie danych produkcyjnych. Dodaje również Państwa własny prywatny katalog oraz pakiety domenowe. Szczegóły znajdują się w rozdziale 2.25, Budowanie dla poszczególnych edycji.
Kolejny rozdział to lektura obowiązkowa przed napisaniem jakiegokolwiek kodu. Zawiera mało wyborów, a dużo zasad – i zasady te są takie same dla pierwszego, jak i tysięcznego rozszerzenia.



