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"]
} | Pole | Znaczenie |
|---|---|
type | "app". Sprawia, że pracownik staje się aplikacją. Nebo odczytuje też starsze artifact_type. |
id | UUID generowany przy tworzeniu aplikacji. Strona jest serwowana pod /apps/<id>/ui/. |
name, version | Nazwa pracownika i wersja pakietu. |
window | title, width, height, resizable, fullscreen, orientation. Domyślnie: 1024 × 768, ze zmianą rozmiaru, nie na pełnym ekranie, pionowo, z tytułem od nazwy pracownika. |
permissions | Co może robić strona. Domyślnie ["storage:readwrite"]. |
Uprawnienia
| Uprawnienie | Daje dostęp do |
|---|---|
storage:readwrite | Magazynu 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-*)iviewport-fit=coveri 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-idinebo-base-url. - Każdy plik jest wysyłany z prawdziwym typem zawartości, także wideo, dźwięk, czcionki,
wasmi modele 3D (glb,gltf). Plik z nieznanym rozszerzeniem jest wysyłany jakoapplication/octet-streami przeglądarka go nie użyje. - Pliki obsługują żądania zakresu (
206lub416dla 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 zindex.html, jest sprawdzane przy każdym otwarciu i zwraca304, 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_employeeusuwa 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 zip | Co się dzieje |
|---|---|
AGENT.md | Persona i manifest wpisu. |
agent.json | Konfiguracja pracownika. {} wystarczy. |
manifest.json | Zachowywany 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ź
filesSkippediuiFilesStoredw 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 archiwumui. Zobacz Sidecar aplikacji i Publikowanie.