كيفية إعداد روبوت مصفوفة باستخدام بايثون ومكتبة Simple-Matrix-Bot-Lib

ما الذي تختاره فعلياً عند بناء روبوت المصفوفة بهذه الطريقة؟

مكتبة Simple-Matrix-Bot-Lib هي طبقة تسهيلية فوق matrix-nioمكتبة عميل بايثون. وهذا ما يجعلها خيارًا مثاليًا عندما ترغب في إنشاء روبوت أوامر صغير، أو روبوت إشعارات، أو مساعد غرف دردشة، دون الحاجة إلى كتابة حلقة مزامنة المصفوفة ومعالجة الأحداث كاملةً بنفسك. لكن في المقابل، ستعتمد على التجريدات وأنماط المصادقة التي توفرها هذه الطبقة التسهيلية، بدلًا من التحكم المباشر في كل تفاصيل عميل المصفوفة.

اعتبارًا من 6 أكتوبر 2026، يُدرج موقع PyPI الإصدار simplematrixbotlib2.13.1، الذي صدر في 29 مارس 2026، ويتطلب Python 3.9 أو أحدث ولكن أقدم من Python 4. ويحذر موقع Read the Docs الخاص بالمشروع حاليًا من أن وثائقه غير مُحدثة وقد تكون قديمة، لذلك يستخدم هذا الدليل PyPI ومواصفات Matrix الحالية كمرجعين أساسيين، ويتعامل مع الوثائق القديمة كإرشادات للتنفيذ وليست دليلًا على السلوك الحالي.

للاطلاع على تفاصيل الحزمة، يُرجى مراجعة مشروع simplematrixbotlib على PyPI . أما بالنسبة لسلوك البروتوكول، فيُرجى استخدام مواصفات واجهة برمجة تطبيقات Matrix Client-Server الحالية .

Simple-Matrix-Bot-Lib، أو matrix-nio، أو خدمة تطبيق؟

إذا كان هدفك هو "الاستجابة للأوامر في الغرف باستخدام حساب بوت واحد"، فإن مكتبة Simple-Matrix-Bot-Lib هي عادةً الخيار الأنسب. أما إذا كنت تعلم مسبقًا أنك بحاجة إلى مصادقة مخصصة، أو سلوك مزامنة غير معتاد، أو تحقق دقيق من الجهاز، أو تحكم دقيق في التشفير، فإن البدء بـ matrix-nio يجنبك التعامل مع برامج وسيطة لاحقًا. بالنسبة للجسور أو التكاملات التي تتطلب توجيهًا على مستوى الخادم الرئيسي، يُنصح بالاطلاع على واجهة برمجة تطبيقات Matrix Application Service API بدلًا من استخدام حساب بوت عادي كبديل.

الخطوة 1: اختر خادمًا منزليًا وتأكد من كيفية تسجيل دخول البوت

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

القرار الأهم هو المصادقة. يدعم معيار Matrix الحالي كلاً من واجهة برمجة تطبيقات المصادقة القديمة وOAuth 2.0. قد يُتيح خادم المنزل أحدهما أو كليهما. تستخدم أمثلة البدء السريع المنشورة في Simple-Matrix-Bot-Lib عنوان URL لخادم المنزل واسم المستخدم وكلمة المرور، لذا يفترض هذا الدليل أن خادمك لا يزال يوفر آلية تسجيل دخول متوافقة باستخدام كلمة المرور.

قبل كتابة التعليمات البرمجية، تحقق من طرق تسجيل الدخول التي يوفرها خادمك المنزلي:

curl https://matrix.example.com/_matrix/client/v3/login

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

الخطوة الثانية: إنشاء بيئة بايثون معزولة وتثبيت المكتبة

استخدم بيئة افتراضية لفصل تبعيات البوت عن بايثون النظام وعن المشاريع الأخرى. تتطلب بيانات PyPI الحالية بايثون 3.9 أو أحدث.

mkdir matrix-bot
cd matrix-bot
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install simplematrixbotlib

في نظام التشغيل Windows PowerShell، قم بتنشيط البيئة باستخدام الأمر التالي:

.venv\Scripts\Activate.ps1

تحقق من البرنامج الذي تم تثبيته بدلاً من افتراض إصدار من برنامج تعليمي قديم:

python -m pip show simplematrixbotlib

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

هل تحتاج إلى تشفير من طرف إلى طرف؟

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

تشير وثائق Simple-Matrix-Bot-Lib ووثائق matrix-nio الحالية إلى أن التشفير من طرف إلى طرف (E2EE) يعتمد على دعم التشفير الخاص بـ matrix-nio ومكتبة libolm. في نظامي Debian أو Ubuntu، توضح وثائق matrix-nio كيفية تثبيته libolm-dev، ثم إضافة ميزة E2EE الإضافية.

sudo apt-get install libolm-dev
python -m pip install "matrix-nio[e2e]"

لا تُفعّل خاصية التشفير من طرف إلى طرف (E2EE) لمجرد أن Matrix يدعمها. استخدمها فقط عندما تتطلب الغرف تشفيرًا وتكون مستعدًا للاحتفاظ ببيانات البوت وإدارة موثوقية الجهاز. تشير وثائق Matrix-nio إلى أن حالة التشفير والمفاتيح وموثوقية الجهاز تُخزّن محليًا عند تفعيل E2EE.

