NeboAI
NeboAI
Zacznij

Aplikacje

Aplikacja to pracownik ze stroną. Właściciele otwierają ją we własnym oknie, żeby bezpośrednio coś zobaczyć i nad tym pracować: tablicę, tracker, formularz. Strona to zwykły HTML i JavaScript i komunikuje się z Nebo oraz ze swoim pracownikiem przez jeden skrypt — App SDK.

Pakiet

Aplikacja to pakiet pracownika z plikiem manifest.json, który oznacza go jako aplikację, oraz folderem ui/ ze stroną.

<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"]
}
PoleZnaczenie
type"app". Sprawia, że pracownik staje się aplikacją. Nebo odczytuje też starsze artifact_type.
idUUID generowany przy tworzeniu aplikacji. Strona jest serwowana pod /apps/<id>/ui/.
name, versionNazwa pracownika i wersja pakietu.
windowtitle, width, height, resizable, fullscreen, orientation. Domyślnie: 1024 × 768, ze zmianą rozmiaru, nie na pełnym ekranie, pionowo, z tytułem od nazwy pracownika.
permissionsCo może robić strona. Domyślnie ["storage:readwrite"].

Uprawnienia

UprawnienieDaje dostęp do
storage:readwriteMagazynu klucz–wartość aplikacji.
subagent:<employee-id>Zadawania pytań innemu pracownikowi ze strony. Własny pracownik aplikacji nie wymaga uprawnienia.
network:<host> lub network:*Żądań do zewnętrznych hostów przez proxy Nebo.
device:motionŻyroskopu i akcelerometru tylko dla tej strony. Na iPhonie strona dodatkowo wywołuje DeviceMotionEvent.requestPermission() po stuknięciu.

Każde uprawnienie ma postać prefix:scope. Proś o minimum, którego aplikacja potrzebuje.

Pełny ekran, orientacja i przechylanie

Gry i filmy mogą zająć cały ekran. Ustaw fullscreen, a dla aplikacji mobilnej także orientation: portrait (domyślnie), landscape lub any. Każda inna orientacja jest odrzucana przy zapisie manifestu.

{
  "type": "app",
  "permissions": ["storage:readwrite", "device:motion"],
  "window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
}
  • Na komputerze aplikacja otwiera się w oknie pełnoekranowym.
  • W aplikacji mobilnej nie ma paska aplikacji, paski systemowe są ukryte, ekran się nie wygasza, a odświeżanie przez przeciągnięcie jest wyłączone. Mały przycisk Zamknij znajduje się w lewym górnym rogu i znika po kilku sekundach; dotknięcie w pobliżu góry ekranu przywraca go. Gest przesunięcia od krawędzi w iOS jest wyłączony, a przycisk Wstecz w Androidzie przechodzi przez historię strony, zanim ją zamknie.
  • Dodaj do strony odstępy za pomocą env(safe-area-inset-*) i viewport-fit=cover i nie umieszczaj elementów sterujących w lewym górnym rogu.

Sterowanie głosowe

Każda aplikacja otwarta w aplikacji Nebo na komputer lub w aplikacji mobilnej pokazuje w prawym dolnym rogu małe sterowanie głosowe, dzięki któremu właściciel może rozmawiać z pracownikiem aplikacji, gdy ten pracuje nad stroną. Sterowanie znajduje się poza Twoją stroną, więc przeładowanie strony nigdy nie przerywa rozmowy.

  • Na komputerze to pasek o wymiarach około 300 na 48 pikseli, odsunięty o 16 pikseli od prawego dolnego rogu okna.
  • W aplikacji mobilnej to okrągły przycisk o rozmiarze 48 punktów w obszarze bezpiecznym, który właściciel może przeciągnąć na dowolną stronę. W aplikacji pełnoekranowej po kilku sekundach rozmowy zwija się z powrotem do tego przycisku.
  • Nie umieszczaj ważnych elementów sterujących w prawym dolnym rogu.
  • Podczas długiego zadania w trakcie rozmowy pracownik mówi krótkie komunikaty, np. „Teraz edytuję.”, i nigdy nie odczytuje nazw plików ani poleceń.

Utwórz aplikację

