NeboAI
NeboAI
ابدأ الآن

مرجع plugin.json

plugin.json هو ملف البيان الذي يقرؤه Nebo لتثبيت إضافة وتشغيلها. المفاتيح بصيغة camelCase. تسرد هذه الصفحة كل حقل يقرؤه Nebo اليوم وما يفعله كل منها.

حقول المستوى الأعلى

الحقلالنوعمطلوبالمعنى
idstringنعممعرّف الإضافة في المتجر. استخدم الاسم المختصر أثناء التطوير.
slugstringنعممعرّف ثابت. [a-z0-9-]، بحد أقصى 64 حرفًا، دون شرطة في البداية أو النهاية أو شرطتين متتاليتين. يسمّي الأداة plugin__<slug> والمتغير <SLUG>_BIN.
namestringنعماسم العرض. سمِّ الخدمة التي تتصل بها.
versionstringنعمإصدار دلالي، مثل 0.1.0.
platformsmapنعممفتاح المنصة مقابل الملف التنفيذي. انظر المنصات.
descriptionstringلاجملة واحدة للناس وللموظفين.
authorstringلااسم الناشر.
categorystringلايساعد الموظفين على العثور على الإضافة.
triggersقائمة نصوصلاكلمات تصف متى تنطبق الإضافة. تُستخدم في تلميحات البحث.
entrySkillsقائمة نصوصلاالمهارات المضمّنة التي تُذكر أولًا في وصف أداة الإضافة.
dependenciesقائمة من {name, version, optional}لاإضافات أخرى تشغّلها هذه الإضافة. القيمة الافتراضية لـ version هي "*"، ولـ optional هي false. تُضبط مسارات <SLUG>_BIN الخاصة بها في كل استدعاء.
authobjectلاتسجيل الدخول والحسابات. انظر المصادقة.
capabilitiesobjectلاconfigSchema, hooks, commands, routes, providers.
permissionsobjectلاتصفية البيئة والحد الأقصى للمهلة.
eventslistلامراقِبات تغذّي سير عمل الموظفين.
interfaceBindingsmapلاعمليات محددة النوع توفّرها الإضافة.
channelobjectلاجسر دائم إلى خدمة مراسلة.
setupobjectلامعالج إعداد خطوة بخطوة.

يتحقق 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 الحزمة.

المصادقة

الحقلالمعنى
typeoauth_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، يحدّد المخطط تسميات حقول نموذج الاتصال الخاص بكل موظف.

الحقلالنوعالقيمة الافتراضيةالمعنى
keystringمطلوباسم متغير البيئة.
labelstringمطلوبتسمية الحقل.
descriptionstring""نص المساعدة.
fieldTypestring"string"نوع الإدخال، مثل string أو number أو boolean أو select أو password.
defaultstringلا شيءقيمة معبّأة مسبقًا.
requiredbooleanfalseلا تكون الإضافة جاهزة حتى تُضبط القيمة.
secretbooleanfalseتُخفى القيمة عند قراءتها.
optionsقائمة نصوصلا شيءخيارات select.

permissions

الحقلالقيمة الافتراضيةالمعنى
envAllow[]متغيرات موروثة يجوز للإضافة رؤيتها. القائمة الفارغة تسمح بكل شيء.
envDeny[]متغيرات موروثة تُزال دائمًا.
maxTimeoutSeconds300الحد الأعلى لمهلة أي استدعاء.
networkfalseيصرّح باستخدام الشبكة. للعلم فقط، ولا يُفرض.

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مطلوبوسائط لملفك التنفيذي.
priority100القيمة الأدنى تعمل أولًا.
timeoutMs500المهلة بالمللي ثانية.

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""يظهر في الإعدادات.
restartDelaySecs5الانتظار قبل إعادة التشغيل بعد التعطّل.
sharedfalseجسر واحد لكل الموظفين، تُوجَّه الرسائل حسب اسم الموظف وتحمل الردود هوية كل موظف.
needsLocalApifalseامنح الجسر عنوان واجهة 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" }
  ]
}
نوع الخطوةالحقول
formtitle, description, fields
generatetitle، description، command، args، outputFormat (yaml، json، toml، text)، buttonLabel. يعرض مخرجات الأمر لنسخها.
externaltitle, description, url, urlLabel, instructions
credentialstitle، description، fields، verifyCommand. تكتمل الخطوة عندما ينجح verifyCommand.

للحقول key وlabel وdefault وplaceholder وmaxLength وhelp وinputType (text، textarea، password) وrequired.