حقول المستوى الأعلى
| الحقل | النوع | مطلوب | المعنى |
|---|---|---|---|
id | string | نعم | معرّف الإضافة في المتجر. استخدم الاسم المختصر أثناء التطوير. |
slug | string | نعم | معرّف ثابت. [a-z0-9-]، بحد أقصى 64 حرفًا، دون شرطة في البداية أو النهاية أو شرطتين متتاليتين. يسمّي الأداة plugin__<slug> والمتغير <SLUG>_BIN. |
name | string | نعم | اسم العرض. سمِّ الخدمة التي تتصل بها. |
version | string | نعم | إصدار دلالي، مثل 0.1.0. |
platforms | map | نعم | مفتاح المنصة مقابل الملف التنفيذي. انظر المنصات. |
description | string | لا | جملة واحدة للناس وللموظفين. |
author | string | لا | اسم الناشر. |
category | string | لا | يساعد الموظفين على العثور على الإضافة. |
triggers | قائمة نصوص | لا | كلمات تصف متى تنطبق الإضافة. تُستخدم في تلميحات البحث. |
entrySkills | قائمة نصوص | لا | المهارات المضمّنة التي تُذكر أولًا في وصف أداة الإضافة. |
dependencies | قائمة من {name, version, optional} | لا | إضافات أخرى تشغّلها هذه الإضافة. القيمة الافتراضية لـ version هي "*"، ولـ optional هي false. تُضبط مسارات <SLUG>_BIN الخاصة بها في كل استدعاء. |
auth | object | لا | تسجيل الدخول والحسابات. انظر المصادقة. |
capabilities | object | لا | configSchema, hooks, commands, routes, providers. |
permissions | object | لا | تصفية البيئة والحد الأقصى للمهلة. |
events | list | لا | مراقِبات تغذّي سير عمل الموظفين. |
interfaceBindings | map | لا | عمليات محددة النوع توفّرها الإضافة. |
channel | object | لا | جسر دائم إلى خدمة مراسلة. |
setup | object | لا | معالج إعداد خطوة بخطوة. |
يتحقق Nebo من عمليات التثبيت من المتجر: قواعد الاسم المختصر، وإصدار دلالي، ومنصة واحدة على الأقل، وbinaryName بلا فواصل مسارات أو ..، وأمر login ما لم يكن auth.type هو env، وأسماء أحداث وأوامر غير فارغة، وقوالب ربط قابلة للتحليل. أما الإضافات في مجلد إضافات المستخدم فتتخطى التحقق.
المنصات
المفاتيح هي darwin-arm64 وdarwin-amd64 وlinux-arm64 وlinux-amd64 وwindows-arm64 وwindows-amd64. لكل إدخال الحقول الخمسة أدناه كلها. وعند النشر، يكتب المتجر البصمة والحجم والتوقيع وعنوان URL للتنزيل الحقيقية، لذا اتركها فارغة في الملف الذي ترفعه.
"platforms": {
"darwin-arm64": { "binaryName": "notes-sync", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
"linux-amd64": { "binaryName": "notes-sync", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
"windows-amd64": { "binaryName": "notes-sync.exe", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" }
} | الحقل | المعنى |
|---|---|
binaryName | اسم ملف البرنامج التنفيذي. أضِف .exe على Windows. |
sha256 | بصمة الملف التنفيذي. يُتحقق منها عند التثبيت. |
signature | توقيع الملف التنفيذي. يُتحقق منه عند التثبيت عندما يتوفر مفتاح توقيع. |
size | الحجم بالبايت. |
downloadUrl | المكان الذي ينزّل منه Nebo الحزمة. |
المصادقة
| الحقل | المعنى |
|---|---|
type | oauth_cli لتسجيل الدخول عبر المتصفح الذي تديره الإضافة، وenv لبيانات الاعتماد المُدخلة كقيم، وneboai لاستلام رمز NeboAI الخاص بالمالك في كل مفتاح auth.env ينتهي بـ _TOKEN. |
env | خريطة من اسم المتغير إلى القيمة الافتراضية. وهي أيضًا أسماء بيانات الاعتماد الوحيدة التي يمرّرها Nebo إلى login. |
commands.login | يسجّل الدخول. مطلوب ما لم يكن type هو env. يعمل مع ضبط مجلد الحساب. |
commands.status | يطبع JSON يوضح ما إذا كان الحساب مسجّل الدخول. |
commands.refresh | يجدّد رمزًا دون تفاعل. |
commands.logout | يسجّل الخروج. لا يستطيع تشغيله إلا المالك. |
profileDirEnv | متغير يستلم مجلد بيانات اعتماد منفصلًا لكل موظف وحساب. ومن دونه تحتفظ الإضافة بحساب مشترك واحد. |
label, description | النص على بطاقة الاتصال. |
help | {url, urlLabel, text} يُعرض أثناء الاتصال. |
publicRedirect | اضبطه على true عندما يرفض المزوّد عمليات إعادة التوجيه إلى http://localhost، فيمرّ تسجيل الدخول عندئذ عبر إعادة التوجيه العامة لدى NeboAI. |
يقرأ Nebo أول ما يجده من authenticated أو isAuthenticated أو logged_in أو loggedIn أو token_valid في مخرجات الحالة. وجود token_error غير فارغ، أو القيمة none في credential_source أو auth_method أو storage أو status، يعني أن الحساب غير مسجّل الدخول. ولأمر الحالة 45 ثانية.
{"authenticated": true, "account": "finance@example.com"} configSchema
يصف capabilities.configSchema القيم التي يضبطها المالك للإضافة. تصل كل قيمة إلى الملف التنفيذي كمتغير بيئة يسمّيه key. ولمفاتيح بيانات الاعتماد المدرجة أيضًا في auth.env، يحدّد المخطط تسميات حقول نموذج الاتصال الخاص بكل موظف.
| الحقل | النوع | القيمة الافتراضية | المعنى |
|---|---|---|---|
key | string | مطلوب | اسم متغير البيئة. |
label | string | مطلوب | تسمية الحقل. |
description | string | "" | نص المساعدة. |
fieldType | string | "string" | نوع الإدخال، مثل string أو number أو boolean أو select أو password. |
default | string | لا شيء | قيمة معبّأة مسبقًا. |
required | boolean | false | لا تكون الإضافة جاهزة حتى تُضبط القيمة. |
secret | boolean | false | تُخفى القيمة عند قراءتها. |
options | قائمة نصوص | لا شيء | خيارات select. |
permissions
| الحقل | القيمة الافتراضية | المعنى |
|---|---|---|
envAllow | [] | متغيرات موروثة يجوز للإضافة رؤيتها. القائمة الفارغة تسمح بكل شيء. |
envDeny | [] | متغيرات موروثة تُزال دائمًا. |
maxTimeoutSeconds | 300 | الحد الأعلى لمهلة أي استدعاء. |
network | false | يصرّح باستخدام الشبكة. للعلم فقط، ولا يُفرض. |
events
الحدث مراقِب طويل الأمد. يشغّله Nebo عندما يراقبه سير عمل موظف، ويعيد تشغيله إذا توقف. كل سطر يكتبه المراقِب إلى stdout حدث واحد. ويُضاف الاسم المختصر كبادئة لاسم الحدث وقت التشغيل، فيصبح note.created هو notes-sync.note.created.
"events": [
{
"name": "note.created",
"description": "A note was created in the watched notebook.",
"command": "watch --notebook {{notebook}} --format ndjson"
}
] | الحقل | المعنى |
|---|---|
name | اسم الحدث، دون الاسم المختصر. مطلوب. |
command | الوسائط التي تشغّل المراقِب. مطلوب. يُستبدل {{key}} من قيم مدخلات الموظف. |
description | ما الذي يسبّب الحدث. |
multiplexed | عندما يكون true، يُصدر مراقِب واحد عدة أنواع من الأحداث ويحمل كل سطر الحقل "event". |
تشترك سير العمل في الأحداث عبر مُشغِّل watch. انظر المُشغِّلات.
interfaceBindings
يربط الربطُ عملية واجهة بأحد أوامرك. يصبح كل ربط أداة محددة النوع للموظفين، تُسمّى باسم العملية بأحرف صغيرة مع تحويل النقاط والشرطات إلى شرطات سفلية: يصبح notes.search هو notes_search. الربط هو الطريقة التي تلبّي بها الإضافة القدرات التي يتطلبها الموظف، انظر القدرات.
"interfaceBindings": {
"notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
"invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
} | العنصر النائب | يتحوّل إلى |
|---|---|
{field} | قيمة الحقل ككلمة واحدة. ولا يُمرَّر الحقل أيضًا كعلَم. |
{field[]:--flag} | زوج --flag <item> واحد لكل عنصر في حقل قائمة. |
{field?:--flag} | --flag <value> عندما يكون الحقل موجودًا، ولا شيء عندما يكون غائبًا. |
{field:cents->dollars} | مبلغ صحيح بالسنتات، يُكتب بالدولارات. |
تُلحق حقول الإدخال التي لا يسمّيها القالب بالشكل --field value. ويجب أن تكون العناصر النائبة للقوائم والحقول الاختيارية كلمات كاملة. ولا يمكن الوصول إلى عملية تتطلب موافقة باستدعاء الأمر نفسه عبر plugin__<slug>.
الخطافات وأوامر الشرطة المائلة والمسارات
"capabilities": {
"hooks": [
{ "hook": "tool.post_execute", "hookType": "filter", "command": "hook redact", "priority": 50, "timeoutMs": 500 }
],
"commands": [
{ "name": "notes", "description": "Show today's notes", "command": "notes today", "slash": true }
],
"routes": [
{ "path": "/callback", "method": "GET", "command": "http callback" }
]
} hooks
الخطّاف يشغّل أمرك عند نقطة معينة من دور الموظف. يكتب Nebo حمولة JSON إلى stdin. يُتجاهل مخرج خطّاف action. أما خطّاف filter فيُرجع {"payload": ..., "handled": false}؛ والقيمة "handled": true توقف الخطّافات اللاحقة. الأخطاء وانتهاء المهلة تُبقي الحمولة السابقة ولا تعطّل الدور أبدًا. وبعد ثلاث حالات فشل متتالية، يُوقَف الخطّاف مؤقتًا لمدة خمس دقائق.
| الحقل | القيمة الافتراضية | المعنى |
|---|---|---|
hook | مطلوب | واحد من tool.pre_execute، tool.post_execute، message.post_receive، session.message_append، steering.generate، agent.turn، agent.should_continue. |
hookType | "action" | action أو filter. |
command | مطلوب | وسائط لملفك التنفيذي. |
priority | 100 | القيمة الأدنى تعمل أولًا. |
timeoutMs | 500 | المهلة بالمللي ثانية. |
commands
مع "slash": true، كتابة /name args في المحادثة تشغّل command args مباشرة، دون الموظف. والمخرجات هي الرد. المهلة 30 ثانية.
routes
يجيب المسار على طلبات HTTP عند /api/v1/plugins/<slug>/api/<path> على البوت، مطابَقةً بـ path وmethod. يذهب نص الطلب إلى stdin ويكون stdout الخاص بك هو الاستجابة. المهلة 30 ثانية.
providers
يضيف المزوّد مصدرًا لنماذج المحادثة. صرّح بـ id وdisplayName وproviderType وmodelsCommand وchatCommand. يرسل Nebo طلب المحادثة كـ JSON على stdin إلى chatCommand ويقرأ الأحداث المتدفقة كـ JSON مفصول بأسطر جديدة على stdout، لمدة تصل إلى 300 ثانية. لا يُستخدم حاليًا إلا بث المحادثة.
channel
تربط القناة خدمة مراسلة. يُبقي Nebo الأمر command قيد التشغيل، ويقرأ الرسائل الواردة من stdout الخاص به ويكتب الردود إلى stdin الخاص به، وكلاهما بصيغة JSON مفصول بأسطر جديدة.
| الحقل | القيمة الافتراضية | المعنى |
|---|---|---|
command | مطلوب | الوسائط التي تشغّل الجسر. |
name, description | "" | يظهر في الإعدادات. |
restartDelaySecs | 5 | الانتظار قبل إعادة التشغيل بعد التعطّل. |
shared | false | جسر واحد لكل الموظفين، تُوجَّه الرسائل حسب اسم الموظف وتحمل الردود هوية كل موظف. |
needsLocalApi | false | امنح الجسر عنوان واجهة API المحلية للبوت ورمزًا ومعرّف الموظف. معطّل ما لم تحتج إليه. |
setup
يرشد معالج الإعداد المالك خلال خطوات لا يغطيها نموذج واحد. القيم من خطوات form تملأ {{key}} في وسائط generate اللاحقة. والقيم من خطوات credentials تُحفظ كمتغيرات بيئة للإضافة.
"setup": {
"title": "Connect Example Chat",
"steps": [
{ "kind": "form", "title": "Bot name", "fields": [ { "key": "bot_name", "label": "Name", "required": true } ] },
{ "kind": "generate", "title": "App manifest", "command": "manifest", "args": ["--name", "{{bot_name}}"], "outputFormat": "yaml" },
{ "kind": "external", "title": "Create the app", "url": "https://example.com/apps", "urlLabel": "Open admin" },
{ "kind": "credentials", "title": "Paste the token", "fields": [ { "key": "EXAMPLE_CHAT_TOKEN", "label": "Token", "inputType": "password", "required": true } ], "verifyCommand": "auth status" }
]
} | نوع الخطوة | الحقول |
|---|---|
form | title, description, fields |
generate | title، description، command، args، outputFormat (yaml، json، toml، text)، buttonLabel. يعرض مخرجات الأمر لنسخها. |
external | title, description, url, urlLabel, instructions |
credentials | title، description، fields، verifyCommand. تكتمل الخطوة عندما ينجح verifyCommand. |
للحقول key وlabel وdefault وplaceholder وmaxLength وhelp وinputType (text، textarea، password) وrequired.