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"]
} | Campo | Significado |
|---|---|
type | "app". Faz do funcionário uma app. O Nebo também lê o antigo artifact_type. |
id | Um UUID gerado quando a app é criada. A página é servida em /apps/<id>/ui/. |
name, version | O nome do funcionário e a versão do pacote. |
window | title, width, height, resizable, fullscreen, orientation. Predefinições: 1024 × 768, redimensionável, sem ecrã inteiro, vertical, com o nome do funcionário como título. |
permissions | O que a página pode fazer. Predefinição ["storage:readwrite"]. |
Permissões
| Permissão | Concede |
|---|---|
storage:readwrite | O 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:motion | O 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-*)eviewport-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-idenebo-base-url. - Todos os ficheiros são enviados com o seu tipo de conteúdo real, incluindo vídeo, som, tipos de letra,
wasme modelos 3D (glb,gltf). Um ficheiro com uma extensão desconhecida é enviado comoapplication/octet-streame o navegador não o usa. - Os ficheiros respondem a pedidos de intervalo (
206, ou416para 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, incluindoindex.html, é verificado sempre que abre e responde304quando 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_employeeremove-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 zip | O que acontece |
|---|---|
AGENT.md | A persona e o manifesto da listagem. |
agent.json | A configuração do funcionário. {} serve. |
manifest.json | Mantido 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
filesSkippedeuiFilesStoredno 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 arquivoui. Ver Sidecar de apps e Publicação.