Jak pluginy fungují
Plugin je spustitelný soubor a manifest. Mezi voláními Nebo nenechává běžet žádný proces pluginu. Pokaždé, když zaměstnanec plugin použije, Nebo spustí binární soubor s příkazem a argumenty, počká na jeho ukončení a výstup předá zpět zaměstnanci.
- Příkazy jsou argumenty. Zaměstnanec zvolí příkaz, například
notes search, a pojmenované argumenty. Nebo předá každý argument jako--name value. Žádný shell se nepoužívá, takže roury a přesměrování se nikdy neuplatní. - Výstup je stdout. Výsledky zapisujte na stdout. Dobře funguje JSON.
- Standardní vstup je zavřený u běžných volání. Hooky, trasy a poskytovatelé chatu stdin používají; viz referenční příručku k plugin.json.
Každý nainstalovaný a povolený plugin se zaměstnancům jeví jako jeden nástroj s názvem plugin__<slug>. Zaměstnanec 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
| Parametr | Typ | Význam |
|---|---|---|
command | řetězec, povinné | Příkaz pluginu a případná poziční slova. |
args | objekt řetězců | Pojmenované argumenty. Z každého se stane --key value. |
timeout | integer | Počet sekund čekání. Výchozí hodnota je 120, omezená hodnotou permissions.maxTimeoutSeconds v manifestu. |
display | string | Věta, kterou vlastník uvidí, když volání vyžaduje schválení. |
Sestavte svůj první plugin
Napište v libovolném jazyce binární soubor, který načte příkaz z argumentů a vypíše výsledek. Pak ho umístěte vedle souboru plugin.json do uživatelského adresáře pluginů na botovi.
<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 jsou povinné. V uživatelském adresáři pluginů může být mapa platforms prázdná: Nebo hledá binární soubor pojmenovaný podle slugu vedle plugin.json, pak v target/release/ a target/debug/. Při publikování obchod doplní platforms pro každý nahraný binární soubor.
<data> je ~/Library/Application Support/Nebo v macOS, %APPDATA%\Nebo ve Windows a ~/.local/share/nebo v Linuxu, případně hodnota NEBO_HOME. Plugin v uživatelském adresáři přepíše plugin z obchodu se stejným slugem, a proto je to správné místo pro testování nového sestavení.
Naučte zaměstnance plugin používat
Vedle plugin.json vytvořte složku skills/. Každá dovednost v ní je k dispozici všem zaměstnancům, dokud je plugin nainstalovaný, a automaticky uvádí plugin jako závislost. V dovednosti popište, jaké příkazy existují, co vracejí a kdy který použít. Nejužitečnější dovednosti uveďte v entrySkills, aby na ně popis nástroje pluginu odkazoval jako první.
Stránka v obchodě je samostatný soubor, PLUGIN.md. Nebo ho za běhu nečte; je to stránka, kterou lidé vidí před instalací. Viz Vydání pluginu.
Prostředí
Každé volání zdědí prostředí bota bez proměnných zavaděče a proměnných umožňujících vkládání do shellu a pak přidá tyto hodnoty. Pozdější položky mají přednost.
| Proměnná | Hodnota |
|---|---|
Klíče auth.env | Výchozí hodnoty z manifestu. |
<SLUG>_BIN | Cesta k binárnímu souboru tohoto pluginu a ke každému pluginu, na kterém závisí. Slug se převede na velká písmena a pomlčky na podtržítka. |
NEBO_DATA_DIR | Vlastní datová složka pluginu, <data>/appdata/plugins/<slug>/. Je to zároveň pracovní adresář a přetrvá odinstalaci. |
PATH | Nejprve složky pluginů, pak zděděná cesta. |
| Nastavení | Hodnoty, které vlastník uložil pro pole configSchema. |
NEBO_AGENT_ID | Zaměstnanec, který volání provádí. |
profileDirEnv | Složka účtu pro tohoto zaměstnance a účet, pokud plugin účty podporuje. |
permissions.envAllow a permissions.envDeny zužují, co plugin od bota dědí. Vlastní proměnné ověřování pluginu nikdy neodstraní.
Účty a přihlašovací údaje
Plugin, který se přihlašuje ke službě, by měl mít jeden účet na zaměstnance. Účetní se přihlásí finančním přihlášením, asistent vlastním a ani jeden nevidí tokeny toho druhého. Deklarujete to v manifestu; o zbytek se 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.envpojmenovává přihlašovací údaje.capabilities.configSchemajim dává popisky a určuje jejich pořadí ve formuláři pro připojení.auth.profileDirEnvpojmenovává proměnnou, ze které váš plugin čte svou složku s přihlašovacími údaji. Nebo vytvoří jednu složku pro každého zaměstnance a účet a tuto proměnnou nastaví při každém volání.- Když vlastník připojí účet, Nebo spustí váš příkaz
logins hodnotami, které vlastník zadal, a s nastavenou složkou účtu. Váš plugin si do této složky uloží, co potřebuje. Nebo si hodnoty neuchovává. - Váš příkaz
statusvypíše JSON, například{"authenticated": true}. Když token vyprší, Nebo spustírefresh, pokud ho deklarujete.
Pro přihlášení v prohlížeči nastavte type na oauth_cli a nechte login vypsat nebo otevřít přihlašovací adresu URL poskytovatele. Zaměstnanci se nikdy nepřihlašují sami: když volání vyžaduje přihlášení, vlastník uvidí kartu připojení. Zaměstnanec s několika účty si jeden vybere tak, že k příkazu přidá --account <label>. Nebo tento přepínač odstraní dřív, než ho uvidí váš binární soubor.
Pojmenujte službu, ne formu. Název pluginu říká, k čemu se připojuje, například „Example Notes“. Do názvu pluginu nikdy nedávejte „CLI“; pro zaměstnance i vlastníky je to připojení, ne příkazová řádka.
Dále
- Referenční příručka k plugin.json: každé pole včetně událostí, hooků a typovaných operací.
- Vydání pluginu: platformy, binární soubory, podepisování a aktualizace.
- Publikování: postup v obchodě pro každý typ obsahu.