ВходЗапазете среща

Глава 2.18

Моделът за разширения

Шестте начина за разширяване на Nexus – от настройка до браншов пакет, границите на всеки от тях и как нивата на доверие и изолация определят къде се изпълнява Вашият код. Прочетете това, преди да отворите пакета за разработка на софтуер (SDK).

Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

16 минути за четене

Първото нещо, което изградих върху Nexus в Corrán Orbital, не беше плъгин. Нашият екип по полетна динамика искаше асистентът да отговаря на въпроса „кои преминавания над наземни станции губим, ако антената в Свалбард излезе от строя за поддръжка?“ в една и съща форма всеки път, с таблицата на преминаванията най-отгоре и цената в контактни минути отдолу. Прекарах половин ден в четене на комплекта за разработка на софтуер (SDK), преди колега да ми посочи, че това, което търся, всъщност е умение: папка с SKILL.md в нея, качена в Skills Engine и публикувана, след като премине тестовете си и бъде одобрена от рецензент. Отне четиридесет минути.

Два плъгина и един домейн пакет по-късно, това все още е съветът, който давам първо. Nexus разполага с шест начина за разширяване, подредени по стълбица според необходимите усилия. Ниските стъпала правят повече, отколкото хората очакват, а високите носят задължения, които лесно се подценяват. Тази глава представя тази стълбица. Изберете най-ниското стъпало, което върши работата. Следващите глави разглеждат всяко от тях в дълбочина: глава 2.19, Правилата, които всяко разширение наследява; глава 2.20, Умения; глава 2.21, SDK за плъгини; глава 2.22, Средата за изпълнение на плъгини; и глава 2.23, Домейн пакети.

Шестте градивни елемента

Ето ги в реда, в който трябва да ги обмисляте.

  1. Настройки и политики. Това са стойности, които администраторът задава в конзолата за организацията, за звено или за един човек, в рамките на позволеното от лиценза. Не пишете никакъв код.
  2. Умения в Skills Engine. Пакет SKILL.md, съдържащ инструкции и инструментите, които умението може да извиква, с допълнителни файлове и скриптове към него. Асистентът, агентите, работните потоци и бутоните с ИИ (изкуствен интелект) на екраните изпълняват едни и същи умения, както и вашата IDE (интегрирана среда за разработка).
  3. Плъгини. Ваш собствен код, деклариран чрез манифест и компилиран с инструментите на SDK. Един плъгин се предлага в едно от три нива: skills-only, ui-only или full-service.
  4. Домейн пакети. Призмите и шаблоните за дадена индустрия, нейните умения и модел на знания, нейните конектори и екрани за телефон, лицензирани като едно цяло. Adverant доставя десет; вие можете да изградите свои собствени.
  5. Призми. Това, което една роля вижда в рамките на пакет или платформа. Призмата стеснява базовата призма и никога не я разширява.
  6. MCP връзки и конектори. Инструментите по Model Context Protocol (MCP), които един плъгин публикува или чрез които се свързва инструмент за програмиране с ИИ, както и конекторите само за четене, които внасят записи от системи, които вече използвате.

Два термина се припокриват, затова нека ги уточним сега. Умение в Skills Engine е пакет SKILL.md в библиотеката. Умение от манифест е типизиран ред в масива skills[] на плъгин, компилиран в регистъра с умения на платформата и изпълняван чрез UNO – системата за работни потоци. На екрана и двете се наричат умения. Те се пишат и управляват по различен начин и в тази документация винаги се посочва кое от двете се има предвид.

Започнете нещо ново
Започнете нещо ново
„Започнете нещо ново“ предлага шест утвърдени пътя – по един за всеки вид разширение. Всеки от тях създава хранилище от версиониран шаблон с манифест, който декларира какво му е необходимо, и настройва тестове, среда за разработка и клонове за данни.

Какво може да прави всеки от тях и какво не може

Таблицата е кратката версия. Включих колоната „Какво не може да прави“ умишлено: всяко ограничение е свойство на дизайна и всяко едно от тях ме е спасявало от нещо.

