NeboAI
NeboAI
Comenzar

Referencia de plugin.json

plugin.json es el manifiesto que Nebo lee para instalar y ejecutar un plugin. Las claves van en camelCase. Esta página enumera cada campo que Nebo lee hoy y lo que hace cada uno.

Campos de nivel superior

CampoTipoObligatorioSignificado
idstringsíEl identificador del plugin en la tienda. Usa el slug mientras desarrollas.
slugstringsí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.
namestringsíNombre visible. Nombra el servicio al que se conecta.
versionstringsíVersión semántica, como 0.1.0.
platformsmapsíClave de plataforma a binario. Consulta Plataformas.
descriptionstringnoUna oración para personas y empleados.
authorstringnoNombre del publicador.
categorystringnoAyuda a los empleados a encontrar el plugin.
triggerslista de cadenasnoPalabras que describen cuándo aplica el plugin. Se usan en las sugerencias de búsqueda.
entrySkillslista de cadenasnoSkills incluidas que se nombran primero en la descripción de la herramienta del plugin.
dependencieslista de {name, version, optional}noOtros plugins que este ejecuta. version toma "*" de forma predeterminada; optional, false. Sus rutas <SLUG>_BIN se definen en cada llamada.
authobjectnoInicio de sesión y cuentas. Consulta Autenticación.
capabilitiesobjectnoconfigSchema, hooks, commands, routes, providers.
permissionsobjectnoFiltrado del entorno y el límite máximo de tiempo.
eventslistnoObservadores que alimentan los flujos de trabajo de los empleados.
interfaceBindingsmapnoOperaciones tipadas que ofrece el plugin.
channelobjectnoUn puente persistente hacia un servicio de mensajería.
setupobjectnoUn 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": "" }
}
CampoSignificado
binaryNameEl nombre de archivo del ejecutable. Agrega .exe en Windows.
sha256Hash del binario. Se verifica al instalar.
signatureFirma del binario. Se verifica al instalar cuando hay una clave de firma disponible.
sizeTamaño en bytes.
downloadUrlDónde descarga Nebo el paquete.

Autenticación

CampoSignificado
typeoauth_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.
envMapa de nombre de variable a valor predeterminado. También son los únicos nombres de credenciales que Nebo pasa a login.
commands.loginInicia sesión. Obligatorio salvo que type sea env. Se ejecuta con la carpeta de la cuenta definida.
commands.statusImprime un JSON que indica si la cuenta tiene la sesión iniciada.
commands.refreshRenueva un token sin interacción.
commands.logoutCierra la sesión. Solo el dueño puede ejecutarlo.
profileDirEnvVariable que recibe una carpeta de credenciales distinta para cada empleado y cuenta. Sin ella, el plugin tiene una sola cuenta compartida.
label, descriptionTexto de la tarjeta de conexión.
help{url, urlLabel, text} que se muestra mientras se conecta.
publicRedirectDefine 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.

CampoTipoPredeterminadoSignificado
keystringobligatorioNombre de la variable de entorno.
labelstringobligatorioEtiqueta del campo.
descriptionstring""Texto de ayuda.
fieldTypestring"string"Tipo de entrada, como string, number, boolean, select o password.
defaultstringningunoValor precargado.
requiredbooleanfalseEl plugin no está listo hasta que se define el valor.
secretbooleanfalseEl valor se oculta cuando se vuelve a leer.
optionslista de cadenasningunoOpciones para select.

permissions

CampoPredeterminadoSignificado
envAllow[]Variables heredadas que el plugin puede ver. Vacío permite todas.
envDeny[]Variables heredadas que siempre se quitan.
maxTimeoutSeconds300Límite superior del tiempo de espera de cualquier llamada.
networkfalseDeclara 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"
  }
]
CampoSignificado
nameNombre del evento, sin el slug. Obligatorio.
commandArgumentos que inician el observador. Obligatorio. {{key}} se reemplaza con los valores de entrada del empleado.
descriptionQué provoca el evento.
multiplexedCuando 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}"
}
MarcadorSe 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.

CampoPredeterminadoSignificado
hookobligatorioUno 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.
commandobligatorioArgumentos para tu binario.
priority100El menor se ejecuta primero.
timeoutMs500Lí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.

CampoPredeterminadoSignificado
commandobligatorioArgumentos que inician el puente.
name, description""Se muestra en la configuración.
restartDelaySecs5Espera antes de reiniciar después de una falla.
sharedfalseUn solo puente para todos los empleados; los mensajes se enrutan por nombre de empleado y las respuestas llevan la identidad de cada empleado.
needsLocalApifalseLe 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 pasoCampos
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Muestra la salida del comando para copiarla.
externaltitle, description, url, urlLabel, instructions
credentialstitle, 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.