Пакет
Застосунок — це пакет співробітника з manifest.json, що позначає його як застосунок, і папкою ui/ зі сторінкою.
<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"]
} | Поле | Значення |
|---|---|
type | "app". Робить співробітника застосунком. Nebo також читає старіше artifact_type. |
id | UUID, що створюється разом із застосунком. Сторінка віддається за адресою /apps/<id>/ui/. |
name, version | Ім’я співробітника й версія пакета. |
window | title, width, height, resizable, fullscreen, orientation. За замовчуванням: 1024 × 768, зі зміною розміру, не на весь екран, книжкова орієнтація, заголовок за ім’ям співробітника. |
permissions | Що може робити сторінка. За замовчуванням ["storage:readwrite"]. |
Дозволи
| Дозвіл | Надає |
|---|---|
storage:readwrite | Сховище «ключ — значення» застосунку. |
subagent:<employee-id> | Запити до іншого співробітника зі сторінки. Власному співробітникові застосунку дозвіл не потрібен. |
network:<host> або network:* | Запити до зовнішніх хостів через проксі Nebo. |
device:motion | Гіроскоп і акселерометр лише для цієї сторінки. На iPhone сторінка також викликає DeviceMotionEvent.requestPermission() після дотику. |
Кожен дозвіл має вигляд prefix:scope. Запитуйте мінімум, потрібний застосунку.
Повний екран, орієнтація й нахил
Ігри й фільми можуть займати весь екран. Встановіть fullscreen і, для мобільного застосунку, orientation: portrait (за замовчуванням), landscape або any. Будь-яка інша орієнтація відхиляється під час запису маніфесту.
{
"type": "app",
"permissions": ["storage:readwrite", "device:motion"],
"window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
} - На комп’ютері застосунок відкривається в повноекранному вікні.
- У мобільному застосунку немає панелі застосунку, системні панелі приховано, екран не гасне, а оновлення потягуванням вимкнено. Невелика кнопка «Закрити» розташована в лівому верхньому куті й зникає через кілька секунд; дотик біля верхнього краю повертає її. Жест від краю в iOS вимкнено, а кнопка «Назад» в Android проходить історією сторінки, перш ніж закрити її.
- Додайте відступи сторінці через
env(safe-area-inset-*)іviewport-fit=coverі не розміщуйте елементи керування в лівому верхньому куті.
Голосове керування
Кожен застосунок, відкритий у десктопному чи мобільному застосунку Nebo, показує в правому нижньому куті невеликий елемент голосового керування, щоб власник міг говорити зі співробітником застосунку, поки той працює над сторінкою. Елемент розташований поза вашою сторінкою, тож перезавантаження сторінки ніколи не обриває дзвінок.
- На комп’ютері це панель приблизно 300 на 48 пікселів, на відстані 16 пікселів від правого нижнього кута вікна.
- У мобільному застосунку це кругла кнопка розміром 48 точок у безпечній зоні, яку власник може перетягнути в будь-який бік. У повноекранному застосунку вона згортається до цієї кнопки через кілька секунд після початку дзвінка.
- Не розміщуйте важливі елементи керування в правому нижньому куті.
- Під час довгого завдання на дзвінку співробітник повідомляє короткі оновлення, як-от «Зараз редагую.», і ніколи не зачитує назви файлів чи команди.
Створення застосунку
Співробітник може створити застосунок двома способами й обирає залежно від того, що каже власник. «Створи мені застосунок для замовлень» створює нового співробітника-застосунок. «Ти і є застосунок» або «створи собі гру» перетворює на застосунок співробітника, з яким говорить власник: він зберігає свій чат, пам’ять і персону, а його сторінка перезавантажується, поки власник із ним говорить. Це працює й для співробітника, найнятого в розмові. Коли незрозуміло, що має на увазі власник, співробітник один раз перепитує.
update_employee(
name: "<the employee's own name>",
app: { window: { title: "Solitaire", fullscreen: true, orientation: "landscape" } },
ui: { "index.html": "<!doctype html>..." }
) Повсякденні інструменти (трекер, форма, невелика панель) створюються за допомогою вбудованої навички Nebo для застосунків. Сторінку, яка має виглядати як продуманий дизайн, а не як згенерована, — наприклад кінематографічну лендинг-сторінку, фільм із прокручуванням, згенероване мистецтво чи гру, — створюють за допомогою навички App Studio з маркетплейсу.
Для нового застосунку найпростіше попросити співробітника. Nebo містить вбудовану навичку для створення застосунків, і співробітник використовує create_employee, який записує папку, маніфест, персону й сторінку за один виклик. Застосунок з’являється в персоналі власника за кілька секунд.
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 приймає ті самі аргументи ui, app і agent_md. Шлях в ui замінює цей один файл. Сторінка читається з диска під час кожного запиту, тож перезавантаження вікна показує зміну.
Мінімальна сторінка
Ця сторінка завантажує SDK, запитує, хто її співробітник, і виводить відповідь. Якщо вона показує id та ім’я співробітника, усе з’єднано правильно.
<!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 визначає id застосунку з адреси сторінки. Сторінці, що віддається з будь-якого іншого місця, потрібен <meta name="nebo-app-id" content="<id>">. Зберігайте стан у сховищі застосунку, а не на сторінці: вікно закривається, а сховище залишається.
Як віддається сторінка
- Nebo віддає
ui/за адресою/apps/<id>/ui/і відкриває її у власному вікні. - Шлях без відповідного файлу перенаправляється на
index.html, тож маршрутизація на стороні клієнта працює. - HTML-сторінки отримують метатеги
nebo-app-idіnebo-base-url. - Кожен файл надсилається з його справжнім типом вмісту, зокрема відео, звук, шрифти,
wasmі 3D-моделі (glb,gltf). Файл з невідомим розширенням надсилається якapplication/octet-stream, і браузер його не використає. - Файли відповідають на запити діапазонів (
206або416для діапазону за межами кінця), тож відео та звук можна перемотувати. У мобільному застосунку відео відтворюється на місці без натискання:<video muted playsinline autoplay loop poster="assets/hero.jpg" src="assets/hero.mp4"></video> - Файл, назва якого містить хеш вмісту, як-от
main-0a8ksftt.js, кешується на рік. Усе інше, зокремаindex.html, перевіряється під час кожного відкриття й відповідає304, якщо не змінилося. Використовуйте збирання з хешованими назвами, а не перейменовуйте файли вручну. - Кожен файл сторінки може мати щонайбільше 10 MB.
- Видалення папки деактивує співробітника;
delete_employeeвилучає його повністю.
Додавання супровідного процесу
Коли сторінці потрібна серверна логіка, власні дані або інструменти, які може викликати співробітник, додайте супровідний процес: виконуваний файл, який Nebo запускає поряд із застосунком. Сторінка звертається до нього через neboFetch з відносним шляхом. Див. Супровідний процес застосунку.
Публікація з Nebo
Застосунок, створений власником, може опублікувати себе сам. Власник каже «опублікуй себе» або натискає Publish у чаті застосунку, на екрані застосунку в мобільному застосунку (на верхній панелі або як кнопку поряд із «Закрити» для повноекранного застосунку), або обирає Publish This App… у меню на комп’ютері (меню File на macOS, коли вікно застосунку на передньому плані; меню App вікна застосунку на Windows і Linux). Співробітник складає опис із застосунку, робить від 3 до 5 знімків екрана й показує опис у чаті, щоб його можна було доопрацювати в розмові. Нічого не надсилається, доки власник не відповість Submit for review у картці — дотиком або голосом.
Застосунок, створений власником, завжди має для себе інструменти розробника: перезавантаження, стан, консоль, знімки екрана й публікацію. Режим розробника застосунків (налаштування бота, «Розробник») дає іншим співробітникам змогу працювати з будь-якими застосунками власника, додає на сторінку плаваючу консоль і вимикає кешування. Застосунки, встановлені з маркетплейсу, ніколи не отримують інструментів розробника чи кнопки Publish.
Самостійна публікація застосунку
Застосунок лише зі сторінкою публікується одним пакетом через інструмент agent. Фронтматер AGENT.md має містити artifact_type: app, інакше маркетплейс створить звичайного співробітника без сторінки. Беріть у лапки кожне значення, що містить двокрапку з пробілом після неї; без лапок фронтматер не прочитається, і застосунок мовчки стане звичайним співробітником.
--- 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") | У zip | Що відбувається |
|---|---|
AGENT.md | Персона й маніфест опису. |
agent.json | Конфігурація співробітника. {} підходить. |
manifest.json | Зберігається як маніфест застосунку: вікно й дозволи переходять у встановлений застосунок. Має бути коректним JSON. |
ui/ | Сторінка. Дозволено: html, css, js, mjs, ts, jsx, tsx, json, map, txt, md, зображення (png, jpg, gif, svg, webp, avif, ico, bmp), шрифти (woff, woff2, ttf, otf), звук (mp3, wav, ogg, m4a, aac, flac, opus), відео (mp4, webm, mov, m4v), wasm, glb, gltf, pdf. Файли, що починаються з крапки, і node_modules/ відкидаються. |
skills/<name>/ | Власні навички співробітника, що перевіряються так само, як навичка, завантажена окремо: SKILL.md зберігається, scripts/ і bin/ — будь-якого типу, усе інше — за списком дозволених для навичок. |
- Ліміти: 10 MB на файл і 50 MB на пакет. Файл понад 10 MB пропускається (перевірте
filesSkippedіuiFilesStoredу результаті); пакет понад 50 MB відхиляється. - Токен завантаження діє 5 хвилин. Єдина папка верхнього рівня в zip відкидається.
- Для приватного застосунку чи застосунку лише для каналів кожне завантаження одразу перезбирає пакет для встановлення, і Nebo повідомляє ботів, які встановили застосунок. Бот у мережі одразу встановлює перезібраний пакет; бот поза мережею робить це під час наступного підключення. Для цього не потрібно підвищувати версію, а налаштування, розклади й дані власника для застосунку зберігаються. Публічні, доступні за посиланням і доступні за запрошенням застосунки зберігають свій схвалений пакет, доки нова версія не пройде перевірку.
- Нова версія встановлюється відповідно до налаштування автоматичних оновлень, яке кожен власник має для застосунку. Воно вимкнене, доки власник його не ввімкне, тож за замовчуванням бот показує «Доступне оновлення», а власник застосовує його в Налаштуваннях → «Оновлення» або з Вхідних. Оновлення ніколи не надає нових дозволів; дозвіл, доданий новою версією, запитується, коли він уперше знадобиться застосунку.
- Якщо NeboAI знімає застосунок з маркетплейсу, кожен бот, що його встановив, вимикає його й повідомляє власника. Нічого не видаляється: усе, що зберіг застосунок, залишається.
- Застосунок із супровідним процесом натомість завантажує виконуваний файл для кожної платформи через
binary-token, а сторінку — як архівui. Див. Супровідний процес застосунку і Публікація.