Campos de nivel superior
| Campo | Tipo | Obligatorio | Significado |
|---|---|---|---|
id | string | sí | El identificador del plugin en la tienda. Usa el slug mientras desarrollas. |
slug | string | sí | Identificador estable. [a-z0-9-], máximo 64 caracteres, sin guion al inicio, al final ni doble. Da nombre a la herramienta plugin__<slug> y a la variable <SLUG>_BIN. |
name | string | sí | Nombre visible. Nombra el servicio al que se conecta. |
version | string | sí | Versión semántica, como 0.1.0. |
platforms | map | sí | Clave de plataforma a binario. Consulta Plataformas. |
description | string | no | Una oración para personas y empleados. |
author | string | no | Nombre del publicador. |
category | string | no | Ayuda a los empleados a encontrar el plugin. |
triggers | lista de cadenas | no | Palabras que describen cuándo aplica el plugin. Se usan en las sugerencias de búsqueda. |
entrySkills | lista de cadenas | no | Skills incluidas que se nombran primero en la descripción de la herramienta del plugin. |
dependencies | lista de {name, version, optional} | no | Otros plugins que este ejecuta. version toma "*" de forma predeterminada; optional, false. Sus rutas <SLUG>_BIN se definen en cada llamada. |
auth | object | no | Inicio de sesión y cuentas. Consulta Autenticación. |
capabilities | object | no | configSchema, hooks, commands, routes, providers. |
permissions | object | no | Filtrado del entorno y el límite máximo de tiempo. |
events | list | no | Observadores que alimentan los flujos de trabajo de los empleados. |
interfaceBindings | map | no | Operaciones tipadas que ofrece el plugin. |
channel | object | no | Un puente persistente hacia un servicio de mensajería. |
setup | object | no | Un asistente de configuración paso a paso. |
Nebo valida las instalaciones desde la tienda: las reglas del slug, una versión semántica, al menos una plataforma, un binaryName sin separadores de ruta ni .., un comando login salvo que auth.type sea env, nombres de eventos y comandos no vacíos, y plantillas de binding que se puedan analizar. Los plugins del directorio de plugins del usuario se saltan la validación.
Plataformas
Las claves son darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 y windows-amd64. Cada entrada tiene los cinco campos de abajo. Cuando publicas, la tienda escribe el hash, el tamaño, la firma y la URL de descarga reales, así que déjalos vacíos en el archivo que subes.
"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": "" }
} | Campo | Significado |
|---|---|
binaryName | El nombre de archivo del ejecutable. Agrega .exe en Windows. |
sha256 | Hash del binario. Se verifica al instalar. |
signature | Firma del binario. Se verifica al instalar cuando hay una clave de firma disponible. |
size | Tamaño en bytes. |
downloadUrl | Dónde descarga Nebo el paquete. |
Autenticación
| Campo | Significado |
|---|---|
type | oauth_cli para un inicio de sesión en el navegador que ejecuta el plugin; env para credenciales que se ingresan como valores; neboai para recibir el token de NeboAI del dueño en cada clave de auth.env que termine en _TOKEN. |
env | Mapa de nombre de variable a valor predeterminado. También son los únicos nombres de credenciales que Nebo pasa a login. |
commands.login | Inicia sesión. Obligatorio salvo que type sea env. Se ejecuta con la carpeta de la cuenta definida. |
commands.status | Imprime un JSON que indica si la cuenta tiene la sesión iniciada. |
commands.refresh | Renueva un token sin interacción. |
commands.logout | Cierra la sesión. Solo el dueño puede ejecutarlo. |
profileDirEnv | Variable que recibe una carpeta de credenciales distinta para cada empleado y cuenta. Sin ella, el plugin tiene una sola cuenta compartida. |
label, description | Texto de la tarjeta de conexión. |
help | {url, urlLabel, text} que se muestra mientras se conecta. |
publicRedirect | Define true cuando el proveedor rechaza redirecciones a http://localhost; entonces el inicio de sesión pasa por la redirección pública de NeboAI. |
Nebo lee el primero de authenticated, isAuthenticated, logged_in, loggedIn o token_valid en la salida de estado. Un token_error no vacío, o el valor none en credential_source, auth_method, storage o status, significa sesión cerrada. El comando de estado tiene 45 segundos.
{"authenticated": true, "account": "finance@example.com"} configSchema
capabilities.configSchema describe los valores que un dueño define para el plugin. Cada valor llega al binario como una variable de entorno con el nombre de key. Para las claves de credenciales que también aparecen en auth.env, el esquema pone las etiquetas de los campos del formulario de conexión por empleado.
| Campo | Tipo | Predeterminado | Significado |
|---|---|---|---|
key | string | obligatorio | Nombre de la variable de entorno. |
label | string | obligatorio | Etiqueta del campo. |
description | string | "" | Texto de ayuda. |
fieldType | string | "string" | Tipo de entrada, como string, number, boolean, select o password. |
default | string | ninguno | Valor precargado. |
required | boolean | false | El plugin no está listo hasta que se define el valor. |
secret | boolean | false | El valor se oculta cuando se vuelve a leer. |
options | lista de cadenas | ninguno | Opciones para select. |
permissions
| Campo | Predeterminado | Significado |
|---|---|---|
envAllow | [] | Variables heredadas que el plugin puede ver. Vacío permite todas. |
envDeny | [] | Variables heredadas que siempre se quitan. |
maxTimeoutSeconds | 300 | Límite superior del tiempo de espera de cualquier llamada. |
network | false | Declara el uso de la red. Es informativo; no se aplica. |
events
Un evento es un observador de larga duración. Nebo lo inicia cuando el flujo de trabajo de un empleado lo observa, y lo reinicia si termina. Cada línea que el observador escribe en stdout es un evento. Al ejecutarse, el nombre del evento lleva el slug como prefijo, así que note.created se convierte en notes-sync.note.created.
"events": [
{
"name": "note.created",
"description": "A note was created in the watched notebook.",
"command": "watch --notebook {{notebook}} --format ndjson"
}
] | Campo | Significado |
|---|---|
name | Nombre del evento, sin el slug. Obligatorio. |
command | Argumentos que inician el observador. Obligatorio. {{key}} se reemplaza con los valores de entrada del empleado. |
description | Qué provoca el evento. |
multiplexed | Cuando es true, un mismo observador emite varios tipos de eventos y cada línea lleva un campo "event". |
Los flujos de trabajo se suscriben a eventos con un disparador watch. Consulta Disparadores.
interfaceBindings
Un binding asigna una operación de interfaz a uno de tus comandos. Cada binding se convierte en una herramienta tipada para los empleados, con el nombre de la operación en minúsculas y con puntos y guiones como guiones bajos: notes.search se convierte en notes_search. Los bindings son la forma en que un plugin cumple las capacidades que requiere un empleado; consulta Capacidades.
"interfaceBindings": {
"notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
"invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
} | Marcador | Se expande a |
|---|---|
{field} | El valor del campo como una sola palabra. El campo no se pasa también como flag. |
{field[]:--flag} | Un par --flag <item> por cada elemento de un campo de lista. |
{field?:--flag} | --flag <value> cuando el campo está presente; nada cuando no está. |
{field:cents->dollars} | Un monto entero en centavos, escrito en dólares. |
Los campos de entrada que una plantilla no nombra se agregan al final como --field value. Los marcadores de lista y opcionales deben ser palabras completas. Una operación que requiere aprobación no se puede alcanzar llamando al mismo comando a través de plugin__<slug>.
Hooks, comandos de barra y rutas
"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 ejecuta tu comando en un punto del turno de un empleado. Nebo escribe un payload JSON en stdin. La salida de un hook action se ignora. Un hook filter devuelve {"payload": ..., "handled": false}; "handled": true detiene los hooks posteriores. Los errores y los tiempos de espera agotados conservan el payload anterior y nunca bloquean el turno. Después de tres fallas seguidas, un hook se pausa durante cinco minutos.
| Campo | Predeterminado | Significado |
|---|---|---|
hook | obligatorio | Uno de tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue. |
hookType | "action" | action o filter. |
command | obligatorio | Argumentos para tu binario. |
priority | 100 | El menor se ejecuta primero. |
timeoutMs | 500 | Límite de tiempo en milisegundos. |
commands
Con "slash": true, escribir /name args en el chat ejecuta command args directamente, sin el empleado. La salida es la respuesta. El límite de tiempo es de 30 segundos.
routes
Una ruta responde solicitudes HTTP en /api/v1/plugins/<slug>/api/<path> en el bot, según path y method. El cuerpo de la solicitud va a stdin y tu stdout es la respuesta. El límite de tiempo es de 30 segundos.
providers
Un proveedor agrega una fuente de modelos de chat. Declara id, displayName, providerType, modelsCommand y chatCommand. Nebo envía una solicitud de chat como JSON por stdin a chatCommand y lee eventos transmitidos como JSON delimitado por saltos de línea en stdout, durante un máximo de 300 segundos. Hoy solo se usa la transmisión de chat.
channel
Un canal conecta un servicio de mensajería. Nebo mantiene command en ejecución, lee los mensajes entrantes de su stdout y escribe las respuestas en su stdin, ambos como JSON delimitado por saltos de línea.
| Campo | Predeterminado | Significado |
|---|---|---|
command | obligatorio | Argumentos que inician el puente. |
name, description | "" | Se muestra en la configuración. |
restartDelaySecs | 5 | Espera antes de reiniciar después de una falla. |
shared | false | Un solo puente para todos los empleados; los mensajes se enrutan por nombre de empleado y las respuestas llevan la identidad de cada empleado. |
needsLocalApi | false | Le da al puente la dirección de la API local del bot, un token y el id del empleado. Desactivado salvo que lo necesites. |
setup
Un asistente de configuración guía al dueño por pasos que un solo formulario no puede cubrir. Los valores de los pasos form completan {{key}} en los argumentos de generate posteriores. Los valores de los pasos credentials se guardan como variables de entorno del 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" }
]
} | Tipo de paso | Campos |
|---|---|
form | title, description, fields |
generate | title, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Muestra la salida del comando para copiarla. |
external | title, description, url, urlLabel, instructions |
credentials | title, description, fields, verifyCommand. El paso se completa cuando verifyCommand tiene éxito. |
Los campos tienen key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) y required.