Версія 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. - Галузеві пакети. Ракурси (lenses) і шаблони для конкретної галузі, її навички та модель знань, її конектори й екрани для мобільних телефонів, що ліцензуються як єдине ціле. Adverant постачає десять таких пакетів; ви можете створити власний.
- Ракурси. Те, що бачить користувач з певною роллю всередині пакета чи платформи. Ракурс звужує базовий ракурс і ніколи не розширює його.
- З'єднання та конектори MCP. Інструменти протоколу Model Context Protocol (MCP), які публікує плагін або через які підключається ШІ-інструмент для написання коду, а також конектори лише для читання, що імпортують записи із систем, які ви вже використовуєте.
Два терміни часто плутають, тож розберімося з ними одразу. Навичка Skills Engine — це пакет SKILL.md у бібліотеці. Навичка маніфесту — це типізований запис у масиві skills[] плагіна, скомпільований у реєстр навичок платформи, який запускається через UNO — рушій робочих процесів. На екрані обидва варіанти називаються навичками. Вони пишуться та контролюються по-різному, і в цій документації завжди чітко вказано, про яку саме йдеться.
Що може і чого не може кожен елемент
Таблиця нижче — це стислий огляд. Я навмисно додав стовпець «Чого не може робити»: кожне обмеження є продуманою властивістю архітектури, і кожне з них свого часу вберегло мене від помилок.
| Будівельний блок | Що може робити | Чого не може робити | Хто створює |
|---|---|---|---|
| Налаштування або політика | Змінювати поведінку функції на будь-якому рівні — від усієї організації до однієї особи; блокувати значення; делегувати його на нижчий рівень; вимагати підтвердження другою особою для внесення змін | Додавати екран або маршрут, зберігати нову таблицю чи запускати новий вид робіт | Адміністратор у консолі |
| Навичка Skills Engine | Давати асистенту, агентам, робочим процесам і кнопкам ШІ повторюваний спосіб виконання одного завдання з власними інструкціями та тестовими прикладами | Зберігати облікові дані; викликати інструмент поза білим списком особи, яка його запускає (SKILL_CANNOT_WIDEN_TOOLS); ставати активною без проходження тестів і схвалення |
Будь-хто з відповідним правом — у конструкторі або зі свого IDE |
Плагін, skills-only |
Публікувати навички маніфесту, що виконуються на платформі: зворотні виклики хоста, завдання в черзі, обхід списку (map) і — за рівня довіри core або verified — навички з підтримкою моделей |
Обслуговувати власні сторінки | Розробник за допомогою SDK |
Плагін, ui-only |
Додавати фронтенд-інтерфейс усередині оболонки | Зберігати власні дані або виконувати обчислення | Розробник за допомогою SDK |
Плагін, full-service |
Мати власний бекенд і фронтенд, схему Postgres, таблицю маршрутів із правами доступу, а також навички та інструменти MCP | Викликати провайдера моделей напряму; зберігати ключ моделі; читати рядки іншої організації, крім як через зафіксований дозвіл; виконувати обчислення поза диспетчеризацією UNO | Розробник за допомогою SDK |
| Галузевий пакет | Надавати вибраним адміністратором підрозділам галузеві ракурси й шаблони, навички та робочі процеси, модель знань, карту доказів і екрани для мобільних телефонів | Змінювати оболонку чи її компоненти або правила оформлення тексту; працювати, якщо це не передбачено ліцензією організації | Adverant або ваші власні розробники в редакції Enterprise |
| Ракурс | Вибирати картки й поля, які бачить певна роль у пакеті чи на платформі, а також доступні їй дії | Показувати будь-що приховане базовим ракурсом (LENS_CANNOT_WIDEN); змінювати те, що дозволено робити ролі |
Автор пакета створює його; адміністратор призначає його на рівні підрозділу |
| Інструменти та конектори MCP | Відкривати інструменти плагіна для агентів та інструментів написання коду; читати записи із системи політик або архіву телеметрії в модель знань | Записувати дані назад у вихідну систему через конектор; діяти за межами власних дозволів авторизованого користувача | Розробник оголошує інструменти MCP; адміністратор налаштовує конектори |
Кілька клітинок цієї таблиці варті окремого речення.
Налаштування — це фреймворк, і кожен плагін використовує один і той самий. Плагін, який оголошує блок settings у своєму маніфесті, отримує рівні ієрархії (платформа, організація, пакет, підрозділ, група, репозиторій, особа), блокування та делегування, журнал змін і підтвердження другою особою — і все це без написання власної таблиці налаштувань. Ось чому найпростішого щабля часто достатньо: якщо потрібна вам поведінка вже існує і потребує лише іншого значення для підрозділу в Rotterdam, це просто налаштування.
Навичка Skills Engine виконується від імені користувача. Вона ніколи не зберігає ключів, може звертатися лише до інструментів із білого списку того, хто її запускає, і читати лише те, що ця особа має право відкривати. Навичка, яка додає інструмент із правом запису, затримується, доки її не схвалять дві особи, після чого запускається спочатку в тіньовому режимі (shadow), потім у канарковому (canary), і лише тоді — для всіх.
Плагін рівня skills-only — це середній щабель. Він потрібен, коли робота виконується вашим власним кодом: детерміноване обчислення, обробник черги, паралельна обробка списку (fan-out). Платформа викликає ваш код; ваш код ніколи не викликає модель.
Плагін рівня 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, які вони викликають;
- плагіни — там, де пакету потрібен власний код;
- конектори лише для читання до систем, у яких уже зберігаються записи;
- мобільна надбудова (overlay), яка визначає, які картки та кроки збору даних відображаються на телефонах;
- і права доступу за ліцензією (entitlement): групи функцій, які має включати ліцензія, перш ніж будь-що з цього увімкнеться.
Жоден із цих елементів не потребує написання інфраструктурного коду для кожного окремого застосунку. Пакет не містить власного коду ізоляції, клієнта моделей чи перевірки ліцензії — він успадковує їх від платформи. Це тема наступного розділу, і саме тому автор пакета в банку й автор пакета в порту пишуть однакову кількість коду безпеки — жодного рядка.
Рівні довіри
Кожен плагін оголошує рівень довіри (trust) у своєму маніфесті. Довіра — це не пропускний пункт, який SDK може обійти за допомогою аргументів. Це довідкові метадані, які платформа читає, щоб вирішити, наскільки ізольовано виконуватимуться компоненти плагіна і до наскільки чутливих даних можуть мати доступ його навички. Активні бар'єри безпеки (класифікація та локалізація даних, експорт і витрати) залишаються точно на своїх місцях.
| Рівень довіри | Для кого він призначений | Режим ізоляції | Максимальний рівень класифікації |
|---|---|---|---|
core |
Власний код платформи, що постачається разом із нею | none: спільне джерело (same-origin), без додаткової ізоляції |
restricted |
verified |
Перевірений сторонній розробник, верифікований видавець | Поверхня same-origin, навички через посередника (brokered) |
restricted |
community |
Неперевірений сторонній розробник; значення за замовчуванням для нового плагіна | Поверхня sandboxed, навички через посередника (brokered) |
tenant |
untrusted |
Будь-що з невідомого джерела | strict: ізольована в пісочниці поверхня, навички лише через посередника, без довіри хоста |
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 |
Захищений (hardened) контейнер у власних подах плагіна; значення за замовчуванням у шаблоні |
| 4 | firecracker |
МікроВМ (microVM) — найвищий рівень ізоляції |
"runtime": {
"nodeVersion": "20",
"executionMode": "hardened_docker",
"isolationLevel": 3,
"entrypoint": "dist/server.js",
"healthCheck": "/health"
}Поле entrypoint є обов'язковим. Точки входу (entrypoints) є артефактами постачання і ніколи не завантажуються під час виконання: у 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 «Розробка за допомогою ШІ-інструментів для написання коду» цей процес розглянуто покроково.
Конектори — це менш помітні сусіди. Модель знань галузевого пакета наповнюється через конектори лише для читання із зовнішніх систем (наприклад, системи адміністрування полісів або системи врегулювання збитків), кожен із яких має власний розклад і кнопку тестування. У вихідну систему нічого назад не записується.
Від вашої гілки коду до екранів користувачів
На якому б щаблі ви не перебували, шлях до продуктивного середовища завжди однаковий. Кожен реліз проходить шлях із вашого середовища розробки (dev space) до тестового середовища (staging), потім до пілотного підрозділу, а відтак — до всіх підрозділів, і на кожному етапі діють контрольні точки (gates): тести, перевірка того, що маніфест не розширив повноваження, пробний запуск на маскованій копії даних і призначені рецензенти, які не є авторами змін. Спроба просування, яка перестрибує через етап, відхиляється з помилкою GATE_CANNOT_BE_SKIPPED. Кожне середовище зберігає попередню версію протягом 30 днів, а відкат одного підрозділу до попередньої версії — це контрольована рецензентом зміна, яка займає близько хвилини.
Саме розгортання відбувається виключно через канали релізів інсталяції. Підрозділи обирають свій канал, а їхній адміністратор погоджує кожен перехід. На сторінці «Канали та встановлення» ви бачите лише кількість установок і частоту помилок за підрозділами, але ніколи не бачите, що саме користувачі робили за допомогою вашого розширення. У розділі 2.28 «Випуск вашого розширення» процес релізу описано від початку до кінця.
Примітка щодо редакцій
Більша частина цих сходів доступна в обох редакціях. Редакція Community отримує налаштування та навички Skills Engine, плагіни всіх рівнів і ті самі еталонні шляхи на одному сервері з розміщенням коду на вашому власному Git-хостингу. Редакція Enterprise додає просування із середовища розробки через staging до пілотного підрозділу з усіма контрольними точками, а також кластери видавців і масковані копії робочих даних. Крім того, вона додає ваш власний приватний каталог і галузеві пакети. Деталі наведено в розділі 2.25 «Розробка для кожної редакції».
Наступний розділ обов'язково варто прочитати перед тим, як ви напишете перший рядок коду. У ньому мало варіантів вибору, проте багато правил, і ці правила однакові як для першого розширення, так і для тисячного.



