تشغيل الشيفرة

توفّر بيئة تطوير QuantCraft ثلاث طرق لتنفيذ الملف الذي تحرّره (مساحة العمل)، لكل منها غرض محدد:

توجد الأزرار الثلاثة في أعلى يمين منطقة المحرر عند فتح ملف. Run وTest متاحان دائمًا لأي ملف؛ أما Compile فيظهر لملفات .py المطابقة لقالب استراتيجية QuantCraft.

---

التشغيل السريع (زر Run)

زر Run هو أبسط طريقة لتنفيذ الشيفرة: فهو ينفّذ الملف الذي تنظر إليه من الأعلى إلى الأسفل، مثل python myfile.py العادي.

كيفية التشغيل

1. افتح في المحرر الملف الذي تريد تشغيله (لا يلزم أن يكون استراتيجية — أي ملف .py يصلح).
2. انقر Run في شريط الأدوات فوق المحرر.
3. في المرة الأولى في كل جلسة سترى مربع حوار Disclaimer (انظر أدناه). انقر I understand للمتابعة.
4. تُبَثّ المخرجات إلى لوحة المخرجات أسفل مساحة العمل فور إنتاجها.

أثناء تشغيل الشيفرة، يكون زرّا Run وTest معطّلين لمنع تداخل عمليات التشغيل.

ما الذي يُنفَّذ

• الملف النشط هو نقطة الدخول.
• تتاح كل الملفات والمجلدات الأخرى في مساحة عملك لتتمكن من import منها داخل الملف الجاري تشغيله (تعمل مجلدات مساحة العمل مثل حزم Python — from my_folder import my_module).
• تعمل الشيفرة في بيئة Python الخاصة ببيئة تطوير QuantCraft (التبعيات)، فأي حزمة مدرجة في Packages (بما فيها ما أضفته) يمكن استيرادها.

ما الذي يعمل داخل Run

• print(...) وكل ما يُكتب إلى stdout / stderr يظهر مباشرةً في لوحة المخرجات (وتُعرض الأخطاء باللون الأحمر).
• تُعرض أشكال Matplotlib (المخططات بأسلوب plt.show()) كصور مضمّنة في لوحة المخرجات.
• تُعرض أشكال Plotly كمخططات تفاعلية مضمّنة.
• يمكن للنص البرمجي استخدام المكتبة القياسية والحزم الخارجية من بيئتك ووحدات مساحة العمل الخاصة بك.

متى لا تستخدم Run

ينفّذ Run شيفرة Python خالصة — فهو لا يشغّل محرك الاختبار الرجعي في QuantCraft. وإذا كان ملفك يعتمد على دوال استراتيجية on_init وon_bar وon_finish، فلن يستدعيها Run؛ استخدم Test بدلًا منه (دورة حياة الاستراتيجية).

---

المخرجات

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

ما ستراه

• أسطر سجل بطابع زمني لكل ما يُكتب إلى stdout.
• أخطاء بالأحمر لكل ما يُكتب إلى stderr، إضافةً إلى شارة عدد الأخطاء الصغيرة في ترويسة اللوحة.
• مخططات مضمّنة — صور Matplotlib ومخططات Plotly التفاعلية.
• (no output) إذا نُفّذ النص بنجاح لكنه لم يطبع شيئًا.
• (exit code N) إذا انتهى النص برمز خروج غير صفري دون كتابة خطأ.

العمل مع اللوحة

• انقر عنوان Output (أو السهم المجاور له) لطيّ / توسيع اللوحة.
• تتمرّر اللوحة تلقائيًا إلى أحدث مخرجات كلما وصلت أسطر جديدة.
• اللوحة مشتركة بين الملفات — في المرة القادمة التي تشغّل فيها Run أو Test تُمسح المخرجات السابقة لتبدأ من جديد.
• استخدم الفاصل فوق اللوحة لتغيير حجمها وما تشغله من الشاشة.

يكتب Run وTest كلاهما إلى لوحة المخرجات نفسها؛ ويعرض Test بالإضافة إلى ذلك نتائج منظّمة في عرض Test Results بمنطقة المحرر.

---

إخلاءات المسؤولية

ينفّذ QuantCraft شيفرة Python على جهازك باستخدام حساب المستخدم الخاص بك. قبل أول تشغيل لك في الجلسة سترى مربع حوار Disclaimer يشرح ذلك بلغة بسيطة.

ما الذي يغطيه التنبيه

• تعمل الشيفرة دون عزل (sandbox) — يمكن للنصوص البرمجية قراءة الملفات التي يمكنك الوصول إليها وكتابتها واستخدام الشبكة وتشغيل برامج أخرى (مثلًا عبر subprocess).
• هذا مناسب لـالتطوير المحلي بشيفرة تثق بها.
• أنت المسؤول عن الشيفرة التي تشغّلها والحزم التي تثبّتها والبيانات التي ترسلها إلى خدمات خارجية.

