NeboAI
NeboAI
ابدأ الآن

الإضافات

تمنح الإضافة الموظفين شيئًا يعملون عليه: خدمة على الإنترنت، أو نظام أعمال، أو برنامجًا على الحاسوب. تبنيها كملف تنفيذي لسطر الأوامر وتصفها بملف بيان plugin.json. يستدعي الموظفون أوامرها، ويتولى Nebo التثبيت والحسابات لكل موظف والتحديثات.

كيف تعمل الإضافات

الإضافة ملف تنفيذي مع ملف بيان. لا يُبقي Nebo أي عملية للإضافة قيد التشغيل بين الاستدعاءات. في كل مرة يستخدم فيها موظف الإضافة، يشغّل Nebo الملف التنفيذي بأمر ووسائط، وينتظر انتهاءه، ويسلّم المخرجات إلى الموظف.

  • الأوامر وسائط. يختار الموظف أمرًا، مثل notes search، ووسائط مسمّاة. يمرّر Nebo كل وسيط بالشكل --name value. لا توجد صدفة أوامر، لذا لا تنطبق الأنابيب وإعادة التوجيه أبدًا.
  • المخرجات هي stdout. اكتب النتائج إلى stdout. وصيغة JSON مناسبة جدًا.
  • الإدخال القياسي مغلق في الاستدعاءات العادية. تستخدم الخطافات والمسارات ومزوّدو المحادثة stdin، انظر مرجع plugin.json.

تظهر كل إضافة مثبّتة ومفعّلة للموظفين كأداة واحدة باسم plugin__<slug>. ويستدعيها الموظف هكذا:

{
  "command": "notes search",
  "args": { "query": "quarterly plan", "limit": "5" },
  "display": "Search notes for the quarterly plan"
}

يشغّل Nebo:

notes-sync notes search --query "quarterly plan" --limit 5
المعاملالنوعالمعنى
commandنص، مطلوبأمر الإضافة وأي كلمات موضعية.
argsكائن من النصوصوسائط مسمّاة. يصبح كل منها --key value.
timeoutintegerثوانٍ الانتظار. القيمة الافتراضية 120، ومحدودة بـ permissions.maxTimeoutSeconds في ملف البيان.
displaystringالجملة التي يراها المالك عندما يحتاج الاستدعاء إلى موافقة.

ابنِ أول إضافة لك

اكتب ملفًا تنفيذيًا بأي لغة يقرأ أمره من الوسائط ويطبع نتيجة. ثم ضعه بجوار plugin.json في مجلد إضافات المستخدم في بوت.

<data>/user/plugins/notes-sync/
├── plugin.json      # runtime manifest
├── notes-sync       # your binary, named after the slug
└── skills/          # optional: skills that teach employees to use it
    └── notes-sync/
        └── SKILL.md
{
  "id": "notes-sync",
  "slug": "notes-sync",
  "name": "Notes Sync",
  "version": "0.1.0",
  "description": "Search, read and create notes in Example Notes.",
  "platforms": {}
}

الحقول id وslug وname وversion وplatforms مطلوبة. في مجلد إضافات المستخدم يمكن أن تكون خريطة platforms فارغة: يبحث Nebo عن ملف تنفيذي يحمل الاسم المختصر بجوار plugin.json، ثم في target/release/ وtarget/debug/. وعند النشر، يملأ المتجر platforms لكل ملف تنفيذي ترفعه.

<data> هو ~/Library/Application Support/Nebo على macOS، و%APPDATA%\Nebo على Windows، و~/.local/share/nebo على Linux، أو قيمة NEBO_HOME. الإضافة في مجلد المستخدم تتجاوز إضافة المتجر ذات الاسم المختصر نفسه، مما يجعله المكان المناسب لاختبار بناء جديد.

علّم الموظفين استخدامها

ضع مجلد skills/ بجوار plugin.json. كل مهارة فيه متاحة لكل موظف ما دامت الإضافة مثبّتة، وتُدرج الإضافة كاعتمادية تلقائيًا. استخدم المهارة لتوضيح الأوامر الموجودة، وما تعيده، ومتى يُستخدم كل منها. وسمِّ أكثر المهارات فائدة في entrySkills ليشير وصف أداة الإضافة إليها أولًا.

صفحة الإدراج في المتجر ملف منفصل هو PLUGIN.md. لا يقرؤه Nebo وقت التشغيل، فهو الصفحة التي يراها الناس قبل التثبيت. انظر شحن إضافة.

