NeboAI
NeboAI
Zacznij

Dokumentacja plugin.json

plugin.json to manifest, który Nebo odczytuje, aby zainstalować i uruchomić wtyczkę. Klucze są w notacji camelCase. Ta strona wymienia każde pole, które Nebo dziś odczytuje, i opisuje, do czego służy.

Pola najwyższego poziomu

PoleTypWymaganeZnaczenie
idstringtakIdentyfikator wtyczki w sklepie. Podczas tworzenia używaj sluga.
slugstringtakStał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.
namestringtakNazwa wyświetlana. Podaj usługę, z którą się łączy.
versionstringtakWersja semantyczna, np. 0.1.0.
platformsmaptakKlucz platformy przypisany do pliku binarnego. Zobacz Platformy.
descriptionstringnieJedno zdanie dla ludzi i pracowników.
authorstringnieNazwa wydawcy.
categorystringniePomaga pracownikom znaleźć wtyczkę.
triggerslista ciągów znakównieSłowa opisujące, kiedy wtyczka ma zastosowanie. Używane w podpowiedziach wyszukiwania.
entrySkillslista ciągów znakównieDołączone umiejętności wymieniane jako pierwsze w opisie narzędzia wtyczki.
dependencieslista {name, version, optional}nieInne 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.
authobjectnieLogowanie i konta. Zobacz Uwierzytelnianie.
capabilitiesobjectnieconfigSchema, hooks, commands, routes, providers.
permissionsobjectnieFiltrowanie środowiska i górny limit czasu.
eventslistnieObserwatory, które zasilają przepływy pracy pracowników.
interfaceBindingsmapnieOperacje typowane udostępniane przez wtyczkę.
channelobjectnieStały most do usługi komunikacyjnej.
setupobjectnieKreator 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": "" }
}
PoleZnaczenie
binaryNameNazwa pliku wykonywalnego. W Windows dodaj .exe.
sha256Skrót pliku binarnego. Sprawdzany przy instalacji.
signaturePodpis pliku binarnego. Sprawdzany przy instalacji, gdy dostępny jest klucz podpisu.
sizeRozmiar w bajtach.
downloadUrlSkąd Nebo pobiera pakiet.

Uwierzytelnianie

PoleZnaczenie
typeoauth_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.
envMapa nazw zmiennych na wartości domyślne. To także jedyne nazwy danych logowania, które Nebo przekazuje do login.
commands.loginLoguje. Wymagane, chyba że type to env. Uruchamiane z ustawionym folderem konta.
commands.statusWyświetla JSON informujący, czy konto jest zalogowane.
commands.refreshOdnawia token bez interakcji.
commands.logoutWylogowuje. Może je uruchomić tylko właściciel.
profileDirEnvZmienna, która otrzymuje osobny folder danych logowania dla każdego pracownika i konta. Bez niej wtyczka ma jedno wspólne konto.
label, descriptionTekst na karcie połączenia.
help{url, urlLabel, text} wyświetlane podczas łączenia.
publicRedirectUstaw 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.

PoleTypDomyślnieZnaczenie
keystringwymaganeNazwa zmiennej środowiskowej.
labelstringwymaganeEtykieta pola.
descriptionstring""Tekst pomocy.
fieldTypestring"string"Typ pola, np. string, number, boolean, select lub password.
defaultstringbrakWstępnie wypełniona wartość.
requiredbooleanfalseWtyczka nie jest gotowa, dopóki wartość nie zostanie ustawiona.
secretbooleanfalseWartość jest maskowana przy odczycie.
optionslista ciągów znakówbrakOpcje dla select.

permissions

PoleDomyślnieZnaczenie
envAllow[]Dziedziczone zmienne, które wtyczka może widzieć. Pusta lista pozwala na wszystkie.
envDeny[]Dziedziczone zmienne, które są zawsze usuwane.
maxTimeoutSeconds300Górny limit czasu dowolnego wywołania.
networkfalseDeklaruje 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"
  }
]
PoleZnaczenie
nameNazwa zdarzenia bez sluga. Wymagane.
commandArgumenty uruchamiające obserwatora. Wymagane. {{key}} jest zastępowane wartościami wejściowymi pracownika.
descriptionCo wywołuje zdarzenie.
multiplexedGdy 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ępczyRozwija 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.

PoleDomyślnieZnaczenie
hookwymaganeJedno 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.
commandwymaganeArgumenty dla Twojego pliku binarnego.
priority100Niższa wartość uruchamia się pierwsza.
timeoutMs500Limit 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.

PoleDomyślnieZnaczenie
commandwymaganeArgumenty uruchamiające most.
name, description""Wyświetlane w ustawieniach.
restartDelaySecs5Czas oczekiwania przed ponownym uruchomieniem po awarii.
sharedfalseJeden most dla wszystkich pracowników; wiadomości są kierowane według nazwy pracownika, a odpowiedzi niosą tożsamość każdego pracownika.
needsLocalApifalsePrzekaż 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 krokuPola
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Pokazuje dane wyjściowe polecenia do skopiowania.
externaltitle, description, url, urlLabel, instructions
credentialstitle, 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.