إضافات Shell

يعمل سطح مكتب OmarOS بوصفه عملية Quickshell واحدة طويلة العمر تدعى omaros-shell، وكل شيء تقريبًا تراه على الشاشة هو إضافة (plugin) داخله. الشريط إضافة، وكذا الألواح التي تنسدل منه، والتراكبات التي تملأ الشاشة مثل منتقي الإيموجي ومدير الحافظة، وقائمة OmarOS نفسها، وشاشة القفل، ومربع حوار polkit، والخدمات غير المرئية التي تراقب بطاريتك وتدفئ شاشتك في الليل.

ليس ذلك مجرد تفاصيل تنفيذية. فهذا يعني أنك تستطيع إيقاف أجزاء من سطح المكتب، أو استبدالها، أو كتابة أجزائك الخاصة دون لمس سطر واحد من رمز OmarOS.

تشحن الإضافات الأساسية (first-party) مع OmarOS وتعيش في $OMAROS_PATH/shell/plugins/. وأي شيء تضيفه بنفسك — تجاربك الخاصة، أو شيئًا وجدته على GitHub — يعيش في ~/.config/omaros/plugins/. يتم اكتشاف كليهما بالطريقة نفسها عند بدء التشغيل، ولكن الإضافات المدمجة تتلقى واجهات shell موثوقة بينما تتلقى إضافات الطرف الثالث واجهة محدودة نطاقها خدمتهم الخاصة ودورة حياتها. أما استنساحات الإضافات المدمجة فتبقي فقط على الإعداد ومناديات واجهة المستخدم الخاصة بالمصدر اللازمة للسلوك الأصلي.

رؤية ما لديك

omaros plugin list

يطبع ذلك كل إضافة مكتشفة مع معرّفها، وما إذا كانت مفعّلة، وما إذا كانت إضافة أساسية (first-party) أو من طرف ثالث (third-party)، وأنواعها، واسم عرضها. أضف --json إذا كنت تغذيها إلى شيء آخر.

معرّفات الإضافات ذات نطاق (namespaced). تبدأ الإضافات المدمجة كلها بـ omaros. — omaros.clock، omaros.network، omaros.notifications — وذلك النطاق محجوز، بحيث لا تستطيع إضافة طرف ثالث أن تدعيه أبدًا.

تفعيلها وتعطيلها

omaros plugin enable omaros.tailscale
omaros plugin disable omaros.weather

أو استخدم القائمة: لدى الإعداد > Plugins Enable وDisable وAdd وClone وRemove، وكل منها مع منتقي يعرض فقط الإضافات المناسبة لذلك الإجراء.

تُخزّن حالة التفعيل في ~/.config/omaros/shell.json، وتختلف القاعدة قليلًا بالنسبة لنوعي الإضافات. إضافة الطرف الثالث تُفعّل بالضبط عندما يظهر معرّفها في مكان ما في ذلك الملف — بوصفها إدخال تخطيط شريط، أو إدخالاً في plugins[]، أو بوصفها bar.id. أما الإضافات الأساسية التي ليست أدوات شريط فهي على النقيض: فهي مفعّلة افتراضيًا ولا تنطفئ إلا بأن تُدرج في disabledPlugins[].

إضافة الشريط الكاملة ليس لها حالة تعطيل أصلاً. فهناك دائمًا شريط واحد بالضبط، لذا تستبدله بتفعيل شريط آخر. يتم تناول موضع أدوات الشريط في الشريط العلوي.

إضافة إضافة من git

إضافة الطرف الثالث هي مجرد مستودع git يحتوي على manifest.json في جذره.

omaros plugin add https://github.com/acme/omaros-weather.git --enable

قبل أن يقوم بأي شيء، سيخبرك بصراحة أن الإضافات تعمل برمز تعسفي وغير معزول (unsandboxed) داخل عملية shell طويلة العمر الخاصة بك، ويعرض عليك عنوان URL، ويطلب منك التأكيد. خذ ذلك على محمل الجد. إن واجهة إضافة الطرف الثالث لا تعرض خدمات المصادقة مباشرة، ويتلقى شريط بديل فقط قدرات محدودة لواجهة مستخدم غير متعلقة بالمصادقة على الإعدادات المضبوطة. ما تزال الإضافات المرئية تشارك مشهد QML الخاص بـ shell ويمكنها تتبّع كائنات الأبوين العادية، بينما يعمل كل رمز الإضافات بكل ما يمكن لحساب مستخدمك الوصول إليه. تُحمى حالة المصادقة بشكل منفصل عن طريق إبقاء تلك الخدمات خارج رسم كائنات المضيف القابلة للوصول إليها. فقط أضف المستودعات التي أنت مستعد لتشغيلها، واقرأها قبل تفعيلها.

يمكن لشريط بديل أن يعرض أدوات مثبتة، ولكن أدوات الطرف الثالث المستندة إلى الخدمة قد تكون لديها وظائف مخفضة هناك لأن الشريط غير مسموح له بطلب كائن خدمة حي لإضافة أخرى. انتقل مرة أخرى إلى omaros.bar المدمج إذا احتاجت أداة ما إلى خدمتها المصاحبة.

