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ámetro | Tipo | Significado |
|---|---|---|
command | cadena, obligatorio | El comando del plugin y cualquier palabra posicional. |
args | objeto de cadenas | Argumentos con nombre. Cada uno se convierte en --key value. |
timeout | integer | Segundos de espera. Predeterminado 120, con el tope de permissions.maxTimeoutSeconds del manifiesto. |
display | string | La 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.
| Variable | Valor |
|---|---|
Claves de auth.env | Valores predeterminados del manifiesto. |
<SLUG>_BIN | Ruta 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_DIR | La carpeta de datos propia del plugin, <data>/appdata/plugins/<slug>/. También es el directorio de trabajo y se conserva al desinstalar. |
PATH | Primero las carpetas de los plugins, luego la ruta heredada. |
| Configuración | Valores que el dueño guardó para los campos de configSchema. |
NEBO_AGENT_ID | El empleado que hace la llamada. |
profileDirEnv | La 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 }
]
} auth.envnombra las credenciales.capabilities.configSchemales pone etiquetas y define su orden en el formulario de conexión.auth.profileDirEnvnombra 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.- Cuando el dueño conecta una cuenta, Nebo ejecuta tu comando
logincon 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. - Tu comando
statusimprime JSON como{"authenticated": true}. Cuando un token vence, Nebo ejecutarefreshsi 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
- Referencia de plugin.json: cada campo, incluidos eventos, hooks y operaciones tipadas.
- Publicar un plugin: plataformas, binarios, firma y actualizaciones.
- Publicación: el flujo de la tienda para cada artefacto.