Градивен елемент Какво може да прави Какво не може да прави Кой го създава
Настройка или политика Да променя начина, по който се държи дадена функция на всяко ниво – от организацията до отделен човек; да заключва стойност; да я делегира надолу; да изисква втори човек при промяна Да добавя екран или маршрут, да съхранява нова таблица или да започва нов вид работа Администратор, в конзолата
Умение в Skills Engine Да дава на асистента и агентите, работните потоци и бутоните с ИИ повторяем начин за извършване на една задача, със собствени инструкции и тестови случаи Да съхранява идентификационни данни; да извиква инструмент извън списъка с разрешени на човека, който го стартира (SKILL_CANNOT_WIDEN_TOOLS); да влиза в експлоатация без своите тестове и одобрение Всеки, който притежава правото – в редактора за създаване или от своята IDE
Плъгин, skills-only Да публикува умения от манифест, които се изпълняват на платформата: обратни извиквания към хоста, работа в опашка, обхождане на списък и – при ниво на доверие core или verified – умения, поддържани от модел Да обслужва собствени страници Разработчик, със SDK
Плъгин, ui-only Да добавя фронтенд интерфейс вътре в обвивката Да съхранява собствени данни или да изпълнява изчисления Разработчик, със SDK
Плъгин, full-service Собствен бекенд и фронтенд, схема в Postgres, таблица с маршрути и права, както и умения и MCP инструменти Да извиква доставчик на модели; да съхранява ключ за модел; да чете редове на друга организация, освен чрез записано разрешение; да изпълнява изчисления извън диспечера на UNO Разработчик, със SDK
Домейн пакет Да предоставя призмите и шаблоните на дадена индустрия, нейните умения и работни потоци, модел на знания, карта на доказателствата и екрани за телефон на звената, избрани от администратора Да променя обвивката или нейните компоненти, или правилата за писане; да се изпълнява, без да е включен в лиценза на организацията Adverant или вашите собствени разработчици в Enterprise
Призма Да избира картите и полетата, които дадена роля вижда в пакет или платформа, както и действията, които предлага Да показва нещо, което базовата ѝ призма скрива (LENS_CANNOT_WIDEN); да променя това, което дадена роля има право да прави Автор на пакет я изгражда; администратор я предоставя за всяко звено
MCP инструменти и конектори Да предоставя инструментите на плъгин на агенти и инструменти за програмиране; да чете записи от система за полици или архив с телеметрия в модела на знания Да записва обратно в изходната система чрез конектор; да действа извън собствените права на вписания потребител Разработчик декларира MCP инструменти; администратор настройва конектори

Няколко от тези клетки заслужават още едно изречение.

Настройките са рамка и всеки плъгин използва една и съща. Плъгин, който декларира блок settings в своя манифест, получава нивата (платформа, организация, пакет, звено, група, хранилище, лице), заключвания и делегиране, дневник на промените и одобрение от втори човек – всичко това без да се пише таблица за настройки. Ето защо най-евтиното стъпало често е достатъчно: ако желаното от вас поведение вече съществува и просто се нуждае от различна стойност за звеното в Ротердам, това е настройка.

Умение в Skills Engine се изпълнява от името на човека. То никога не съхранява ключ и има достъп само до инструменти от списъка с разрешени на този, който го стартира, и чете само това, което този човек има право да отвори. Умение, което добавя инструмент, извършващ запис, се задържа, докато двама души не го одобрят, след което преминава в скрит режим (shadow), после в канарен режим (canary) и накрая става достъпно за всички.

Плъгин от ниво skills-only е средното стъпало. Той ви е необходим, когато работата представлява ваш собствен код: детерминистично изчисление, обработчик на опашка, разклоняване върху списък. Платформата извиква вашия код; вашият код никога не извиква модел.

Плъгин от ниво full-service е малък продукт. Той притежава схема в Postgres, таблица с маршрути и регистър на правата, фронтенд, набор от роли в базата данни и всяко задължение за изолация от глава 2.19, Правилата, които всяко разширение наследява. Той е правилното решение по-често, отколкото хората се опасяват, и грешното решение по-често, отколкото се надяват.

Кой ми е необходим?

Започнете от началото на тази таблица и спрете на първия ред, който отговаря на случая.

