NeboAI
NeboAI
Commencer

Référence plugin.json

plugin.json est le manifeste que Nebo lit pour installer et exécuter un plugin. Les clés sont en camelCase. Cette page liste chaque champ que Nebo lit aujourd'hui et ce que fait chacun d'eux.

Champs de premier niveau

ChampTypeObligatoireSignification
idstringouiL’identifiant du plugin dans la boutique. Utilisez le slug pendant le développement.
slugstringouiIdentifiant stable. [a-z0-9-], 64 caractères au maximum, sans trait d’union au début, à la fin ni doublé. Donne son nom à l’outil plugin__<slug> et à la variable <SLUG>_BIN.
namestringouiNom affiché. Indiquez le service auquel il se connecte.
versionstringouiVersion sémantique, par exemple 0.1.0.
platformsmapouiClé de plateforme vers binaire. Voir Plateformes.
descriptionstringnonUne phrase destinée aux personnes et aux employés.
authorstringnonNom de l’éditeur.
categorystringnonAide les employés à trouver le plugin.
triggersliste de chaînesnonMots qui décrivent quand le plugin s’applique. Utilisés dans les suggestions de recherche.
entrySkillsliste de chaînesnonSkills intégrés à citer en premier dans la description de l’outil du plugin.
dependenciesliste de {name, version, optional}nonAutres plugins exécutés par celui-ci. version vaut "*" par défaut ; optional vaut false. Leurs chemins <SLUG>_BIN sont définis à chaque appel.
authobjectnonConnexion et comptes. Voir Authentification.
capabilitiesobjectnonconfigSchema, hooks, commands, routes, providers.
permissionsobjectnonFiltrage de l’environnement et plafond de délai d’expiration.
eventslistnonDes observateurs qui alimentent les workflows des employés.
interfaceBindingsmapnonLes opérations typées fournies par le plugin.
channelobjectnonUne passerelle permanente vers un service de messagerie.
setupobjectnonUn assistant de configuration étape par étape.

Nebo valide les installations depuis la boutique : les règles du slug, une version sémantique, au moins une plateforme, un binaryName sans séparateur de chemin ni .., une commande login sauf si auth.type vaut env, des noms d'événements et des commandes non vides, et des modèles de liaison analysables. Les plugins du dossier des plugins utilisateur ne sont pas validés.

Plateformes

Les clés sont darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 et windows-amd64. Chaque entrée comporte les cinq champs ci-dessous. Lors de la publication, la boutique inscrit le hash, la taille, la signature et l'URL de téléchargement réels : laissez-les vides dans le fichier que vous envoyez.

"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": "" }
}
ChampSignification
binaryNameLe nom de fichier de l’exécutable. Ajoutez .exe sur Windows.
sha256Hash du binaire. Vérifié à l’installation.
signatureSignature du binaire. Vérifiée à l’installation quand une clé de signature est disponible.
sizeTaille en octets.
downloadUrlL’endroit où Nebo télécharge le paquet.

Authentification

ChampSignification
typeoauth_cli pour une connexion dans le navigateur gérée par le plugin ; env pour des identifiants saisis sous forme de valeurs ; neboai pour recevoir le jeton NeboAI du propriétaire dans chaque clé auth.env se terminant par _TOKEN.
envCorrespondance entre nom de variable et valeur par défaut. Ce sont aussi les seuls noms d’identifiants que Nebo transmet à login.
commands.loginConnecte. Obligatoire sauf si type vaut env. S’exécute avec le dossier du compte défini.
commands.statusAffiche un JSON qui indique si le compte est connecté.
commands.refreshRenouvelle un jeton sans interaction.
commands.logoutDéconnecte. Seul le propriétaire peut l’exécuter.
profileDirEnvVariable qui reçoit un dossier d’identifiants distinct pour chaque employé et chaque compte. Sans elle, le plugin n’a qu’un seul compte partagé.
label, descriptionTexte de la carte de connexion.
help{url, urlLabel, text} affiché pendant la connexion.
publicRedirectMettez true quand le fournisseur refuse les redirections vers http://localhost ; la connexion passe alors par la redirection publique de NeboAI.

Nebo lit le premier des champs authenticated, isAuthenticated, logged_in, loggedIn ou token_valid dans la sortie d'état. Un token_error non vide, ou la valeur none dans credential_source, auth_method, storage ou status, signifie déconnecté. La commande d'état dispose de 45 secondes.

{"authenticated": true, "account": "finance@example.com"}

configSchema

capabilities.configSchema décrit les valeurs qu'un propriétaire définit pour le plugin. Chaque valeur parvient au binaire sous forme de variable d'environnement nommée par key. Pour les clés d'identifiants également listées dans auth.env, le schéma donne leurs libellés aux champs du formulaire de connexion par employé.

ChampTypePar défautSignification
keystringobligatoireNom de la variable d’environnement.
labelstringobligatoireLibellé du champ.
descriptionstring""Texte d’aide.
fieldTypestring"string"Type de saisie, par exemple string, number, boolean, select ou password.
defaultstringaucuneValeur pré-remplie.
requiredbooleanfalseLe plugin n’est pas prêt tant que la valeur n’est pas définie.
secretbooleanfalseLa valeur est masquée à la relecture.
optionsliste de chaînesaucuneChoix pour select.

