التوثيقDocumentation

التثبيتInstall

1. نزّل المثبّت وشغّله. ما يحتاج صلاحيات مدير.Download the installer and run it. It does not need administrator rights.
2. تحذير SmartScreen: المثبّت مو موقّع رقمياً للحين، فممكن ويندوز يطلع لك «Windows protected your PC». اضغط More info وبعدين Run anyway.SmartScreen warning: the installer is not code-signed yet, so Windows may show "Windows protected your PC". Choose More info, then Run anyway.
3. تحتاج بايثون 3.10 أو أحدث على جهازك. أول ما تشغّل البرنامج تطلع لك قائمة تتأكد من بايثون وتقول لك وش ناقص.You need Python 3.10 or newer on your computer. On first start a checklist detects Python and tells you what is missing.

أول درسYour first lesson

افتح «مسار التعلّم» من الشريط الجانبي، واختر الدرس الأول (أمر /ping)، واختر مجلد ينشأ فيه المشروع. دايماً ينشأ مجلد جديد وما ينكتب فوق أي شي موجود.Open the Learning path from the side bar, pick lesson 1 (the /ping command), and choose a folder to create the project in. A new folder is always created; nothing existing is overwritten.

تطلع لوحة الشرح جنب المحرر: كل خطوة تضيء سطورها في الكود وتشرحها. تنقّل بين الخطوات، وعند آخر خطوة اضغط «أنهيت هذا الدرس». تقدّمك ينحفظ.The explanation panel opens beside the editor: each step lights up its lines and explains them. Move through the steps and press "finish" on the last one. Your progress is saved.

لو عدّلت الكود فوق سطور خطوة ممكن السطور المضاءة ما تطابق الشرح. هذا معروف ومذكور في اللوحة.If you edit code above a step's lines, the highlighted lines may no longer match the explanation. This is known and noted in the panel.

تشغيل بوتك والتوكنRunning your bot and the token

• وثّق في المجلد: لما تفتح مجلد البرنامج يسألك لو تثق فيه، لأن تشغيل الكود يحتاج كذا.Trust the folder: when you open a folder the app asks whether you trust it, because running code requires it.
• تثبيت المتطلبات: زر «تثبيت المتطلبات» ينشئ بيئة .venv للمشروع ويثبّت اللي في requirements.txt.Install requirements: the install button creates a .venv for the project and installs what is in requirements.txt.
• التوكن: حطه في الإعدادات. ينحفظ مشفّر وما تقدر تقراه من النافذة بعدين (كتابة بس). لما تضغط «تشغيل» يوصل لبوتك في المتغير DISCORD_TOKEN، فاقراه في كودك بـ os.environ["DISCORD_TOKEN"] ولا تكتبه في الملف أبداً. السجل يخفيه.The token: put it in Settings. It is stored encrypted and cannot be read back from the window (write-only). When you press Run it is given to your bot in DISCORD_TOKEN, so read it with os.environ["DISCORD_TOKEN"] and never write it in a file. The log hides it.
• تشغيل وإيقاف: الأزرار في الشريط العلوي، أو F5 و Shift+F5. مخرجات البوت تطلع في تبويب «السجل»، ولو فشل التشغيل البرنامج يشرح السبب ويقترح الحل.Run and stop: the buttons in the top bar, or F5 and Shift+F5. Your bot's output appears in the Log tab, and if a run fails the app explains why and suggests a fix.

المحاكيThe simulator

المحاكي يشغّل بوتك زي ما هو على ديسكورد وهمي: بدون شبكة ولا توكن ولا سيرفر. افتح تبويب «المحاكي» في اللوحة السفلية واضغط تشغيل. السيرفر الوهمي فيه قنوات #general و#bot-commands و#mod-log وأشخاص: Alex (مشرف) وSam (عضو) وRoboHelper (بوت) وJordan (يدخل ويطلع)، وبوتك TestBot. بدّل مين يتصرف من الشريط.The simulator runs your bot unchanged against a pretend Discord: no network, no token, no server. Open the Simulator tab in the bottom panel and press start. The pretend server has the channels #general, #bot-commands and #mod-log and these people: Alex (admin), Sam (member), RoboHelper (a bot) and Jordan (joins and leaves), and your bot, TestBot. Switch who is acting from the toolbar.

يحاكي اللي تسويه ديسكورد فعلاً:It copies what Discord really does:

