パッケージ
アプリとは、アプリであることを示す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ポイントの丸いボタンで、オーナーが左右どちらにもドラッグできます。全画面のアプリでは、通話が始まって数秒でそのボタンに折りたたまれます。
- 重要な操作部品は、右下の隅から離して配置してください。
- 通話中の長いタスクでは、社員は「編集中です。」のような短い進捗を伝え、ファイル名やコマンドを読み上げることはありません。
アプリを作成する
社員がアプリを作る方法は2つあり、オーナーの言葉によって選びます。「注文管理のアプリを作って」と言われれば、新しいアプリ社員を作ります。「あなたがアプリになって」や「自分をゲームにして」と言われれば、オーナーが話している社員そのものをアプリにします。チャット、メモリ、ペルソナはそのままで、オーナーと話している間にページが再読み込みされます。会話の中で雇った社員でも同じように動きます。オーナーがどちらを意図しているかはっきりしないときは、社員が一度だけ確認します。
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を使って、フォルダ、マニフェスト、ペルソナ、ページを1回の呼び出しで書き込みます。アプリは数秒でオーナーのワークフォースに表示されます。
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内のパスは、その1つのファイルを置き換えます。ページはリクエストのたびにディスクから読み込まれるので、ウィンドウを再読み込みすれば変更が表示されます。
最小構成のページ
このページは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のmetaタグが付きます。 - すべてのファイルは、動画、音声、フォント、
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のように、名前にコンテンツのハッシュを含むファイルは1年間キャッシュされます。それ以外のファイルはindex.htmlも含め、開くたびに確認され、変更がなければ304を返します。ファイル名を手で変えるのではなく、ハッシュ付きの名前でビルドしてください。- ページのファイルは、1つにつき最大10 MBです。
- フォルダを削除すると社員は無効になります。
delete_employeeを使うと完全に削除されます。
サイドカーを追加する
ページにサーバーのロジック、独自のデータ、社員が呼び出せるツールが必要な場合は、サイドカーを追加します。Neboがアプリの横で動かすバイナリです。ページはneboFetchと相対パスでサイドカーにアクセスします。アプリのサイドカーをご覧ください。
Neboから公開する
オーナーが作ったアプリは、自分自身を公開できます。オーナーが「自分を公開して」と言うか、アプリのチャット、モバイルアプリのアプリ画面(上部のバー、全画面のアプリでは「閉じる」の横のボタン)で公開をタップするか、デスクトップのメニューからこのアプリを公開…を選びます(macOSではアプリのウィンドウが前面にあるときのファイルメニュー、WindowsとLinuxではアプリのウィンドウのアプリメニュー)。社員はアプリから掲載情報を下書きし、スクリーンショットを3〜5枚撮り、チャットに掲載情報を表示します。会話をしながら内容を整えられます。オーナーがカードの審査に申請にタップか音声で答えるまで、何も送信されません。
オーナーが作ったアプリは、自分用の開発者ツールを常に使えます。再読み込み、ステータス、コンソール、スクリーンショット、公開です。アプリ開発者モード(ボットの設定 → 開発者)をオンにすると、他の社員もオーナーのどのアプリでも作業できるようになり、ページにフローティングのコンソールが追加され、キャッシュが無効になります。マーケットプレイスからインストールしたアプリに、開発者ツールや公開ボタンが付くことはありません。
アプリを自分で公開する
ページだけのアプリは、agentツールで1つのバンドルとして公開します。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/はあらゆる種類、それ以外はスキルの許可リストに従います。 |
- 上限: 1ファイルにつき10 MB、1バンドルにつき50 MB。10 MBを超えるファイルはスキップされ(結果の
filesSkippedとuiFilesStoredを確認してください)、50 MBを超えるバンドルは拒否されます。 - アップロードトークンの有効期間は5分です。zip内の最上位フォルダが1つだけの場合、そのフォルダは取り除かれます。
- 非公開またはチャンネル限定のアプリでは、アップロードのたびにインストール用パッケージがすぐに作り直され、Neboはアプリをインストールしたボットに知らせます。オンラインのボットは作り直されたパッケージをすぐに配置し、オフラインのボットは次に接続したときに配置します。そのためにバージョンを上げる必要はなく、アプリに関するオーナーの設定、スケジュール、データは保持されます。公開、限定公開、招待制のアプリは、新しいバージョンが審査を通るまで承認済みのパッケージを使い続けます。
- 新しいバージョンは、そのアプリに対する各オーナーの自動アップデート設定に従います。オーナーがオンにしない限りオフなので、デフォルトではボットに「アップデートがあります」と表示され、オーナーが「設定」→「アップデート」または受信トレイから適用します。アップデートで新しい権限が付与されることはありません。新しいバージョンで追加された権限は、アプリが初めてそれを必要としたときに確認されます。
- NeboAIがマーケットプレイスからアプリを取り下げた場合、そのアプリをインストールしたすべてのボットがアプリを無効にし、オーナーに知らせます。何も削除されず、アプリが保存したものはすべて保持されます。
- サイドカーを持つアプリは、代わりに
binary-tokenで各プラットフォームのバイナリをアップロードし、ページをuiアーカイブとしてアップロードします。アプリのサイドカーと公開をご覧ください。