NeboAI
NeboAI
Empezar

Apps

Una app es un empleado con una página. Los propietarios la abren en su propia ventana para ver algo y trabajar con ello directamente: un tablero, un registro de seguimiento, un formulario. La página es HTML y JavaScript normales, y se comunica con Nebo y con su empleado mediante un único script, el SDK de apps.

El paquete

Una app es un paquete de empleado con un manifest.json que lo marca como app y una carpeta ui/ con la página.

<data>/user/agents/deal-board/
├── manifest.json     # marks the employee as an app
├── AGENT.md          # the employee behind the page
├── agent.json        # optional: sidecar tools, workflows
└── ui/
    ├── index.html
    └── app.js
{
  "id": "<minted UUID>",
  "name": "deal-board",
  "version": "1.0.0",
  "type": "app",
  "window": { "title": "Deal Board", "width": 900, "height": 700, "resizable": true },
  "permissions": ["storage:readwrite"]
}
CampoSignificado
type"app". Convierte al empleado en una app. Nebo también lee el antiguo artifact_type.
idUn UUID generado al crear la app. La página se sirve en /apps/<id>/ui/.
name, versionEl nombre del empleado y la versión del paquete.
windowtitle, width, height, resizable, fullscreen, orientation. Valores predeterminados: 1024 × 768, redimensionable, sin pantalla completa, vertical, con el nombre del empleado como título.
permissionsLo que puede hacer la página. Valor predeterminado: ["storage:readwrite"].

Permisos

PermisoConcede
storage:readwriteEl almacén de clave-valor de la app.
subagent:<employee-id>Preguntar a otro empleado desde la página. El propio empleado de la app no necesita permiso.
network:<host> o network:*Solicitudes a hosts externos a través del proxy de Nebo.
device:motionEl giroscopio y el acelerómetro, solo para esta página. En el iPhone, la página también llama a DeviceMotionEvent.requestPermission() a partir de un toque.

Cada permiso es prefix:scope. Pide lo mínimo que necesite la app.

Pantalla completa, orientación e inclinación

Los juegos y las películas pueden ocupar toda la pantalla. Establece fullscreen y, para la app móvil, una orientation: portrait (la predeterminada), landscape o any. Cualquier otra orientación se rechaza al escribir el manifiesto.

{
  "type": "app",
  "permissions": ["storage:readwrite", "device:motion"],
  "window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
}
  • En el escritorio, la app se abre en una ventana a pantalla completa.
  • En la app móvil no hay barra de la app, las barras del sistema se ocultan, la pantalla no se apaga y el gesto de deslizar para actualizar está desactivado. Una pequeña píldora Cerrar se sitúa en la esquina superior izquierda y se desvanece al cabo de unos segundos; un toque cerca de la parte superior la hace volver. El deslizamiento desde el borde de iOS está desactivado, y el botón Atrás de Android recorre el historial de la página antes de cerrarla.
  • Añade márgenes a la página con env(safe-area-inset-*) y viewport-fit=cover, y deja libre de controles la esquina superior izquierda.

El control de voz

Cada app que se abre en la app de escritorio de Nebo o en la app móvil muestra un pequeño control de voz en la esquina inferior derecha, para que el propietario pueda hablar con el empleado de la app mientras trabaja en la página. El control está fuera de tu página, así que recargar la página nunca corta la llamada.

  • En el escritorio es una barra de unos 300 por 48 píxeles, a 16 píxeles de la esquina inferior derecha de la ventana.
  • En la app móvil es un botón redondo de 48 puntos dentro del área segura que el propietario puede arrastrar a cualquiera de los dos lados. En una app a pantalla completa, se vuelve a plegar en ese botón a los pocos segundos de empezar una llamada.
  • Deja libre de controles importantes la esquina inferior derecha.
  • Durante una tarea larga en una llamada, el empleado da breves actualizaciones como «Editando ahora.» y nunca lee en voz alta nombres de archivo ni comandos.

Crea una app

Un empleado puede crear una app de dos formas, y elige según lo que diga el propietario. «Créame una app para mis pedidos» crea un nuevo empleado que es una app. «Tú eres la app» o «créate un juego» convierte en la app al empleado con el que está hablando el propietario: conserva su chat, su memoria y su personalidad, y su página se recarga mientras el propietario habla con él. Esto también funciona con un empleado contratado en la conversación. Cuando no está claro a qué se refiere el propietario, el empleado pregunta una vez.

