NeboAI
NeboAI
Zacznij

Wtyczki

Wtyczka daje pracownikom coś, na czym mogą działać: usługę online, system firmowy albo program na komputerze. Budujesz ją jako plik binarny wiersza poleceń i opisujesz manifestem plugin.json. Pracownicy wywołują jej polecenia, a Nebo zajmuje się instalacją, kontami poszczególnych pracowników i aktualizacjami.

Jak działają wtyczki

Wtyczka to plik wykonywalny plus manifest. Nebo nie utrzymuje procesu wtyczki między wywołaniami. Za każdym razem, gdy pracownik korzysta z wtyczki, Nebo uruchamia plik binarny z poleceniem i argumentami, czeka, aż się zakończy, i przekazuje dane wyjściowe pracownikowi.

  • Polecenia to argumenty. Pracownik wybiera polecenie, np. notes search, i nazwane argumenty. Nebo przekazuje każdy argument jako --name value. Nie ma powłoki, więc potoki i przekierowania nigdy nie działają.
  • Dane wyjściowe to stdout. Zapisuj wyniki na stdout. JSON sprawdza się dobrze.
  • Standardowe wejście jest zamknięte przy zwykłych wywołaniach. Hooki, trasy i dostawcy czatu używają stdin; zobacz dokumentację plugin.json.

Każda zainstalowana i włączona wtyczka jest widoczna dla pracowników jako jedno narzędzie o nazwie plugin__<slug>. Pracownik wywołuje je tak:

{
  "command": "notes search",
  "args": { "query": "quarterly plan", "limit": "5" },
  "display": "Search notes for the quarterly plan"
}

Nebo uruchamia:

notes-sync notes search --query "quarterly plan" --limit 5
ParametrTypZnaczenie
commandciąg znaków, wymaganePolecenie wtyczki i ewentualne słowa pozycyjne.
argsobiekt ciągów znakówNazwane argumenty. Każdy staje się --key value.
timeoutintegerCzas oczekiwania w sekundach. Domyślnie 120, ograniczony przez permissions.maxTimeoutSeconds w manifeście.
displaystringZdanie, które widzi właściciel, gdy wywołanie wymaga zatwierdzenia.

Zbuduj swoją pierwszą wtyczkę

Napisz w dowolnym języku plik binarny, który odczytuje polecenie z argumentów i wyświetla wynik. Następnie umieść go obok pliku plugin.json w katalogu wtyczek użytkownika na bocie.

<data>/user/plugins/notes-sync/
├── plugin.json      # runtime manifest
├── notes-sync       # your binary, named after the slug
└── skills/          # optional: skills that teach employees to use it
    └── notes-sync/
        └── SKILL.md
{
  "id": "notes-sync",
  "slug": "notes-sync",
  "name": "Notes Sync",
  "version": "0.1.0",
  "description": "Search, read and create notes in Example Notes.",
  "platforms": {}
}

id, slug, name, version i platforms są wymagane. W katalogu wtyczek użytkownika mapa platforms może być pusta: Nebo szuka pliku binarnego o nazwie sluga obok plugin.json, a potem w target/release/ i target/debug/. Gdy publikujesz, sklep uzupełnia platforms dla każdego przesłanego pliku binarnego.

<data> to ~/Library/Application Support/Nebo w macOS, %APPDATA%\Nebo w Windows i ~/.local/share/nebo w Linuksie albo wartość NEBO_HOME. Wtyczka w katalogu użytkownika zastępuje wtyczkę ze sklepu o tym samym slugu, dlatego to właściwe miejsce do testowania nowej kompilacji.

Naucz pracowników z niej korzystać

Umieść folder skills/ obok plugin.json. Każda umiejętność w nim jest dostępna dla każdego pracownika, dopóki wtyczka jest zainstalowana, i automatycznie wymienia wtyczkę jako zależność. W umiejętności napisz, jakie polecenia istnieją, co zwracają i kiedy używać każdego z nich. Najbardziej przydatne umiejętności wymień w entrySkills, żeby opis narzędzia wtyczki wskazywał je jako pierwsze.

