انتقل إلى المحتوى الرئيسي

فهرسة قاعدة الكود في Cursor: كيف تجعلها تعمل بشكل أفضل

فهرسة قاعدة الكود في Cursor هي ما يجعله يبدو "ذكيًا" حول مشروعك. عندما تعمل، تحصل على اقتراحات ذات صلة، وإشارات @ دقيقة، وإجابات تفهم بنيتك الفعلية. عندما لا تعمل، يبدو Cursor أعمى.

يشرح هذا الدليل كيفية عمل الفهرسة وكيفية تحسينها.

كيف يفهم Cursor قاعدة الكود الخاصة بك​

يبني Cursor شيئين في الخلفية:

  1. التضمينات - تمثيلات متجهية لملفات الكود الخاصة بك. عندما تطرح سؤالاً أو تستخدم @، يبحث Cursor في هذه المتجهات لإيجاد الملفات الأكثر صلة دلاليًا.

  2. تحليل AST (شجرة البنية المجردة) - يقوم Cursor بتحليل كودك لفهم الاستيرادات، وتعريفات الدوال، وتسلسلات الهرمية للفئات، والعلاقات بين الملفات.

يعمل هذان النظامان معًا. تجد التضمينات "ما يبدو ذا صلة"، ويحدد تحليل AST "ما هو مرتبط فعليًا."

معلومات

تحدث الفهرسة تلقائيًا عند فتح مشروع. بالنسبة لقواعد الكود الكبيرة، قد تستغرق المسح الأولي بضع دقائق. ستشاهر مؤشر التقدم في شريط الحالة.

الرموز @: الطريقة الصحيحة لاستخدامها​

الرمز @ هو خطك المباشر إلى فهرسة Cursor. استخدمه لسحب سياق محدد إلى الدردشة أو التحرير المضمن.

@file - الإشارة إلى ملف محدد​

@src/utils/auth.ts كيف تعمل التحقق من الرمز؟

هذه هي الطريقة الأكثر موثوقية لضمان رؤية Cursor للملف الدقيق الذي تهتم به. إنها تتجاوز بحث التضمين وتُرفق محتوى الملف الكامل (حتى حدود السياق).

@folder - الإشارة إلى دليل كامل​

@src/components اشرح تسلسل الهرمي للمكونات هنا

مفيد لأسئلة البنية، ولكن احذر — المجلدات الكبيرة يمكن أن تستهلك نافذة السياق بسرعة.

@code - الإشارة إلى رمز محدد​

@code:validateUser ما حالات الحافة التي يتعامل معها هذا؟

يستخدم هذا فهرس AST لإيجاد تعريف الدالة أو الفئة أو المتغير الدقيق. إنه دقيق وفعال في استخدام السياق.

تلميح

فضّل @code: على @file عندما تحتاج فقط إلى دالة واحدة. إنه يوفر مساحة السياق ويقلل الضوضاء.

التحسين للمشاريع الكبيرة​

إذا كان مشروعك يحتوي على آلاف الملفات، قد تفوت الفهرسة الافتراضية بعض الأشياء أو تبدو بطيئة.

التحقق مما هو مُفهرس فعليًا​

افتح إعدادات Cursor > عام > فهرسة قاعدة الكود. ستشاهد:

  • إجمالي الملفات المُفهرسة
  • وقت آخر فهرسة
  • أي ملفات فشلت في التحليل

زيادة صلة السياق​

بالنسبة لمونوريبوس، قد يلتقط Cursor أحيانًا ملفات غير ذات صلة. كن صريحًا في موجهاتك:

انظر فقط إلى @packages/api/src لهذا السؤال. تجاهل كود الواجهة الأمامية.

تقسيم الملفات الضخمة​

يمكن أن تسبب الملفات التي تتجاوز بضعة آلاف من الأسطر مشاكل. قد يفهرس Cursor فقط البداية أو يواجه صعوبة مع التضمينات. إذا كان لديك ملف مساعد بطول 5000 سطر، فكر في تقسيمه.

تجاهل الملفات باستخدام .cursorignore​

