الصفحاتالمرجع · 28 / 29

مرجع وثائق QuantCraft

يأتي QuantCraft بنوعين متكاملين من التوثيق: مواضيع داخل التطبيق تقرؤها داخل بيئة التطوير، وملفات Markdown مرجعية للاستراتيجيات مرفقة بالمنتج لتفاصيل أعمق عن الواجهة البرمجية. وتصف معًا كيفية كتابة الاستراتيجيات وتشغيل الاختبارات الرجعية واستخدام بيئة التطوير. تعكس هذه الوثائق على الويب كثيرًا من تلك المواضيع — ابدأ بـالمقدمة أو البدء.

أين تقرأ الوثائق في التطبيق

افتح QuantCraft من التطبيق الرئيسي.
وسّع الشريط الجانبي الأيمن (إن كان مطويًّا).
افتح علامة التبويب Documentation (بجانب QuantCraft AI).

ستصل إلى فهرس قابل للبحث للمواضيع. اكتب في مربع البحث للتصفية بحسب العنوان أو الملخّص أو الكلمات المفتاحية المضمّنة (مثل on_finish وPaperAccount وchart_indicator_series).

اضغط على بطاقة موضوع لفتح المقال الكامل. واستخدم Back للعودة إلى الفهرس.

فهرس المواضيع (داخل التطبيق)

تُجمَّع المواضيع في قسمين، يطابقان الشريط الجانبي Documentation.

Getting started

الموضوع	ما ستتعلمه
البيانات الأساسية	بيانات القوائم المالية والجداول المفهرسة بالتاريخ وكيفية محاذاة البيانات الأساسية للأعمدة وكيفية قراءتها في استراتيجية.
عوامل فاما-فرينش	عوائد عوامل FF3/FF5 الشهرية العالمية عبر `fama_french.qc` (Premium؛ دون وسيط استدعاء).
بيانات التقويم	توزيعات الأرباح والتجزئات ومواعيد الأرباح والإيداعات (وسيط الاستدعاء `calendar`، للاختبارات الرجعية فقط) والإجراءات المؤسسية في المحاكاة.
الحساب	`PaperAccount`: الأرصدة والمراكز والأوامر والربح/الخسارة ومقاييس الأداء المتاحة أثناء الاختبار الرجعي.
دورة الحياة	ترتيب دوال الاستدعاء: `on_init` و`on_bar` و`on_tick` و`on_timer` الاختيارية (للتشغيل الأمامي فقط) و`on_finish` — بما في ذلك أساسيات الرموز المتعددة و`on_finish(bars)` الاختياري بالسلسلة الكاملة.

Reference

الموضوع	ما ستتعلمه
معاملات الإدخال	التصريح بـ `quantcraft.inputs.params` والأنواع وكيفية تقديم القيم من نوافذ التشغيل (الاختبار الرجعي والأمامي الجماعي والأمامي على الرسم البياني).
إعدادات التشغيل المسبقة (.qcs)	حفظ إعدادات نوافذ التشغيل وإعادة تحميلها كملفات `.qcs` في مساحة عملك.
تصحيح الأخطاء	Debug Run مقابل Debug Test ونقاط التوقف والتنفيذ خطوة بخطوة ومكدّس الاستدعاءات والمتغيرات.
التداول الآلي (AutoTrading)	عمليات تشغيل أمامية محلية للخوارزميات والوكلاء وNew Bulk / Agent Bulk Run ومراقبة المهام الجماعية / على الرسم البياني.
QuantCloud	عمليات تشغيل أمامية جماعية على منفِّذات سحابية حين يكون حاسوبك مطفأً (دليل مستخدم سطح المكتب).
الوكلاء	وكلاء Trading وTest وOptimization؛ بناء رسوم العقد يدويًا أو بـAI Builder؛ المعاملات المكشوفة والتحسين؛ اختبار رجعي على حساب ورقي، وأمامي / حقيقي عبر الوسيط المتصل؛ استيراد / تصدير `.qca`.
QuantCraft AI	محادثة الذكاء الاصطناعي في بيئة التطوير وربط نموذج (AI → API Providers) وأدوات الماسح وAI Tools وخوادم MCP وعقد AI Prompt في الوكلاء.
أدوات QuantCraft	أدوات سوق مدمجة للقراءة فقط يمكن للذكاء الاصطناعي استدعاؤها (المحادثة وعقد AI Prompt ووكلاء Test / Optimization).
OHLCV	شكل العمود (`OhlcvBarView`) والمحمِّلات (الوسيط المتصل مقابل B2) والنطاقات الزمنية واستخدام بيانات الأعمدة في دوال الاستدعاء.
سلاسل المؤشرات	بناء تراكبات `chart_indicator_series` (خطوط ومدرّجات ولوحات) على رسوم نتائج الاختبار الرجعي.