Искате да… Използвайте Защо не нещо по-леко
Промените стойност или лимит, или кой какво може да прави Настройка или политика Не съществува нищо по-леко
Накарате асистента да извършва една задача по един и същ начин всеки път Умение в Skills Engine Настройката не може да съдържа инструкции
Поставите „бутон с ИИ“ на екран, който стартира тази задача Умение в Skills Engine, обвързано с бутона Бутонът стартира само умения; няма нищо за изграждане
Позволите на инструмент за програмиране с ИИ да достигне до Nexus MCP връзка през Workbench Няма нищо за писане; човекът се вписва през своя браузър
Четете записи от съществуваща система в модела на знания Конектор само за четене Конекторът не записва нищо обратно, така че не носи риск при запис
Изпълнявате детерминистичен код, който притежавате, по графика на платформата Плъгин skills-only с умение host_callback или plugin_queue Умение в Skills Engine не може да изпълнява вашия код
Добавите един или два екрана вътре в обвивката Плъгин ui-only Само плъгините добавят екрани
Съхранявате собствени записи зад собствени маршрути и права Плъгин full-service Само това ниво притежава схема
Дадете на една роля по-тесен изглед към екраните за дадена индустрия Призма върху съществуващ пакет Призмата е данни, а не код
Предоставите модел на знания и призми за дадена индустрия, заедно с екрани за телефон, на няколко звена Домейн пакет Отделният плъгин няма призми или лицензионно ограничение

В Corrán Orbital въпросът за планиране на преминаванията си остана умение в Skills Engine. Прогнозирането на орбитата, от което се нуждае, стана плъгин skills-only с едно умение host_callback, тъй като числената обработка е наша и трябва да дава един и същ отговор при повторно изпълнение. Таблото ни за преглед на аномалии стана плъгин full-service, защото поддържа собствени записи за това кой кое телеметрично отклонение е прегледал и какво е решил. Пакетът дойде последен, когато второ звено поиска същото нещо.

Как се комбинират елементите

Градивните елементи се надграждат един друг. Домейн пакетът е най-ясният пример, тъй като представлява пакет от останалите елементи плюс лицензионно ограничение:

  • модел на знания – видовете неща, които индустрията познава, и как те се свързват, често изграден върху базов модел от друг пакет;
  • призми – по една за всяка роля, като всяка стеснява базова призма;
  • шаблони и работни потоци, както и уменията в Skills Engine, които те извикват;
  • плъгини, където пакетът се нуждае от собствен код;
  • конектори само за четене към системите, които вече съхраняват записите;
  • мобилен слой, който определя кои карти и стъпки за въвеждане се показват на телефони;
  • и правото на ползване: групите от функции, които лицензът трябва да включва, преди каквото и да било от това да се активира.
Начертайте стек от хоризонтални ленти. Най-отдолу е „Основни функции на Nexus“ (асистент, файлове, памет, задачи), а до него – „Диспечер на UNO“ и „AI Provider Router“. Над тях има лента „Плъгини“ с две полета – „skills-only“ и „full-service“, и лента „Умения в Skills Engine“. Над тях се намира широко поле „Домейн пакет“, съдържащо четири по-малки полета: „Модел на знания“, „Призми“, „Шаблони и работни потоци“, „Мобилен слой“. Вляво от пакета има поле „Конектори само за четене“ със стрелка към „Модел на знания“. Най-отгоре са разположени три полета за звена („Ротердам“, „Феликстоу“, „Централен офис“) със стрелки надолу от пакета с надпис „призма, предоставена според ролята“. Катинар на ръба на пакета носи надпис „лиценз: domain_packs“.
Как един домейн пакет обединява останалите градивни елементи.

Нищо от това не е инфраструктурен код за отделно приложение. Пакетът не доставя собствен код за изолация, нито клиент за модел, нито проверка на лиценза: той наследява тези на платформата. Това е темата на следващата глава и причината, поради която автор на пакет в банка и такъв в пристанище пишат едно и също количество код за сигурност – а именно никакъв.

Браншови пакети
Браншови пакети
Страницата „Домейн пакети“ изброява всичките десет пакета с това, от което всеки се нуждае, и къде се изпълнява. Пакет, който не е включен в лиценза, остава в списъка в сиво, заедно с изискванията за него.

Нива на доверие