لا ينبغي فهرسة كل شيء. الملفات المُنشأة، ومخرجات البناء، والكود التابع لجهات خارجية تضيع مساحة السياق وتلوث نتائج البحث.

أنشئ ملف .cursorignore في جذر مشروعك:

# مخرجات البناء
dist/
build/
.out/

# التبعيات
node_modules/
vendor/

# الملفات المُنشأة
*.generated.ts
*.min.js
coverage/

# ملفات البيانات الكبيرة
*.csv
*.json
warning

يستخدم .cursorignore نفس بناء جملة .gitignore، لكنه ملف منفصل. لا تفترض أن .gitignore كافٍ — لا يحترم Cursor تلقائيًا.

بعد تعديل .cursorignore، أعد تشغيل Cursor أو انتظر دقيقة لإعادة الفهرسة.

عندما تتعطل الفهرسة: استكشاف الأخطاء وإصلاحها​

أحيانًا يبدو بوضوح أن Cursor لا "يرى" كودك. إليك قائمة التحقق:

1. تحقق مما إذا كان الملف مُفهرسًا​

افتح الملف، ثم اسأل:

ما الملف الذي أنا أنظر إليه حاليًا؟

إذا لم يتمكن Cursor من الإجابة، فقد لا يكون الملف في الفهرس.

2. إجبار إعادة الفهرسة​

لوحة الأوامر (Ctrl+Shift+P) → "Cursor: Reindex Codebase"

يبني هذا الفهرس بالكامل من الصفر. يستغرق وقتًا ولكنه يصلح معظم مشاكل الفساد.

3. البحث عن أخطاء التحليل​

في الإعدادات > عام > فهرسة قاعدة الكود، تحقق من الملفات ذات مؤشرات الخطأ الحمراء. لا يتم تحليل هذه الملفات للعلاقات AST.

الأسباب الشائعة:

  • أخطاء بناء الجملة في الملف
  • لغة غير مدعومة (يدعم Cursor حوالي 20 لغة بشكل جيد)
  • ملفات ثنائية أو مُصغرة تم تحديدها بالخطأ ككود مصدري

4. تحقق من أن .cursorignore ليس شديد التشدد​

إذا تجاهلت *.config.* وكان vite.config.ts يحتوي على أسماء مستعارة للمسارات مهمة، فلن يفهم Cursor استيراداتك.

تحسين جودة السياق​

إدخال الملفات الصحيحة في السياق هو نصف المعركة فقط. كيفية استخدام ذلك السياق مهم أيضًا.

كن محددًا في أسئلتك​

سيئ:

كيف يعمل المصادقة؟

جيد:

في @src/auth/middleware.ts، كيف يتعامل التحقق من JWT مع الرموز المنتهية الصلاحية؟

سلسلة سياقك​

إذا أعطى Cursor إجابة جزئية، تابع بإشارات @ أكثر تحديدًا بدلاً من تكرار السؤال بالكامل.

ذكرت تحديد المعدل. @src/middleware/rateLimit.ts - كيف يتم حساب الحد؟

استخدم الملفات الحديثة​

يعطي Cursor أوزانًا أعلى للملفات المفتوحة حديثًا في بحث التضمينات. إذا فتحت ملفًا للتو، فمن المرجح أن تعمل إشارات @ إلى الملفات ذات الصلة دون إشارات صريحة.

تلميح

بالنسبة لإعادة البناء المعقدة، افتح جميع الملفات التي تخطط لتغييرها أولاً. هذا "يحضّر" الفهرس للتعامل معها كملفات ذات صلة.

الملخص​

  • يستخدم Cursor التضمينات + AST لفهم كودك
  • استخدم @file و @folder و @code: للتحكم في السياق صراحةً
  • أنشئ .cursorignore لاستبعاد الضوضاء
  • أعد الفهرسة عندما تشعر أن الأمور معطلة
  • كن محددًا في الموجهات — الفهرس يجد الملفات، ولكنك أنت من يرشد كيفية استخدامها

إعدادات فهرسة قاعدة الكود في Cursor

تعرض لوحة إعدادات فهرسة قاعدة الكود حالة فهرسة مشروعك وأي أخطاء.