NeboAI
NeboAI
Начать

Справочник по plugin.json

plugin.json — это манифест, который Nebo читает, чтобы установить и запустить плагин. Ключи записываются в camelCase. На этой странице перечислены все поля, которые Nebo читает сегодня, и что делает каждое из них.

Поля верхнего уровня

ПолеТипОбязательноЗначение
idstringдаИдентификатор плагина в маркетплейсе. Во время разработки используйте slug.
slugstringдаПостоянный идентификатор. [a-z0-9-], не более 64 символов, без дефиса в начале, в конце и двойного дефиса. Даёт имя инструменту plugin__<slug> и переменной <SLUG>_BIN.
namestringдаОтображаемое имя. Назовите сервис, к которому он подключается.
versionstringдаСемантическая версия, например 0.1.0.
platformsmapдаКлюч платформы для бинарного файла. См. «Платформы».
descriptionstringнетОдно предложение для людей и сотрудников.
authorstringнетИмя издателя.
categorystringнетПомогает сотрудникам найти плагин.
triggersсписок строкнетСлова, описывающие, когда применяется плагин. Используются в подсказках поиска.
entrySkillsсписок строкнетВстроенные навыки, которые называются первыми в описании инструмента плагина.
dependenciesсписок {name, version, optional}нетДругие плагины, которые запускает этот. version по умолчанию "*"; optional — false. Их пути <SLUG>_BIN задаются при каждом вызове.
authobjectнетВход и аккаунты. См. «Авторизация».
capabilitiesobjectнетconfigSchema, hooks, commands, routes, providers.
permissionsobjectнетФильтрация окружения и предельный тайм-аут.
eventslistнетНаблюдатели, которые питают рабочие процессы сотрудников.
interfaceBindingsmapнетТипизированные операции, которые предоставляет плагин.
channelobjectнетПостоянный мост к сервису обмена сообщениями.
setupobjectнетПошаговый мастер настройки.

Nebo проверяет установки из маркетплейса: правила для slug, семантическую версию, хотя бы одну платформу, binaryName без разделителей пути и .., команду login, если только auth.type не равно env, непустые имена событий и команды, а также разбираемые шаблоны привязок. Плагины в каталоге пользовательских плагинов проверку не проходят.

Платформы

Ключи: darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 и windows-amd64. Каждая запись содержит все пять полей ниже. При публикации маркетплейс записывает настоящие хеш, размер, подпись и URL загрузки, поэтому в загружаемом файле оставьте их пустыми.

