NeboAI
NeboAI
Empezar

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 recoge todos los campos que Nebo lee hoy y qué hace cada uno.

Campos de nivel superior

CampoTipoObligatorioSignificado
idstringsíEl identificador del plugin en la tienda. Usa el slug durante el desarrollo.
slugstringsíIdentificador estable. [a-z0-9-], como máximo 64 caracteres, sin guion inicial, final ni doble. Da nombre a la herramienta plugin__<slug> y a la variable <SLUG>_BIN.
namestringsíNombre visible. Indica el servicio al que se conecta.
versionstringsíVersión semántica, como 0.1.0.
platformsmapsíClave de plataforma a binario. Consulta Plataformas.
descriptionstringnoUna frase para las personas y los empleados.
authorstringnoNombre del editor.
categorystringnoAyuda a los empleados a encontrar el plugin.
triggerslista de cadenasnoPalabras que describen cuándo se 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 vale "*" por defecto; 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 límite máximo de tiempo de espera.
eventslistnoObservadores que alimentan los flujos de trabajo de los empleados.
interfaceBindingsmapnoOperaciones tipadas que ofrece el plugin.
channelobjectnoUn puente persistente con 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 enlace que se puedan analizar. Los plugins del directorio de plugins del usuario no pasan por 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 siguientes. 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 subas.

"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. Añade .exe en Windows.
sha256Hash del binario. Se comprueba al instalar.
signatureFirma del binario. Se comprueba 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 gestiona el plugin; env para credenciales introducidas como valores; neboai para recibir el token de NeboAI del propietario en cada clave de auth.env que termine en _TOKEN.
envMapa de nombre de variable a valor por defecto. 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 propietario puede ejecutarlo.
profileDirEnvVariable que recibe una carpeta de credenciales independiente para cada empleado y cuenta. Sin ella, el plugin tiene una única cuenta compartida.
label, descriptionTexto de la tarjeta de conexión.
help{url, urlLabel, text} que se muestra durante la conexión.
publicRedirectPonlo a true cuando el proveedor rechace las redirecciones a http://localhost; el inicio de sesión pasa entonces 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 que no hay sesión iniciada. El comando de estado dispone de 45 segundos.

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

configSchema

capabilities.configSchema describe los valores que un propietario define para el plugin. Cada valor llega al binario como una variable de entorno con el nombre indicado en key. Para las claves de credenciales que también aparecen en auth.env, el esquema pone etiqueta a los campos del formulario de conexión de cada empleado.

CampoTipoPor defectoSignificado
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 al volver a leerlo.
optionslista de cadenasningunoOpciones para select.

permissions

CampoPor defectoSignificado
envAllow[]Variables heredadas que el plugin puede ver. Si está vacío, se permiten todas.
envDeny[]Variables heredadas que siempre se eliminan.
maxTimeoutSeconds300Límite superior del tiempo de espera de cualquier llamada.
networkfalseDeclara el uso de la red. 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 delante el slug, así que note.created pasa a ser 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 sustituye por los valores de entrada del empleado.
descriptionQué provoca el evento.
multiplexedSi es true, un solo observador emite varios tipos de evento y cada línea lleva un campo "event".

Los flujos de trabajo se suscriben a eventos con un disparador watch. Consulta Disparadores.

interfaceBindings

Un enlace asigna una operación de interfaz a uno de tus comandos. Cada enlace se convierte en una herramienta tipada para los empleados, con el nombre de la operación en minúsculas y los puntos y guiones cambiados por guiones bajos: notes.search pasa a ser notes_search. Los enlaces 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 además 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 falta.
{field:cents->dollars}Un importe entero en céntimos, escrito en dólares.

Los campos de entrada que una plantilla no nombra se añaden al final como --field value. Los marcadores de lista y opcionales deben ser palabras completas. A una operación que requiere aprobación no se puede llegar llamando al mismo comando mediante 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 momento concreto 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. Tras tres fallos seguidos, un hook se pausa durante cinco minutos.

CampoPor defectoSignificado
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 a solicitudes HTTP en /api/v1/plugins/<slug>/api/<path> del 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 añade 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 los eventos transmitidos como JSON delimitado por saltos de línea en stdout, durante un máximo de 300 segundos. Hoy solo se usa el streaming de chat.

channel

Un canal hace de puente con 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.

CampoPor defectoSignificado
commandobligatorioArgumentos que inician el puente.
name, description""Se muestra en la configuración.
restartDelaySecs5Espera antes de reiniciar tras un fallo.
sharedfalseUn puente para todos los empleados; los mensajes se enrutan por el nombre del empleado y las respuestas llevan la identidad de cada empleado.
needsLocalApifalseDa 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 propietario por pasos que un solo formulario no puede cubrir. Los valores de los pasos form rellenan {{key}} en los argumentos 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.