update_employee(
  name: "<the employee's own name>",
  app: { window: { title: "Solitaire", fullscreen: true, orientation: "landscape" } },
  ui: { "index.html": "<!doctype html>..." }
)

Las herramientas del día a día (un registro de seguimiento, un formulario, un pequeño panel) se crean con la skill de apps integrada en Nebo. Una página que deba parecer diseñada y no generada, como una página de inicio cinematográfica, una película que avanza con el desplazamiento, arte generativo o un juego, se crea con la skill App Studio de la tienda.

Para una app nueva, lo más sencillo es pedírsela a un empleado. Nebo incluye una skill integrada para crear apps, y el empleado usa create_employee, que escribe la carpeta, el manifiesto, la personalidad y la página en una sola llamada. La app aparece en la plantilla del propietario en cuestión de segundos.

create_employee(
  name: "deal-board",
  description: "A board of open deals, sorted by close date.",
  app: {
    window: { title: "Deal Board", width: 900, height: 700, resizable: true },
    permissions: ["storage:readwrite"]
  },
  ui: { "index.html": "<!doctype html>..." }
)

update_employee recibe los mismos argumentos ui, app y agent_md. Una ruta en ui sustituye solo ese archivo. La página se lee del disco en cada solicitud, así que al recargar la ventana se ve el cambio.

Una página mínima

Esta página carga el SDK, pregunta quién es su empleado y muestra la respuesta. Si aparecen el id y el nombre del empleado, la conexión es correcta.

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title>Deal Board</title>
</head>
<body>
  <h1>Deal Board</h1>
  <pre id="who">loading...</pre>
  <script src="/sdk/nebo.global.js"></script>
  <script>
    NeboAppSDK.nebo.identity.get()
      .then(me => { document.getElementById('who').textContent = JSON.stringify(me, null, 2); })
      .catch(err => { document.getElementById('who').textContent = String(err); });
  </script>
</body>
</html>

El SDK obtiene el id de la app a partir de la dirección de la página. Una página servida desde cualquier otro sitio necesita <meta name="nebo-app-id" content="<id>">. Guarda el estado en el almacenamiento de la app, no en la página: la ventana se cierra y el almacenamiento perdura.

Cómo se sirve la página

  • Nebo sirve ui/ en /apps/<id>/ui/ y la abre en su propia ventana.
  • Una ruta sin archivo coincidente recurre a index.html, así que el enrutamiento del lado del cliente funciona.
  • Las páginas HTML reciben las metaetiquetas nebo-app-id y nebo-base-url.
  • Cada archivo se envía con su tipo de contenido real, incluidos vídeo, sonido, fuentes, wasm y modelos 3D (glb, gltf). Un archivo con una extensión desconocida se envía como application/octet-stream y el navegador no lo usará.
  • Los archivos responden a solicitudes de rango (206, o 416 para un rango que pasa del final), así que el vídeo y el sonido se pueden adelantar y retroceder. En la app móvil, el vídeo se reproduce en su sitio sin necesidad de tocarlo: <video muted playsinline autoplay loop poster="assets/hero.jpg" src="assets/hero.mp4"></video>
  • Un archivo cuyo nombre lleva un hash del contenido, como main-0a8ksftt.js, se guarda en caché durante un año. Todo lo demás, incluido index.html, se comprueba cada vez que se abre y responde 304 si no ha cambiado. Compila con nombres con hash en lugar de cambiar el nombre de los archivos a mano.
  • Cada archivo de la página puede ocupar como máximo 10 MB.
  • Eliminar la carpeta desactiva el empleado; delete_employee lo quita por completo.

Añade un sidecar

Cuando la página necesite lógica de servidor, sus propios datos o herramientas a las que pueda llamar el empleado, añade un sidecar: un binario que Nebo ejecuta junto a la app. La página llega a él con neboFetch y una ruta relativa. Consulta Sidecar de la app.

Publica desde Nebo

Una app que ha creado el propietario puede publicarse a sí misma. El propietario dice «publícate», o toca Publicar en el chat de la app o en la pantalla de la app en la app móvil (en la barra superior, o como píldora junto a Cerrar en una app a pantalla completa), o elige Publicar esta app… en el menú de escritorio (el menú Archivo en macOS mientras haya una ventana de app delante; el menú App de la ventana de la app en Windows y Linux). El empleado redacta la ficha a partir de la app, hace de 3 a 5 capturas de pantalla y muestra la ficha en el chat para ajustarla hablando. No se envía nada hasta que el propietario responde Enviar a revisión en la tarjeta, con un toque o con la voz.

