Pola najwyższego poziomu
| Pole | Typ | Wymagane | Znaczenie |
|---|---|---|---|
id | string | tak | Identyfikator wtyczki w sklepie. Podczas tworzenia używaj sluga. |
slug | string | tak | Stały identyfikator. [a-z0-9-], maksymalnie 64 znaki, bez łącznika na początku, na końcu ani podwójnego. Nadaje nazwę narzędziu plugin__<slug> i zmiennej <SLUG>_BIN. |
name | string | tak | Nazwa wyświetlana. Podaj usługę, z którą się łączy. |
version | string | tak | Wersja semantyczna, np. 0.1.0. |
platforms | map | tak | Klucz platformy przypisany do pliku binarnego. Zobacz Platformy. |
description | string | nie | Jedno zdanie dla ludzi i pracowników. |
author | string | nie | Nazwa wydawcy. |
category | string | nie | Pomaga pracownikom znaleźć wtyczkę. |
triggers | lista ciągów znaków | nie | Słowa opisujące, kiedy wtyczka ma zastosowanie. Używane w podpowiedziach wyszukiwania. |
entrySkills | lista ciągów znaków | nie | Dołączone umiejętności wymieniane jako pierwsze w opisie narzędzia wtyczki. |
dependencies | lista {name, version, optional} | nie | Inne wtyczki, które ta wtyczka uruchamia. version domyślnie ma wartość "*"; optional — false. Ich ścieżki <SLUG>_BIN są ustawiane przy każdym wywołaniu. |
auth | object | nie | Logowanie i konta. Zobacz Uwierzytelnianie. |
capabilities | object | nie | configSchema, hooks, commands, routes, providers. |
permissions | object | nie | Filtrowanie środowiska i górny limit czasu. |
events | list | nie | Obserwatory, które zasilają przepływy pracy pracowników. |
interfaceBindings | map | nie | Operacje typowane udostępniane przez wtyczkę. |
channel | object | nie | Stały most do usługi komunikacyjnej. |
setup | object | nie | Kreator konfiguracji krok po kroku. |
Nebo weryfikuje instalacje ze sklepu: reguły sluga, wersję semantyczną, co najmniej jedną platformę, binaryName bez separatorów ścieżki ani .., polecenie login, chyba że auth.type to env, niepuste nazwy zdarzeń i polecenia oraz szablony powiązań, które dają się przetworzyć. Wtyczki w katalogu wtyczek użytkownika pomijają weryfikację.
Platformy
Klucze to darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 i windows-amd64. Każdy wpis ma wszystkie pięć poniższych pól. Gdy publikujesz, sklep zapisuje prawdziwy skrót, rozmiar, podpis i adres URL pobierania, więc w przesyłanym pliku zostaw je puste.
"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": "" }
} | Pole | Znaczenie |
|---|---|
binaryName | Nazwa pliku wykonywalnego. W Windows dodaj .exe. |
sha256 | Skrót pliku binarnego. Sprawdzany przy instalacji. |
signature | Podpis pliku binarnego. Sprawdzany przy instalacji, gdy dostępny jest klucz podpisu. |
size | Rozmiar w bajtach. |
downloadUrl | Skąd Nebo pobiera pakiet. |
Uwierzytelnianie
| Pole | Znaczenie |
|---|---|
type | oauth_cli dla logowania w przeglądarce prowadzonego przez wtyczkę; env dla danych logowania wpisywanych jako wartości; neboai, aby otrzymywać token NeboAI właściciela w każdym kluczu auth.env kończącym się na _TOKEN. |
env | Mapa nazw zmiennych na wartości domyślne. To także jedyne nazwy danych logowania, które Nebo przekazuje do login. |
commands.login | Loguje. Wymagane, chyba że type to env. Uruchamiane z ustawionym folderem konta. |
commands.status | Wyświetla JSON informujący, czy konto jest zalogowane. |
commands.refresh | Odnawia token bez interakcji. |
commands.logout | Wylogowuje. Może je uruchomić tylko właściciel. |
profileDirEnv | Zmienna, która otrzymuje osobny folder danych logowania dla każdego pracownika i konta. Bez niej wtyczka ma jedno wspólne konto. |
label, description | Tekst na karcie połączenia. |
help | {url, urlLabel, text} wyświetlane podczas łączenia. |
publicRedirect | Ustaw true, gdy dostawca odrzuca przekierowania na http://localhost; logowanie przechodzi wtedy przez publiczne przekierowanie NeboAI. |
Nebo odczytuje pierwsze z pól authenticated, isAuthenticated, logged_in, loggedIn lub token_valid w danych wyjściowych statusu. Niepusty token_error albo wartość none w credential_source, auth_method, storage lub status oznacza wylogowanie. Polecenie statusu ma 45 sekund.
{"authenticated": true, "account": "finance@example.com"} configSchema
capabilities.configSchema opisuje wartości, które właściciel ustawia dla wtyczki. Każda wartość trafia do pliku binarnego jako zmienna środowiskowa o nazwie podanej w key. Dla kluczy danych logowania wymienionych także w auth.env schemat nadaje etykiety polom formularza połączenia dla poszczególnych pracowników.
| Pole | Typ | Domyślnie | Znaczenie |
|---|---|---|---|
key | string | wymagane | Nazwa zmiennej środowiskowej. |
label | string | wymagane | Etykieta pola. |
description | string | "" | Tekst pomocy. |
fieldType | string | "string" | Typ pola, np. string, number, boolean, select lub password. |
default | string | brak | Wstępnie wypełniona wartość. |
required | boolean | false | Wtyczka nie jest gotowa, dopóki wartość nie zostanie ustawiona. |
secret | boolean | false | Wartość jest maskowana przy odczycie. |
options | lista ciągów znaków | brak | Opcje dla select. |
permissions
| Pole | Domyślnie | Znaczenie |
|---|---|---|
envAllow | [] | Dziedziczone zmienne, które wtyczka może widzieć. Pusta lista pozwala na wszystkie. |
envDeny | [] | Dziedziczone zmienne, które są zawsze usuwane. |
maxTimeoutSeconds | 300 | Górny limit czasu dowolnego wywołania. |
network | false | Deklaruje korzystanie z sieci. Informacyjnie; nie jest egzekwowane. |
events
Zdarzenie to długo działający obserwator. Nebo uruchamia go, gdy przepływ pracy pracownika go obserwuje, i uruchamia ponownie, jeśli się zakończy. Każdy wiersz, który obserwator zapisuje na stdout, to jedno zdarzenie. W czasie działania nazwa zdarzenia dostaje przedrostek ze slugiem, więc note.created staje się notes-sync.note.created.
"events": [
{
"name": "note.created",
"description": "A note was created in the watched notebook.",
"command": "watch --notebook {{notebook}} --format ndjson"
}
] | Pole | Znaczenie |
|---|---|
name | Nazwa zdarzenia bez sluga. Wymagane. |
command | Argumenty uruchamiające obserwatora. Wymagane. {{key}} jest zastępowane wartościami wejściowymi pracownika. |
description | Co wywołuje zdarzenie. |
multiplexed | Gdy true, jeden obserwator emituje kilka typów zdarzeń, a każdy wiersz zawiera pole "event". |
Przepływy pracy subskrybują zdarzenia za pomocą wyzwalacza watch. Zobacz Wyzwalacze.
interfaceBindings
Powiązanie przypisuje operację interfejsu do jednego z Twoich poleceń. Każde powiązanie staje się typowanym narzędziem dla pracowników, nazwanym tak jak operacja, małymi literami, z kropkami i łącznikami zamienionymi na podkreślenia: notes.search staje się notes_search. Za pomocą powiązań wtyczka spełnia możliwości wymagane przez pracownika; zobacz Możliwości.
"interfaceBindings": {
"notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
"invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
} | Symbol zastępczy | Rozwija się do |
|---|---|
{field} | Wartość pola jako jedno słowo. Pole nie jest dodatkowo przekazywane jako flaga. |
{field[]:--flag} | Jedna para --flag <item> dla każdego elementu pola listy. |
{field?:--flag} | --flag <value>, gdy pole jest obecne; nic, gdy go brak. |
{field:cents->dollars} | Kwota całkowita w centach zapisana w dolarach. |
Pola wejściowe, których szablon nie wymienia, są dopisywane jako --field value. Symbole zastępcze list i pól opcjonalnych muszą być całymi słowami. Operacji wymagającej zatwierdzenia nie da się wywołać, uruchamiając to samo polecenie przez plugin__<slug>.
Hooki, polecenia z ukośnikiem i trasy
"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
Hook uruchamia Twoje polecenie w określonym momencie tury pracownika. Nebo zapisuje ładunek JSON na stdin. Wynik hooka action jest ignorowany. Hook filter zwraca {"payload": ..., "handled": false}; "handled": true zatrzymuje kolejne hooki. Błędy i przekroczenia czasu zachowują poprzedni ładunek i nigdy nie blokują tury. Po trzech niepowodzeniach z rzędu hook jest wstrzymywany na pięć minut.
| Pole | Domyślnie | Znaczenie |
|---|---|---|
hook | wymagane | Jedno z: tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue. |
hookType | "action" | action lub filter. |
command | wymagane | Argumenty dla Twojego pliku binarnego. |
priority | 100 | Niższa wartość uruchamia się pierwsza. |
timeoutMs | 500 | Limit czasu w milisekundach. |
commands
Przy "slash": true wpisanie /name args w czacie uruchamia bezpośrednio command args, bez udziału pracownika. Dane wyjściowe są odpowiedzią. Limit czasu wynosi 30 sekund.
routes
Trasa odpowiada na żądania HTTP pod adresem /api/v1/plugins/<slug>/api/<path> na bocie, dopasowywane według path i method. Treść żądania trafia na stdin, a Twoje stdout jest odpowiedzią. Limit czasu wynosi 30 sekund.
providers
Dostawca dodaje źródło modeli czatu. Zadeklaruj id, displayName, providerType, modelsCommand i chatCommand. Nebo wysyła żądanie czatu jako JSON na stdin do chatCommand i odczytuje strumieniowane zdarzenia jako JSON rozdzielany znakami nowego wiersza na stdout, przez maksymalnie 300 sekund. Obecnie używane jest tylko strumieniowanie czatu.
channel
Kanał łączy z usługą komunikacyjną. Nebo utrzymuje działające command, odczytuje wiadomości przychodzące z jego stdout i zapisuje odpowiedzi na jego stdin, w obu przypadkach jako JSON rozdzielany znakami nowego wiersza.
| Pole | Domyślnie | Znaczenie |
|---|---|---|
command | wymagane | Argumenty uruchamiające most. |
name, description | "" | Wyświetlane w ustawieniach. |
restartDelaySecs | 5 | Czas oczekiwania przed ponownym uruchomieniem po awarii. |
shared | false | Jeden most dla wszystkich pracowników; wiadomości są kierowane według nazwy pracownika, a odpowiedzi niosą tożsamość każdego pracownika. |
needsLocalApi | false | Przekaż mostowi lokalny adres API bota, token i identyfikator pracownika. Wyłączone, chyba że tego potrzebujesz. |
setup
Kreator konfiguracji prowadzi właściciela przez kroki, których nie obejmie pojedynczy formularz. Wartości z kroków form wypełniają {{key}} w późniejszych argumentach generate. Wartości z kroków credentials są zapisywane jako zmienne środowiskowe wtyczki.
"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" }
]
} | Rodzaj kroku | Pola |
|---|---|
form | title, description, fields |
generate | title, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Pokazuje dane wyjściowe polecenia do skopiowania. |
external | title, description, url, urlLabel, instructions |
credentials | title, description, fields, verifyCommand. Krok kończy się, gdy verifyCommand zakończy się powodzeniem. |
Pola mają key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) i required.