PineForge يُشغّل اختباراتك التاريخية لـ Pine Script في CI، ويُفشل البناء إذا انحرفت الصفقات.
لماذا المطابقة في CI
تنحرف الاستراتيجيات مثل أي شيفرة. إعادة تسمية معامل، أو إعادة هيكلة دالة مساعدة، أو تغيير في API لـ Pine v6 لم تلاحظه: أيٌّ من هذه قد يُغيّر الإشارات بصمت دون أن يكسر أي اختبار قائم. ومن دون بوّابة مطابقة في CI، قد يُغيّر إيداعٌ أجريته قبل شهرين قائمة صفقات الأسبوع الماضي، ولن تكتشف ذلك إلا حين تبدو أرقام الربح والخسارة في التداول الحيّ خاطئة.
الانضباط في حفظ قائمة صفقاتك المرجعية في المستودع بجانب شيفرة استراتيجيتك المصدرية هو الانضباط نفسه الذي يجعل البرمجيات موثوقة: تصف المخرج المتوقَّع، ويفشل البناء إذا انحرف عنه المخرج الفعلي. وفي الاختبار التاريخي، المخرج المتوقَّع هو قائمة الصفقات (شمعة الدخول، وشمعة الخروج، والاتجاه، والحجم، وسعر التنفيذ) على مجموعة بيانات تاريخية مثبَّتة.
حين تعمل تلك المقارنة مع كل إيداع، تحصل على آلية ضمان: السلوك التاريخي لاستراتيجيتك يستطيع التحسّن فقط، لا التراجع بالخطأ. تعرف بالضبط أيّ إيداع غيّر المخرج، لأنّ البناء فشل عند ذلك الإيداع. لديك git blame لمنحنى حقوق الملكية.
هذا أهمّ ممّا يدركه معظم المتداولين الكمّيين في البداية. الفجوة بين «اختبرت هذه الاستراتيجية» و«لديّ سجلّ قابل لإعادة الإنتاج ومحفوظ بإصدارات لكل إشارة تاريخية أنتجتها هذه الاستراتيجية» ضخمة. الأولى لقطة شاشة. الثانية مسار تدقيق. وCI هو ما يتيح لك الحفاظ على الثانية دون جهد يدوي مع كل دفع للتغييرات.
يلائم PineForge هذا السياق لأنّ بيئة التشغيل صورة Docker: تعمل أينما يعمل Docker، وتعطي الصفقات نفسها للمدخلات نفسها، وتكتب تقرير JSON يمكنك تحليله بأداة jq. ولا متصفّح، ولا تسجيل دخول، ولا حدّ لمعدّل الطلبات على الاختبار التاريخي نفسه.
مثال GitHub Actions
سير العمل الكامل: اسحب استراتيجيتك من المستودع، وحوّلها إلى C++ بصورة pineforge-release، وشغّل الاختبار التاريخي على ملف OHLCV بصيغة CSV المثبَّت لديك، وحلّل تقرير JSON بأداة jq، وقارن النتيجة بخط الأساس المُودَع لديك، وأسقط البناء إذا تغيّر اتجاه أي صفقة أو شمعتها، أو تجاوز فرق صافي الربح والخسارة عتبتك.
بيئة التشغيل صورة حاوية، فلا مفتاح API عليك إدارته. يكفي أن تُشغّلها بالأمر docker run داخل المهمّة. أنشئ .github/workflows/backtest.yml:
name: Backtest parity
on:
push:
branches: [main, "feat/**"]
pull_request:
jobs:
backtest:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
# Pin the image version so results only change when you change it.
- name: Transpile strategy to C++
run: |
docker run --rm --network=none \
-e PINEFORGE_TRANSPILE_ONLY=1 \
-v "$PWD/strategy.pine":/in/strategy.pine:ro \
ghcr.io/pineforge-4pass/pineforge-release:1.12.0 > strategy.cpp
- name: Run backtest
run: |
docker run --rm --network=none \
-v "$PWD/strategy.cpp":/in/strategy.cpp:ro \
-v "$PWD/data/ohlcv.csv":/in/ohlcv.csv:ro \
ghcr.io/pineforge-4pass/pineforge-release:1.12.0 \
> report.json
- name: Assert parity
run: |
# Every trade keeps its side and its entry and exit bars,
# and net P&L moves by at most THRESHOLD.
BARS='[.trades[] | [.side, .entry_bar_index, .exit_bar_index]]'
ACTUAL=$(jq '.summary.net_pnl' report.json)
BASELINE=$(jq '.summary.net_pnl' baseline/report.json)
DELTA=$(echo "$ACTUAL $BASELINE" | awk '{d=$1-$2; print (d<0)?-d:d}')
THRESHOLD="0.01"
if [ "$(jq -c "$BARS" report.json)" != "$(jq -c "$BARS" baseline/report.json)" ]; then
echo "Parity drift: a trade changed side, entry bar or exit bar"
elif awk "BEGIN{exit !($DELTA > $THRESHOLD)}"; then
echo "Parity drift: net_pnl delta $DELTA exceeds threshold $THRESHOLD"
else
echo "Parity OK - same sides and bars, net_pnl delta $DELTA (threshold $THRESHOLD)"
exit 0
fi
# One trade per line, so diff's line numbers are trade numbers.
TRADE='.trades[] | {side, entry_bar_index, exit_bar_index, entry_price, exit_price, qty, pnl}'
diff <(jq -c "$TRADE" baseline/report.json) <(jq -c "$TRADE" report.json)
exit 1احفظ تقرير الأساس في baseline/report.json في المستودع، مُودَعاً بجانب مصدر الاستراتيجية. حين يُغيّر PR سلوك الاستراتيجية عمداً، يُحدّث المؤلّف الأساس ضمن الـ PR. ذلك الفرق يصبح سجلاً دائماً لما تغيّر ولماذا.
يعمل سير العمل نفسه بالطريقة نفسها على GitLab CI أو Bitbucket Pipelines أو أي مُشغّل يدعم Docker. بدّل صياغة YAML، واحتفظ بأوامر الطرفية كما هي.
رموز الخروج وتأكيد المطابقة
تخرج بيئة تشغيل PineForge بالرمز 0 عند التشغيل النظيف، وبرمز غير صفري عند الإخفاق: 2 لملف إدخال مفقود، و3 لإخفاق التصريف، و4 لإخفاق الاختبار التاريخي، و5 لإخفاق التحويل (Pine غير مدعوم أو خطأ في الصياغة). وتلتقط أنظمة CI هذه الرموز دون أي معالجة خاصة.
التحقّق من النتيجة متروك لسير عملك. يبدو التقرير هكذا (مختصراً):
{
"engine": "pineforge",
...
"summary": {
"total_trades": 3483,
"wins": 1288,
"losses": 2194,
"win_rate_pct": 36.9796,
"net_pnl": 2518.39,
"max_drawdown": -1382.76,
...
},
"trades": [
{
"n": 1,
"side": "long",
"entry_time": 1729402200000,
"exit_time": 1729422000000,
"entry_price": 2640.96,
"exit_price": 2645.15,
"qty": 1.0,
"pnl": 4.19,
"entry_bar_index": 34,
"exit_bar_index": 56,
...
}
],
"metrics": { "all": { "profit_factor": 1.06, ... }, "equity": { "sharpe_tv": ..., ... } },
"equity_curve": [ ... ],
"fingerprint": { "digest": "sha256:...", ... }
}لفحص مطابقة عددي بسيط، قارن summary.net_pnl و summary.total_trades مع الأساس. ويقرأ سير العمل أعلاه مصفوفة trades أيضاً: يجب أن تحافظ كل صفقة على اتجاهها وعلى شمعتَي دخولها وخروجها. وعند إخفاق أي فحص، يقارن سير العمل قائمتَي الصفقات بأداة diff، صفقةً واحدة في كل سطر، فتكون أرقام الأسطر في مخرجات diff هي أرقام الصفقات، ويعرض كل سطر، قبل التغيير وبعده، اتجاه الصفقة، وشمعتَي الدخول والخروج وسعرَيهما، والكمية، والربح والخسارة.
عتبة عملية للحقول العددية: اقبل فروقات الفاصلة العائمة حتى 0.01 (سنت واحد من صافي الربح والخسارة) وأسقط أي شيء أكبر. أمّا الصفقات فلا هامش سماح لها: يُخفق سير العمل أعلاه عند أي تغيّر في الاتجاه أو في entry_bar_index أو exit_bar_index، مهما كان الربح والخسارة. فالصفقة التي تقع على شمعة مختلفة تعني أنّ منطق إشاراتك قد تغيّر.
نمط عملي: حدّث خط الأساس في خطوة منفصلة من سير العمل مشروطة بوسم على طلب الدمج (PR)، ليظهر التغيير المقصود في مراجعة الشيفرة بجوار تغيير Pine الذي تسبّب فيه.