الحزمة
التطبيق حزمة موظف تحتوي على 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، وتسأل عن هوية موظفها، وتطبع الإجابة. إذا ظهر معرّف الموظف واسمه، فالتوصيل صحيح.
<!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>">. احتفظ بالحالة في تخزين التطبيق لا في الصفحة: فالنافذة تُغلق، والتخزين يبقى.
كيف تُقدَّم الصفحة
- يقدّم 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عندما لا يتغير. ابنِ بأسماء تحتوي على بصمات بدلًا من إعادة تسمية الملفات يدويًا. - يجوز أن يبلغ حجم كل ملف من ملفات الصفحة 10 MB كحد أقصى.
- حذف المجلد يعطّل الموظف، أما
delete_employeeفيزيله تمامًا.
إضافة مكوّن مرافق
عندما تحتاج الصفحة إلى منطق خادم، أو بيانات خاصة بها، أو أدوات يستطيع الموظف استدعاءها، أضِف مكوّنًا مرافقًا: ملفًا تنفيذيًا يشغّله Nebo بجوار التطبيق. تصل إليه الصفحة عبر neboFetch ومسار نسبي. انظر المكوّن المرافق للتطبيق.
النشر من Nebo
يستطيع التطبيق الذي صنعه المالك أن ينشر نفسه. يقول المالك "انشر نفسك"، أو يضغط نشر في محادثة التطبيق، أو على شاشة التطبيق في تطبيق الهاتف المحمول (في الشريط العلوي، أو كزر بجوار إغلاق في التطبيق بملء الشاشة)، أو يختار نشر هذا التطبيق… من قائمة سطح المكتب (قائمة File على macOS عندما تكون نافذة التطبيق في المقدمة، وقائمة App في نافذة التطبيق على 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 تطبيقًا من المتجر، يعطّله كل بوت ثبّته ويُعلم المالك. لا يُحذف شيء: يُحتفظ بكل ما حفظه التطبيق.
- التطبيق الذي لديه مكوّن مرافق يرفع الملف التنفيذي لكل منصة عبر
binary-tokenبدلًا من ذلك، والصفحة كأرشيفui. انظر المكوّن المرافق للتطبيق والنشر.