البيئة

يرث كل استدعاء بيئة البوت بعد إزالة متغيرات المُحمِّل وحقن الصدفة، ثم يضيف هذه القيم. والإدخالات اللاحقة لها الأولوية.

المتغيرالقيمة
مفاتيح auth.envالقيم الافتراضية من ملف البيان.
<SLUG>_BINمسار الملف التنفيذي لهذه الإضافة، ولكل إضافة تعتمد عليها. يُكتب الاسم المختصر بأحرف كبيرة مع تحويل الشرطات إلى شرطات سفلية.
NEBO_DATA_DIRمجلد البيانات الخاص بالإضافة، <data>/appdata/plugins/<slug>/. وهو أيضًا مجلد العمل، ويبقى بعد إلغاء التثبيت.
PATHمجلدات الإضافة أولًا، ثم المسار الموروث.
الإعداداتالقيم التي حفظها المالك لحقول configSchema.
NEBO_AGENT_IDالموظف الذي يُجري الاستدعاء.
profileDirEnvمجلد الحساب لهذا الموظف والحساب، عندما تدعم الإضافة الحسابات.

يضيّق permissions.envAllow وpermissions.envDeny ما ترثه الإضافة من البوت. ولا يزيلان أبدًا متغيرات المصادقة الخاصة بالإضافة.

الحسابات وبيانات الاعتماد

ينبغي للإضافة التي تسجّل الدخول إلى خدمة أن تحتفظ بحساب واحد لكل موظف. يسجّل المحاسب الدخول ببيانات الدخول المالية، والمساعد ببياناته الخاصة، ولا يرى أي منهما رموز الآخر. تصرّح بذلك في ملف البيان، ويتولى Nebo الباقي.

"auth": {
  "type": "env",
  "label": "Example Notes account",
  "env": { "EXAMPLE_NOTES_TOKEN": "" },
  "commands": { "login": "auth login", "status": "auth status", "logout": "auth logout" },
  "profileDirEnv": "EXAMPLE_NOTES_CONFIG_DIR"
},
"capabilities": {
  "configSchema": [
    { "key": "EXAMPLE_NOTES_TOKEN", "label": "API token", "fieldType": "password", "secret": true, "required": true }
  ]
}
  1. يسمّي auth.env بيانات الاعتماد. ويحدّد capabilities.configSchema تسمياتها وترتيبها في نموذج الاتصال.
  2. يسمّي auth.profileDirEnv المتغير الذي تقرؤه إضافتك لمعرفة مجلد بيانات الاعتماد. ينشئ Nebo مجلدًا لكل موظف وحساب ويضبط ذلك المتغير في كل استدعاء.
  3. عندما يربط المالك حسابًا، يشغّل Nebo أمر login الخاص بك مع القيم التي كتبها المالك ومع ضبط مجلد الحساب. تحفظ إضافتك ما تحتاج إليه في ذلك المجلد. ولا يحتفظ Nebo بالقيم.
  4. يطبع أمر status الخاص بك JSON مثل {"authenticated": true}. وعندما تنتهي صلاحية رمز، يشغّل Nebo الأمر refresh إذا عرّفته.

لتسجيل الدخول عبر المتصفح، اضبط type على oauth_cli واجعل login يطبع عنوان URL لتسجيل الدخول لدى المزوّد أو يفتحه. لا يسجّل الموظفون الدخول بأنفسهم أبدًا: عندما يحتاج استدعاء إلى تسجيل دخول، يرى المالك بطاقة اتصال. والموظف الذي لديه عدة حسابات يختار أحدها بإضافة --account <label> إلى الأمر. ويزيل Nebo ذلك العلَم قبل أن يراه ملفك التنفيذي.

سمِّ الخدمة، لا الشكل. يقول اسم الإضافة ما الذي تتصل به، مثل "Example Notes". لا تضع أبدًا "CLI" في اسم إضافة، فهي بالنسبة إلى الموظفين والمالكين اتصال، لا سطر أوامر.

التالي

  • مرجع plugin.json: كل حقل، بما في ذلك الأحداث والخطافات والعمليات المحددة النوع.
  • شحن إضافة: المنصات، والملفات التنفيذية، والتوقيع، والتحديثات.
  • النشر: مسار المتجر لكل عنصر.