Як працюють плагіни
Плагін — це виконуваний файл плюс маніфест. Між викликами Nebo не тримає жодного процесу плагіна. Щоразу, коли співробітник використовує плагін, Nebo запускає бінарний файл із командою й аргументами, чекає на його завершення й передає вивід співробітнику.
- Команди — це аргументи. Співробітник вибирає команду, наприклад
notes search, та іменовані аргументи. Nebo передає кожен аргумент як--name value. Оболонки немає, тож канали й переспрямування ніколи не застосовуються. - Вивід — це stdout. Пишіть результати в stdout. JSON добре підходить.
- Стандартний ввід закрито для звичайних викликів. Хуки, маршрути й провайдери чату використовують stdin; див. довідник plugin.json.
Кожен установлений і ввімкнений плагін бачать співробітники як один інструмент із назвою plugin__<slug>. Співробітник викликає його так:
{
"command": "notes search",
"args": { "query": "quarterly plan", "limit": "5" },
"display": "Search notes for the quarterly plan"
} Nebo виконує:
notes-sync notes search --query "quarterly plan" --limit 5
| Параметр | Тип | Значення |
|---|---|---|
command | рядок, обов'язковий | Команда плагіна й будь-які позиційні слова. |
args | об'єкт рядків | Іменовані аргументи. Кожен стає --key value. |
timeout | integer | Скільки секунд чекати. За замовчуванням 120, обмежено значенням permissions.maxTimeoutSeconds у маніфесті. |
display | string | Речення, яке бачить власник, коли виклик потребує схвалення. |
Створіть свій перший плагін
Напишіть бінарний файл будь-якою мовою, який читає команду з аргументів і виводить результат. Потім покладіть його поруч із plugin.json у каталог користувацьких плагінів бота.
<data>/user/plugins/notes-sync/
├── plugin.json # runtime manifest
├── notes-sync # your binary, named after the slug
└── skills/ # optional: skills that teach employees to use it
└── notes-sync/
└── SKILL.md {
"id": "notes-sync",
"slug": "notes-sync",
"name": "Notes Sync",
"version": "0.1.0",
"description": "Search, read and create notes in Example Notes.",
"platforms": {}
} id, slug, name, version і platforms обов'язкові. У каталозі користувацьких плагінів словник platforms може бути порожнім: Nebo шукає бінарний файл, названий за slug, поруч із plugin.json, а потім у target/release/ і target/debug/. Під час публікації маркетплейс заповнює platforms для кожного вивантаженого бінарного файлу.
<data> — це ~/Library/Application Support/Nebo на macOS, %APPDATA%\Nebo на Windows і ~/.local/share/nebo на Linux або значення NEBO_HOME. Плагін у користувацькому каталозі замінює плагін із маркетплейсу з тим самим slug, тому саме там зручно тестувати нову збірку.
Навчіть співробітників ним користуватися
Покладіть папку skills/ поруч із plugin.json. Кожна навичка в ній доступна всім співробітникам, поки плагін установлено, і автоматично зазначає плагін як залежність. Опишіть у навичці, які команди існують, що вони повертають і коли використовувати кожну. Назвіть найкорисніші навички в entrySkills, щоб опис інструмента плагіна вказував на них першими.
Сторінка в маркетплейсі — це окремий файл, PLUGIN.md. Nebo не читає його під час роботи; це сторінка, яку люди бачать перед установленням. Див. Випуск плагіна.
Середовище
Кожен виклик успадковує середовище бота без змінних завантажувача й тих, що дозволяють ін'єкції в оболонку, а потім додає ці значення. Пізніші записи мають пріоритет.
| Змінна | Значення |
|---|---|
Ключі auth.env | Значення за замовчуванням із маніфесту. |
<SLUG>_BIN | Шлях до бінарного файлу цього плагіна й кожного плагіна, від якого він залежить. Slug пишеться великими літерами, а дефіси замінено підкресленнями. |
NEBO_DATA_DIR | Власна папка даних плагіна, <data>/appdata/plugins/<slug>/. Це також робочий каталог, і він зберігається після видалення. |
PATH | Спочатку папки плагінів, потім успадкований шлях. |
| Налаштування | Значення, які власник зберіг для полів configSchema. |
NEBO_AGENT_ID | Співробітник, який виконує виклик. |
profileDirEnv | Папка акаунта для цього співробітника й акаунта, якщо плагін підтримує акаунти. |
permissions.envAllow і permissions.envDeny звужують те, що плагін успадковує від бота. Вони ніколи не вилучають власні змінні автентифікації плагіна.
Акаунти й облікові дані
Плагін, який входить у службу, повинен мати окремий акаунт для кожного співробітника. Бухгалтер входить із фінансовим логіном, а асистент — зі своїм, і жоден не бачить токенів іншого. Ви оголошуєте це в маніфесті; решту робить Nebo.
"auth": {
"type": "env",
"label": "Example Notes account",
"env": { "EXAMPLE_NOTES_TOKEN": "" },
"commands": { "login": "auth login", "status": "auth status", "logout": "auth logout" },
"profileDirEnv": "EXAMPLE_NOTES_CONFIG_DIR"
},
"capabilities": {
"configSchema": [
{ "key": "EXAMPLE_NOTES_TOKEN", "label": "API token", "fieldType": "password", "secret": true, "required": true }
]
} auth.envназиває облікові дані.capabilities.configSchemaдає їм підписи й задає їхній порядок у формі підключення.auth.profileDirEnvназиває змінну, з якої ваш плагін читає папку облікових даних. Nebo створює одну папку для кожного співробітника й акаунта та задає цю змінну під час кожного виклику.- Коли власник підключає акаунт, Nebo запускає вашу команду
loginзі значеннями, які ввів власник, і заданою папкою акаунта. Ваш плагін зберігає в цій папці все потрібне. Nebo цих значень не зберігає. - Ваша команда
statusвиводить JSON, наприклад{"authenticated": true}. Коли строк дії токена спливає, Nebo запускаєrefresh, якщо ви її оголосили.
Для входу через браузер установіть type як oauth_cli, і нехай login виводить або відкриває URL входу провайдера. Співробітники ніколи не входять самостійно: коли виклик потребує входу, власник бачить картку підключення. Співробітник із кількома акаунтами вибирає один, додаючи до команди --account <label>. Nebo вилучає цей прапорець, перш ніж його побачить ваш бінарний файл.
Називайте службу, а не форму. Назва плагіна говорить, до чого він підключається, наприклад «Example Notes». Ніколи не додавайте «CLI» до назви плагіна; для співробітників і власників це підключення, а не командний рядок.
Далі
- Довідник plugin.json: кожне поле, зокрема події, хуки й типізовані операції.
- Випуск плагіна: платформи, бінарні файли, підписування й оновлення.
- Публікація: процес у маркетплейсі для кожного артефакту.