أي بطاقة في الفهرس لا تفتح مقالًا كاملًا بعد تحمل وسم Soon في الواجهة.

كيف ترتبط الوثائق المدمجة بسير عملك

استخدم هذه الخريطة السريعة عندما تكون منشغلًا بشيء ما في بيئة التطوير:

تريد أن…	ابدأ بـ
تضبط الرموز والتواريخ والبيانات الأساسية وتشغّل محاكاة	دورة حياة الاستراتيجية + OHLCV؛ ثم تشغيل الشيفرة (Test) ونتائج الاختبار.
تحدد أحجام المراكز أو الإيقافات أو تقرأ شارب / التراجع	نموذج الحساب
تتيح للمستخدمين ضبط العتبات دون تحرير الشيفرة	معاملات الإدخال
ترسم سلاسل مخصّصة على رسم حقوق الملكية	سلاسل المؤشرات
تمزج الأسعار مع الإيداعات / القوائم المالية	البيانات الأساسية
تمزج الأسعار مع عوائد العوامل العالمية	عوامل فاما-فرينش
تتفاعل مع التوزيعات / التجزئات أو تحتاط حول مواعيد الأرباح	بيانات التقويم — وسيط الاستدعاء `calendar` و`days_to_earnings` والإجراءات المؤسسية
تجمع بين الأطر الزمنية الأساسية والثانوية	بيانات OHLCV والأعمدة — Additional timeframes + `rt.get_bar`
تعيد استخدام إعدادات نافذة اختبار رجعي أو أمامي	إعدادات التشغيل المسبقة (.qcs)
تتوقف عند سطر وتفحص المتغيرات	تصحيح الأخطاء
تشغّل الخوارزميات أماميًا على جهازك	التداول الآلي (AutoTrading)
تشغّل الخوارزميات على منفِّذ بعيد	QuantCloud
تبني أتمتة من عقد مرئية	الوكلاء

كُتبت المقالات المدمجة لـمؤلفي الاستراتيجيات ومستخدمي بيئة التطوير. ولا تغطي هذه الوثائق العامة إعداد خادم QuantCloud للمشغّلين.

استيرادات الاستراتيجية

اكتب كل استيراد بصيغة quantcraft.*، بأسماء وحدات بلا لاحقة (مثل quantcraft.inputs لا quantcraft.inputs_module). ما زالت المسارات الأقدم ide.* و**quantcraft.*_module** تعمل، وكذلك quantcraft.backtest.* — اسم الحزمة السابق قبل إعادة تسميتها إلى quantcraft.process.* — فتستمر الاستراتيجيات الحالية بالعمل دون تغيير — لكن لا تكتب شيفرة جديدة عليها.