الخطوة 3: أنشئ حساب البوت واحتفظ ببيانات الاعتماد بعيدًا عن شفرة المصدر

أنشئ حسابًا مخصصًا على منصة Matrix باستخدام برنامج العميل أو عملية إدارة الحسابات التي يوفرها خادمك المنزلي. تختلف واجهة التسجيل باختلاف مزود الخدمة، لذا لا يفترض هذا الدليل شاشة Element محددة ولا يدّعي أن التسجيل المفتوح متاح في كل مكان.

لأغراض التطوير، قم بتصدير ثلاثة متغيرات بيئية:

export MATRIX_HOMESERVER="https://matrix.example.com"
export MATRIX_USERNAME="botname"
export MATRIX_PASSWORD="replace-with-a-secret"

تُعدّ متغيرات البيئة مفيدةً للتدريب المحلي، لكنها لا تُشكّل تلقائيًا نظامًا لإدارة الأسرار على مستوى الإنتاج. على منصة VPS أو منصة حاويات، يُفضّل استخدام مخزن الأسرار الخاص بالمنصة، أو ملف بيئة محمي خارج نظام التحكم بالمصادر، أو مدير أسرار مُخصّص. لا تُضِف أبدًا كلمة مرور Matrix أو رمز الوصول إلى Git.

قم بدعوة حساب البوت إلى غرفة اختبار واقبل الدعوة باستخدام عميل Matrix إذا لم يكن خادمك أو إعدادات البوت تسمح بالانضمام التلقائي للدعوات. ابدأ بغرفة اختبار خاصة. هذا يحد من تنفيذ الأوامر عن طريق الخطأ أثناء التحقق من سلوك البوت.

الخطوة الرابعة: كتابة وتشغيل واختبار روبوت أوامر بسيط

أنشئ bot.pyباستخدام !pingأمر بسيط. يتبع الهيكل أدناه مثال الحزمة العامة: أنشئ Creds، أنشئ Bot، أضف مستمع رسائل غير متزامن، استخدم MessageMatch، وأرسل رسالة نصية من خلال bot.api.

import os
import simplematrixbotlib as botlib

HOMESERVER = os.environ["MATRIX_HOMESERVER"]
USERNAME = os.environ["MATRIX_USERNAME"]
PASSWORD = os.environ["MATRIX_PASSWORD"]
PREFIX = "!"

creds = botlib.Creds(HOMESERVER, USERNAME, PASSWORD)
bot = botlib.Bot(creds)

@bot.listener.on_message_event
async def ping(room, message):
    match = botlib.MessageMatch(room, message, bot, PREFIX)

    if (
        match.is_not_from_this_bot()
        and match.prefix()
        and match.command("ping")
    ):
        await bot.api.send_text_message(room.room_id, "Pong!")

bot.run()

قم بتشغيله من البيئة الافتراضية المُفعّلة:

python bot.py

في غرفة الاختبار، أرسل:

!ping

النتيجة الناجحة بسيطة: يبقى البوت متصلاً، ويرى حدث الغرفة، ويرد Pong!. تأكد أيضاً من أنه لا يرد على رده الخاص. هذا is_not_from_this_bot()التحقق مهم لأن البوت البسيط الذي يعتمد على الصدى قد يُنشئ حلقات تغذية راجعة.

متى يجب إضافة قائمة السماح؟

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

تُعلن مكتبة Simple-Matrix-Bot-Lib عن إدارة وصول المستخدمين وتكوين قوائم السماح/الحظر كميزات أساسية. بالنسبة لروبوتات الإنتاج، تعامل مع عملية التفويض كجزء لا يتجزأ من منطق التطبيق، وليس كخطوة تحسين اختيارية. قيّد الوصول باستخدام معرّف المستخدم، أو معرّف الغرفة، أو كليهما، واحتفظ بصلاحيات الخادم على الأنظمة الفرعية كخط دفاع ثانٍ.

تسجيل الدخول بكلمة المرور مقابل رموز الوصول: ما هي المقايضة العملية؟

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

تُقلل رموز الوصول من استخدام كلمات المرور بشكل متكرر، لكن قواعد دورة حياة هذه الرموز تعتمد على نظام المصادقة. تنص مواصفات Matrix على ضرورة التعامل مع رموز الوصول كبيانات اعتماد غير شفافة وإرسالها باستخدام Authorization: Bearerبروتوكول HTTP. كما تدعم الإصدارات الحالية من Matrix انتهاء صلاحية رموز الوصول ورموز التحديث في بعض العمليات. لذا، لا تفترض أن مثالًا مكتوبًا لبيانات اعتماد كلمات المرور يُعالج تلقائيًا التحديث أو الإلغاء أو OAuth.

