Версия 1.0.0-alpha.1последно
Глава 2.18
Моделът за разширения
Шестте начина за разширяване на Nexus – от настройка до браншов пакет, границите на всеки от тях и как нивата на доверие и изолация определят къде се изпълнява Вашият код. Прочетете това, преди да отворите пакета за разработка на софтуер (SDK).
Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

Първото нещо, което изградих върху Nexus в Corrán Orbital, не беше плъгин. Нашият екип по полетна динамика искаше асистентът да отговаря на въпроса „кои преминавания над наземни станции губим, ако антената в Свалбард излезе от строя за поддръжка?“ в една и съща форма всеки път, с таблицата на преминаванията най-отгоре и цената в контактни минути отдолу. Прекарах половин ден в четене на комплекта за разработка на софтуер (SDK), преди колега да ми посочи, че това, което търся, всъщност е умение: папка с SKILL.md в нея, качена в Skills Engine и публикувана, след като премине тестовете си и бъде одобрена от рецензент. Отне четиридесет минути.
Два плъгина и един домейн пакет по-късно, това все още е съветът, който давам първо. Nexus разполага с шест начина за разширяване, подредени по стълбица според необходимите усилия. Ниските стъпала правят повече, отколкото хората очакват, а високите носят задължения, които лесно се подценяват. Тази глава представя тази стълбица. Изберете най-ниското стъпало, което върши работата. Следващите глави разглеждат всяко от тях в дълбочина: глава 2.19, Правилата, които всяко разширение наследява; глава 2.20, Умения; глава 2.21, SDK за плъгини; глава 2.22, Средата за изпълнение на плъгини; и глава 2.23, Домейн пакети.
Шестте градивни елемента
Ето ги в реда, в който трябва да ги обмисляте.
- Настройки и политики. Това са стойности, които администраторът задава в конзолата за организацията, за звено или за един човек, в рамките на позволеното от лиценза. Не пишете никакъв код.
- Умения в Skills Engine. Пакет
SKILL.md, съдържащ инструкции и инструментите, които умението може да извиква, с допълнителни файлове и скриптове към него. Асистентът, агентите, работните потоци и бутоните с ИИ (изкуствен интелект) на екраните изпълняват едни и същи умения, както и вашата IDE (интегрирана среда за разработка). - Плъгини. Ваш собствен код, деклариран чрез манифест и компилиран с инструментите на SDK. Един плъгин се предлага в едно от три нива:
skills-only,ui-onlyилиfull-service. - Домейн пакети. Призмите и шаблоните за дадена индустрия, нейните умения и модел на знания, нейните конектори и екрани за телефон, лицензирани като едно цяло. Adverant доставя десет; вие можете да изградите свои собствени.
- Призми. Това, което една роля вижда в рамките на пакет или платформа. Призмата стеснява базовата призма и никога не я разширява.
- 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, които те извикват;
- плъгини, където пакетът се нуждае от собствен код;
- конектори само за четене към системите, които вече съхраняват записите;
- мобилен слой, който определя кои карти и стъпки за въвеждане се показват на телефони;
- и правото на ползване: групите от функции, които лицензът трябва да включва, преди каквото и да било от това да се активира.
Нищо от това не е инфраструктурен код за отделно приложение. Пакетът не доставя собствен код за изолация, нито клиент за модел, нито проверка на лиценза: той наследява тези на платформата. Това е темата на следващата глава и причината, поради която автор на пакет в банка и такъв в пристанище пишат едно и също количество код за сигурност – а именно никакъв.
Нива на доверие
Всеки плъгин декларира ниво 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, Изграждане с инструменти за програмиране с ИИ, разглежда този процес стъпка по стъпка.
Конекторите са по-тихият съсед. Моделът на знания на домейн пакета се захранва от конектори само за четене към системи като администриране на полици или система за щети, всеки със собствен график и бутон за тестване. Нищо не се записва обратно в източника.
От Вашия клон до екраните на хората
На което и стъпало да се намирате, пътят към продукционна среда е един и същ. Всяка версия преминава от вашата среда за разработка към тестова среда (staging), след това към пилотно звено и накрая към всички звена, като всяка стъпка има контролни бариери: тестове, манифест, който не е разширил правата си, пробно изпълнение върху маскирано копие и поименно посочени рецензенти, различни от автора. Повишаване на версията, което се опитва да прескочи стъпка, се отхвърля с GATE_CANNOT_BE_SKIPPED. Всяка среда пази предишната версия за 30 дни, а връщането на едно звено към стара версия е рецензирана промяна, която отнема около минута.
Самото внедряване преминава единствено през каналите за версии на инсталацията. Звената избират своя канал и техният администратор одобрява всяко преминаване. На страницата „Канали и инсталации“ виждате бройки и честота на грешките по звена, но никога какво е правил някой с вашето разширение. Глава 2.28, Пускане на вашето разширение, обхваща процеса по пускане от край до край.
Бележка относно изданията
По-голямата част от тази стълбица съществува и в двете издания. Community получава настройки и умения в Skills Engine, плъгини на всяко ниво и същите утвърдени пътища на един сървър с код във вашия собствен Git хост. Enterprise добавя придвижването от средата за разработка през тестовата среда до пилотно звено с неговите бариери, плюс клъстери за издатели и маскирани копия на реални данни. То добавя също ваш собствен частен каталог и домейн пакети. Подробностите са в глава 2.25, Изграждане за всяко издание.
Следващата глава е тази, която трябва да прочетете, преди да напишете какъвто и да е код. В нея има малко избори и много правила, а правилата са едни и същи както за първото разширение, така и за хилядното.



