NeboAI
NeboAI
Začať

Doplnky

Doplnok dáva zamestnancom niečo, s čím môžu pracovať: online službu, firemný systém alebo program v počítači. Zostavíte ho ako binárny súbor pre príkazový riadok a opíšete ho manifestom plugin.json. Zamestnanci volajú jeho príkazy a Nebo sa stará o inštaláciu, účty pre jednotlivých zamestnancov a aktualizácie.

Ako fungujú doplnky

Doplnok je spustiteľný súbor plus manifest. Nebo medzi volaniami nenecháva bežať žiadny proces doplnku. Zakaždým, keď zamestnanec doplnok použije, Nebo spustí binárny súbor s príkazom a argumentmi, počká, kým skončí, a výstup odovzdá zamestnancovi.

  • Príkazy sú argumenty. Zamestnanec zvolí príkaz, napríklad notes search, a pomenované argumenty. Nebo odovzdá každý argument ako --name value. Nepoužíva sa shell, takže rúry ani presmerovania sa nikdy neuplatnia.
  • Výstup je stdout. Výsledky zapisujte na stdout. Dobre funguje JSON.
  • Štandardný vstup je zatvorený pri bežných volaniach. Háčiky, trasy a poskytovatelia chatu stdin používajú; pozrite referenciu k plugin.json.

Každý nainštalovaný a zapnutý doplnok sa zamestnancom zobrazuje ako jeden nástroj s názvom plugin__<slug>. Zamestnanec ho volá takto:

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

Nebo spustí:

notes-sync notes search --query "quarterly plan" --limit 5
ParameterTypVýznam
commandreťazec, povinnéPríkaz doplnku a prípadné pozičné slová.
argsobjekt reťazcovPomenované argumenty. Z každého sa stane --key value.
timeoutintegerPočet sekúnd čakania. Predvolene 120, obmedzené hodnotou permissions.maxTimeoutSeconds v manifeste.
displaystringVeta, ktorú vlastník uvidí, keď volanie potrebuje schválenie.

Zostavte svoj prvý doplnok

Napíšte v ľubovoľnom jazyku binárny súbor, ktorý prečíta príkaz z argumentov a vypíše výsledok. Potom ho umiestnite vedľa súboru plugin.json do adresára používateľských doplnkov bota.

<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 a platforms sú povinné. V adresári používateľských doplnkov môže byť mapa platforms prázdna: Nebo hľadá binárny súbor pomenovaný podľa slugu vedľa plugin.json, potom v target/release/ a target/debug/. Pri zverejnení obchod vyplní platforms pre každý nahratý binárny súbor.

<data> je ~/Library/Application Support/Nebo v macOS, %APPDATA%\Nebo vo Windows a ~/.local/share/nebo v Linuxe, prípadne hodnota NEBO_HOME. Doplnok v používateľskom adresári má prednosť pred doplnkom z obchodu s rovnakým slugom, preto je to miesto na testovanie novej zostavy.

Naučte zamestnancov ho používať

Vedľa plugin.json vytvorte priečinok skills/. Každá zručnosť v ňom je dostupná každému zamestnancovi, kým je doplnok nainštalovaný, a automaticky uvádza doplnok ako závislosť. V zručnosti napíšte, aké príkazy existujú, čo vracajú a kedy ktorý použiť. Najužitočnejšie zručnosti uveďte v entrySkills, aby na ne popis nástroja doplnku odkazoval ako prvý.

Záznam v obchode je samostatný súbor, PLUGIN.md. Nebo ho pri behu nečíta; je to stránka, ktorú ľudia vidia pred inštaláciou. Pozrite Vydanie doplnku.

Prostredie

Každé volanie zdedí prostredie bota bez premenných zavádzača a premenných umožňujúcich vkladanie do shellu a potom pridá tieto hodnoty. Neskoršie položky majú prednosť.

PremennáHodnota
Kľúče auth.envPredvolené hodnoty z manifestu.
<SLUG>_BINCesta k binárnemu súboru tohto doplnku a každého doplnku, od ktorého závisí. Slug sa píše veľkými písmenami, so spojovníkmi nahradenými podčiarkovníkmi.
NEBO_DATA_DIRVlastný dátový priečinok doplnku, <data>/appdata/plugins/<slug>/. Je to zároveň pracovný adresár a prežije odinštalovanie.
PATHNajprv priečinky doplnkov, potom zdedená cesta.
NastaveniaHodnoty, ktoré vlastník uložil pre polia configSchema.
NEBO_AGENT_IDZamestnanec, ktorý volá.
profileDirEnvPriečinok účtu pre tohto zamestnanca a účet, ak doplnok podporuje účty.

permissions.envAllow a permissions.envDeny zužujú, čo doplnok zdedí od bota. Nikdy neodstránia vlastné overovacie premenné doplnku.

Účty a prihlasovacie údaje

Doplnok, ktorý sa prihlasuje do služby, by mal mať jeden účet pre každého zamestnanca. Účtovník sa prihlási finančným prihlásením, asistent vlastným a ani jeden nevidí tokeny toho druhého. Deklarujete to v manifeste; o zvyšok sa postará 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 pomenúva prihlasovacie údaje. capabilities.configSchema im dáva označenia a určuje ich poradie vo formulári pripojenia.
  2. auth.profileDirEnv pomenúva premennú, z ktorej váš doplnok číta svoj priečinok s prihlasovacími údajmi. Nebo vytvorí jeden priečinok pre každého zamestnanca a účet a túto premennú nastaví pri každom volaní.
  3. Keď vlastník pripojí účet, Nebo spustí váš príkaz login s hodnotami, ktoré vlastník zadal, a s nastaveným priečinkom účtu. Váš doplnok si do tohto priečinka uloží, čo potrebuje. Nebo hodnoty neuchováva.
  4. Váš príkaz status vypíše JSON, napríklad {"authenticated": true}. Keď token vyprší, Nebo spustí refresh, ak ho deklarujete.

Pri prihlásení v prehliadači nastavte type na oauth_cli a nechajte login vypísať alebo otvoriť URL prihlásenia poskytovateľa. Zamestnanci sa nikdy neprihlasujú sami: keď volanie potrebuje prihlásenie, vlastník uvidí kartu pripojenia. Zamestnanec s viacerými účtami si jeden vyberie tak, že k príkazu pridá --account <label>. Nebo tento prepínač odstráni skôr, než ho uvidí váš binárny súbor.

Pomenujte službu, nie formu. Názov doplnku hovorí, k čomu sa pripája, napríklad „Example Notes“. Do názvu doplnku nikdy nedávajte „CLI“; pre zamestnancov a vlastníkov je to pripojenie, nie príkazový riadok.

Ďalej