Champs de premier niveau
| Champ | Type | Obligatoire | Signification |
|---|---|---|---|
id | string | oui | L’identifiant du plugin dans la boutique. Utilisez le slug pendant le développement. |
slug | string | oui | Identifiant 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. |
name | string | oui | Nom affiché. Indiquez le service auquel il se connecte. |
version | string | oui | Version sémantique, par exemple 0.1.0. |
platforms | map | oui | Clé de plateforme vers binaire. Voir Plateformes. |
description | string | non | Une phrase destinée aux personnes et aux employés. |
author | string | non | Nom de l’éditeur. |
category | string | non | Aide les employés à trouver le plugin. |
triggers | liste de chaînes | non | Mots qui décrivent quand le plugin s’applique. Utilisés dans les suggestions de recherche. |
entrySkills | liste de chaînes | non | Skills intégrés à citer en premier dans la description de l’outil du plugin. |
dependencies | liste de {name, version, optional} | non | Autres plugins exécutés par celui-ci. version vaut "*" par défaut ; optional vaut false. Leurs chemins <SLUG>_BIN sont définis à chaque appel. |
auth | object | non | Connexion et comptes. Voir Authentification. |
capabilities | object | non | configSchema, hooks, commands, routes, providers. |
permissions | object | non | Filtrage de l’environnement et plafond de délai d’expiration. |
events | list | non | Des observateurs qui alimentent les workflows des employés. |
interfaceBindings | map | non | Les opérations typées fournies par le plugin. |
channel | object | non | Une passerelle permanente vers un service de messagerie. |
setup | object | non | Un 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": "" }
} | Champ | Signification |
|---|---|
binaryName | Le nom de fichier de l’exécutable. Ajoutez .exe sur Windows. |
sha256 | Hash du binaire. Vérifié à l’installation. |
signature | Signature du binaire. Vérifiée à l’installation quand une clé de signature est disponible. |
size | Taille en octets. |
downloadUrl | L’endroit où Nebo télécharge le paquet. |
Authentification
| Champ | Signification |
|---|---|
type | oauth_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. |
env | Correspondance entre nom de variable et valeur par défaut. Ce sont aussi les seuls noms d’identifiants que Nebo transmet à login. |
commands.login | Connecte. Obligatoire sauf si type vaut env. S’exécute avec le dossier du compte défini. |
commands.status | Affiche un JSON qui indique si le compte est connecté. |
commands.refresh | Renouvelle un jeton sans interaction. |
commands.logout | Déconnecte. Seul le propriétaire peut l’exécuter. |
profileDirEnv | Variable 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, description | Texte de la carte de connexion. |
help | {url, urlLabel, text} affiché pendant la connexion. |
publicRedirect | Mettez 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é.
| Champ | Type | Par défaut | Signification |
|---|---|---|---|
key | string | obligatoire | Nom de la variable d’environnement. |
label | string | obligatoire | Libellé du champ. |
description | string | "" | Texte d’aide. |
fieldType | string | "string" | Type de saisie, par exemple string, number, boolean, select ou password. |
default | string | aucune | Valeur pré-remplie. |
required | boolean | false | Le plugin n’est pas prêt tant que la valeur n’est pas définie. |
secret | boolean | false | La valeur est masquée à la relecture. |
options | liste de chaînes | aucune | Choix pour select. |
permissions
| Champ | Par défaut | Signification |
|---|---|---|
envAllow | [] | Variables héritées que le plugin peut voir. Vide, tout est autorisé. |
envDeny | [] | Variables héritées toujours supprimées. |
maxTimeoutSeconds | 300 | Limite supérieure du délai d’expiration de tout appel. |
network | false | Dé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"
}
] | Champ | Signification |
|---|---|
name | Nom de l’événement, sans le slug. Obligatoire. |
command | Arguments qui démarrent l’observateur. Obligatoire. {{key}} est remplacé par les valeurs saisies pour l’employé. |
description | Ce qui déclenche l’événement. |
multiplexed | Avec 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.
| Champ | Par défaut | Signification |
|---|---|---|
hook | obligatoire | L’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. |
command | obligatoire | Arguments pour votre binaire. |
priority | 100 | Le plus bas s’exécute en premier. |
timeoutMs | 500 | Limite 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.
| Champ | Par défaut | Signification |
|---|---|---|
command | obligatoire | Arguments qui démarrent la passerelle. |
name, description | "" | Affiché dans les paramètres. |
restartDelaySecs | 5 | Attente avant redémarrage après un plantage. |
shared | false | Une 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é. |
needsLocalApi | false | Donne à 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’étape | Champs |
|---|---|
form | title, description, fields |
generate | title, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Affiche la sortie de la commande à copier. |
external | title, description, url, urlLabel, instructions |
credentials | title, 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.