Pracownik może zbudować aplikację na dwa sposoby i wybiera na podstawie tego, co mówi właściciel. „Zbuduj mi aplikację do zamówień” tworzy nowego pracownika-aplikację. „Ty jesteś aplikacją” albo „zbuduj sobie grę” zamienia w aplikację pracownika, z którym właściciel rozmawia: zachowuje on swój czat, pamięć i personę, a jego strona przeładowuje się w trakcie rozmowy z właścicielem. Działa to także dla pracownika zatrudnionego w rozmowie. Gdy nie jest jasne, o co chodzi właścicielowi, pracownik pyta raz.

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

Narzędzia na co dzień (tracker, formularz, mały pulpit) powstają z wbudowanej umiejętności aplikacji Nebo. Stronę, która ma wyglądać na zaprojektowaną, a nie wygenerowaną — np. kinową stronę docelową, film sterowany przewijaniem, generatywną sztukę albo grę — buduje się umiejętnością App Studio ze sklepu.

W przypadku nowej aplikacji najprościej poprosić pracownika. Nebo ma wbudowaną umiejętność budowania aplikacji, a pracownik używa create_employee, które w jednym wywołaniu zapisuje folder, manifest, personę i stronę. Aplikacja pojawia się w personelu właściciela w ciągu kilku sekund.

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 przyjmuje te same argumenty ui, app i agent_md. Ścieżka w ui zastępuje ten jeden plik. Strona jest odczytywana z dysku przy każdym żądaniu, więc przeładowanie okna pokazuje zmianę.

Minimalna strona

Ta strona ładuje SDK, pyta, kim jest jej pracownik, i wypisuje odpowiedź. Jeśli pokazuje ID i nazwę pracownika, wszystko jest prawidłowo połączone.

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

SDK odczytuje ID aplikacji z adresu strony. Strona serwowana z innego miejsca potrzebuje <meta name="nebo-app-id" content="<id>">. Stan trzymaj w storage aplikacji, a nie na stronie: okno się zamyka, a storage zostaje.

Jak serwowana jest strona

  • Nebo serwuje ui/ pod /apps/<id>/ui/ i otwiera ją we własnym oknie.
  • Ścieżka bez pasującego pliku kieruje awaryjnie do index.html, więc routing po stronie klienta działa.
  • Strony HTML dostają metatagi nebo-app-id i nebo-base-url.
  • Każdy plik jest wysyłany z prawdziwym typem zawartości, także wideo, dźwięk, czcionki, wasm i modele 3D (glb, gltf). Plik z nieznanym rozszerzeniem jest wysyłany jako application/octet-stream i przeglądarka go nie użyje.
  • Pliki obsługują żądania zakresu (206 lub 416 dla zakresu poza końcem pliku), więc wideo i dźwięk można przewijać. W aplikacji mobilnej wideo odtwarza się w miejscu bez stuknięcia: <video muted playsinline autoplay loop poster="assets/hero.jpg" src="assets/hero.mp4"></video>
  • Plik, którego nazwa zawiera skrót zawartości, np. main-0a8ksftt.js, jest przechowywany w pamięci podręcznej przez rok. Wszystko inne, łącznie z index.html, jest sprawdzane przy każdym otwarciu i zwraca 304, jeśli się nie zmieniło. Buduj z nazwami zawierającymi skróty, zamiast ręcznie zmieniać nazwy plików.
  • Każdy plik strony może mieć najwyżej 10 MB.
  • Usunięcie folderu wyłącza pracownika; delete_employee usuwa go całkowicie.

Dodaj sidecar

Gdy strona potrzebuje logiki serwerowej, własnych danych albo narzędzi, które pracownik może wywołać, dodaj sidecar: plik binarny, który Nebo uruchamia obok aplikacji. Strona łączy się z nim przez neboFetch ze ścieżką względną. Zobacz Sidecar aplikacji.

Publikowanie z Nebo

Aplikacja stworzona przez właściciela może opublikować się sama. Właściciel mówi „opublikuj się” albo stuka Opublikuj na czacie aplikacji, na ekranie aplikacji w aplikacji mobilnej (na górnym pasku lub, w aplikacji pełnoekranowej, jako przycisk obok Zamknij), albo wybiera Opublikuj tę aplikację… z menu na komputerze (z menu Plik w macOS, gdy okno aplikacji jest na wierzchu; z menu Aplikacja w oknie aplikacji w Windows i Linuksie). Pracownik przygotowuje wpis na podstawie aplikacji, robi od 3 do 5 zrzutów ekranu i pokazuje wpis na czacie, żeby można go było dopracować w rozmowie. Nic nie zostaje wysłane, dopóki właściciel nie odpowie Wyślij do weryfikacji na karcie, stuknięciem lub głosem.