• نية محتوى الرسائل (Message Content): لو ما فعّلتها يوصل نص الرسائل فاضي، وننبّهك على السبب.The Message Content intent: if you do not enable it, message text arrives empty, and you are told why.
• نية الأعضاء (Server Members) لأحداث الدخول والخروج.The Server Members intent for join and leave events.
• أي أمر ما استدعيت له tree.sync() يظهر معطّل مع السبب.A command you never synced with tree.sync() is shown disabled, with the reason.
• قاعدة الثلاث ثواني، ورد واحد لكل تفاعل، والرد الخاص (ephemeral)، وdefer وfollowup.The three-second rule, one answer per interaction, ephemeral replies, defer and followup.
• بعد كل إجراء تضيء في المحرر السطور اللي اشتغلت من ملفاتك، ويطلع زمن الاستجابة.After every action the lines of your own files that ran are lit in the editor, and the response time is shown.

المحاكي تقريب لديسكورد مو بديل عنه. اللي ينجح فيه ممكن يفشل على ديسكورد، فجرّب على السيرفر الحقيقي قبل ما تعتمد عليه. أي محاولة اتصال بديسكورد من داخله تنرفض.The simulator approximates Discord; it does not replace it. What works in it may still fail on Discord, so test on the real thing before you rely on it. Any attempt to reach Discord from inside it is refused.

خريطة البوت والفحوصاتBot map and checks

افتح «خريطة البوت» (Ctrl+Shift+M): تعرض أوامر مشروعك وأحداثه وأزراره ومهامه الدورية، وتضغط على أي بند وينقلك لسطره، وتقترح الصلاحيات اللي يحتاجها كودك. الخريطة تحلّل كودك بأداة بايثون ast بدون ما تشغّله.Open the Bot map (Ctrl+Shift+M): it lists your project's commands, events, buttons and scheduled tasks, clicking an item jumps to its line, and it suggests the permissions your code needs. It reads your code with Python's ast without running it.

والفحوصات تظهر في المحرر مشاكل شائعة، منها: استخدام message.content بدون نية المحتوى، وon_member_join بدون نية الأعضاء، وأوامر ما انعملت لها مزامنة بـ tree.sync()، وtime.sleep داخل دالة async، وتوكن مكتوب في الكود، ونسيان await قبل send_message، والرد مرتين على تفاعل واحد. الفحوصات تنخفي أثناء درس «اعثر على الخطأ» عشان ما تكشف الحل.Checks show common problems in the editor, including: using message.content without the message content intent, on_member_join without the members intent, commands never synced with tree.sync(), time.sleep inside an async function, a token written in the code, a missing await before send_message, and answering one interaction twice. The checks are hidden during the "find the bug" lesson so they do not give the answer away.

رابط الدعوةInvite link

في خريطة البوت بتلقى أداة رابط الدعوة: اكتب معرّف التطبيق (Application ID)، وهو مو سرّ، وبيبني لك الرابط بالنطاقين bot وapplications.commands والصلاحيات اللي يحتاجها كودك. انسخ الرابط وافتحه بنفسك.The Bot map has an invite link tool: type your Application ID (it is not secret) and it builds the link with the bot and applications.commands scopes and the permissions your code needs. Copy the link and open it yourself.

مساعد ذكاء اصطناعي (MCP)AI assistants (MCP)

تقدر تسمح لتطبيق الذكاء الاصطناعي اللي تستخدمه (Claude Code وCursor وغيرهم مما يدعم MCP) يشتغل داخل البرنامج: يشوف مشروعك ويعدّل ملفاته ويشغّله ويقرأ سجله ويجرّب بوتك في المحاكي ويطّلع على الدروس وتقدّمك. ما عندنا سيرفر ولا حساب ولا مفتاح: التطبيق يكلّم برنامجك على جهازك.You can let the AI app you already use (Claude Code, Cursor, or anything that supports MCP) work inside the app: it can see your project, edit its files, run it, read its log, test your bot in the simulator, and look at the lessons and your progress. There is no server of ours, no account and no key: the AI app talks to Musaed Engine on your computer.

1. افتح الإعدادات ← مساعدات الذكاء الاصطناعي (MCP) وفعّل الخيار. هو مقفل من البداية.Open Settings → AI assistants (MCP) and tick the option. It is off by default.
2. انسخ السطر اللي يناسب تطبيقك (Claude Code، أو تطبيق يقبل رابط، أو تطبيق يشغّل أوامر) والصقه فيه.Copy the line that fits your app (Claude Code, an app that takes a URL, or an app that starts commands) and paste it there.
3. خلّ البرنامج مفتوح وقت الشغل. زر «سر جديد» يبطّل السر القديم على طول.Keep the app open while you work. The "New secret" button invalidates the old secret at once.

