NeboAI
NeboAI
Começar

Apps

Uma app é um funcionário com uma página. Os proprietários abrem-na na sua própria janela para ver algo e trabalhar diretamente com ele: um quadro, um registo, um formulário. A página é HTML e JavaScript simples, e comunica com o Nebo e com o seu funcionário através de um único script, o App SDK.

O pacote

Uma app é um pacote de funcionário com um manifest.json que a marca como app e uma pasta ui/ com a 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". Faz do funcionário uma app. O Nebo também lê o antigo artifact_type.
idUm UUID gerado quando a app é criada. A página é servida em /apps/<id>/ui/.
name, versionO nome do funcionário e a versão do pacote.
windowtitle, width, height, resizable, fullscreen, orientation. Predefinições: 1024 × 768, redimensionável, sem ecrã inteiro, vertical, com o nome do funcionário como título.
permissionsO que a página pode fazer. Predefinição ["storage:readwrite"].

Permissões

PermissãoConcede
storage:readwriteO armazenamento chave-valor da app.
subagent:<employee-id>Perguntar a outro funcionário a partir da página. O próprio funcionário da app não precisa de permissão.
network:<host> ou network:*Pedidos a anfitriões externos através do proxy do Nebo.
device:motionO giroscópio e o acelerómetro, apenas para esta página. No iPhone, a página também chama DeviceMotionEvent.requestPermission() a partir de um toque.

Todas as permissões têm a forma prefix:scope. Peça o mínimo de que a app precisa.

Ecrã inteiro, orientação e inclinação

Jogos e filmes podem ocupar o ecrã inteiro. Defina fullscreen e, para a app móvel, uma orientation: portrait (a predefinição), landscape ou any. Qualquer outra orientação é recusada quando o manifesto é escrito.

{
  "type": "app",
  "permissions": ["storage:readwrite", "device:motion"],
  "window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
}
  • No computador, a app abre numa janela em ecrã inteiro.
  • Na app móvel não há barra da app, as barras do sistema ficam ocultas, o ecrã mantém-se ligado e o gesto de puxar para atualizar fica desativado. Um pequeno botão Fechar fica no canto superior esquerdo e desvanece ao fim de alguns segundos; tocar perto do topo fá-lo reaparecer. O gesto de deslizar a partir da margem no iOS fica desativado, e o botão Voltar do Android percorre o histórico da página antes de fechar.
  • Ajuste as margens da página com env(safe-area-inset-*) e viewport-fit=cover, e mantenha os controlos afastados do canto superior esquerdo.

O controlo de voz

Todas as apps abertas na app do Nebo para computador ou na app móvel mostram um pequeno controlo de voz no canto inferior direito, para que o proprietário possa falar com o funcionário da app enquanto ele trabalha na página. O controlo fica fora da sua página, por isso recarregar a página nunca interrompe a chamada.

  • No computador é uma barra com cerca de 300 por 48 píxeis, a 16 píxeis do canto inferior direito da janela.
  • Na app móvel é um botão redondo de 48 pontos dentro da área segura, que o proprietário pode arrastar para qualquer um dos lados. Numa app em ecrã inteiro, recolhe-se nesse botão alguns segundos depois de começar uma chamada.
  • Mantenha os controlos importantes afastados do canto inferior direito.
  • Durante uma tarefa longa numa chamada, o funcionário dá atualizações curtas como «A editar agora.» e nunca lê em voz alta nomes de ficheiros ou comandos.

Criar uma app

Um funcionário pode criar uma app de duas formas e escolhe consoante o que o proprietário diz. «Cria-me uma app para as minhas encomendas» cria um novo funcionário-app. «Tu és a app» ou «cria um jogo para ti» transforma na app o funcionário com quem o proprietário está a falar: mantém o chat, a memória e a persona, e a sua página recarrega enquanto o proprietário fala com ele. Isto também funciona com um funcionário contratado numa conversa. Quando não é claro o que o proprietário quer dizer, o funcionário pergunta uma vez.

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

As ferramentas do dia a dia (um registo, um formulário, um pequeno painel) são criadas com a skill de apps integrada no Nebo. Uma página que deva parecer desenhada e não gerada, como uma landing page cinematográfica, um filme comandado pelo scroll, arte gerada ou um jogo, é criada com a skill App Studio da loja.

Para uma nova app, o mais simples é pedir a um funcionário. O Nebo inclui uma skill integrada para criar apps, e o funcionário usa create_employee, que escreve a pasta, o manifesto, a persona e a página numa só chamada. A app aparece no pessoal do proprietário em 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 recebe os mesmos argumentos ui, app e agent_md. Um caminho em ui substitui esse ficheiro. A página é lida do disco a cada pedido, por isso recarregar a janela mostra a alteração.

Uma página mínima

Esta página carrega o SDK, pergunta quem é o seu funcionário e mostra a resposta. Se aparecerem o id e o nome do funcionário, as ligações estão certas.

<!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>

O SDK obtém o id da app a partir do endereço da página. Uma página servida a partir de outro sítio precisa de <meta name="nebo-app-id" content="<id>">. Guarde o estado no armazenamento da app, não na página: a janela fecha-se, e o armazenamento sobrevive.