Una app que ha creado el propietario siempre tiene sus herramientas de desarrollo para sí misma: recargar, estado, consola, capturas de pantalla y publicación. El modo Desarrollador de apps (Configuración del bot, Desarrollador) permite que otros empleados trabajen en cualquiera de las apps del propietario, añade una consola flotante a la página y desactiva la caché. Las apps instaladas desde la tienda nunca tienen herramientas de desarrollo ni botón de publicar.

Publica una app tú mismo

Una app que solo tiene página se publica como un único paquete con la herramienta agent. El frontmatter de AGENT.md debe decir artifact_type: app; si no, la tienda crea un empleado normal sin página. Pon entre comillas cualquier valor que contenga dos puntos seguidos de un espacio; sin comillas, el frontmatter no se puede leer y la app se convierte sin avisar en un empleado normal.

---
name: deal-board
description: "A board of open deals: sorted by close date, with a chat that knows each deal."
artifact_type: app
metadata:
  version: "1.0.0"
---
# Deal Board

You work beside the Deal Board app. ...
agent(action: "create", name: "deal-board", version: "1.0.0",
      description: "A board of open deals, sorted by close date.",
      manifestContent: "<contents of AGENT.md>")
agent(action: "bundle-token", id: "<app id>")

zip -r deal-board.zip deal-board -x '*/.git/*' '*/node_modules/*' '*/src/*'
curl -X POST "https://neboai.com/api/v1/skills/<app id>/bundle" \
  -H "Authorization: Bearer <token>" \
  -F file=@deal-board.zip

agent(action: "submit", id: "<app id>", version: "1.0.0")
En el zipQué ocurre
AGENT.mdLa personalidad y el manifiesto de la ficha.
agent.jsonLa configuración del empleado. {} es suficiente.
manifest.jsonSe conserva como manifiesto de la app: la ventana y los permisos llegan a la app instalada. Debe ser JSON válido.
ui/La página. Se permiten: html, css, js, mjs, ts, jsx, tsx, json, map, txt, md, imágenes (png, jpg, gif, svg, webp, avif, ico, bmp), fuentes (woff, woff2, ttf, otf), sonido (mp3, wav, ogg, m4a, aac, flac, opus), vídeo (mp4, webm, mov, m4v), wasm, glb, gltf, pdf. Los archivos ocultos y node_modules/ se descartan.
skills/<name>/Las skills propias del empleado, que se comprueban como una skill subida por separado: SKILL.md se conserva, scripts/ y bin/ de cualquier tipo, y todo lo demás según la lista de permitidos de las skills.
  • Límites: 10 MB por archivo y 50 MB por paquete. Un archivo de más de 10 MB se omite (revisa filesSkipped y uiFilesStored en el resultado); un paquete de más de 50 MB se rechaza.
  • El token de subida dura 5 minutos. Si el zip tiene una única carpeta raíz, se elimina.
  • En una app privada o solo para canales, cada subida vuelve a generar al instante el paquete instalable y Nebo avisa a los bots que tienen instalada la app. Un bot que está en línea coloca el paquete regenerado de inmediato; uno que está desconectado lo hace la próxima vez que se conecte. No hace falta subir la versión para esto, y se conservan los ajustes, las programaciones y los datos del propietario para la app. Las apps públicas, no listadas y solo por invitación conservan su paquete aprobado hasta que una nueva versión supera la revisión.
  • Una nueva versión sigue la configuración de actualizaciones automáticas que cada propietario tenga para la app. Está desactivada salvo que el propietario la active, así que por defecto el bot muestra «Actualización disponible» y el propietario la aplica desde Configuración, luego Actualizaciones, o desde la bandeja de entrada. Una actualización nunca concede permisos nuevos; un permiso que añade la nueva versión se pide cuando la app lo necesita por primera vez.
  • Si NeboAI retira una app de la tienda, todos los bots que la tienen instalada la desactivan y avisan al propietario. No se elimina nada: se conserva todo lo que la app ha guardado.
  • Una app con sidecar sube en su lugar el binario de cada plataforma con binary-token, y la página como archivo ui. Consulta Sidecar de la app y Publicación.