Поля верхнего уровня
| Поле | Тип | Обязательно | Значение |
|---|---|---|---|
id | string | да | Идентификатор плагина в маркетплейсе. Во время разработки используйте slug. |
slug | string | да | Постоянный идентификатор. [a-z0-9-], не более 64 символов, без дефиса в начале, в конце и двойного дефиса. Даёт имя инструменту plugin__<slug> и переменной <SLUG>_BIN. |
name | string | да | Отображаемое имя. Назовите сервис, к которому он подключается. |
version | string | да | Семантическая версия, например 0.1.0. |
platforms | map | да | Ключ платформы для бинарного файла. См. «Платформы». |
description | string | нет | Одно предложение для людей и сотрудников. |
author | string | нет | Имя издателя. |
category | string | нет | Помогает сотрудникам найти плагин. |
triggers | список строк | нет | Слова, описывающие, когда применяется плагин. Используются в подсказках поиска. |
entrySkills | список строк | нет | Встроенные навыки, которые называются первыми в описании инструмента плагина. |
dependencies | список {name, version, optional} | нет | Другие плагины, которые запускает этот. version по умолчанию "*"; optional — false. Их пути <SLUG>_BIN задаются при каждом вызове. |
auth | object | нет | Вход и аккаунты. См. «Авторизация». |
capabilities | object | нет | configSchema, hooks, commands, routes, providers. |
permissions | object | нет | Фильтрация окружения и предельный тайм-аут. |
events | list | нет | Наблюдатели, которые питают рабочие процессы сотрудников. |
interfaceBindings | map | нет | Типизированные операции, которые предоставляет плагин. |
channel | object | нет | Постоянный мост к сервису обмена сообщениями. |
setup | object | нет | Пошаговый мастер настройки. |
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 скачивает пакет. |
Авторизация
| Поле | Значение |
|---|---|
type | oauth_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, схема задаёт подписи полей формы подключения для каждого сотрудника.
| Поле | Тип | По умолчанию | Значение |
|---|---|---|---|
key | string | обязательно | Имя переменной окружения. |
label | string | обязательно | Подпись поля. |
description | string | "" | Текст подсказки. |
fieldType | string | "string" | Тип ввода, например string, number, boolean, select или password. |
default | string | нет | Предзаполненное значение. |
required | boolean | false | Плагин не готов, пока значение не задано. |
secret | boolean | false | При чтении значение маскируется. |
options | список строк | нет | Варианты для select. |
permissions
| Поле | По умолчанию | Значение |
|---|---|---|
envAllow | [] | Унаследованные переменные, которые может видеть плагин. Пустой список разрешает все. |
envDeny | [] | Унаследованные переменные, которые всегда удаляются. |
maxTimeoutSeconds | 300 | Верхний предел тайм-аута любого вызова. |
network | false | Объявляет использование сети. Носит информационный характер; не применяется принудительно. |
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 | обязательно | Аргументы для вашего бинарного файла. |
priority | 100 | Меньшее значение выполняется первым. |
timeoutMs | 500 | Ограничение времени в миллисекундах. |
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 | "" | Показывается в настройках. |
restartDelaySecs | 5 | Ожидание перед перезапуском после сбоя. |
shared | false | Один мост для всех сотрудников; сообщения направляются по имени сотрудника, а ответы несут личность каждого сотрудника. |
needsLocalApi | false | Передать мосту локальный адрес 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" }
]
} | Вид шага | Поля |
|---|---|
form | title, description, fields |
generate | title, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Показывает вывод команды для копирования. |
external | title, description, url, urlLabel, instructions |
credentials | title, description, fields, verifyCommand. Шаг завершается, когда verifyCommand выполняется успешно. |
У полей есть key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) и required.