"platforms": {
  "darwin-arm64":  { "binaryName": "notes-sync",     "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
  "linux-amd64":   { "binaryName": "notes-sync",     "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
  "windows-amd64": { "binaryName": "notes-sync.exe", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" }
}
ПолеЗначение
binaryNameИмя исполняемого файла. В Windows добавьте .exe.
sha256Хеш бинарного файла. Проверяется при установке.
signatureПодпись бинарного файла. Проверяется при установке, если доступен ключ подписи.
sizeРазмер в байтах.
downloadUrlОткуда Nebo скачивает пакет.

Авторизация

ПолеЗначение
typeoauth_cli — для входа через браузер, который выполняет плагин; env — для учётных данных, вводимых как значения; neboai — чтобы получать токен NeboAI владельца в каждом ключе auth.env, оканчивающемся на _TOKEN.
envСоответствие имени переменной и значения по умолчанию. Это также единственные имена учётных данных, которые Nebo передаёт в login.
commands.loginВыполняет вход. Обязательно, если type не равно env. Запускается с заданной папкой аккаунта.
commands.statusВыводит JSON, который сообщает, выполнен ли вход в аккаунт.
commands.refreshОбновляет токен без участия пользователя.
commands.logoutВыполняет выход. Запустить может только владелец.
profileDirEnvПеременная, которая получает отдельную папку учётных данных для каждого сотрудника и аккаунта. Без неё у плагина один общий аккаунт.
label, descriptionТекст на карточке подключения.
help{url, urlLabel, text}, показываемые во время подключения.
publicRedirectУстановите true, если провайдер не принимает перенаправления на http://localhost; тогда вход идёт через публичное перенаправление NeboAI.

Nebo читает первое из полей authenticated, isAuthenticated, logged_in, loggedIn или token_valid в выводе статуса. Непустое token_error или значение none в credential_source, auth_method, storage или status означает, что вход не выполнен. На команду статуса отводится 45 секунд.

{"authenticated": true, "account": "finance@example.com"}

configSchema

capabilities.configSchema описывает значения, которые владелец задаёт для плагина. Каждое значение попадает в бинарный файл как переменная окружения с именем из key. Для ключей учётных данных, которые также перечислены в auth.env, схема задаёт подписи полей формы подключения для каждого сотрудника.

ПолеТипПо умолчаниюЗначение
keystringобязательноИмя переменной окружения.
labelstringобязательноПодпись поля.
descriptionstring""Текст подсказки.
fieldTypestring"string"Тип ввода, например string, number, boolean, select или password.
defaultstringнетПредзаполненное значение.
requiredbooleanfalseПлагин не готов, пока значение не задано.
secretbooleanfalseПри чтении значение маскируется.
optionsсписок строкнетВарианты для select.

permissions

ПолеПо умолчаниюЗначение
envAllow[]Унаследованные переменные, которые может видеть плагин. Пустой список разрешает все.
envDeny[]Унаследованные переменные, которые всегда удаляются.
maxTimeoutSeconds300Верхний предел тайм-аута любого вызова.
networkfalseОбъявляет использование сети. Носит информационный характер; не применяется принудительно.

events

Событие — это долго работающий наблюдатель. Nebo запускает его, когда рабочий процесс сотрудника следит за ним, и перезапускает, если он завершается. Каждая строка, которую наблюдатель пишет в stdout, — одно событие. Во время работы к имени события добавляется префикс slug, поэтому note.created становится notes-sync.note.created.

"events": [
  {
    "name": "note.created",
    "description": "A note was created in the watched notebook.",
    "command": "watch --notebook {{notebook}} --format ndjson"
  }
]
ПолеЗначение
nameИмя события без slug. Обязательно.
commandАргументы, которые запускают наблюдателя. Обязательно. {{key}} заменяется значениями из входных данных сотрудника.
descriptionЧто вызывает событие.
multiplexedЕсли true, один наблюдатель выдаёт события нескольких типов, и каждая строка содержит поле "event".

Рабочие процессы подписываются на события с помощью триггера watch. См. Триггеры.

interfaceBindings

Привязка сопоставляет операцию интерфейса с одной из ваших команд. Каждая привязка становится для сотрудников типизированным инструментом, названным по операции в нижнем регистре, где точки и дефисы заменены подчёркиваниями: notes.search становится notes_search. Именно через привязки плагин обеспечивает возможности, которые требуются сотруднику; см. Возможности.

"interfaceBindings": {
  "notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
  "invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
}
ЗаполнительРаскрывается в
{field}Значение поля одним словом. Поле не передаётся дополнительно как флаг.
{field[]:--flag}Одна пара --flag <item> для каждого элемента поля-списка.
{field?:--flag}--flag <value>, если поле есть; ничего, если его нет.
{field:cents->dollars}Целая сумма в центах, записанная в долларах.

Входные поля, которые шаблон не называет, добавляются в конце как --field value. Заполнители списков и необязательные заполнители должны быть целыми словами. До операции, требующей одобрения, нельзя добраться, вызвав ту же команду через plugin__<slug>.

Хуки, слэш-команды и маршруты

"capabilities": {
  "hooks": [
    { "hook": "tool.post_execute", "hookType": "filter", "command": "hook redact", "priority": 50, "timeoutMs": 500 }
  ],
  "commands": [
    { "name": "notes", "description": "Show today's notes", "command": "notes today", "slash": true }
  ],
  "routes": [
    { "path": "/callback", "method": "GET", "command": "http callback" }
  ]
}

hooks

Хук запускает вашу команду в определённый момент хода сотрудника. Nebo записывает JSON-данные в stdin. Вывод хука action игнорируется. Хук filter возвращает {"payload": ..., "handled": false}; "handled": true останавливает последующие хуки. При ошибках и тайм-аутах сохраняются прежние данные, и ход никогда не блокируется. После трёх сбоев подряд хук приостанавливается на пять минут.

ПолеПо умолчаниюЗначение
hookобязательноОдно из: tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue.
hookType"action"action или filter.
commandобязательноАргументы для вашего бинарного файла.
priority100Меньшее значение выполняется первым.
timeoutMs500Ограничение времени в миллисекундах.

commands

С "slash": true ввод /name args в чате сразу запускает command args, без участия сотрудника. Вывод становится ответом. Ограничение времени — 30 секунд.

routes

Маршрут отвечает на HTTP-запросы по адресу /api/v1/plugins/<slug>/api/<path> на боте, сопоставляя их по path и method. Тело запроса поступает в stdin, а ваш stdout становится ответом. Ограничение времени — 30 секунд.

providers

Провайдер добавляет источник чат-моделей. Объявите id, displayName, providerType, modelsCommand и chatCommand. Nebo отправляет запрос чата как JSON в stdin команды chatCommand и читает потоковые события как JSON с разделением по строкам из stdout в течение не более 300 секунд. Сегодня используется только потоковая передача чата.

channel

Канал служит мостом к сервису обмена сообщениями. Nebo держит command запущенной, читает входящие сообщения из её stdout и пишет ответы в её stdin, в обоих случаях как JSON с разделением по строкам.

ПолеПо умолчаниюЗначение
commandобязательноАргументы, которые запускают мост.
name, description""Показывается в настройках.
restartDelaySecs5Ожидание перед перезапуском после сбоя.
sharedfalseОдин мост для всех сотрудников; сообщения направляются по имени сотрудника, а ответы несут личность каждого сотрудника.
needsLocalApifalseПередать мосту локальный адрес API бота, токен и id сотрудника. Выключено, если вам это не нужно.

setup

Мастер настройки проводит владельца через шаги, которые не уместить в одну форму. Значения из шагов form подставляются в {{key}} в последующих аргументах generate. Значения из шагов credentials сохраняются как переменные окружения плагина.

"setup": {
  "title": "Connect Example Chat",
  "steps": [
    { "kind": "form", "title": "Bot name", "fields": [ { "key": "bot_name", "label": "Name", "required": true } ] },
    { "kind": "generate", "title": "App manifest", "command": "manifest", "args": ["--name", "{{bot_name}}"], "outputFormat": "yaml" },
    { "kind": "external", "title": "Create the app", "url": "https://example.com/apps", "urlLabel": "Open admin" },
    { "kind": "credentials", "title": "Paste the token", "fields": [ { "key": "EXAMPLE_CHAT_TOKEN", "label": "Token", "inputType": "password", "required": true } ], "verifyCommand": "auth status" }
  ]
}
Вид шагаПоля
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Показывает вывод команды для копирования.
externaltitle, description, url, urlLabel, instructions
credentialstitle, description, fields, verifyCommand. Шаг завершается, когда verifyCommand выполняется успешно.

У полей есть key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) и required.