Всеки плъгин декларира ниво trust в своя манифест. Доверието не е бариера, която SDK може да заобиколи. То е препоръчителни метаданни, които платформата чете, за да реши колко изолирано да се изпълняват компонентите на плъгина и кои са най-чувствителните данни, до които уменията му могат да имат достъп. Действащите бариери (класификация и местоположение на данните, експорт и разходи) остават точно там, където са.

Доверие За кого е предназначен Режим на изолация Таван на класификация
core Собствен код, който се доставя с платформата none: същия произход (same-origin), без допълнителна изолация restricted
verified Проверена трета страна, верифициран издател Повърхност same-origin, посреднически умения restricted
community Непроверена трета страна; по подразбиране за нов плъгин Повърхност sandboxed, посреднически умения tenant
untrusted Всичко от неизвестен източник strict: изолирана в sandbox повърхност, само посреднически умения, без доверие от хоста public

От тази таблица следват две правила и create-nexus-plugin validate прилага и двете, преди да бъде компилирано каквото и да било.

Първо, стойността classification на дадено умение не може да надвишава тавана на неговия плъгин. Класификациите се подреждат така: public, след това tenant, след това restricted. Плъгин с community, който декларира умение с restricted, не успява да се компилира.

Второ, само плъгини с core и verified могат да декларират умения, които достигат до AI Provider Router. Това са нивата tool_using и llm_only. Плъгин с community или untrusted посредничи при детерминистична работа (host_callback, plugin_queue и map върху тях) и моли платформата да извърши всичко, което се нуждае от модел. Първият ми плъгин беше community и загубих един следобед в опити да декларирам умение за обобщаване llm_only, преди да разбера, че отказът е самата цел.

Ако пропуснете trust, SDK третира плъгина като community. Пропуснато поле никога не може да доведе до повишаване на нивото.

Нива на изолация от 1 до 4

Отделно от доверието, блокът runtime в манифеста указва как се изпълнява плъгинът. isolationLevel е цяло число от 1 до 4 и режимът на изпълнение следва от него. Не избирате двете независимо едно от друго: валидаторът извежда едното от другото и отхвърля манифест, чиято двойка стойности си противоречи.

isolationLevel executionMode Какво означава
1 external_https Плъгинът се изпълнява извън инсталацията и е достъпен през HTTPS
2 mcp_container Контейнер, който предоставя MCP инструменти
3 hardened_docker Защитен контейнер в собствените подове на плъгина; стойността по подразбиране в шаблона
4 firecracker Микро виртуална машина (microVM), най-силното разделяне
"runtime": {
  "nodeVersion": "20",
  "executionMode": "hardened_docker",
  "isolationLevel": 3,
  "entrypoint": "dist/server.js",
  "healthCheck": "/health"
}

Изисква се entrypoint. Входните точки са доставени артефакти и никога не се извличат по време на изпълнение: SDK изобщо няма път за динамичен импорт или отдалечено зареждане, така че доверието се записва и проверява веднъж, след което се замразява, а никога не се изтегля.

Какво поемате на всяко стъпало

Поддръжката на всяко стъпало над настройките има своята цена. Ето какво ви струва всяко едно от тях.

  • Умение в Skills Engine се нуждае от тестови случаи, рецензент, който не сте вие, и история на версиите, за която ще ви питат, когато то се държи неправилно. Едни и същи байтове никога не се публикуват два пъти (CONTENT_HASH_ALREADY_PUBLISHED), така че „просто го качете отново“ не е решение.
  • Плъгинът се нуждае от манифест, чиято таблица с маршрути съвпада с маршрутите, които вашият код регистрира, и в двете посоки. Маршрут, който съществува, но не е деклариран, е грешка при съответствието, както и деклариран маршрут, който кодът никога не регистрира.
  • Плъгин от ниво full-service притежава схема с пет роли в базата данни, принудителна сигурност на ниво ред (row-level security) за всяка таблица и процес на стартиране, който отказва да приема заявки, докато базата данни не докаже, че защитната преграда държи. Освен това той повтаря трите закона на платформата в своя манифест, дума по дума.
  • Домейн пакетът се лицензира. Той се активира звено по звено, чрез пилотно внедряване, и лицензът на организацията трябва да го включва. Не вие решавате дали даден клиент разполага с него.
  • Призмата може само да отнема. Ако дадена роля трябва да вижда повече, трябва да се промени базовата призма, което изисква разговор с този, който притежава тази база.

