NeboAI
NeboAI
Empezar

Plugins

Un plugin da a los empleados algo sobre lo que actuar: un servicio online, un sistema de la empresa o un programa del ordenador. 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 de cada 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 unos argumentos, espera a que termine y devuelve 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 se 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 las palabras posicionales.
argsobjeto de cadenasArgumentos con nombre. Cada uno se convierte en --key value.
timeoutintegerSegundos de espera. 120 por defecto, con el límite de permissions.maxTimeoutSeconds del manifiesto.
displaystringLa frase que ve el propietario cuando la llamada necesita aprobación.

Crea tu primer plugin

Escribe en cualquier lenguaje un binario que lea su comando de los argumentos e imprima un resultado. Después 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, y después en target/release/ y target/debug/. Cuando publicas, la tienda rellena platforms para cada binario que subas.

<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 sustituye a un plugin de la tienda con el mismo slug, lo que lo convierte en el sitio para probar una compilación nueva.

Enseña 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 figura automáticamente con el plugin como dependencia. Usa la skill para explicar 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 remita a ellas primero.

La ficha de la tienda es un archivo aparte, PLUGIN.md. Nebo no lo lee al ejecutarse; es la página que la gente ve 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 después añade estos valores. Las entradas posteriores prevalecen.

VariableValor
Claves de auth.envValores por defecto del manifiesto.
<SLUG>_BINRuta del binario de este plugin y de cada plugin del que depende. El slug va en mayúsculas, con los guiones cambiados por 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 plugins y después la ruta heredada.
ConfiguraciónValores que el propietario 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 eliminan 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 contable 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 etiqueta y fija su orden en el formulario de conexión.
  2. auth.profileDirEnv nombra la variable que tu plugin lee para obtener su carpeta de credenciales. Nebo crea una carpeta para cada empleado y cuenta y define esa variable en cada llamada.
  3. Cuando el propietario conecta una cuenta, Nebo ejecuta tu comando login con los valores que escribió el propietario y con la carpeta de la cuenta definida. Tu plugin guarda en esa carpeta lo que necesite. Nebo no conserva los valores.
  4. Tu comando status imprime un JSON como {"authenticated": true}. Cuando caduca un token, Nebo ejecuta refresh si declaras uno.

Para un inicio de sesión en el navegador, pon type a 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 iniciar sesión, el propietario ve una tarjeta de conexión. Un empleado con varias cuentas elige una añadiendo --account <label> a un comando. Nebo quita ese flag antes de que lo vea tu binario.

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

Siguiente