بسته
برنامه یک بسته کارمند است با یک 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. هر جهت دیگری هنگام نوشتن manifest رد میشود.
{
"type": "app",
"permissions": ["storage:readwrite", "device:motion"],
"window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
} - روی رایانه، برنامه در یک پنجره تمامصفحه باز میشود.
- در برنامه موبایل نوار برنامه وجود ندارد، نوارهای سیستم پنهاناند، صفحه روشن میماند و کشیدن برای تازهسازی خاموش است. یک دکمه کوچک بستن در گوشه بالا سمت چپ قرار دارد و پس از چند ثانیه محو میشود؛ لمس نزدیک بالای صفحه آن را برمیگرداند. کشیدن از لبه در iOS خاموش است و دکمه برگشت Android پیش از بستن، تاریخچه صفحه را به عقب میبرد.
- با
env(safe-area-inset-*)وviewport-fit=coverبه صفحه حاشیه بدهید و کنترلها را از گوشه بالا سمت چپ دور نگه دارید.
کنترل صوتی
هر برنامهای که در برنامه رایانهای Nebo یا برنامه موبایل باز شود، یک کنترل صوتی کوچک در گوشه پایین سمت راست خود نشان میدهد تا مالک بتواند وقتی کارمند برنامه روی صفحه کار میکند با او حرف بزند. این کنترل بیرون از صفحه شماست، پس بارگذاری دوباره صفحه هرگز تماس را قطع نمیکند.
- روی رایانه، نواری است حدود ۳۰۰ در ۴۸ پیکسل، با ۱۶ پیکسل فاصله از گوشه پایین سمت راست پنجره.
- در برنامه موبایل، دکمهای گرد به اندازه ۴۸ پوینت درون ناحیه امن است که مالک میتواند آن را به هر طرف بکشد. در برنامه تمامصفحه، چند ثانیه پس از شروع تماس دوباره به همان دکمه جمع میشود.
- کنترلهای مهم را از گوشه پایین سمت راست دور نگه دارید.
- در طول یک کار طولانی هنگام تماس، کارمند بهروزرسانیهای کوتاهی مثل «در حال ویرایش.» میگوید و هرگز نام فایلها یا فرمانها را بلند نمیخواند.
ساختن برنامه
کارمند میتواند به دو روش برنامه بسازد و بر اساس حرف مالک انتخاب میکند. «برایم یک برنامه برای سفارشهایم بساز» یک کارمند برنامه تازه میسازد. «تو خودت برنامه باش» یا «برای خودت یک بازی بساز» کارمندی را که مالک با او حرف میزند به برنامه تبدیل میکند: چت، حافظه و شخصیتش را نگه میدارد و صفحهاش در حالی که مالک با او حرف میزند دوباره بارگذاری میشود. این برای کارمندی که در گفتگو استخدام شده هم کار میکند. وقتی روشن نیست منظور مالک کدام است، کارمند یک بار میپرسد.
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 استفاده میکند که پوشه، manifest، شخصیت و صفحه را در یک فراخوانی مینویسد. برنامه ظرف چند ثانیه در نیروی کار مالک ظاهر میشود.
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 را بارگذاری میکند، میپرسد کارمندش کیست و پاسخ را نمایش میدهد. اگر شناسه و نام کارمند را نشان داد، اتصالها درست است.
<!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 شناسه برنامه را از نشانی صفحه پیدا میکند. صفحهای که از جای دیگری ارائه شود به <meta name="nebo-app-id" content="<id>"> نیاز دارد. وضعیت را در storage برنامه نگه دارید، نه در صفحه: پنجره بسته میشود، اما storage باقی میماند.
صفحه چطور ارائه میشود
- Nebo پوشه
ui/را در/apps/<id>/ui/ارائه میدهد و آن را در پنجره مخصوص خودش باز میکند. - مسیری که فایل منطبق ندارد به
index.htmlبرمیگردد، پس مسیریابی سمت کلاینت کار میکند. - صفحههای HTML تگهای meta به نام
nebo-app-idوnebo-base-urlمیگیرند. - هر فایل با نوع محتوای واقعی خودش فرستاده میشود، از جمله ویدیو، صدا، فونتها،
wasmو مدلهای سهبعدی (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پاسخ میدهد. بهجای تغییر نام دستی فایلها، با نامهای هشدار build کنید. - هر فایل صفحه حداکثر میتواند 10 MB باشد.
- حذف پوشه کارمند را غیرفعال میکند؛
delete_employeeآن را کاملاً حذف میکند.
افزودن sidecar
وقتی صفحه به منطق سمت سرور، دادههای مخصوص خودش یا ابزارهایی که کارمند بتواند فرا بخواند نیاز دارد، یک sidecar اضافه کنید: فایل اجراییای که Nebo کنار برنامه اجرا میکند. صفحه با neboFetch و یک مسیر نسبی به آن دسترسی دارد. App Sidecar را ببینید.
انتشار از داخل Nebo
برنامهای که مالک ساخته میتواند خودش را منتشر کند. مالک میگوید «خودت را منتشر کن»، یا روی Publish در چت برنامه یا در صفحه برنامه در برنامه موبایل (در نوار بالا، یا برای برنامه تمامصفحه بهصورت دکمهای کنار بستن) میزند، یا از منوی رایانه گزینه Publish This App… را انتخاب میکند (در macOS از منوی File وقتی پنجره برنامه جلو است؛ در Windows و Linux از منوی App پنجره برنامه). کارمند از روی برنامه پیشنویس صفحه فروشگاه را مینویسد، ۳ تا ۵ اسکرینشات میگیرد و صفحه را در چت نشان میدهد تا با حرف زدن شکلش بدهید. تا وقتی مالک روی کارت با لمس یا صدا به Submit for review پاسخ ندهد، هیچ چیز ارسال نمیشود.
برنامهای که مالک ساخته همیشه ابزارهای توسعه خودش را برای خودش دارد: بارگذاری دوباره، وضعیت، کنسول، اسکرینشات و انتشار. حالت App Developer (تنظیمات بات، Developer) به کارمندان دیگر اجازه میدهد روی هر کدام از برنامههای مالک کار کنند، یک کنسول شناور به صفحه اضافه میکند و حافظه نهان را خاموش میکند. برنامههایی که از فروشگاه نصب شدهاند هرگز ابزارهای توسعه یا دکمه انتشار نمیگیرند.
خودتان یک برنامه منتشر کنید
برنامهای که فقط صفحه دارد با ابزار agent بهصورت یک بسته منتشر میشود. frontmatter فایل AGENT.md باید artifact_type: app داشته باشد، وگرنه فروشگاه یک کارمند ساده بدون صفحه میسازد. هر مقداری را که شامل دونقطه و پس از آن فاصله است داخل گیومه بگذارید؛ بدون گیومه، frontmatter خوانده نمیشود و برنامه بیصدا به یک کارمند ساده تبدیل میشود.
--- 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 | شخصیت و manifest صفحه فروشگاه. |
agent.json | پیکربندی کارمند. {} هم قابل قبول است. |
manifest.json | بهعنوان manifest برنامه نگه داشته میشود: پنجره و مجوزها به برنامه نصبشده میرسند. باید 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 رد میشود. - توکن بارگذاری ۵ دقیقه اعتبار دارد. اگر zip فقط یک پوشه سطح بالا داشته باشد، آن پوشه حذف میشود.
- برای برنامه خصوصی یا فقط کانالی، هر بارگذاری بسته قابل نصب را فوراً از نو میسازد و Nebo به باتهایی که برنامه را نصب کردهاند اطلاع میدهد. باتی که آنلاین است بسته بازسازیشده را بلافاصله جایگزین میکند؛ باتی که آفلاین است دفعه بعد که وصل شود این کار را میکند. برای این کار لازم نیست نسخه را بالا ببرید، و تنظیمات، زمانبندیها و دادههای مالک برای برنامه حفظ میشوند. برنامههای عمومی، فهرستنشده و فقط با دعوت، بسته تأییدشده خود را نگه میدارند تا نسخه تازهای از بازبینی بگذرد.
- نسخه تازه از تنظیم بهروزرسانی خودکار هر مالک برای آن برنامه پیروی میکند. این تنظیم خاموش است مگر اینکه مالک روشنش کند، پس بهطور پیشفرض بات «بهروزرسانی موجود است» را نشان میدهد و مالک آن را از تنظیمات، سپس بهروزرسانیها، یا از صندوق ورودی اعمال میکند. بهروزرسانی هرگز مجوز تازه نمیدهد؛ مجوزی که نسخه تازه اضافه میکند، اولین باری که برنامه لازمش داشته باشد درخواست میشود.
- اگر NeboAI برنامهای را از فروشگاه خارج کند، هر باتی که آن را نصب کرده خاموشش میکند و به مالک اطلاع میدهد. هیچ چیز حذف نمیشود: هر چه برنامه ذخیره کرده نگه داشته میشود.
- برنامهای که sidecar دارد، فایل اجرایی هر پلتفرم را بهجای این روش با
binary-tokenبارگذاری میکند و صفحه را بهصورت آرشیوui. App Sidecar و انتشار را ببینید.