Como a página é servida

  • O Nebo serve ui/ em /apps/<id>/ui/ e abre-a na sua própria janela.
  • Um caminho sem ficheiro correspondente recorre a index.html, por isso o encaminhamento do lado do cliente funciona.
  • As páginas HTML recebem as meta tags nebo-app-id e nebo-base-url.
  • Todos os ficheiros são enviados com o seu tipo de conteúdo real, incluindo vídeo, som, tipos de letra, wasm e modelos 3D (glb, gltf). Um ficheiro com uma extensão desconhecida é enviado como application/octet-stream e o navegador não o usa.
  • Os ficheiros respondem a pedidos de intervalo (206, ou 416 para um intervalo para além do fim), por isso é possível avançar e recuar em vídeo e som. Na app móvel, o vídeo é reproduzido no próprio sítio sem tocar: <video muted playsinline autoplay loop poster="assets/hero.jpg" src="assets/hero.mp4"></video>
  • Um ficheiro cujo nome inclua um hash do conteúdo, como main-0a8ksftt.js, fica em cache durante um ano. Tudo o resto, incluindo index.html, é verificado sempre que abre e responde 304 quando não mudou. Compile com nomes com hash em vez de mudar o nome dos ficheiros à mão.
  • Cada ficheiro da página pode ter no máximo 10 MB.
  • Eliminar a pasta desativa o funcionário; delete_employee remove-o por completo.

Adicionar um sidecar

Quando a página precisa de lógica de servidor, de dados próprios ou de ferramentas que o funcionário possa chamar, adicione um sidecar: um binário que o Nebo corre ao lado da app. A página chega a ele com neboFetch e um caminho relativo. Ver Sidecar de apps.

Publicar a partir do Nebo

Uma app criada pelo proprietário pode publicar-se a si própria. O proprietário diz «publica-te», ou toca em Publicar no chat da app, no ecrã da app na app móvel (na barra superior ou, numa app em ecrã inteiro, num botão ao lado de Fechar), ou escolhe Publicar esta app… no menu do computador (o menu Ficheiro no macOS, com uma janela de app em primeiro plano; o menu App da janela da app no Windows e no Linux). O funcionário redige a listagem a partir da app, tira 3 a 5 capturas de ecrã e mostra a listagem no chat para a ajustar a conversar. Nada é enviado até o proprietário responder Submeter para revisão no cartão, com um toque ou por voz.

Uma app criada pelo proprietário tem sempre as suas ferramentas de programador para si: recarregar, estado, consola, capturas de ecrã e publicação. O modo Programador de apps (definições do bot, Programador) permite que outros funcionários trabalhem em qualquer app do proprietário, acrescenta uma consola flutuante à página e desativa a cache. As apps instaladas a partir da loja nunca recebem ferramentas de programador nem um botão Publicar.

Publicar uma app por si

Uma app só com página é publicada como um único pacote com a ferramenta agent. O frontmatter do AGENT.md tem de dizer artifact_type: app, caso contrário a loja cria um funcionário simples sem página. Ponha entre aspas qualquer valor que contenha dois pontos seguidos de um espaço; sem aspas, o frontmatter não pode ser lido e a app torna-se, sem aviso, um funcionário simples.

---
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")
No zipO que acontece
AGENT.mdA persona e o manifesto da listagem.
agent.jsonA configuração do funcionário. {} serve.
manifest.jsonMantido como manifesto da app: a janela e as permissões chegam à app instalada. Tem de ser JSON válido.
ui/A página. Permitidos: html, css, js, mjs, ts, jsx, tsx, json, map, txt, md, imagens (png, jpg, gif, svg, webp, avif, ico, bmp), tipos de letra (woff, woff2, ttf, otf), som (mp3, wav, ogg, m4a, aac, flac, opus), vídeo (mp4, webm, mov, m4v), wasm, glb, gltf, pdf. Os ficheiros ocultos e node_modules/ são descartados.
skills/<name>/As skills próprias do funcionário, verificadas como uma skill carregada isoladamente: SKILL.md mantido, scripts/ e bin/ de qualquer tipo, tudo o resto segundo a lista de permissões das skills.
  • Limites: 10 MB por ficheiro e 50 MB por pacote. Um ficheiro com mais de 10 MB é ignorado (verifique filesSkipped e uiFilesStored no resultado); um pacote com mais de 50 MB é recusado.
  • O token de carregamento dura 5 minutos. Se o zip tiver uma única pasta de topo, ela é removida.
  • Numa app privada ou só para canais, cada carregamento reconstrói de imediato o pacote instalável e o Nebo avisa os bots que instalaram a app. Um bot que esteja online coloca logo o pacote reconstruído no lugar; um que esteja offline fá-lo quando voltar a ligar-se. Não precisa de subir a versão para isso, e as definições, os agendamentos e os dados do proprietário para a app são mantidos. As apps públicas, não listadas e só por convite mantêm o pacote aprovado até uma nova versão passar na revisão.
  • Uma nova versão segue a definição de atualizações automáticas de cada proprietário para a app. Está desativada a menos que o proprietário a ative, por isso, por predefinição, o bot mostra «Atualização disponível» e o proprietário aplica-a em Definições, depois Atualizações, ou a partir da Caixa de entrada. Uma atualização nunca concede novas permissões; uma permissão acrescentada pela nova versão é pedida quando a app precisar dela pela primeira vez.
  • Se a NeboAI retirar uma app da loja, todos os bots que a instalaram desativam-na e avisam o proprietário. Nada é eliminado: tudo o que a app guardou é mantido.
  • Uma app com sidecar carrega antes o binário de cada plataforma com binary-token, e a página como arquivo ui. Ver Sidecar de apps e Publicação.