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.