Поля верхнього рівня
| Поле | Тип | Обов'язкове | Значення |
|---|---|---|---|
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.