الاستيراد الأساسي	مسارات أقدم قد تراها	يُستخدم من أجل
`quantcraft.process.runtime`	`quantcraft.backtest.runtime`, `ide.backtest.runtime`	`account` و`chart_indicators` و`qc_fundamentals` و`qc_fama_french` و`qc_calendar` و`get_bar` (عبر `import quantcraft.runtime as rt`)
`quantcraft` (`Timeframe`)	—	تعداد الأطر الزمنية لـ `rt.get_bar(Timeframe.DAILY, shift=1)` (الإطار الأساسي والإضافية)
`quantcraft.runtime`	—	الوحدة نفسها كـ `quantcraft.process.runtime` بكتابة أقصر — `import quantcraft.runtime as rt` لـ `rt.get_bar` ومقابض وقت التشغيل
`quantcraft.timeframes`	—	التعداد `Timeframe` (وأيضًا `from quantcraft import Timeframe`)
`quantcraft.inputs`	`ide.inputs_module`, `quantcraft.inputs_module`	`params` من نوافذ التشغيل
`quantcraft.process.ohlcv`	`quantcraft.backtest.ohlcv`, `ide.backtest.ohlcv_module`, `quantcraft.backtest.ohlcv_module`	`QcOhlcv` و`qc_ohlcv`
`quantcraft.fundamentals`	`ide.fundamentals_module`, `quantcraft.fundamentals_module`	`QcFundamentals`
`quantcraft.fama_french`	`ide.factors_module`	`QcFamaFrench` و`fama_french.qc`
`quantcraft.account`	`quantcraft.process.account`, `quantcraft.backtest.account`, `ide.account_module`, `quantcraft.account_module`	`PaperAccount` و`OpenPosition`
`quantcraft.process.indicator_series`	`quantcraft.backtest.indicator_series`, `ide.backtest.indicator_series_module`, `quantcraft.backtest.indicator_series_module`	`ChartIndicatorSeries` و`coerce_chart_time`
`quantcraft.calendar_module`	—	`BacktestCalendar` — يُمرَّر كوسيط الاستدعاء `calendar` عند تفعيل بيانات التقويم؛ راجع بيانات التقويم. الوحدة الوحيدة التي تحتفظ بلاحقة `_module` — فلا يوجد `quantcraft.calendar`.
`quantcraft.cross_sectional`	—	الترتيب / الدرجات المعيارية على مستوى المجموعة كلها — راجع أدناه
`quantcraft.process`	—	`clamp_indicator_period`

وتعمل أيضًا إعادات التصدير الأقصر: quantcraft.indicator_series وquantcraft.account. أما لفاما-فرينش فضّل from quantcraft import fama_french واقرأ fama_french.qc داخل دوال الاستدعاء.

الوصول إلى صفوف فاما-فرينش: dataset["rows"] قاموس YYYYMM ← قيم لا قائمة. استخدم .row(...) أو .rows_chronological(...)؛ و**latest_row(...)** في عمليات التشغيل الأمامية فقط (ففي الاختبار الرجعي هو استشراف — راجع عوامل فاما-فرينش). ولا تستخدم rows[0] / rows[-1].

لا تستخدم حزمًا داخلية مثل quantcraft.b2.* (طبقة تنزيل البيانات خلف محمِّلات الأسعار والبيانات الأساسية) ولا quantcraft.ai_assistant.* في نصوص الاستراتيجيات — فهذه مساعدات داخلية لا واجهة الاستراتيجية. ولا تخلط بين quantcraft.process.ohlcv (واجهة OHLCV للاستراتيجية) وquantcraft.b2.ohlcv (طبقة البيانات الداخلية).

مساعدات المقطع العرضي

يتضمن quantcraft.cross_sectional مساعدات متجهية لمقارنة رموز كثيرة دفعة واحدة (numpy): stack_field وlatest_return وlatest_sma وlatest_std وlatest_rsi وrank وzscore وdemean وwinsorize، إضافةً إلى ColumnarBarArena.

import quantcraft.runtime as rt
import quantcraft.cross_sectional as xs

def on_bar(bar_index, bar, symbol=None):
    syms, close = xs.stack_field(rt.qc_ohlcv_by_symbol, "close")
    momentum = xs.latest_return(close, 20)       # per-symbol 20-bar return
    score = dict(zip(syms, xs.rank(momentum)))   # rank in [0, 1]

عمليات التشغيل الأمامية / الجماعية فقط كما هو مكتوب. في الاختبار الرجعي يحتفظ rt.qc_ohlcv_by_symbol بـالنطاق المحمَّل كاملًا لكل رمز، فيعني "الأحدث" هناك آخر عمود في الاختبار — أي استشرافًا. في الاختبار الرجعي اجمع إغلاقات كل رمز من bar الخاص به أثناء مرور التشغيل ومرّر تلك المصفوفات إلى المساعدات.

مقابض الوحدات مقابل الأسماء المستوردة

quantcraft.process.runtime و**quantcraft.fama_french** اسمان بديلان لوحدتين، لذا فالوصول بالسمات يقرأ القيمة الحيّة للجلسة:

import quantcraft.process.runtime as rt
import quantcraft.fama_french as ff

