Cursor Worktree متقدّم: Best-of-N و worktrees.json

المنشور السابق 08-worktree-merge غطى worktree التلقائي في Cursor وApply. هذا يتعمق في أمرين: Best-of-N (نفس الـ prompt، نماذج متعددة بالتوازي، ثم اختر واحداً لتطبيقه) وworktrees.json (تثبيت تلقائي للتبعيات، تشغيل migrations، نسخ .env عند إنشاء worktree).

Best-of-N: prompt واحد، نماذج متعددة دفعة واحدة

Best-of-N يعني: ترسل مهمة واحدة، Cursor يشغّل نماذج متعددة في worktrees منفصلة، وتحصل على "بطاقات" متعددة كل واحدة بتغييرات نموذج واحد — اختر واحدة واضغط Apply.

متى تستخدم Best-of-N؟

باختصار: نماذج متعددة تنفّذ نفس المهمة، أنت تختار واحداً — خاصة للمهام الصعبة أو عندما تهتم بالجودة.

كيف تستخدمه

في Cursor، عند بدء Agent اختر "نماذج متعددة" أو خيار Best-of-N (حسب الواجهة الحالية). بعد إرسال الـ prompt سترى بطاقات متعددة؛ انتقل بينها للمقارنة ثم Apply التي تريدها على main.

إن طبّقت أكثر من بطاقة من نفس تشغيل Best-of-N (مثلاً Apply A ثم B)، قد يسأل Cursor: دمج مع حل تعارضات، أو Full Overwrite (استبدال الملف بالكامل).

worktrees.json: تجهيز البيئة عند إنشاء worktree

عند إنشاء Cursor لـ worktree، ينسخ الملفات المتتبعة من المجلد الرئيسي افتراضياً، لكنه لا يثبت التبعيات ولا ينسخ .env ولا يشغّل migrations قاعدة البيانات.
مع .cursor/worktrees.json يمكنك تحديد أوامر تُشغّل بعد إنشاء كل worktree جديد، مثل npm ci، cp .env، npm run db:migrate.

أين يكون الإعداد؟

Cursor يبحث بالترتيب:

1. جذر المشروع: .cursor/worktrees.json
2. مسار الـ worktree

عادة ضعه في جذر المشروع: .cursor/worktrees.json.

ثلاثة مفاتيح إعداد

كل مفتاح يمكن أن يكون:

• سلسلة: مسار لسكربت (نسبي إلى المجلد الذي يحتوي .cursor/worktrees.json)
• مصفوفة: قائمة أوامر shell، تُنفَّذ بالترتيب

مثال: مشروع Node

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

$ROOT_WORKTREE_PATH يوفّره Cursor ويشير إلى المجلد الرئيسي للعمل، مثلاً لنسخ .env.
على Windows قد تحتاج copy أو PowerShell؛ يمكنك التقسيم حسب النظام:

{
  "setup-worktree-unix": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ],
  "setup-worktree-windows": [
    "npm ci",
    "copy %ROOT_WORKTREE_PATH%\\.env .env"
  ]
}

مثال: تشغيل migrations قاعدة البيانات

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env",
    "npm run db:migrate"
  ]
}

أكثر تعقيداً: استخدام ملفات سكربت

لأوامر أو منطق كثير، استخدم سكربتاً وأشر إليه في worktrees.json:

{
  "setup-worktree-unix": "setup-worktree-unix.sh",
  "setup-worktree-windows": "setup-worktree-windows.ps1",
  "setup-worktree": ["echo 'Using generic fallback'"]
}

ضع السكربتات تحت .cursor/، مثلاً .cursor/setup-worktree-unix.sh، مع npm ci، نسخ .env، chmod، migrations، إلخ.
على Windows استخدم .ps1 وفي السكربت استخدم $env:ROOT_WORKTREE_PATH لمسار المجلد الرئيسي.

نصيحة: تجنّب ربط التبعيات بـ symlink في worktree — قد يتعارض مع worktree الرئيسي؛ استخدم npm ci، pnpm، bun، uv، إلخ للتثبيت من جديد.

تنظيف worktree والحدود

Cursor يدير عدد worktrees حتى لا ينفد القرص:

• كل workspace له عدد أقصى من worktrees (مثلاً 20)
• عند تجاوز الحد، الأقل استخداماً مؤخراً يُزال
• التنظيف لكل workspace؛ المستودعات المختلفة لا تؤثر على بعضها

للضبط (إن كانت نسخة Cursor تدعمه)، ابحث عن إعدادات مثل:

• cursor.worktreeMaxCount: أقصى worktrees للاحتفاظ بها
• cursor.worktreeCleanupIntervalHours: كم مرة تشغّل التنظيف

أسماء المفاتيح الدقيقة تعتمد على إعدادات Cursor الحالية.

تصحيح إعداد worktree

إنه بعد إنشاء worktree لم تُثبَّت التبعيات أو لم تُشغَّل migrations، افتح لوحة Output في Cursor، اختر "Worktrees Setup" من القائمة المنسدلة، وراجع الأوامر والأخطاء التي نُفّذت عند الإنشاء — يساعد في تصحيح worktrees.json أو مشاكل السكربتات.

ملخص

• Best-of-N: نفس الـ prompt، نماذج متعددة بالتوازي في worktrees منفصلة؛ قارن وطبّق بطاقة واحدة؛ جيد للمعايير والمهام الصعبة والجودة
• worktrees.json: في .cursor/worktrees.json استخدم setup-worktree / setup-worktree-windows / setup-worktree-unix لتشغيل أوامر أو سكربتات بعد الإنشاء
• استخدم $ROOT_WORKTREE_PATH (Unix) أو %ROOT_WORKTREE_PATH% / $env:ROOT_WORKTREE_PATH (Windows) لنسخ .env إلخ من main
• worktrees لها حد وتنظيف تلقائي؛ التصحيح عبر Output → Worktrees Setup

التالي: 10-headless-scripts — الوضع Headless مع --print و--force وسكربتات تعدّل الملفات فعلياً.