اللي ما يقدر يسويه: يشوف التوكن أو يقراه أو يغيّره (ما في أداة له أصلاً، والتشغيل اللي يبدأه ما يستلم التوكن)، أو يوثّق في مجلد بدالك، أو يغيّر الإعدادات أو السر، أو يوصل لملفات برا المشروع المفتوح.What it cannot do: see, read or change your token (there is no tool for it, and a run it starts does not receive it), trust a folder for you, change settings or the secret, or reach files outside the open project.

بصراحة: بايثون مو معزول. تطبيق ذكاء اصطناعي يكتب ملف بايثون ويشغّله يشتغل بصلاحيات حسابك، وإخفاء التوكن يغطي التوكن بس. اربط التطبيقات اللي تثق فيها بس، وفعّل الخيار وقت ما تحتاجه.Honestly: Python is not sandboxed. An AI app that writes a Python file and runs it has your account's permissions, and hiding the token covers only the token. Connect only apps you trust, and switch it on when you need it.

اختصارات لوحة المفاتيحKeyboard shortcuts

على ماك استخدم Cmd بدل Ctrl. نفس القائمة موجودة في الإعدادات.On a Mac use Cmd instead of Ctrl. The same list is in Settings.

وفي المحرر تشتغل مفاتيح Monaco المعتادة:In the editor the usual Monaco keys work: Ctrl+Z Ctrl+Y Ctrl+F Ctrl+H Ctrl+G Ctrl+/ Alt+↑/↓ Ctrl+D F1.

التحديثات والخصوصيةUpdates and privacy

البرنامج يبحث عن إصدار أحدث لما تشغّله وكل كم ساعة، وينزّله بهدوء، وبعدين يعرض «أعد التشغيل وحدّث» في الإعدادات (ويثبّته بعد لما تسكّره). تقدر توقف البحث من الإعدادات. البحث ما يرسل شي غير الطلب نفسه.The app looks for a newer version when it starts and every few hours, downloads it quietly, and then shows "Restart and update" in Settings (it also installs when you close the app). You can switch the check off in Settings. The check sends nothing but the request itself.

أرقام الاستخدام المجهولة شغّالة من البداية، وتقدر توقفها وتحذف اللي انرسل من الإعدادات. التفاصيل الكاملة في صفحة الخصوصية.Anonymous usage counts are on by default; you can turn them off and delete what was sent in Settings. Full details on the privacy page.

المثبّت مو موقّع رقمياً للحين، وحمايته الوحيدة عنوان السيرفر (https) وبصمة الملف في latest.yml.The installer is not code-signed yet; its only protection is the server address (https) and the file hash in latest.yml.

حل المشكلاتTroubleshooting

• «ما لقينا بايثون»: نزّل بايثون 3.10 أو أحدث من python.org وافتح البرنامج من جديد. لو عندك أكثر من نسخة اختر وحدة في قائمة التحقق."Python not found": install Python 3.10 or newer from python.org and reopen the app. If you have several, choose one in the checklist.
• البوت ما يتصل: تأكد من التوكن في الإعدادات ومن تفعيل النوايا (intents) في لوحة مطوّري ديسكورد. جرّب المحاكي عشان تفرّق بين مشكلة الكود ومشكلة الاتصال.The bot does not connect: check the token in Settings and that the intents are enabled in the Discord developer portal. Try the simulator to separate a code problem from a connection problem.
• أوامر السلاش ما تظهر في ديسكورد: تأكد إنك تستدعي tree.sync() (الفحوصات تنبّهك لو ناقص)، وإنك دعوت البوت بنطاق applications.commands.Slash commands do not show in Discord: make sure tree.sync() is called (the checks warn if it is missing) and that you invited the bot with the applications.commands scope.
• انقفل البرنامج فجأة: لما تفتحه من جديد يعرض عليك ترجّع تعديلاتك اللي ما انحفظت.The app closed unexpectedly: when you reopen it, it offers to restore your unsaved edits.
• تطبيق الذكاء الاصطناعي ما يتصل: تأكد إن الخيار مفعّل وإن البرنامج مفتوح، وانسخ الأسطر من الإعدادات من جديد لو غيّرت السر. خطأ 401 معناه إن السر تغيّر.The AI app does not connect: check that the option is on and the app is open, and copy the lines from Settings again if you changed the secret. A 401 error means the secret changed.