NeboAI
NeboAI
Comenzar

Plugins

Un plugin les da a los empleados algo sobre lo cual actuar: un servicio en línea, un sistema del negocio o un programa en la computadora. Lo creas como un binario de línea de comandos y lo describes con un manifiesto plugin.json. Los empleados llaman a sus comandos, y Nebo se encarga de la instalación, las cuentas por empleado y las actualizaciones.

Cómo funcionan los plugins

Un plugin es un ejecutable más un manifiesto. Nebo no mantiene ningún proceso del plugin en ejecución entre llamadas. Cada vez que un empleado usa el plugin, Nebo inicia el binario con un comando y argumentos, espera a que termine y le entrega la salida al empleado.

  • Los comandos son argumentos. El empleado elige un comando, como notes search, y argumentos con nombre. Nebo pasa cada argumento como --name value. No hay shell, así que las tuberías y las redirecciones nunca aplican.
  • La salida es stdout. Escribe los resultados en stdout. JSON funciona bien.
  • La entrada estándar está cerrada en las llamadas normales. Los hooks, las rutas y los proveedores de chat usan stdin; consulta la referencia de plugin.json.

Cada plugin instalado y activado aparece ante los empleados como una herramienta llamada plugin__<slug>. Un empleado la llama así:

{
  "command": "notes search",
  "args": { "query": "quarterly plan", "limit": "5" },
  "display": "Search notes for the quarterly plan"
}

Nebo ejecuta:

notes-sync notes search --query "quarterly plan" --limit 5
ParámetroTipoSignificado
commandcadena, obligatorioEl comando del plugin y cualquier palabra posicional.
argsobjeto de cadenasArgumentos con nombre. Cada uno se convierte en --key value.
timeoutintegerSegundos de espera. Predeterminado 120, con el tope de permissions.maxTimeoutSeconds del manifiesto.
displaystringLa oración que ve el dueño cuando la llamada necesita aprobación.

Crea tu primer plugin

Escribe un binario en cualquier lenguaje que lea su comando de los argumentos e imprima un resultado. Luego colócalo junto a un plugin.json en el directorio de plugins del usuario de 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 y platforms son obligatorios. En el directorio de plugins del usuario, el mapa platforms puede estar vacío: Nebo busca un binario con el nombre del slug junto a plugin.json, luego en target/release/ y target/debug/. Cuando publicas, la tienda completa platforms con cada binario que subes.

<data> es ~/Library/Application Support/Nebo en macOS, %APPDATA%\Nebo en Windows y ~/.local/share/nebo en Linux, o el valor de NEBO_HOME. Un plugin en el directorio del usuario reemplaza a un plugin de la tienda con el mismo slug, por eso es el lugar para probar una compilación nueva.

Enséñales a los empleados a usarlo

Pon una carpeta skills/ junto a plugin.json. Cada skill que contenga está disponible para todos los empleados mientras el plugin esté instalado, y declara el plugin como dependencia automáticamente. Usa la skill para decir qué comandos existen, qué devuelven y cuándo usar cada uno. Nombra las skills más útiles en entrySkills para que la descripción de la herramienta del plugin apunte primero a ellas.

La ficha de la tienda es un archivo aparte, PLUGIN.md. Nebo no lo lee al ejecutarse; es la página que las personas ven antes de instalar. Consulta Publicar un plugin.

Entorno

Cada llamada hereda el entorno del bot sin las variables del cargador ni las de inyección de shell, y luego agrega estos valores. Las entradas posteriores tienen prioridad.

VariableValor
Claves de auth.envValores predeterminados del manifiesto.
<SLUG>_BINRuta del binario de este plugin y de cada plugin del que depende. El slug va en mayúsculas, con guiones como guiones bajos.
NEBO_DATA_DIRLa carpeta de datos propia del plugin, <data>/appdata/plugins/<slug>/. También es el directorio de trabajo y se conserva al desinstalar.
PATHPrimero las carpetas de los plugins, luego la ruta heredada.
ConfiguraciónValores que el dueño guardó para los campos de configSchema.
NEBO_AGENT_IDEl empleado que hace la llamada.
profileDirEnvLa carpeta de la cuenta para este empleado y esta cuenta, cuando el plugin admite cuentas.

permissions.envAllow y permissions.envDeny limitan lo que el plugin hereda del bot. Nunca quitan las variables de autenticación propias del plugin.

Cuentas y credenciales

Un plugin que inicia sesión en un servicio debe tener una cuenta por empleado. El contador inicia sesión con el acceso de finanzas y el asistente con el suyo, y ninguno ve los tokens del otro. Tú lo declaras en el manifiesto; Nebo hace el resto.

"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 }
  ]
}
  1. auth.env nombra las credenciales. capabilities.configSchema les pone etiquetas y define su orden en el formulario de conexión.
  2. auth.profileDirEnv nombra la variable que tu plugin lee para su carpeta de credenciales. Nebo crea una carpeta para cada empleado y cuenta, y define esa variable en cada llamada.
  3. Cuando el dueño conecta una cuenta, Nebo ejecuta tu comando login con los valores que escribió el dueño y la carpeta de la cuenta definida. Tu plugin guarda lo que necesita en esa carpeta. Nebo no conserva los valores.
  4. Tu comando status imprime JSON como {"authenticated": true}. Cuando un token vence, Nebo ejecuta refresh si declaras uno.

Para un inicio de sesión en el navegador, define type como oauth_cli y haz que login imprima o abra la URL de inicio de sesión del proveedor. Los empleados nunca inician sesión por su cuenta: cuando una llamada necesita un inicio de sesión, el dueño ve una tarjeta de conexión. Un empleado con varias cuentas elige una agregando --account <label> a un comando. Nebo quita esa flag antes de que tu binario la vea.

Nombra el servicio, no la forma. El nombre de un plugin dice a qué se conecta, como "Example Notes". Nunca pongas "CLI" en el nombre de un plugin; para los empleados y los dueños es una conexión, no una línea de comandos.

Siguiente