Aplikacja stworzona przez właściciela zawsze ma dla siebie narzędzia deweloperskie: przeładowanie, status, konsolę, zrzuty ekranu i publikowanie. Tryb dewelopera aplikacji (Ustawienia bota, Deweloper) pozwala innym pracownikom pracować nad dowolną aplikacją właściciela, dodaje do strony pływającą konsolę i wyłącza pamięć podręczną. Aplikacje zainstalowane ze sklepu nigdy nie dostają narzędzi deweloperskich ani przycisku Opublikuj.

Opublikuj aplikację samodzielnie

Aplikacja składająca się tylko ze strony jest publikowana jako jedna paczka za pomocą narzędzia agent. Nagłówek AGENT.md musi zawierać artifact_type: app, w przeciwnym razie sklep utworzy zwykłego pracownika bez strony. Każdą wartość zawierającą dwukropek ze spacją ujmij w cudzysłów; bez cudzysłowu nagłówka nie da się odczytać i aplikacja po cichu staje się zwykłym pracownikiem.

---
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")
W pliku zipCo się dzieje
AGENT.mdPersona i manifest wpisu.
agent.jsonKonfiguracja pracownika. {} wystarczy.
manifest.jsonZachowywany jako manifest aplikacji: okno i uprawnienia trafiają do zainstalowanej aplikacji. Musi być poprawnym JSON-em.
ui/Strona. Dozwolone: html, css, js, mjs, ts, jsx, tsx, json, map, txt, md, obrazy (png, jpg, gif, svg, webp, avif, ico, bmp), czcionki (woff, woff2, ttf, otf), dźwięk (mp3, wav, ogg, m4a, aac, flac, opus), wideo (mp4, webm, mov, m4v), wasm, glb, gltf, pdf. Pliki zaczynające się od kropki i node_modules/ są pomijane.
skills/<name>/Własne umiejętności pracownika, sprawdzane tak jak umiejętność przesłana osobno: SKILL.md jest zachowywany, scripts/ i bin/ dowolnego typu, wszystko inne według listy dozwolonych dla umiejętności.
  • Limity: 10 MB na plik i 50 MB na paczkę. Plik powyżej 10 MB jest pomijany (sprawdź filesSkipped i uiFilesStored w wyniku); paczka powyżej 50 MB jest odrzucana.
  • Token przesyłania jest ważny 5 minut. Pojedynczy folder najwyższego poziomu w pliku zip jest usuwany.
  • W przypadku aplikacji prywatnej lub dostępnej tylko w kanałach każde przesłanie od razu przebudowuje pakiet instalacyjny, a Nebo powiadamia boty, które zainstalowały aplikację. Bot, który jest online, od razu podmienia pakiet na przebudowany; bot offline robi to przy następnym połączeniu. Nie musisz w tym celu podnosić wersji, a ustawienia, harmonogramy i dane właściciela dla aplikacji zostają zachowane. Aplikacje publiczne, niepubliczne i dostępne tylko na zaproszenie zachowują zatwierdzony pakiet, dopóki nowa wersja nie przejdzie weryfikacji.
  • Nowa wersja stosuje się do ustawienia automatycznych aktualizacji, które każdy właściciel ma dla danej aplikacji. Jest ono wyłączone, dopóki właściciel go nie włączy, więc domyślnie bot pokazuje „Dostępna aktualizacja”, a właściciel instaluje ją w Ustawienia → Aktualizacje albo ze Skrzynki odbiorczej. Aktualizacja nigdy nie przyznaje nowych uprawnień; o uprawnienie dodane w nowej wersji aplikacja pyta, gdy pierwszy raz go potrzebuje.
  • Jeśli NeboAI wycofa aplikację ze sklepu, każdy bot, który ją zainstalował, wyłącza ją i informuje właściciela. Nic nie jest usuwane: wszystko, co aplikacja zapisała, zostaje zachowane.
  • Aplikacja z sidecarem przesyła zamiast tego plik binarny dla każdej platformy przez binary-token, a stronę jako archiwum ui. Zobacz Sidecar aplikacji i Publikowanie.