Как работают плагины
Плагин — это исполняемый файл плюс манифест. 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: все поля, включая события, хуки и типизированные операции.
- Выпуск плагина: платформы, бинарные файлы, подпись и обновления.
- Публикация: процесс публикации в маркетплейсе для любого артефакта.