Pole nejvyšší úrovně
| Pole | Typ | Povinné | Význam |
|---|---|---|---|
id | string | ano | Identifikátor pluginu v obchodě. Během vývoje použijte slug. |
slug | string | ano | Stálý identifikátor. [a-z0-9-], nejvýše 64 znaků, bez pomlčky na začátku a na konci a bez dvojité pomlčky. Určuje název nástroje plugin__<slug> a proměnné <SLUG>_BIN. |
name | string | ano | Zobrazovaný název. Uveďte v něm službu, ke které se plugin připojuje. |
version | string | ano | Sémantická verze, například 0.1.0. |
platforms | map | ano | Klíč platformy přiřazený k binárnímu souboru. Viz Platformy. |
description | string | ne | Jedna věta pro lidi i zaměstnance. |
author | string | ne | Název vydavatele. |
category | string | ne | Pomáhá zaměstnancům plugin najít. |
triggers | seznam řetězců | ne | Slova popisující, kdy se plugin uplatní. Používají se v nápovědách pro vyhledávání. |
entrySkills | seznam řetězců | ne | Přibalené dovednosti, které se v popisu nástroje pluginu uvedou jako první. |
dependencies | seznam {name, version, optional} | ne | Další pluginy, které tento plugin spouští. version má výchozí hodnotu "*", optional hodnotu false. Jejich cesty <SLUG>_BIN se nastavují při každém volání. |
auth | object | ne | Přihlášení a účty. Viz Ověřování. |
capabilities | object | ne | configSchema, hooks, commands, routes, providers. |
permissions | object | ne | Filtrování prostředí a maximální časový limit. |
events | list | ne | Sledovače, které napájejí pracovní postupy zaměstnanců. |
interfaceBindings | map | ne | Typované operace, které plugin poskytuje. |
channel | object | ne | Trvalý most ke službě pro zasílání zpráv. |
setup | object | ne | Podrobný průvodce nastavením krok za krokem. |
Nebo ověřuje instalace z obchodu: pravidla pro slug, sémantickou verzi, alespoň jednu platformu, binaryName bez oddělovačů cesty a bez .., příkaz login, pokud auth.type není env, neprázdné názvy událostí a příkazy a šablony vazeb, které jdou zpracovat. Pluginy v uživatelském adresáři pluginů se neověřují.
Platformy
Klíče jsou darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 a windows-amd64. Každá položka má všech pět níže uvedených polí. Při publikování doplní obchod skutečný hash, velikost, podpis a adresu URL ke stažení, takže je v nahrávaném souboru nechte prázdné.
"platforms": {
"darwin-arm64": { "binaryName": "notes-sync", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
"linux-amd64": { "binaryName": "notes-sync", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
"windows-amd64": { "binaryName": "notes-sync.exe", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" }
} | Pole | Význam |
|---|---|
binaryName | Název spustitelného souboru. Ve Windows přidejte .exe. |
sha256 | Hash binárního souboru. Ověřuje se při instalaci. |
signature | Podpis binárního souboru. Ověřuje se při instalaci, pokud je k dispozici podpisový klíč. |
size | Velikost v bajtech. |
downloadUrl | Odkud Nebo balíček stahuje. |
Ověřování
| Pole | Význam |
|---|---|
type | oauth_cli pro přihlášení v prohlížeči, které řídí plugin; env pro přihlašovací údaje zadané jako hodnoty; neboai pro získání tokenu NeboAI vlastníka v každém klíči auth.env končícím na _TOKEN. |
env | Mapa názvů proměnných na výchozí hodnoty. Zároveň jediné názvy přihlašovacích údajů, které Nebo předává příkazu login. |
commands.login | Přihlásí účet. Povinné, pokud type není env. Spouští se s nastavenou složkou účtu. |
commands.status | Vypíše JSON s informací, zda je účet přihlášen. |
commands.refresh | Obnoví token bez zásahu uživatele. |
commands.logout | Odhlásí účet. Spustit ho může jen vlastník. |
profileDirEnv | Proměnná, která dostane samostatnou složku s přihlašovacími údaji pro každého zaměstnance a účet. Bez ní má plugin jeden sdílený účet. |
label, description | Text na kartě připojení. |
help | {url, urlLabel, text} zobrazené během připojování. |
publicRedirect | Nastavte na true, když poskytovatel odmítá přesměrování na http://localhost; přihlášení pak probíhá přes veřejné přesměrování NeboAI. |
Nebo ve výstupu stavu čte první z hodnot authenticated, isAuthenticated, logged_in, loggedIn nebo token_valid. Neprázdné token_error nebo hodnota none v credential_source, auth_method, storage či status znamená, že účet je odhlášen. Příkaz stavu má 45 sekund.
{"authenticated": true, "account": "finance@example.com"} configSchema
capabilities.configSchema popisuje hodnoty, které vlastník pro plugin nastavuje. Každá hodnota se k binárnímu souboru dostane jako proměnná prostředí pojmenovaná podle key. U klíčů přihlašovacích údajů uvedených také v auth.env dává schéma popisky polím formuláře pro připojení jednotlivých zaměstnanců.
| Pole | Typ | Výchozí | Význam |
|---|---|---|---|
key | string | povinné | Název proměnné prostředí. |
label | string | povinné | Popisek pole. |
description | string | "" | Text nápovědy. |
fieldType | string | "string" | Typ vstupu, například string, number, boolean, select nebo password. |
default | string | žádné | Předvyplněná hodnota. |
required | boolean | false | Plugin není připraven, dokud hodnota není nastavena. |
secret | boolean | false | Hodnota se při zpětném čtení maskuje. |
options | seznam řetězců | žádné | Možnosti pro select. |
permissions
| Pole | Výchozí | Význam |
|---|---|---|
envAllow | [] | Zděděné proměnné, které plugin smí vidět. Prázdný seznam povoluje všechny. |
envDeny | [] | Zděděné proměnné, které se vždy odstraní. |
maxTimeoutSeconds | 300 | Horní mez časového limitu kteréhokoli volání. |
network | false | Deklaruje používání sítě. Pouze informativní; nevynucuje se. |
events
Událost je dlouhodobě běžící sledovač. Nebo ho spustí, když ho sleduje pracovní postup zaměstnance, a když skončí, spustí ho znovu. Každý řádek, který sledovač zapíše na stdout, je jedna událost. Název události dostane za běhu předponu se slugem, takže z note.created se stane notes-sync.note.created.
"events": [
{
"name": "note.created",
"description": "A note was created in the watched notebook.",
"command": "watch --notebook {{notebook}} --format ndjson"
}
] | Pole | Význam |
|---|---|
name | Název události bez slugu. Povinné. |
command | Argumenty, které sledovač spouštějí. Povinné. {{key}} se nahradí vstupními hodnotami zaměstnance. |
description | Co událost vyvolává. |
multiplexed | Při hodnotě true vysílá jeden sledovač několik typů událostí a každý řádek obsahuje pole "event". |
Pracovní postupy se k odběru událostí přihlašují spouštěčem watch. Viz Spouštěče.
interfaceBindings
Vazba mapuje operaci rozhraní na jeden z vašich příkazů. Každá vazba se pro zaměstnance stane typovaným nástrojem pojmenovaným podle operace malými písmeny, s tečkami a pomlčkami nahrazenými podtržítky: z notes.search se stane notes_search. Vazbami plugin splňuje schopnosti, které zaměstnanec vyžaduje; viz Schopnosti.
"interfaceBindings": {
"notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
"invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
} | Zástupný symbol | Rozvine se na |
|---|---|
{field} | Hodnota pole jako jedno slovo. Pole se navíc nepředává jako přepínač. |
{field[]:--flag} | Jedna dvojice --flag <item> pro každou položku pole se seznamem. |
{field?:--flag} | --flag <value>, když je pole uvedeno; nic, když chybí. |
{field:cents->dollars} | Celočíselná částka v centech zapsaná v dolarech. |
Vstupní pole, která šablona neuvádí, se připojí jako --field value. Zástupné symboly pro seznamy a volitelné hodnoty musí tvořit celá slova. K operaci, která vyžaduje schválení, se nelze dostat voláním stejného příkazu přes plugin__<slug>.
Hooky, lomítkové příkazy a trasy
"capabilities": {
"hooks": [
{ "hook": "tool.post_execute", "hookType": "filter", "command": "hook redact", "priority": 50, "timeoutMs": 500 }
],
"commands": [
{ "name": "notes", "description": "Show today's notes", "command": "notes today", "slash": true }
],
"routes": [
{ "path": "/callback", "method": "GET", "command": "http callback" }
]
} hooks
Hook spustí váš příkaz v určitém bodě tahu zaměstnance. Nebo zapíše na stdin datovou část JSON. Výstup hooku action se ignoruje. Hook filter vrací {"payload": ..., "handled": false}; "handled": true zastaví pozdější hooky. Chyby a vypršení časového limitu zachovají předchozí datovou část a nikdy tah neblokují. Po třech selháních za sebou se hook na pět minut pozastaví.
| Pole | Výchozí | Význam |
|---|---|---|
hook | povinné | Jedno z tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue. |
hookType | "action" | action nebo filter. |
command | povinné | Argumenty pro váš binární soubor. |
priority | 100 | Nižší hodnota běží dřív. |
timeoutMs | 500 | Časový limit v milisekundách. |
commands
S "slash": true spustí zadání /name args v chatu přímo command args, bez zaměstnance. Výstup je odpovědí. Časový limit je 30 sekund.
routes
Trasa odpovídá na požadavky HTTP na adrese /api/v1/plugins/<slug>/api/<path> na botovi podle path a method. Tělo požadavku jde na stdin a váš stdout je odpověď. Časový limit je 30 sekund.
providers
Poskytovatel přidává zdroj chatovacích modelů. Deklarujte id, displayName, providerType, modelsCommand a chatCommand. Nebo posílá požadavek chatu jako JSON na stdin příkazu chatCommand a až 300 sekund čte streamované události jako JSON oddělený novými řádky ze stdout. Dnes se používá jen streamování chatu.
channel
Kanál propojuje službu pro zasílání zpráv. Nebo udržuje command spuštěný, čte příchozí zprávy z jeho stdout a odpovědi zapisuje na jeho stdin, obojí jako JSON oddělený novými řádky.
| Pole | Výchozí | Význam |
|---|---|---|
command | povinné | Argumenty, které most spouštějí. |
name, description | "" | Zobrazuje se v nastavení. |
restartDelaySecs | 5 | Prodleva před restartem po pádu. |
shared | false | Jeden most pro všechny zaměstnance; zprávy se směrují podle jména zaměstnance a odpovědi nesou identitu každého zaměstnance. |
needsLocalApi | false | Předá mostu adresu místního API bota, token a id zaměstnance. Vypnuto, pokud to nepotřebujete. |
setup
Průvodce nastavením provede vlastníka kroky, které jeden formulář nepokryje. Hodnoty z kroků form vyplní {{key}} v pozdějších argumentech generate. Hodnoty z kroků credentials se uloží jako proměnné prostředí pluginu.
"setup": {
"title": "Connect Example Chat",
"steps": [
{ "kind": "form", "title": "Bot name", "fields": [ { "key": "bot_name", "label": "Name", "required": true } ] },
{ "kind": "generate", "title": "App manifest", "command": "manifest", "args": ["--name", "{{bot_name}}"], "outputFormat": "yaml" },
{ "kind": "external", "title": "Create the app", "url": "https://example.com/apps", "urlLabel": "Open admin" },
{ "kind": "credentials", "title": "Paste the token", "fields": [ { "key": "EXAMPLE_CHAT_TOKEN", "label": "Token", "inputType": "password", "required": true } ], "verifyCommand": "auth status" }
]
} | Druh kroku | Pole |
|---|---|
form | title, description, fields |
generate | title, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Zobrazí výstup příkazu ke zkopírování. |
external | title, description, url, urlLabel, instructions |
credentials | title, description, fields, verifyCommand. Krok je dokončen, když verifyCommand uspěje. |
Pole mají key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) a required.