Strona w sklepie to osobny plik, PLUGIN.md. Nebo nie odczytuje go w czasie działania; to strona, którą ludzie widzą przed instalacją. Zobacz Wydawanie wtyczki.

Środowisko

Każde wywołanie dziedziczy środowisko bota bez zmiennych modułu ładującego i umożliwiających wstrzykiwanie poleceń powłoki, a następnie dodaje poniższe wartości. Późniejsze wpisy mają pierwszeństwo.

ZmiennaWartość
Klucze auth.envWartości domyślne z manifestu.
<SLUG>_BINŚcieżka pliku binarnego tej wtyczki i każdej wtyczki, od której zależy. Slug jest zapisany wielkimi literami, z łącznikami zamienionymi na podkreślenia.
NEBO_DATA_DIRWłasny folder danych wtyczki, <data>/appdata/plugins/<slug>/. Jest to też katalog roboczy i przetrwa odinstalowanie.
PATHNajpierw foldery wtyczek, potem odziedziczona ścieżka.
UstawieniaWartości zapisane przez właściciela dla pól configSchema.
NEBO_AGENT_IDPracownik, który wykonuje wywołanie.
profileDirEnvFolder konta dla tego pracownika i konta, gdy wtyczka obsługuje konta.

permissions.envAllow i permissions.envDeny zawężają to, co wtyczka dziedziczy od bota. Nigdy nie usuwają własnych zmiennych uwierzytelniania wtyczki.

Konta i dane logowania

Wtyczka, która loguje się do usługi, powinna mieć jedno konto na pracownika. Księgowy loguje się kontem finansowym, a asystent własnym, i żaden nie widzi tokenów drugiego. Deklarujesz to w manifeście; resztą zajmuje się Nebo.

"auth": {
  "type": "env",
  "label": "Example Notes account",
  "env": { "EXAMPLE_NOTES_TOKEN": "" },
  "commands": { "login": "auth login", "status": "auth status", "logout": "auth logout" },
  "profileDirEnv": "EXAMPLE_NOTES_CONFIG_DIR"
},
"capabilities": {
  "configSchema": [
    { "key": "EXAMPLE_NOTES_TOKEN", "label": "API token", "fieldType": "password", "secret": true, "required": true }
  ]
}
  1. auth.env określa nazwy danych logowania. capabilities.configSchema nadaje im etykiety i ustala ich kolejność w formularzu połączenia.
  2. auth.profileDirEnv określa zmienną, z której Twoja wtyczka odczytuje swój folder danych logowania. Nebo tworzy jeden folder dla każdego pracownika i konta i ustawia tę zmienną przy każdym wywołaniu.
  3. Gdy właściciel łączy konto, Nebo uruchamia Twoje polecenie login z wartościami wpisanymi przez właściciela i ustawionym folderem konta. Twoja wtyczka zapisuje w tym folderze to, czego potrzebuje. Nebo nie przechowuje tych wartości.
  4. Twoje polecenie status wypisuje JSON, np. {"authenticated": true}. Gdy token wygaśnie, Nebo uruchamia refresh, jeśli je zadeklarujesz.

Przy logowaniu w przeglądarce ustaw type na oauth_cli, a login niech wyświetla lub otwiera adres URL logowania dostawcy. Pracownicy nigdy nie logują się sami: gdy wywołanie wymaga logowania, właściciel widzi kartę połączenia. Pracownik z kilkoma kontami wybiera jedno, dodając do polecenia --account <label>. Nebo usuwa tę flagę, zanim zobaczy ją Twój plik binarny.

Nazwij usługę, nie formę. Nazwa wtyczki mówi, z czym się łączy, np. „Example Notes”. Nigdy nie umieszczaj „CLI” w nazwie wtyczki; dla pracowników i właścicieli to połączenie, a nie wiersz poleceń.

Dalej