Přihlásit seDomluvit prezentaci

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ě

16 min čtení

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.

  1. 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.
  2. Dovednosti ve Skills Engine. Balíček SKILL.md obsahují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í).
  3. Pluginy. Váš vlastní kód deklarovaný manifestem a sestavený pomocí nástrojů SDK. Plugin existuje v jedné ze tří úrovní: skills-only, ui-only nebo full-service.
  4. 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í.
  5. 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.
  6. 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.

Začít něco nového
Začít něco nového
Možnost Začít něco nového nabízí šest osvědčených cest (golden paths), jednu pro každý druh rozšíření. Každá z nich vytvoří repozitář z verzované šablony s manifestem, který deklaruje vše potřebné, a nastaví testy, vývojový prostor a datové větve.

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.
Nakreslete sloupec vodorovných pásů. Dole jsou „Základní funkce systému Nexus“ (asistent, soubory, paměť, úlohy) a vedle nich „Dispečink UNO“ a „AI Provider Router“. Nad tím je pás „Pluginy“ se dvěma poli, „skills-only“ a „full-service“, a pás „Dovednosti ve Skills Engine“. Nad nimi je široké pole „Doménový balíček“ obsahující čtyři menší pole: „Znalostní model“, „Pohledy (lenses)“, „Šablony a pracovní postupy“, „Mobilní vrstva“. Nalevo od balíčku je pole „Konektory pouze pro čtení“ se šipkou směřující do pole „Znalostní model“. Nahoře jsou tři pole jednotek („Rotterdam“, „Felixstowe“, „Centrála“) se šipkami vedoucími dolů z balíčku, označenými „pohled udělený podle role“. Visací zámek na okraji balíčku nese označení „licence: domain_packs“.
Jak doménový balíček sdružuje ostatní stavební prvky.

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é.

Oborové balíčky
Oborové balíčky
Stránka Doménové balíčky uvádí všech deset balíčků spolu s tím, co každý z nich vyžaduje a kde běží. Balíček, který licence neobsahuje, zůstává v seznamu zašedlý s informací o tom, co by potřeboval.

Ú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-service vlastní 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.

Instalace pluginu třetí strany
Instalace pluginu třetí strany
Instalace pluginu třetí strany funguje jako oprávnění aplikací. Každý rozsah (scope), který jeho manifest deklaruje, je udělen nebo odepřen pro každou jednotku zvlášť a volání čehokoli, co nedeklaroval, je odmítnuto s kódem 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.

Pluginy a synchronizace MCP
Pluginy a synchronizace MCP
Obrazovka Pluginy a synchronizace MCP ukazuje, které pluginy přinášejí dovednosti, které synchronizace byly zcela odmítnuty, a třináct nástrojů MCP, které Claude Code a agenti používají pro přístup ke knihovně.

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í.