Пакет
Приложение — это пакет сотрудника с 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удаляет его полностью.
Добавление sidecar
Когда странице нужна серверная логика, собственные данные или инструменты, которые может вызывать сотрудник, добавьте sidecar — бинарный файл, который Nebo запускает рядом с приложением. Страница обращается к нему через neboFetch с относительным путём. См. Sidecar приложения.
Публикация из Nebo
Приложение, созданное владельцем, может опубликовать себя само. Владелец говорит «опубликуй себя» или нажимает Опубликовать в чате приложения, на экране приложения в мобильном приложении (на верхней панели или, для полноэкранного приложения, на кнопке рядом с «Закрыть»), либо выбирает Опубликовать это приложение… в меню настольного приложения (в меню «Файл» на macOS, когда окно приложения активно; в меню «Приложение» окна приложения в Windows и Linux). Сотрудник готовит описание для размещения на основе приложения, делает 3-5 снимков экрана и показывает описание в чате, чтобы его можно было доработать в разговоре. Ничего не отправляется, пока владелец не ответит Отправить на проверку на карточке — нажатием или голосом.
У приложения, созданного владельцем, всегда есть свои инструменты разработчика: перезагрузка, статус, консоль, снимки экрана и публикация. Режим разработчика приложений (Настройки бота, «Разработчик») позволяет другим сотрудникам работать с любыми приложениями владельца, добавляет на страницу плавающую консоль и отключает кэширование. Приложения, установленные из маркетплейса, никогда не получают инструменты разработчика или кнопку «Опубликовать».
Публикация приложения самостоятельно
Приложение только со страницей публикуется одним пакетом через инструмент 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 снимает приложение с маркетплейса, каждый бот, который его установил, отключает его и сообщает владельцу. Ничего не удаляется: всё, что сохранило приложение, остаётся.
- Приложение с sidecar вместо этого загружает бинарный файл для каждой платформы через
binary-token, а страницу — как архивui. См. Sidecar приложения и Публикация.