NeboAI
NeboAI
Začít

Reference plugin.json

plugin.json je manifest, který Nebo čte při instalaci a spouštění pluginu. Klíče se píší v camelCase. Tato stránka uvádí každé pole, které Nebo dnes čte, a co které dělá.

Pole nejvyšší úrovně

PoleTypPovinnéVýznam
idstringanoIdentifikátor pluginu v obchodě. Během vývoje použijte slug.
slugstringanoStá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.
namestringanoZobrazovaný název. Uveďte v něm službu, ke které se plugin připojuje.
versionstringanoSémantická verze, například 0.1.0.
platformsmapanoKlíč platformy přiřazený k binárnímu souboru. Viz Platformy.
descriptionstringneJedna věta pro lidi i zaměstnance.
authorstringneNázev vydavatele.
categorystringnePomáhá zaměstnancům plugin najít.
triggersseznam řetězcůneSlova popisující, kdy se plugin uplatní. Používají se v nápovědách pro vyhledávání.
entrySkillsseznam řetězcůnePřibalené dovednosti, které se v popisu nástroje pluginu uvedou jako první.
dependenciesseznam {name, version, optional}neDalší 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í.
authobjectnePřihlášení a účty. Viz Ověřování.
capabilitiesobjectneconfigSchema, hooks, commands, routes, providers.
permissionsobjectneFiltrování prostředí a maximální časový limit.
eventslistneSledovače, které napájejí pracovní postupy zaměstnanců.
interfaceBindingsmapneTypované operace, které plugin poskytuje.
channelobjectneTrvalý most ke službě pro zasílání zpráv.
setupobjectnePodrobný 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": "" }
}
PoleVýznam
binaryNameNázev spustitelného souboru. Ve Windows přidejte .exe.
sha256Hash binárního souboru. Ověřuje se při instalaci.
signaturePodpis binárního souboru. Ověřuje se při instalaci, pokud je k dispozici podpisový klíč.
sizeVelikost v bajtech.
downloadUrlOdkud Nebo balíček stahuje.

Ověřování

PoleVýznam
typeoauth_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.
envMapa 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.loginPřihlásí účet. Povinné, pokud type není env. Spouští se s nastavenou složkou účtu.
commands.statusVypíše JSON s informací, zda je účet přihlášen.
commands.refreshObnoví token bez zásahu uživatele.
commands.logoutOdhlásí účet. Spustit ho může jen vlastník.
profileDirEnvPromě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, descriptionText na kartě připojení.
help{url, urlLabel, text} zobrazené během připojování.
publicRedirectNastavte 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ů.

PoleTypVýchozíVýznam
keystringpovinnéNázev proměnné prostředí.
labelstringpovinnéPopisek pole.
descriptionstring""Text nápovědy.
fieldTypestring"string"Typ vstupu, například string, number, boolean, select nebo password.
defaultstringžádnéPředvyplněná hodnota.
requiredbooleanfalsePlugin není připraven, dokud hodnota není nastavena.
secretbooleanfalseHodnota se při zpětném čtení maskuje.
optionsseznam řetězcůžádnéMožnosti pro select.

permissions

PoleVý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í.
maxTimeoutSeconds300Horní mez časového limitu kteréhokoli volání.
networkfalseDeklaruje 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"
  }
]
PoleVýznam
nameNázev události bez slugu. Povinné.
commandArgumenty, které sledovač spouštějí. Povinné. {{key}} se nahradí vstupními hodnotami zaměstnance.
descriptionCo událost vyvolává.
multiplexedPř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ý symbolRozvine 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í.

PoleVýchozíVýznam
hookpovinné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.
commandpovinnéArgumenty pro váš binární soubor.
priority100Nižší hodnota běží dřív.
timeoutMs500Č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.

PoleVýchozíVýznam
commandpovinnéArgumenty, které most spouštějí.
name, description""Zobrazuje se v nastavení.
restartDelaySecs5Prodleva před restartem po pádu.
sharedfalseJeden 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.
needsLocalApifalsePř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 krokuPole
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Zobrazí výstup příkazu ke zkopírování.
externaltitle, description, url, urlLabel, instructions
credentialstitle, 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.