rt.account            # this run's PaperAccount
rt.chart_indicators   # this run's collector
ff.qc                 # this run's Fama-French loader

وكل ما عدا ذلك يعيد تصدير الأسماء بالقيمة، لذا فإن from ... import <name> يربط لقطة أُخذت وقت الاستيراد.

بالنسبة إلى المقابض التي يسندها المحرك في كل تشغيل، يعيد المحرك ربط تلك الأسماء في ملف الخوارزمية الجذري بعد تحميله، فصيغة from ... import آمنة هناك — للأسماء التي يعيد ربطها:

الاختبار الرجعي / Debug Test: account وchart_indicators وget_bar وqc_ohlcv وqc_ohlcv_by_symbol وqc_ohlcv_by_tf وqc_fundamentals وqc_fama_french وqc_calendar.
عمليات التشغيل الأمامية: account وqc_fundamentals وqc_fama_french فقط — لذا استخدم rt.<name> لـ chart_indicators ومقابض OHLCV هناك.

# Fine in the root algo file — the engine rebinds these after loading your script
from quantcraft.process.runtime import account, qc_fundamentals, qc_fama_french

أما الوحدة المساعدة المقسّمة فمختلفة: إذ تبقى مخزّنة مؤقتًا في sys.modules عبر عمليات التشغيل في العملية نفسها، فيحتفظ الاسم المستورد بمقبض الجلسة التي كانت حالية عند أول استيراد — وهو قديم للتشغيل التالي (أمامي / جماعي). في الوحدات المساعدة استورد الوحدة واستخدم الوصول بالسمات:

# helpers/signals.py — always read through the module
import quantcraft.process.runtime as rt

def record(sym, t, value):
    rt.chart_indicators.add(...)   # live handle for *this* run

from quantcraft.inputs import params هو الاستثناء: فـparams كائن حيّ واحد تتغير قيمه في كل تشغيل، لذا فصيغة from آمنة في كل مكان — راجع معاملات الإدخال.

مرجع الاستراتيجيات المرفق (Markdown)

لسلوك الوحدات على مستوى السطر وعقود دوال الاستدعاء وتفاصيل المحرك، يتضمن المنتج أيضًا ملفات Markdown ضمن حزمة quantcraft-dev (مفهوميًا: "مرجع استراتيجيات QuantCraft"). وفيما يلي جدول محتويات نموذجي:

المستند	التركيز
IMPORTS	مسارات الاستيراد `quantcraft.` (بما فيها `quantcraft.cross_sectional`) والمسارات الأقدم `ide.` / `quantcraft.backtest.*` التي ما زالت تُحسم للنصوص الحالية، ومقابض الوحدات مقابل الأسماء المستوردة
BACKTEST_README	نظرة عامة على حزمة الاختبار الرجعي
BACKTEST_ENGINE	تنسيق المحرك والإعدادات ودوال الاستدعاء وحمولة النتيجة
BACKTEST_MODULE	نقطة دخول WebSocket للاختبار الرجعي من بيئة التطوير
IDE_BACKTEST_RUNNER	المشغّل بعملية فرعية بجانب خدمة Python
RUNTIME	المتغيرات العامة لوقت التشغيل: `account` و`chart_indicators` و`get_bar` / الأطر الأساسية والإضافية؛ المقابض لكل جلسة والوصول `rt.<name>`
INPUTS_MODULE	ربط `params` من نوافذ التشغيل
RUN_CONFIG_QCS	صيغة إعدادات التشغيل المسبقة `.qcs` والتعيين عبر النوافذ
ACCOUNT_MODULE	واجهة تداول `PaperAccount` والعمولة / الانزلاق
OHLCV_MODULE	محمِّلات `QcOhlcv` و`bar` في دوال الاستدعاء والأطر الزمنية الثانوية
INDICATOR_SERIES_MODULE	حمولة سلاسل الرسم والمساعدات
FUNDAMENTALS_MODULE	شكل JSON للبيانات الأساسية وواجهتها
FAMA_FRENCH	عوامل فاما-فرينش العالمية / `fama_french.qc` / قاموس صفوف `YYYYMM`
CALENDAR_MODULE	توزيعات الأرباح والتجزئات ومواعيد الأرباح (وسيط الاستدعاء `calendar`)؛ والإجراءات المؤسسية في المحاكاة — صفحة المستخدم هي بيانات التقويم
DEBUGGING	Debug Run / Debug Test ونقاط التوقف ومكدّس الاستدعاءات والمتغيرات — صفحة المستخدم هي تصحيح الأخطاء
AUTO_TRADING	عمليات التشغيل الأمامية المحلية (خوارزمية + وكيل جماعي) ونافذة New Run — صفحة المستخدم هي التداول الآلي (AutoTrading)
QUANT_CLOUD	مهام التشغيل الأمامي الجماعي للخوارزميات على منفِّذات سحابية — صفحة المستخدم هي QuantCloud
AGENTS	وكلاء Trading / Test / Optimization وAI Builder والاختبار الورقي مقابل الأمامي/الحقيقي عبر الوسيط المتصل — صفحة المستخدم هي الوكلاء
AI_ASSISTANT	محادثة الذكاء الاصطناعي في بيئة التطوير ومزوّدو النماذج وأدوات الماسح وAI Tools وخوادم MCP — صفحة المستخدم هي QuantCraft AI
QUANTCRAFT_TOOLS	أدوات سوق مدمجة للقراءة فقط للذكاء الاصطناعي — صفحة المستخدم هي أدوات QuantCraft
SCREENER	مرشّحات بلا برمجة وبـ Python وإعدادات مسبقة وعمليات تشغيل يقودها الماسح — صفحة المستخدم هي الماسح (Screener)
POSSIBLE_ERRORS	الأخطاء الشائعة وحلولها — صفحة المستخدم هي الأخطاء المحتملة