permissions

ChampPar défautSignification
envAllow[]Variables héritées que le plugin peut voir. Vide, tout est autorisé.
envDeny[]Variables héritées toujours supprimées.
maxTimeoutSeconds300Limite supérieure du délai d’expiration de tout appel.
networkfalseDéclare l’utilisation du réseau. Informatif ; non appliqué.

events

Un événement est un observateur de longue durée. Nebo le démarre quand le workflow d'un employé l'observe, et le relance s'il s'arrête. Chaque ligne que l'observateur écrit sur stdout est un événement. Le nom de l'événement est préfixé par le slug à l'exécution : note.created devient notes-sync.note.created.

"events": [
  {
    "name": "note.created",
    "description": "A note was created in the watched notebook.",
    "command": "watch --notebook {{notebook}} --format ndjson"
  }
]
ChampSignification
nameNom de l’événement, sans le slug. Obligatoire.
commandArguments qui démarrent l’observateur. Obligatoire. {{key}} est remplacé par les valeurs saisies pour l’employé.
descriptionCe qui déclenche l’événement.
multiplexedAvec true, un seul observateur émet plusieurs types d’événements et chaque ligne contient un champ "event".

Les workflows s'abonnent aux événements avec un déclencheur watch. Voir Déclencheurs.

interfaceBindings

Une liaison associe une opération d'interface à l'une de vos commandes. Chaque liaison devient un outil typé pour les employés, nommé d'après l'opération en minuscules, les points et traits d'union devenant des tirets bas : notes.search devient notes_search. C'est par les liaisons qu'un plugin fournit les capacités qu'un employé exige ; voir Capacités.

"interfaceBindings": {
  "notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
  "invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
}
Espace réservéDevient
{field}La valeur du champ en un seul mot. Le champ n’est pas aussi transmis comme option.
{field[]:--flag}Une paire --flag <item> pour chaque élément d’un champ de type liste.
{field?:--flag}--flag <value> quand le champ est présent ; rien quand il est absent.
{field:cents->dollars}Un montant entier en centimes, écrit en dollars.

Les champs d'entrée qu'un modèle ne nomme pas sont ajoutés à la fin sous la forme --field value. Les espaces réservés de liste et facultatifs doivent être des mots entiers. Une opération qui exige une approbation ne peut pas être atteinte en appelant la même commande via plugin__<slug>.

Hooks, commandes slash et routes

"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

Un hook exécute votre commande à un moment donné du tour d'un employé. Nebo écrit une charge utile JSON sur stdin. La sortie d'un hook action est ignorée. Un hook filter renvoie {"payload": ..., "handled": false} ; "handled": true arrête les hooks suivants. Les erreurs et les dépassements de délai conservent la charge utile précédente et ne bloquent jamais le tour. Après trois échecs d'affilée, un hook est mis en pause pendant cinq minutes.

ChampPar défautSignification
hookobligatoireL’un de tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue.
hookType"action"action ou filter.
commandobligatoireArguments pour votre binaire.
priority100Le plus bas s’exécute en premier.
timeoutMs500Limite de temps en millisecondes.

commands

Avec "slash": true, taper /name args dans la discussion exécute directement command args, sans passer par l'employé. La sortie constitue la réponse. La limite de temps est de 30 secondes.

routes

Une route répond aux requêtes HTTP sur /api/v1/plugins/<slug>/api/<path> du bot, selon path et method. Le corps de la requête est envoyé sur stdin et votre stdout constitue la réponse. La limite de temps est de 30 secondes.

providers

Un fournisseur ajoute une source de modèles de discussion. Déclarez id, displayName, providerType, modelsCommand et chatCommand. Nebo envoie une requête de discussion en JSON sur stdin à chatCommand et lit les événements diffusés en JSON délimité par des sauts de ligne sur stdout, pendant 300 secondes au maximum. Seul le streaming de discussion est utilisé aujourd'hui.

channel

Un canal relie un service de messagerie. Nebo maintient command en cours d'exécution, lit les messages entrants sur sa stdout et écrit les réponses sur sa stdin, dans les deux cas en JSON délimité par des sauts de ligne.

ChampPar défautSignification
commandobligatoireArguments qui démarrent la passerelle.
name, description""Affiché dans les paramètres.
restartDelaySecs5Attente avant redémarrage après un plantage.
sharedfalseUne seule passerelle pour tous les employés ; les messages sont routés selon le nom de l’employé et les réponses portent l’identité de chaque employé.
needsLocalApifalseDonne à la passerelle l’adresse de l’API locale du bot, un jeton et l’identifiant de l’employé. Désactivé, sauf si vous en avez besoin.

setup

Un assistant de configuration guide le propriétaire à travers des étapes qu'un simple formulaire ne peut pas couvrir. Les valeurs des étapes form remplissent {{key}} dans les arguments generate suivants. Les valeurs des étapes credentials sont enregistrées comme variables d'environnement du plugin.

"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" }
  ]
}
Type d’étapeChamps
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Affiche la sortie de la commande à copier.
externaltitle, description, url, urlLabel, instructions
credentialstitle, description, fields, verifyCommand. L’étape est terminée quand verifyCommand réussit.

Les champs comportent key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) et required.