إذا كانت دورة حياة الرمز المميز، أو تسجيل الدخول الموحد، أو OAuth، أو المصادقة على غرار حساب الخدمة، أساسيةً في عملية النشر لديك، فتحقق من هذه الإمكانية في إصدار Simple-Matrix-Bot-Lib الذي تقوم بتثبيته. إذا لم يوفر الغلاف تحكمًا كافيًا، فإن استخدام matrix-nio مباشرةً هو الخيار الأمثل من الناحية الهندسية.

هل يجب تشغيل البوت على جهاز كمبيوتر محمول، أو خادم افتراضي خاص، أو حاوية، أو Kubernetes؟

بالنسبة للروبوتات الخفيفة غير المشفرة، عادةً ما تكفي آلة افتراضية صغيرة أو حاوية. أما بالنسبة للروبوتات المشفرة، فيُصبح الحفاظ على البيانات شرطًا أساسيًا في التصميم: إذ يُمكن أن يؤدي فقدان مخزن التشفير المحلي إلى تغيير هوية الجهاز وزعزعة الثقة. تُؤكد أمثلة التشفير التام بين الأطراف (E2EE) في matrix-nio على ضرورة الحفاظ على مُعرّف الجهاز ومخزن التشفير بعد إعادة التشغيل.

أعطال الإعداد الشائعة ومعانيها المعتادة

• فشل تسجيل الدخول فورًا: تأكد من عنوان URL الخاص بالخادم الرئيسي وافحصه /_matrix/client/v3/login. قد لا يعمل الخادم الذي لا يُعلن عن تسجيل الدخول بكلمة مرور مع خاصية التشغيل السريع القائمة على كلمة المرور.
• يبدأ البوت ولكنه لا يرى الرسائل أبدًا: تأكد من أن حساب البوت منضم بالفعل إلى الغرفة وأنك تختبر باستخدام حدث نصي عادي.
• يرد الروبوت بشكل متكرر: تأكد من أن المعالج يتجاهل الأحداث المرسلة من الروبوت نفسه.
• الغرف المشفرة غير قابلة للقراءة: تثبيت الحزمة الأساسية غير كافٍ. أضف تبعيات matrix-nio E2EE، وفعّل التشفير وفقًا لإعدادات المكتبة، واحتفظ بمخزن التشفير.
• يُظهر مثال قديم خطأً في واجهة برمجة التطبيقات (API): تحقق من إصدار الحزمة المثبتة لديك. تُشير وثائق Simple-Matrix-Bot-Lib العامة حاليًا إلى أنها غير مُحدثة، لذا قد تتأخر الأمثلة عن إصدار PyPI.

أي مسار يجب أن تختار؟

اختر مكتبة Simple-Matrix-Bot-Lib عندما يكون بوتك مستخدمًا واحدًا لـ Matrix، وتكون أوامرك واضحة ومباشرة، وتُفضّل كتابة كود بايثون مُختصر على التحكم المُعقّد في البروتوكولات. وهي مُناسبة بشكل خاص للنماذج الأولية، وروبوتات الإشعارات، وأدوات غرف الدردشة، وأنظمة التشغيل الآلي الداخلية الصغيرة.

اختر مكتبة matrix-nio مباشرةً عندما تكون متطلبات التشفير، والتحقق من الجهاز، والمصادقة المخصصة، وأنواع الأحداث، وسلوك المزامنة، أو إدارة الرموز المميزة أساسية. ستكتب المزيد من التعليمات البرمجية، لكن مستوى التجريد سيكون أقل، مما يسهل فهمه في العمل المتقدم مع Matrix.

اختر خدمة التطبيقات عندما يكون التكامل عبارة عن امتداد أو جسر أو بوابة لخادم رئيسي، وليس مجرد روبوت مستخدم واحد. صُممت واجهة برمجة تطبيقات خدمة التطبيقات خصيصًا لهذا النموذج المتصل بالخادم، وتتطلب تهيئة الخادم الرئيسي.

بالنسبة لأول روبوت Matrix، !pingيُعدّ المثال البسيط نقطة انطلاق جيدة: إذا استطاع الروبوت المصادقة، والانضمام إلى الغرفة الصحيحة، وتجاهل أحداثه الخاصة، والرد بشكل موثوق، فقد تحققت من صحة المسار الأساسي. أضف التشفير، والتفويض، وواجهات برمجة التطبيقات الخارجية، وأتمتة النشر فقط بعد أن يصبح هذا الأساس مستقرًا.

المراجع الأساسية

• Simple-Matrix-Bot-Lib على PyPI - بيانات تعريف الحزمة الحالية، ومتطلبات بايثون، وسجل الإصدارات، ومثال أساسي.
• وثائق Simple-Matrix-Bot-Lib — مرجع استخدام تاريخي مفيد؛ يحذر الموقع حاليًا من أنها قد تكون قديمة.
• توثيق matrix-nio - مكتبة العميل الأساسية، والتبعيات من طرف إلى طرف، والتخزين، والأمثلة.
• واجهة برمجة تطبيقات Matrix Client-Server - سلوك بروتوكول المصادقة وتسجيل الدخول والرمز المميز والغرفة والحدث الحالي.
• واجهة برمجة تطبيقات Matrix Application Service API — بديل متكامل مع الخادم للجسور وعمليات التكامل الأكبر.