هذه الملفات موجَّهة لـمؤلفي الاستراتيجيات الذين يحتاجون إلى الأسماء والعقود بدقة. وتُضمَّن المواضيع المتقدمة مثل BACKTEST_MODULE (نقطة دخول WebSocket للاختبار الرجعي) وIDE_BACKTEST_RUNNER (المشغّل بعملية فرعية) في الحزمة للمساهمين لكنها ليست مسارات المستخدم الأساسية. ويأتي QuantCraft AI في بيئة التطوير محمَّلًا مسبقًا بهذه المادة لتبقى الإجابات متوافقة مع الوحدات المشحونة.

أسطح مساعدة أخرى في QuantCraft

هذه ليست علامة تبويب Documentation لكنها جزء من "منظومة المراجع" نفسها للمستخدمين:

QuantCraft AI — اطرح أسئلة بلغة طبيعية؛ ويمكن للإجابات الاستشهاد بمدوّنة التطوير نفسها. اربط نموذجًا من AI → API Providers (مفتاحك الخاص، أو QuantCraft Premium / الخيارات المستضافة).
الاستيراد والتصدير — انقل ملفات .py (وما يتصل بها) بين القرص ومساحة العمل.
نتائج الاختبار — رسم حقوق الملكية والمقاييس والصفقات وتصدير HTML بعد الاختبار الرجعي.

نصائح البحث

فضّل الرموز القصيرة التي تظهر في الشيفرة: on_finish وparams وchart_indicator_series وcoerce_chart_time وpane_id.
إن لم يطابق شيء فامسح البحث — إذ يسرد الفهرس كل موضوع بحسب القسم.
الأفكار العابرة للمواضيع (مثل "البيانات الأساسية + on_bar") تحتاج غالبًا إلى مقالين: افتح البيانات الأساسية لشكل البيانات، ثم دورة حياة الاستراتيجية لمعرفة متى تتاح.

سجل المستند

تُصان الوثائق المدمجة جنبًا إلى جنب مع وقت تشغيل الاستراتيجيات. وعندما تتغير وحدات Python أو حمولة الاختبار الرجعي، تُحدَّث المواضيع المدمجة وملفات Markdown المرفقة معًا لتبقى الأمثلة والأسماء متزامنة. وتُكتب أمثلة استيراد الاستراتيجيات بمسارات quantcraft.* بلا لاحقة في كل مكان؛ أما المسارات الأقدم ide.*_module و**quantcraft.*_module** فتُوثَّق فقط كعون على قراءة النصوص الحالية.

10 دقائق للقراءةاقترح تعديلًا ↗