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» в названии плагина: для сотрудников и владельцев это подключение, а не командная строка.

Далее