Fonctionnement des plugins
Un plugin, c'est un exécutable plus un manifeste. Nebo ne laisse aucun processus de plugin tourner entre deux appels. Chaque fois qu'un employé utilise le plugin, Nebo lance le binaire avec une commande et des arguments, attend qu'il se termine et renvoie la sortie à l'employé.
- Les commandes sont des arguments. L'employé choisit une commande, comme
notes search, et des arguments nommés. Nebo transmet chaque argument sous la forme--name value. Il n'y a pas de shell : les pipes et redirections ne s'appliquent jamais. - La sortie, c'est stdout. Écrivez les résultats sur stdout. Le JSON convient très bien.
- L'entrée standard est fermée pour les appels ordinaires. Les hooks, les routes et les fournisseurs de discussion utilisent stdin ; voir la référence de plugin.json.
Chaque plugin installé et activé apparaît aux employés comme un seul outil nommé plugin__<slug>. Un employé l'appelle ainsi :
{
"command": "notes search",
"args": { "query": "quarterly plan", "limit": "5" },
"display": "Search notes for the quarterly plan"
} Nebo exécute :
notes-sync notes search --query "quarterly plan" --limit 5
| Paramètre | Type | Signification |
|---|---|---|
command | chaîne, obligatoire | La commande du plugin et les éventuels mots positionnels. |
args | objet de chaînes | Arguments nommés. Chacun devient --key value. |
timeout | integer | Secondes d’attente. 120 par défaut, plafonné par permissions.maxTimeoutSeconds du manifeste. |
display | string | La phrase que voit le propriétaire quand l’appel nécessite une approbation. |
Créer votre premier plugin
Écrivez, dans le langage de votre choix, un binaire qui lit sa commande dans les arguments et affiche un résultat. Placez-le ensuite à côté d'un plugin.json dans le dossier des plugins utilisateur d'un bot.
<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 et platforms sont obligatoires. Dans le dossier des plugins utilisateur, la table platforms peut être vide : Nebo cherche un binaire portant le nom du slug à côté de plugin.json, puis dans target/release/ et target/debug/. Lors de la publication, la boutique remplit platforms pour chaque binaire que vous envoyez.
<data> correspond à ~/Library/Application Support/Nebo sur macOS, %APPDATA%\Nebo sur Windows et ~/.local/share/nebo sur Linux, ou à la valeur de NEBO_HOME. Un plugin du dossier utilisateur remplace un plugin de la boutique ayant le même slug, ce qui en fait l'endroit idéal pour tester une nouvelle version.
Apprendre aux employés à s’en servir
Placez un dossier skills/ à côté de plugin.json. Chaque skill qu'il contient est disponible pour tous les employés tant que le plugin est installé, et indique automatiquement le plugin comme dépendance. Servez-vous du skill pour dire quelles commandes existent, ce qu'elles renvoient et quand utiliser chacune. Citez les skills les plus utiles dans entrySkills pour que la description de l'outil du plugin les mette en avant.
La fiche de la boutique est un fichier distinct, PLUGIN.md. Nebo ne le lit pas à l'exécution ; c'est la page que les gens voient avant d'installer. Voir Livrer un plugin.
Environnement
Chaque appel hérite de l'environnement du bot, privé des variables du chargeur et d'injection shell, puis y ajoute ces valeurs. Les dernières entrées l'emportent.
| Variable | Valeur |
|---|---|
Clés auth.env | Valeurs par défaut du manifeste. |
<SLUG>_BIN | Chemin du binaire de ce plugin et de chaque plugin dont il dépend. Le slug est mis en majuscules, les traits d’union devenant des tirets bas. |
NEBO_DATA_DIR | Le dossier de données propre au plugin, <data>/appdata/plugins/<slug>/. C’est aussi le répertoire de travail, et il est conservé à la désinstallation. |
PATH | Les dossiers des plugins d’abord, puis le chemin hérité. |
| Paramètres | Les valeurs que le propriétaire a enregistrées pour les champs configSchema. |
NEBO_AGENT_ID | L’employé qui effectue l’appel. |
profileDirEnv | Le dossier du compte pour cet employé et ce compte, quand le plugin prend en charge les comptes. |
permissions.envAllow et permissions.envDeny restreignent ce que le plugin hérite du bot. Ils ne suppriment jamais les variables d'authentification propres au plugin.
Comptes et identifiants
Un plugin qui se connecte à un service devrait avoir un compte par employé. Le comptable se connecte avec l'identifiant de la comptabilité et l'assistant avec le sien, et aucun ne voit les jetons de l'autre. Vous le déclarez dans le manifeste ; Nebo s'occupe du reste.
"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 }
]
} auth.envnomme les identifiants.capabilities.configSchemaleur donne un libellé et fixe leur ordre dans le formulaire de connexion.auth.profileDirEnvnomme la variable que votre plugin lit pour trouver son dossier d'identifiants. Nebo crée un dossier pour chaque employé et chaque compte, et définit cette variable à chaque appel.- Quand le propriétaire connecte un compte, Nebo exécute votre commande
loginavec les valeurs saisies par le propriétaire et le dossier du compte défini. Votre plugin enregistre ce dont il a besoin dans ce dossier. Nebo ne conserve pas les valeurs. - Votre commande
statusaffiche du JSON comme{"authenticated": true}. Quand un jeton expire, Nebo exécuterefreshsi vous en déclarez une.
Pour une connexion dans le navigateur, mettez type à oauth_cli et faites en sorte que login affiche ou ouvre l'URL de connexion du fournisseur. Les employés ne se connectent jamais seuls : quand un appel nécessite une connexion, le propriétaire voit une carte de connexion. Un employé qui a plusieurs comptes en choisit un en ajoutant --account <label> à une commande. Nebo retire cette option avant que votre binaire ne la voie.
Nommez le service, pas la forme. Le nom d'un plugin dit à quoi il se connecte, par exemple « Example Notes ». N'ajoutez jamais « CLI » au nom d'un plugin ; pour les employés et les propriétaires, c'est une connexion, pas une ligne de commande.
Ensuite
- Référence de plugin.json : chaque champ, y compris les événements, les hooks et les opérations typées.
- Livrer un plugin : plateformes, binaires, signature et mises à jour.
- Publication : le parcours de la boutique pour chaque type d'élément.