Verze 1.0.0-alpha.1nejnovější
Kapitola 2.18
Model rozšíření
Šest způsobů, jak rozšířit Nexus, od nastavení až po oborový balíček, limity každého z nich a jak úrovně důvěryhodnosti a izolace rozhodují o tom, kde váš kód běží. Přečtěte si to před otevřením sady pro vývoj softwaru (SDK).
Tato stránka byla přeložena pomocí AI z anglického originálu. Pokud je cokoliv nejasné, směrodatná je anglická stránka. Přečíst tuto stránku v angličtině

První věc, kterou jsem v Corrán Orbital na systému Nexus postavil, nebyl plugin. Náš tým letové dynamiky chtěl, aby asistent odpovídal na otázku „o které přelety nad pozemními stanicemi přijdeme, pokud bude anténa na Špicberkách odstavena kvůli údržbě?“ pokaždé ve stejném tvaru, s tabulkou přeletů na prvním místě a ztrátou v kontaktních minutách pod ní. Strávil jsem půl dne čtením sady pro vývoj softwaru (SDK), než mě kolega upozornil, že to, co hledám, je dovednost (skill): složka se souborem SKILL.md uvnitř, nahraná do Skills Engine a publikovaná poté, co projdou její testy a schválí ji recenzent. Trvalo to čtyřicet minut.
O dva pluginy a jeden doménový balíček později je to stále rada, kterou dávám jako první. Nexus nabízí šest způsobů rozšíření, které tvoří žebříček podle náročnosti. Levné příčky dokážou více, než lidé čekají, a ty drahé s sebou nesou závazky, které je snadné podcenit. Tato kapitola tento žebříček představuje. Vyberte si nejnižší příčku, která splní daný úkol. Následující kapitoly se každé z nich věnují do hloubky: kapitola 2.19, Pravidla, která dědí každé rozšíření; kapitola 2.20, Dovednosti; kapitola 2.21, Plugin SDK; kapitola 2.22, Běhové prostředí pluginů; a kapitola 2.23, Doménové balíčky.
Šest stavebních kamenů
Zde jsou uvedeny v pořadí, v jakém byste je měli zvažovat.
- Nastavení a zásady. Jde o hodnoty, které správce nastavuje v konzoli pro celou organizaci, organizační jednotku nebo jednoho člověka v rámci toho, co dovoluje licence. Nepíšete vůbec žádný kód.
- Dovednosti ve Skills Engine. Balíček
SKILL.mdobsahující instrukce a nástroje, které může dovednost volat, s volitelnými soubory a skripty. Asistent, agenti, pracovní postupy (workflows) a tlačítka AI (umělé inteligence) na obrazovkách spouštějí tytéž dovednosti, a stejně tak i vaše IDE (integrované vývojové prostředí). - Pluginy. Váš vlastní kód deklarovaný manifestem a sestavený pomocí nástrojů SDK. Plugin existuje v jedné ze tří úrovní:
skills-only,ui-onlynebofull-service. - Doménové balíčky. Pohledy (lenses) a šablony pro jedno odvětví, jeho dovednosti a znalostní model, jeho konektory a obrazovky pro telefony, licencované jako jeden celek. Adverant jich dodává deset; můžete si však vytvořit i vlastní.
- Pohledy (lenses). To, co vidí jedna role uvnitř balíčku nebo platformy. Pohled vždy zužuje základní pohled a nikdy jej nerozšiřuje.
- Připojení a konektory MCP. Nástroje protokolu Model Context Protocol (MCP), které publikuje plugin nebo přes které se připojuje programovací nástroj s AI, a konektory pouze pro čtení, které přinášejí záznamy ze systémů, které již provozujete.
Dva pojmy se často překrývají, proto je hned na začátku upřesním. Dovednost ve Skills Engine je balíček SKILL.md v knihovně. Manifestová dovednost je typovaný řádek v poli skills[] pluginu, zkompilovaný do registru dovedností platformy a spouštěný přes UNO, engine pro pracovní postupy. Obojí se na obrazovce nazývá dovednost (skill). Píšou se i spravují odlišně a tato dokumentace vždy uvádí, kterou z nich má na mysli.
Co jednotlivé prvky umí a co ne
Tabulka představuje stručný přehled. Sloupec „Co nedokáže“ jsem zařadil záměrně: každé omezení je vlastností návrhu a každé z nich mě už před něčím zachránilo.
| Stavební prvek | Co dokáže | Co nedokáže | Kdo jej vytváří |
|---|---|---|---|
| Nastavení nebo zásada | Změnit chování funkce na libovolné úrovni od organizace až po jednotlivce; uzamknout hodnotu; delegovat ji níže; vyžádat si schválení změny druhou osobou | Přidat obrazovku nebo cestu (route), uložit novou tabulku nebo spustit nový druh práce | Správce v konzoli |
| Dovednost ve Skills Engine | Poskytnout asistentovi, agentům, pracovním postupům a tlačítkům AI opakovatelný způsob provedení jednoho úkolu s vlastními instrukcemi a testovacími případy | Uchovávat přihlašovací údaje; volat nástroj mimo seznam povolených položek (allow-list) osoby, která jej spouští (SKILL_CANNOT_WIDEN_TOOLS); přejít do ostrého provozu bez testů a schválení |
Kdokoli s příslušným oprávněním, v tvůrci nebo ze svého IDE |
Plugin, skills-only |
Publikovat manifestové dovednosti, které běží na platformě: zpětná volání hostitele, práci ve frontě, mapování přes seznam a na úrovni důvěryhodnosti core nebo verified také dovednosti využívající modely |
Poskytovat vlastní stránky | Vývojář pomocí SDK |
Plugin, ui-only |
Přidat frontendové rozhraní uvnitř prostředí (shellu) | Ukládat vlastní data nebo spouštět výpočty | Vývojář pomocí SDK |
Plugin, full-service |
Vlastní backend a frontend, schéma Postgres, směrovací tabulku s oprávněními, dovednosti a nástroje MCP | Volat poskytovatele modelu; uchovávat klíč k modelu; číst řádky jiné organizace s výjimkou zaznamenaného udělení přístupu; spouštět výpočty mimo dispečink UNO | Vývojář pomocí SDK |
| Doménový balíček | Přinést pohledy a šablony pro dané odvětví, jeho dovednosti a pracovní postupy, znalostní model, mapu důkazů a obrazovky pro telefony do jednotek, které vybere správce | Měnit prostředí (shell) nebo jeho komponenty či pravidla zápisu; běžet bez příslušné licence organizace | Adverant nebo vaši vlastní vývojáři v edici Enterprise |
| Pohled (lens) | Vybrat karty a pole, které vidí jedna role v rámci balíčku nebo platformy, a akce, které jí nabízí | Zobrazit cokoli, co skrývá jeho základní pohled (LENS_CANNOT_WIDEN); změnit to, co smí daná role dělat |
Autor balíčku jej sestaví; správce jej přiděluje jednotlivým jednotkám |
| Nástroje a konektory MCP | Zpřístupnit nástroje pluginu agentům a programovacím nástrojům; číst záznamy ze systému správy pojistek nebo archivu telemetrie do znalostního modelu | Zapisovat zpět do zdrojového systému přes konektor; jednat nad rámec vlastních oprávnění přihlášené osoby | Vývojář deklaruje nástroje MCP; správce nastavuje konektory |
Několik z těchto buněk si zaslouží ještě jednu větu.
Nastavení tvoří ucelený rámec (framework) a každý plugin používá tentýž. Plugin, který ve svém manifestu deklaruje blok settings, získá úrovně (platforma, organizace, balíček, jednotka, skupina, repozitář, osoba), zámky a delegování, protokol změn a schvalování druhou osobou, to vše bez nutnosti psát tabulku nastavení. Proto často stačí ta nejlevnější příčka: pokud požadované chování již existuje a potřebuje pouze jinou hodnotu pro jednotku v Rotterdamu, jde o nastavení.
Dovednost ve Skills Engine běží pod identitou dané osoby. Nikdy neuchovává klíč, může přistupovat pouze k nástrojům na seznamu povolených položek toho, kdo ji spouští, a číst jen to, co smí tato osoba otevřít. Dovednost, která přidává nástroj provádějící zápis, je pozdržena, dokud ji neschválí dvě osoby, poté přejde do stínového provozu (shadow), následně do kanárkového nasazení (canary) a pak teprve pro všechny.
Plugin skills-only představuje střední příčku. Potřebujete jej, když je prací váš vlastní kód: deterministický výpočet, worker fronty nebo rozvětvené zpracování (fan-out) seznamu. Platforma volá váš kód; váš kód nikdy nevolá model.
Plugin full-service je malý samostatný produkt. Vlastní schéma Postgres, směrovací tabulku s registrem oprávnění, frontend, sadu databázových rolí a veškeré závazky týkající se izolace uvedené v kapitole 2.19, Pravidla, která dědí každé rozšíření. Je to správná volba častěji, než se lidé obávají, a špatná volba častěji, než lidé doufají.
Který potřebuji?
Začněte na začátku této tabulky a zastavte se u prvního řádku, který vyhovuje.
| Chcete… | Použijte | Proč ne něco jednoduššího |
|---|---|---|
| Změnit hodnotu či limit nebo určit, kdo smí něco udělat | Nastavení nebo zásadu | Nic jednoduššího neexistuje |
| Zajistit, aby asistent prováděl jeden úkol pokaždé stejným způsobem | Dovednost ve Skills Engine | Nastavení nemůže obsahovat instrukce |
| Umístit na obrazovku „tlačítko AI“, které tento úkol spustí | Dovednost ve Skills Engine navázanou na tlačítko | Tlačítko pouze spouští dovednosti; není třeba nic programovat |
| Umožnit programovacímu nástroji s AI přístup k systému Nexus | Připojení MCP přes Workbench | Není třeba nic psát; osoba se přihlásí přes svůj prohlížeč |
| Číst záznamy ze stávajícího systému do znalostního modelu | Konektor pouze pro čtení | Konektor nic nezapisuje zpět, takže nenese žádné riziko zápisu |
| Spouštět vlastní deterministický kód podle rozvrhu platformy | Plugin skills-only s dovedností host_callback nebo plugin_queue |
Dovednost ve Skills Engine nemůže spouštět váš kód |
| Přidat jednu či dvě obrazovky do prostředí (shellu) | Plugin ui-only |
Obrazovky mohou přidávat pouze pluginy |
| Uchovávat vlastní záznamy za vlastními cestami (routes) a oprávněními | Plugin full-service |
Schéma vlastní pouze tato úroveň |
| Poskytnout jedné roli užší pohled na odvětvové obrazovky | Pohled (lens) nad stávajícím balíčkem | Pohled jsou data, nikoli kód |
| Přinést znalostní model a pohledy pro dané odvětví včetně obrazovek pro telefony do několika jednotek | Doménový balíček | Samotný plugin nemá pohledy ani licenční bránu |
V Corrán Orbital zůstala otázka plánování přeletů dovedností ve Skills Engine. Výpočet šíření oběžné dráhy, který potřebuje, se stal pluginem skills-only s jednou dovedností host_callback, protože numerické výpočty jsou naše a musí dát dvakrát stejný výsledek. Naše komise pro přezkum anomálií se stala pluginem full-service, protože si vede vlastní záznamy o tom, kdo zkoumal kterou telemetrickou odchylku a jak rozhodl. Balíček přišel na řadu jako poslední, když totéž chtěla druhá jednotka.
Jak se jednotlivé části kombinují
Stavební prvky se skládají směrem nahoru. Doménový balíček je nejjasnějším příkladem, protože jde o souhrn ostatních prvků doplněný o licenční bránu:
- znalostní model, tedy druhy entit, které dané odvětví zná, a způsoby jejich propojení, často postavený na základním modelu z jiného balíčku;
- pohledy (lenses), jeden pro každou roli, z nichž každý zužuje základní pohled;
- šablony a pracovní postupy a dovednosti ve Skills Engine, které volají;
- pluginy tam, kde balíček potřebuje vlastní kód;
- konektory pouze pro čtení napojené na systémy, které již záznamy uchovávají;
- mobilní vrstva (overlay), která určuje, které karty a kroky sběru dat se zobrazují na telefonech;
- a oprávnění (entitlement): skupiny funkcí, které musí licence obsahovat, než se cokoli z toho zapne.
Nic z toho není infrastruktura budovaná pro každou aplikaci zvlášť. Balíček nedodává žádný vlastní izolační kód, žádného klienta modelu ani žádnou kontrolu licence: vše dědí od platformy. To je tématem následující kapitoly a je to důvod, proč autor balíčku v bance a autor v přístavu napíšou stejné množství bezpečnostního kódu – tedy žádné.
Úrovně důvěryhodnosti
Každý plugin deklaruje ve svém manifestu úroveň trust. Důvěryhodnost (trust) není brána, kterou by SDK mohlo obejít. Jsou to informativní metadata, která platforma čte, aby rozhodla, s jakou mírou izolace poběží příspěvky pluginu a jak nejcitlivějších dat se mohou jeho dovednosti dotknout. Aktivní brány (klasifikace a rezidence dat, export a výdaje) zůstávají přesně tam, kde jsou.
| Důvěryhodnost | Pro koho je určen | Úroveň izolace | Strop klasifikace |
|---|---|---|---|
core |
Kód první strany dodávaný přímo v platformě | none: stejný původ (same-origin), žádná dodatečná izolace |
restricted |
verified |
Zkontrolovaná třetí strana, ověřený vydavatel | Rozhraní same-origin, zprostředkované (brokered) dovednosti |
restricted |
community |
Nezkontrolovaná třetí strana; výchozí hodnota pro nový plugin | Rozhraní sandboxed, zprostředkované (brokered) dovednosti |
tenant |
untrusted |
Cokoli z neznámého zdroje | strict: rozhraní v sandboxu, pouze zprostředkované dovednosti, žádná důvěra hostitele |
public |
Z této tabulky vyplývají dvě pravidla a create-nexus-plugin validate obě vynucuje ještě předtím, než se cokoli sestaví.
Za prvé, hodnota classification dovednosti nemůže překročit strop svého pluginu. Klasifikace se řadí od public přes tenant až po restricted. Sestavení pluginu s úrovní community, který deklaruje dovednost s klasifikací restricted, selže.
Za druhé, pouze pluginy s úrovní core a verified mohou deklarovat dovednosti, které přistupují k AI Provider Router. Jedná se o úrovně tool_using a llm_only. Plugin s úrovní community nebo untrusted zprostředkovává deterministickou práci (host_callback, plugin_queue a map nad nimi) a o vše, co vyžaduje model, žádá platformu. Můj první plugin měl úroveň community a ztratil jsem celé odpoledne snahou deklarovat sumarizační dovednost llm_only, než jsem pochopil, že toto odmítnutí je záměrné.
Pokud pole trust vynecháte, SDK zachází s pluginem jako s community. Vynechané pole nikdy nemůže vést k povýšení úrovně.
Úrovně izolace 1 až 4
Nezávisle na důvěryhodnosti určuje blok runtime v manifestu způsob, jakým plugin běží. isolationLevel je celé číslo od 1 do 4 a režim provádění z něj vychází. Tyto dvě hodnoty nevolíte nezávisle: validátor odvodí jednu z druhé a odmítne manifest, ve kterém si tato dvojice neodpovídá.
isolationLevel |
executionMode |
Co to znamená |
|---|---|---|
| 1 | external_https |
Plugin běží mimo instalaci a přistupuje se k němu přes HTTPS |
| 2 | mcp_container |
Kontejner, který zpřístupňuje nástroje MCP |
| 3 | hardened_docker |
Zabezpečený (hardened) kontejner ve vlastních podech pluginu; výchozí hodnota šablony |
| 4 | firecracker |
MicroVM, nejsilnější oddělení |
"runtime": {
"nodeVersion": "20",
"executionMode": "hardened_docker",
"isolationLevel": 3,
"entrypoint": "dist/server.js",
"healthCheck": "/health"
}Pole entrypoint je povinné. Vstupní body (entrypoints) jsou dodávané artefakty a nikdy se nestahují za běhu: SDK nemá vůbec žádnou cestu pro dynamický import ani vzdálené načítání, takže důvěryhodnost je zapsána a zkontrolována jednou, poté zmrazena a nikdy se nestahuje.
K čemu se zavazujete na jednotlivých stupních
Údržba každé příčky nad nastavením něco stojí. Zde je přehled toho, co vás každá z nich bude stát.
- Dovednost ve Skills Engine potřebuje testovací případy, recenzenta, kterým nejste vy, a historii verzí, na kterou se vás budou ptát, až se začne chovat nesprávně. Stejné bajty se nikdy nepublikují dvakrát (
CONTENT_HASH_ALREADY_PUBLISHED), takže „prostě to nahrát znovu“ není řešení. - Plugin potřebuje manifest, jehož směrovací tabulka odpovídá cestám (routes), které váš kód registruje, a to v obou směrech. Cesta, která existuje, ale není deklarována, představuje chybu shody, a stejně tak i deklarovaná cesta, kterou kód nikdy nezaregistruje.
- Plugin
full-servicevlastní schéma s pěti databázovými rolemi, zabezpečením na úrovni řádků (row-level security) vynuceným u každé tabulky a spouštěcím procesem, který odmítne naslouchat, dokud databáze neprokáže, že tato bariéra drží. Ve svém manifestu také slovo od slova znovu uvádí tři zákony platformy. - Doménový balíček podléhá licenci. Zapíná se postupně po jednotlivých jednotkách prostřednictvím pilotního provozu a licence organizace jej musí obsahovat. Nemůžete sami rozhodnout o tom, že jej zákazník má.
- Pohled (lens) může pouze ubírat. Pokud určitá role potřebuje vidět více, musí se změnit základní pohled, což znamená domluvu s tím, kdo tento základ vlastní.
O žádném z těchto nákladů nelze vyjednávat u jednotlivých aplikací, což je podstata tohoto kompromisu. U prvního pluginu se vzdáte části svobody a u každého dalšího ji získáte zpět.
CONNECTION_SCOPE_EXCEEDED.Nástroje a připojení MCP
Protokol MCP se objevuje na třech místech a je snadné si je splést.
Plugin může publikovat nástroje MCP jejich deklarováním v mcpTools[]: name, description a inputSchema. Jediné pravidlo, které validátor přidává, je, že inputSchema nesmí na nejvyšší úrovni používat oneOf, allOf ani anyOf, protože kombinátor na vrcholu schématu způsobí, že každý klient MCP, který nástroj importuje, selže s chybou 400. Plugin s isolationLevel 2 běží jako mcp_container.
Knihovna Skills Engine je dostupná přes MCP. Claude Code a agenti používají třináct nástrojů MCP k vyhledávání a párování dovedností, jejich spouštění a zaznamenávání běhu a také k jejich vytváření, importu či synchronizaci, přičemž každé volání běží pod identitou osoby, která jej spustila, v rámci jejího seznamu povolených položek.
A programovací nástroj s AI se připojuje přes Workbench: jedna adresa na instalaci, přihlášení přes prohlížeč dané osoby, jednohodinový přístupový token místo uloženého klíče a pouze ty nástroje, které tato osoba zaškrtne. Podrobně to prochází kapitola 2.26, Vývoj pomocí programovacích nástrojů s AI.
Konektory jsou tišším sousedem. Znalostní model doménového balíčku je plněn konektory pouze pro čtení ze systémů, jako je správa pojistných smluv nebo systém likvidace pojistných událostí, přičemž každý má svůj rozvrh a testovací tlačítko. Do zdroje se nic nezapisuje zpět.
Z vaší větve na obrazovky uživatelů
Ať už jste na kterékoli příčce, cesta do produkce je stejná. Každé vydání postupuje z vašeho vývojového prostoru do testovacího prostředí (staging), poté do pilotní jednotky a následně do všech jednotek, přičemž každý krok má své brány: testy, manifest, který se nerozšířil, zkušební běh na maskované kopii a jmenované recenzenty, kteří nejsou autory. Povýšení, které se pokusí přeskočit krok, je odmítnuto s kódem GATE_CANNOT_BE_SKIPPED. Každé prostředí uchovává předchozí verzi po dobu 30 dnů a vrácení jedné jednotky zpět (rollback) je schvalovaná změna, která trvá přibližně minutu.
Samotné nasazení probíhá výhradně přes kanály vydání dané instalace. Jednotky si volí svůj kanál a jejich správce schvaluje každý přesun. Na stránce Kanály a instalace vidíte počty a míru chybovosti pro jednotlivé jednotky, ale nikdy to, co kdokoli s vaším rozšířením dělal. Kapitola 2.28, Vydávání vašeho rozšíření, pokrývá proces vydávání od začátku do konce.
Poznámka k edicím
Většina tohoto žebříčku existuje v obou edicích. Edice Community získává nastavení a dovednosti ve Skills Engine, pluginy na všech úrovních a stejné osvědčené cesty (golden paths) na jednom serveru s kódem na vašem vlastním hostingu Git. Edice Enterprise přidává povyšování z vývojového prostoru přes testovací prostředí (staging) do pilotní jednotky s příslušnými branami, a k tomu clustery vydavatelů a maskované kopie živých dat. Přidává také váš vlastní soukromý katalog a doménové balíčky. Podrobnosti uvádí kapitola 2.25, Vývoj pro jednotlivé edice.
Následující kapitolu byste si měli přečíst dříve, než napíšete jakýkoli kód. Nabízí málo možností volby, ale zato spoustu pravidel – a tato pravidla jsou stejná pro první i tisící rozšíření.



