NeboAI
NeboAI
Začít

Pluginy

Plugin dává zaměstnancům něco, s čím mohou pracovat: online službu, firemní systém nebo program v počítači. Sestavíte ho jako binární soubor pro příkazovou řádku a popíšete manifestem plugin.json. Zaměstnanci volají jeho příkazy a Nebo se stará o instalaci, účty jednotlivých zaměstnanců a aktualizace.

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
ParametrTypVýznam
commandřetězec, povinnéPříkaz pluginu a případná poziční slova.
argsobjekt řetězcůPojmenované argumenty. Z každého se stane --key value.
timeoutintegerPočet sekund čekání. Výchozí hodnota je 120, omezená hodnotou permissions.maxTimeoutSeconds v manifestu.
displaystringVě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.envVýchozí hodnoty z manifestu.
<SLUG>_BINCesta 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_DIRVlastní datová složka pluginu, <data>/appdata/plugins/<slug>/. Je to zároveň pracovní adresář a přetrvá odinstalaci.
PATHNejprve složky pluginů, pak zděděná cesta.
NastaveníHodnoty, které vlastník uložil pro pole configSchema.
NEBO_AGENT_IDZaměstnanec, který volání provádí.
profileDirEnvSlož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 }
  ]
}
  1. auth.env pojmenovává přihlašovací údaje. capabilities.configSchema jim dává popisky a určuje jejich pořadí ve formuláři pro připojení.
  2. auth.profileDirEnv pojmenová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í.
  3. Když vlastník připojí účet, Nebo spustí váš příkaz login s 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á.
  4. Váš příkaz status vypíš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