بعد ذلك يستنسخ المستودع إلى مجلد تجميع (staging directory)، ويتحقق من البيان (manifest)، ويرفض التثبيت إذا ادعت إضافة أخرى ذلك المعرّف أصلًا، وينقله إلى ~/.config/omaros/plugins/<id>/. ودون --enable سيسأل ما إذا كنت تريده مفعّلاً الآن، ويمكنك أن تقول لا واذهب واقرأ الرمز أولًا. لا يقوم أبدًا بتشغيل أي شيء من الإضافة، ولا ينفّذ أبدًا خطاف تثبيت، ولا يطلب sudo أبدًا — إنه يستنسخ الملفات ويتحقق من البيان ويقلب بت عبر IPC.

التحديث عبارة عن سحب fast-forward لنفس النسخة:

omaros plugin update acme.weather
omaros plugin update

ودون معرّف يقوم بتحديث كل إضافة مدارة بواسطة git لديك. يعرض عليك الفرق قبل تطبيقه، ويرفض التحديث إذا كانت لديك تغييرات محلية لا يستطيع المضي بسرعة لتجاوزها، ويتراجع إذا فشل التحقق من النسخة الجديدة.

omaros plugin remove acme.weather

الإزالة تعطّل الإضافة أولًا، ثم تحذفها إذا كانت نسخة git (ما زال المستودع موجودًا في المصدر) أو تفكّ ربطها إذا كانت رابطًا رمزيًا. أما مجلد إضافة مصنوع يدويًا دون مستودع git فيُنقل إلى نسخة احتياطية مختومة بالوقت داخل مجلد الإضافات بدلًا من أن يُحذف بشكل نهائي.

استنساخ إضافة مدمجة لتعديلها

هذا هو الجزء المفضل لديّ. إذا كنت تريد تغيير كيفية تصرف أداة مدمجة، فلا تعدّل الملفات تحت $OMAROS_PATH — فهي تنتمي إلى الحزمة وسيقوم التحديث التالي باستبدالها. استنسخها بدلًا من ذلك:

omaros plugin clone omaros.clock

هذا ينسخ الإضافة بأكملها إلى ~/.config/omaros/plugins/omar.clock (اسم مستخدمك، لا اسمي)، ويعيد تسميتها إلى "My Clock"، ويفعّلها، ويبدّل shell للتحويل من المدمجة إلى نسختك — مع الحفاظ على موضع وإعدادات أداة الشريط الحالية. أضف --edit لفتح المجلد الجديد في $EDITOR على الفور، وهو ما تفعله قائمة الإعداد > Plugins > Clone Plugin من أجلك.

تبقي بادئة اسم المستخدم معرّف استنساخك خاصًا بك، لذا فإن مشاركته لا يصطدم مع أي شخص آخر. تُوجّه الاستدعاءات الموجهة إلى معرّف الإضافة المدمجة الأصلية إلى استنساخك، لذا لا يحتاج أي شيء يشير إلى omaros.clock إلى تحديث. وإذا أفسدت الأمر، فالتراجع عنه عبر omaros plugin remove omar.clock يعيد الإضافة المدمجة.

حفظ ملف في أي مكان تحت ~/.config/omaros/plugins/ يعيد تحميل رمز الإضافة تلقائيًا، لتتمكن من ترك المحرر مفتوحًا ومشاهدة تغييراتك تظهر.

كتابة ما تريده بنفسك

الإضافة عبارة عن مجلد يحتوي على manifest.json وبعض QML. يصرّح البيان عن schemaVersion: 1، ومعرّف id، واسم name، وإصدار version، ونوع واحد أو أكثر kinds، وكائن entryPoints يشير إلى ملف QML لكل نوع:

Kind	What it is
bar-widget	مكون يمكن للشريط النشط إسقاطه في قسم
panel	نافذة عائمة ثابتة أو تُستدعى
overlay	تراكبة تملأ الشاشة
menu	سطح قائمة يُستدعى
service	كائن مفرد بلا واجهة مستخدم (headless)
bar	شريط كامل يحل محل الشريط المدمج

يمكن لإضافة أن تعلن عن عدة أنواع في وقت واحد — إضافة الوسائط هي service وbar-widget معًا. تحصل أدوات الشريط على كتلة إضافية barWidget مع اسم عرض، وفئة، وdefaultSection اختيارية، وallowMultiple، التي تشير إلى ما إذا كان من المنطقي أن يكون هناك أكثر من واحدة على الشريط. تعيّن معظم الأدوات ذلك على false؛ أما الفواصل والمؤشرات فتعيّنه على true.

قبل أن تنشر أي شيء، تحقق منه:

omaros plugin validate ./my-plugin

هذا يشغّل الفحوصات نفسها التي يقوم بها shell في وقت التحميل: إصدار المخطط (schema version)، والحقول المطلوبة، ومعرّف ليس محجوزًا، ونقاط إدخال هي مسارات نسبية آمنة وموجودة فعليًا، ونقطة إدخال لكل نوع ادعيته، ولا روابط رمزية في أي مكان داخل المجلد.

من أجل تطوير الإضافات، انظر مرجع shell وكتالوج الإضافات الأساسية.

مشاركة ما تريده مع العالم

بمجرد أن تصنع شيئًا يعجبك، ضعه في مستودع git عام. هذه هي آلية التوزيع بأكملها — يمكن لأي شخص بعد ذلك تشغيل omaros plugin add ضد عنوان URL الخاص بك وجعله يعمل في ثوانٍ.