NeboAI
NeboAI
Почати

Плагіни

Плагін дає співробітникам те, з чим можна працювати: онлайн-службу, бізнес-систему або програму на комп'ютері. Ви створюєте його як бінарний файл командного рядка й описуєте маніфестом plugin.json. Співробітники викликають його команди, а Nebo бере на себе встановлення, акаунти для кожного співробітника й оновлення.

Як працюють плагіни

Плагін — це виконуваний файл плюс маніфест. Між викликами 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.
timeoutintegerСкільки секунд чекати. За замовчуванням 120, обмежено значенням permissions.maxTimeoutSeconds у маніфесті.
displaystringРечення, яке бачить власник, коли виклик потребує схвалення.

Створіть свій перший плагін

Напишіть бінарний файл будь-якою мовою, який читає команду з аргументів і виводить результат. Потім покладіть його поруч із 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 }
  ]
}
  1. auth.env називає облікові дані. capabilities.configSchema дає їм підписи й задає їхній порядок у формі підключення.
  2. auth.profileDirEnv називає змінну, з якої ваш плагін читає папку облікових даних. Nebo створює одну папку для кожного співробітника й акаунта та задає цю змінну під час кожного виклику.
  3. Коли власник підключає акаунт, Nebo запускає вашу команду login зі значеннями, які ввів власник, і заданою папкою акаунта. Ваш плагін зберігає в цій папці все потрібне. Nebo цих значень не зберігає.
  4. Ваша команда status виводить JSON, наприклад {"authenticated": true}. Коли строк дії токена спливає, Nebo запускає refresh, якщо ви її оголосили.

Для входу через браузер установіть type як oauth_cli, і нехай login виводить або відкриває URL входу провайдера. Співробітники ніколи не входять самостійно: коли виклик потребує входу, власник бачить картку підключення. Співробітник із кількома акаунтами вибирає один, додаючи до команди --account <label>. Nebo вилучає цей прапорець, перш ніж його побачить ваш бінарний файл.

Називайте службу, а не форму. Назва плагіна говорить, до чого він підключається, наприклад «Example Notes». Ніколи не додавайте «CLI» до назви плагіна; для співробітників і власників це підключення, а не командний рядок.

Далі