Нито един от тези разходи не подлежи на договаряне за отделно приложение – в това се състои компромисът. Отказвате се от известна свобода при първия плъгин и си я връщате при всеки следващ.

Инсталиране на плъгин от трета страна
Инсталиране на плъгин от трета страна
Инсталирането на плъгин от трета страна работи като разрешенията за приложения. Всеки обхват, деклариран в неговия манифест, се предоставя или отказва за всяко отделно звено, а заявка за нещо, което не е декларирано, се отхвърля с CONNECTION_SCOPE_EXCEEDED.

Инструменти и връзки за MCP

MCP се появява на три места и е лесно те да бъдат объркани.

Плъгин може да публикува MCP инструменти, като ги декларира в mcpTools[]: name, description и inputSchema. Единственото правило, което валидаторът добавя, е, че inputSchema не може да използва oneOf, allOf или anyOf на най-горно ниво, тъй като комбинатор на върха на схемата кара всеки MCP клиент, който импортира инструмента, да прекъсне с грешка 400. Плъгин на isolationLevel 2 се изпълнява като mcp_container.

Библиотеката на Skills Engine е достъпна през MCP. Claude Code и агентите използват тринадесет MCP инструмента за намиране и съпоставяне на умения, стартирането им и записване на изпълнението, както и за създаването, импортирането или синхронизирането им, като всяко извикване се изпълнява от името на човека, който го е стартирал, в рамките на неговия списък с разрешени.

Освен това инструмент за програмиране с ИИ се свързва през Workbench: един адрес за всяка инсталация, вписване през браузъра на човека, едночасов пропуск вместо съхранен ключ и само инструментите, които този човек е отметнал. Глава 2.26, Изграждане с инструменти за програмиране с ИИ, разглежда този процес стъпка по стъпка.

Конекторите са по-тихият съсед. Моделът на знания на домейн пакета се захранва от конектори само за четене към системи като администриране на полици или система за щети, всеки със собствен график и бутон за тестване. Нищо не се записва обратно в източника.

Плъгини и MCP синхронизация
Плъгини и MCP синхронизация
„Плъгини и MCP синхронизация“ показва кои плъгини предоставят умения, кои синхронизации са били отхвърлени изцяло и тринадесетте MCP инструмента, които Claude Code и агентите използват за достъп до библиотеката.

От Вашия клон до екраните на хората

На което и стъпало да се намирате, пътят към продукционна среда е един и същ. Всяка версия преминава от вашата среда за разработка към тестова среда (staging), след това към пилотно звено и накрая към всички звена, като всяка стъпка има контролни бариери: тестове, манифест, който не е разширил правата си, пробно изпълнение върху маскирано копие и поименно посочени рецензенти, различни от автора. Повишаване на версията, което се опитва да прескочи стъпка, се отхвърля с GATE_CANNOT_BE_SKIPPED. Всяка среда пази предишната версия за 30 дни, а връщането на едно звено към стара версия е рецензирана промяна, която отнема около минута.

Самото внедряване преминава единствено през каналите за версии на инсталацията. Звената избират своя канал и техният администратор одобрява всяко преминаване. На страницата „Канали и инсталации“ виждате бройки и честота на грешките по звена, но никога какво е правил някой с вашето разширение. Глава 2.28, Пускане на вашето разширение, обхваща процеса по пускане от край до край.

Бележка относно изданията

По-голямата част от тази стълбица съществува и в двете издания. Community получава настройки и умения в Skills Engine, плъгини на всяко ниво и същите утвърдени пътища на един сървър с код във вашия собствен Git хост. Enterprise добавя придвижването от средата за разработка през тестовата среда до пилотно звено с неговите бариери, плюс клъстери за издатели и маскирани копия на реални данни. То добавя също ваш собствен частен каталог и домейн пакети. Подробностите са в глава 2.25, Изграждане за всяко издание.

Следващата глава е тази, която трябва да прочетете, преди да напишете какъвто и да е код. В нея има малко избори и много правила, а правилата са едни и същи както за първото разширение, така и за хилядното.