الطريقتان اللتان يظهر بهما

• تنبيه مسار Run — يظهر عند نقر Run (أو Test). ويتضمن خانة «Don't show this again». إذا حدّدتها قبل نقر I understand، فستتخطى عمليات Run وTest المستقبلية مربع الحوار وتُنفَّذ فورًا.
• التنبيه المرجعي — يمكن الوصول إليه في أي وقت أيضًا من زر Disclaimer في ترويسة لوحة المخرجات. هذه النسخة للقراءة فقط — وإغلاقها لا يغيّر إعداداتك.

إذا غيّرت رأيك لاحقًا وأردت عودة مربع الحوار، فامسح بيانات موقع QuantCraft في المتصفح/التطبيق (أو استخدم مسار إعادة ضبط التطبيق المعتاد) وسيظهر التنبيه مجددًا عند تشغيل Run التالي.

---

Run أم Test أم Compile — متى تستخدم أيًّا منها

استخدم هذا الدليل القصير لاختيار الإجراء المناسب.

استخدم Run عندما…

• تريد تنفيذ نص برمجي بسرعة ورؤية ما يطبعه أو يرسمه.
• تقوم بتجريب دوال مساعدة أو استكشاف بيانات أو التحقق من أن عملية حسابية تفعل ما تتوقعه.
• تكتب نصًا مساعدًا صغيرًا ليس استراتيجية على الإطلاق.
• تريد طباعة قيم وسيطة أثناء التطوير.

Run هو أسرع حلقة تغذية راجعة. فهو لا يحاكي التداول ولا يحسب مقاييس الأداء ولا يحتاج إلى قالب استراتيجية.

استخدم Test عندما…

• تريد إجراء اختبار رجعي لاستراتيجية على بيانات تاريخية.
• يتبع ملفك قالب استراتيجية QuantCraft (مع on_init وon_bar وon_finish).
• تحتاج إلى نتائج منظّمة: منحنى حقوق الملكية ومقاييس الأداء وسجل الصفقات والمخططات.
• تريد مسح المعاملات (تحسين بالقوة الغاشمة) أو تشغيل تحسين جيني للبحث عن تركيبات جيدة من المعاملات.

عند نقر Test يُفتح مربع حوار Backtest لتختار الرمز والنطاق الزمني والمعاملات (واختياريًا) إعدادات التحسين. يشغّل Test استراتيجيتك عبر عملية فرعية للاختبار الرجعي (وليس المسار نفسه لـ Run البسيط) — إذ ترسل بيئة التطوير الإعدادات عبر WebSocket وتبثّ التقدّم إلى لوحة المخرجات. ثم تظهر النتائج في عرض Test Results بالمحرر. ويمكنك إيقاف اختبار طويل في أي وقت بـ Stop.

استخدم Compile عندما…

• يكون لديك استراتيجية منتهية تريد ربطها بمخطط (لتعمل على بيانات حية أو مسجّلة خارج بيئة التطوير).
• يكون الملف استراتيجية .py تتضمن دوال الاستدعاء المطلوبة (on_init وon_bar وon_finish).

يجمع Compile الاستراتيجية مع وحدات مساحة العمل التي تستوردها وحزم بيئة التطوير التي تحتاجها في ملف حزمة قابلة للتشغيل واحد (*.qcraft.json) تحفظه على القرص عبر مربع حوار الملفات في النظام. لا تعمل الحزمة بمفردها — بل هي مخصّصة لـالربط بمخطط لتشغيل استراتيجية من هناك.

إذا كان زر Compile معطّلًا، فهذا يعني أن الملف ينقصه أحد دوال الاستراتيجية المطلوبة. أضف def on_init(): وdef on_bar(...): وdef on_finish(): (أو استخدم قالب الاستراتيجية الافتراضي) لتفعيله.

---

نصائح

• إيقاف تشغيل طويل — عندما يكون اختبار رجعي قيد التنفيذ، يظهر زر Stop بجوار عناصر Run/Test. ويمكن إنهاء نصوص Run البسيطة بإغلاق الملف أو مقاطعة الخادم الخلفي.
• أين ذهبت مخرجاتي؟ — لوحة المخرجات مشتركة بين Run وTest. إذا بدّلت بينهما، فمرّر لأعلى في اللوحة؛ إذ تكون مخرجات آخر تشغيل في الأسفل.
• استيراد الملفات الأخرى في مساحة العمل يعمل مع Run أيضًا — يرى Run وTest كلاهما مساحة عملك كشجرة حزم، لذا تتصرف عبارات import نفسها بشكل متسق في كليهما.
• اضغط Compile قبل المشاركة — إذا أردت استخدام الاستراتيجية على مخطط، فنفّذ Compile دائمًا بعد آخر تعديل لك لتعكس الحزمة أحدث شيفرتك.