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
| Parameter | Typ | Význam |
|---|---|---|
command | reťazec, povinné | Príkaz doplnku a prípadné pozičné slová. |
args | objekt reťazcov | Pomenované argumenty. Z každého sa stane --key value. |
timeout | integer | Počet sekúnd čakania. Predvolene 120, obmedzené hodnotou permissions.maxTimeoutSeconds v manifeste. |
display | string | Veta, 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.env | Predvolené hodnoty z manifestu. |
<SLUG>_BIN | Cesta 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_DIR | Vlastný dátový priečinok doplnku, <data>/appdata/plugins/<slug>/. Je to zároveň pracovný adresár a prežije odinštalovanie. |
PATH | Najprv priečinky doplnkov, potom zdedená cesta. |
| Nastavenia | Hodnoty, ktoré vlastník uložil pre polia configSchema. |
NEBO_AGENT_ID | Zamestnanec, ktorý volá. |
profileDirEnv | Prieč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 }
]
} auth.envpomenúva prihlasovacie údaje.capabilities.configSchemaim dáva označenia a určuje ich poradie vo formulári pripojenia.auth.profileDirEnvpomenú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í.- Keď vlastník pripojí účet, Nebo spustí váš príkaz
logins 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. - Váš príkaz
statusvypíš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
- Referencia k plugin.json: každé pole vrátane udalostí, háčikov a typových operácií.
- Vydanie doplnku: platformy, binárne súbory, podpisovanie a aktualizácie.
- Zverejňovanie: postup v obchode pre každý artefakt.