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ámetro | Tipo | Significado |
|---|---|---|
command | cadena, obligatorio | El comando del plugin y las palabras posicionales. |
args | objeto de cadenas | Argumentos con nombre. Cada uno se convierte en --key value. |
timeout | integer | Segundos de espera. 120 por defecto, con el límite de permissions.maxTimeoutSeconds del manifiesto. |
display | string | La 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.
| Variable | Valor |
|---|---|
Claves de auth.env | Valores por defecto del manifiesto. |
<SLUG>_BIN | Ruta 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_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 plugins y después la ruta heredada. |
| Configuración | Valores que el propietario 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 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 }
]
} auth.envnombra las credenciales.capabilities.configSchemales pone etiqueta y fija su orden en el formulario de conexión.auth.profileDirEnvnombra 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.- Cuando el propietario conecta una cuenta, Nebo ejecuta tu comando
logincon 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. - Tu comando
statusimprime un JSON como{"authenticated": true}. Cuando caduca un token, Nebo ejecutarefreshsi 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
- Referencia de plugin.json: todos los campos, incluidos los eventos, los hooks y las operaciones tipadas.
- Publicar un plugin: plataformas, binarios, firma y actualizaciones.
- Publicación: el proceso de la tienda para cada artefacto.