استكشاف أخطاء Context Sync وتحسينه في Cursor

Context Sync هو الآلية التي يستخدمها Cursor لفهرسة قاعدة الشفرة وتوفير سياق ذي صلة لمساعد الذكاء الاصطناعي. عندما يعمل بشكل صحيح، فإنه يتيح اقتراحات شفرة دقيقة، ومراجع ملفات دقيقة، واستجابات ذكية مدركة للمشروع. عندما يتعطل، قد تواجه اقتراحات قديمة، أو مراجع ملفات مفقودة، أو الخطأ المخيف "Context Sync is not running". يأخذك هذا الدليل عبر التشخيص والإصلاح والتحسين.

فهم Context Sync

يعمل Context Sync في الخلفية، حيث يقوم بمسح ملفات مشروعك باستمرار وبناء فهرس قابل للبحث. يتيح هذا الفهرس للذكاء الاصطناعي فهم بنية مشروعك، والعثور على الملفات ذات الصلة، وتقديم استجابات دقيقة من حيث السياق.

كيف تعمل الفهرسة

تتبع عملية الفهرسة هذه المراحل:

1. الاكتشاف: يقوم Cursor بمسح مساحة العمل بحثاً عن جميع الملفات، مع مراعاة .gitignore وقواعد الاستبعاد المخصصة
2. التحليل: يتم تحليل كل ملف لاستخراج الرموز والواردات والبيانات الوصفية الهيكلية
3. التضمين: يتم تحويل أجزاء الشفرة إلى تضمينات متجهة للبحث الدلالي
4. التخزين: يتم تخزين الفهرس محلياً ومزامنته اختيارياً مع السحابة
5. التحديثات: تؤدي تغييرات الملفات إلى تحديثات تزايدية للفهرس

تلميح

قد تستغرق فهرسة قاعدة شفرة كبيرة لأول مرة عدة دقائق. خلال هذا الوقت، قد تلاحظ استخداماً أعلى لوحدة المعالجة المركزية واستجابات أبطأ للذكاء الاصطناعي. هذا طبيعي وسينحل بمجرد اكتمال الفهرس الأولي.

إدارة نافذة السياق

تحدد نافذة السياق مقدار المعلومات التي يمكن للذكاء الاصطناعي العمل معها في وقت واحد. يدير Cursor ذلك تلقائياً، لكن فهم الحدود يساعدك في تحسين سير عملك:

الخطة	نافذة السياق	الحد الأقصى للملفات المفهرسة
Free	25,000 رمز	500 ملف
Pro	200,000 رمز	5,000 ملف
Business	200,000 رمز	25,000 ملف
Enterprise	مخصص	مخصص

تشخيص مشكلات Context Sync

التحقق من حالة المزامنة

الخطوة الأولى في استكشاف الأخطاء هي التحقق من حالة Context Sync الحالية. يوفر Cursor عدة طرق للقيام بذلك:

الطريقة 1: شريط الحالة

انظر إلى الزاوية السفلية اليمنى من نافذة Cursor. يشير الرمز الدوار إلى مزامنة نشطة، بينما تعني علامة الصح أن المزامنة محدّثة. إذا رأيت رمز خطأ، مرر مؤشر الماوس فوقه للحصول على التفاصيل.

الطريقة 2: لوحة الأوامر

# افتح لوحة الأوامر (Ctrl+Shift+P / Cmd+Shift+P)
# اكتب: Cursor: Show Context Sync Status

يفتح هذا لوحة مفصلة تعرض:

• حالة المزامنة الحالية (قيد التشغيل، متوقف، خطأ)
• عدد الملفات المفهرسة
• الطابع الزمني Last للمزامنة الأخيرة
• أي رسائل خطأ
• حجم الفهرس على القرص

الطريقة 3: لوحة الإخراج

# عرض > الإخراج
# اختر "Cursor Indexing" من القائمة المنسدلة

تعرض لوحة الإخراج سجلات الفهرسة في الوقت الفعلي، بما في ذلك التقدم لكل ملف ورسائل الخطأ.

warning

إذا كانت حالة Context Sync تعرض "not running" ولا توجد أخطاء مرئية، فقد يشير ذلك إلى فشل صامت. تحقق من لوحة الإخراج بحثاً عن رسائل خطأ قد لا تكون ظهرت في الواجهة. ابحث عن أسطر تحتوي على "ERROR" أو "FATAL".

رسائل الخطأ الشائعة

إليك أكثر أخطاء Context Sync شيوعاً وما تعنيه:

"Context Sync is not running"

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

"Index corruption detected"

تلف ملف الفهرس المحلي، عادة بسبب إيقاف غير متوقع أو خطأ في القرص. الحل هو حذف الفهرس وإعادة بنائه من الصفر.

"File watcher limit reached"

تم تجاوز حد مراقب الملفات في نظام التشغيل. هذا شائع في أنظمة Linux ذات مساحات عمل كبيرة. الحل هو زيادة حد inotify في النظام.

"Embedding service unavailable"

خدمة التضمين السحابية غير متاحة مؤقتاً. عادة ما تكون عابرة وتُحل من تلقاء نفسها خلال بضع دقائق.

"Rate limit exceeded for indexing"

لقد وصلت إلى حد معدل الفهرسة. يحدث هذا عندما يتم تعديل عدد كبير جداً من الملفات في فترة قصيرة. انتظر بضع دقائق وستستأنف المزامنة تلقائياً.

إصلاح Context Sync

إصلاح سريع: إعادة تشغيل Context Sync

أبسط إصلاح لمعظم مشكلات Context Sync هو إعادة تشغيل عملية المزامنة:

# لوحة الأوامر (Ctrl+Shift+P / Cmd+Shift+P)
# اكتب: Cursor: Restart Context Sync

بدلاً من ذلك، يمكنك استخدام الإعدادات لفرض إعادة التشغيل:

// في settings.json
{
  "cursor.contextSync.forceRestart": true
}

بعد حفظ هذا الإعداد، سيعيد Cursor تشغيل عملية المزامنة عند إعادة تحميل النافذة التالية.

إعادة فهرسة كاملة

عندما لا تحل إعادة التشغيل السريعة المشكلة، تكون هناك حاجة إلى إعادة فهرسة كاملة. يحذف هذا الفهرس الحالي ويعيد بناءه من الصفر.

# الخطوة 1: مسح ذاكرة التخزين المؤقت للفهرس
# لوحة الأوامر: Cursor: Clear Index Cache

# الخطوة 2: تشغيل إعادة فهرسة كاملة
# لوحة الأوامر: Cursor: Reindex Workspace

warning

قد تستغرق إعادة الفهرسة الكاملة لقاعدة شفرة كبيرة من 10 إلى 30 دقيقة. خلال هذا الوقت، ستكون ميزات الذكاء الاصطناعي ذات سياق محدود أو بلا سياق. خطط لإعادة الفهرسة خلال استراحة أو عندما لا تحتاج فوراً إلى مساعدة الذكاء الاصطناعي.

إصلاح الفهرس يدوياً

إذا لم تعمل الأوامر المدمجة، يمكنك مسح ملفات الفهرس يدوياً:

على Windows:

# أغلق Cursor أولاً
# امسح دليل الفهرس
Remove-Item -Recurse -Force "$env:APPDATA\Cursor\index"
Remove-Item -Recurse -Force "$env:APPDATA\Cursor\codebase-index"

# امسح ذاكرة التخزين المؤقت
Remove-Item -Recurse -Force "$env:APPDATA\Cursor\cache"

# أعد تشغيل Cursor ودعه يعيد بناء الفهرس

على macOS:

# أغلق Cursor أولاً
rm -rf ~/Library/Application\ Support/Cursor/index
rm -rf ~/Library/Application\ Support/Cursor/codebase-index
rm -rf ~/Library/Application\ Support/Cursor/cache

# أعد تشغيل Cursor

على Linux:

# أغلق Cursor أولاً
rm -rf ~/.config/Cursor/index
rm -rf ~/.config/Cursor/codebase-index
rm -rf ~/.config/Cursor/cache

# أعد تشغيل Cursor

تلميح

قبل حذف الفهرس، تحقق من حجمه. إذا كان دليل الفهرس كبيراً بشكل غير عادي (عدة غيغابايتات لمشروع صغير)، فإن الفساد محتمل. سجل الحجم قبل الحذف للمقارنة بعد إعادة البناء.

تكوين الفهرسة

تحسين نطاق الفهرس

التحكم في الملفات التي يتم فهرستها هو الطريقة الأكثر فعالية لتحسين أداء Context Sync. بشكل افتراضي، يحترم Cursor ملف .gitignore، لكن يمكنك إضافة استبعادات مخصصة.

// في settings.json
{
  "cursor.contextSync.exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.next/**",
    "**/coverage/**",
    "**/*.min.js",
    "**/*.map",
    "**/vendor/**",
    "**/.cache/**",
    "**/*.lock",
    "**/package-lock.json",
    "**/yarn.lock",
    "**/*.png",
    "**/*.jpg",
    "**/*.gif",
    "**/*.svg"
  ],
  "cursor.contextSync.include": [
    "**/*.ts",
    "**/*.tsx",
    "**/*.js",
    "**/*.jsx",
    "**/*.py",
    "**/*.go",
    "**/*.rs",
    "**/README.md",
    "**/*.json"
  ]
}

warning

تضمين الملفات الثنائية (الصور، الملفات الثنائية المترجمة، ملفات القفل) في الفهرس يهدر المساحة ويقلل جودة البحث. استبعد دائماً الملفات الثنائية والملفات المُنشأة من الفهرسة. لا يمكن للذكاء الاصطناعي معالجة المحتوى الثنائي بشكل ذي معنى، وتضيف هذه الملفات ضوضاً إلى الفهرس.

تعيين حدود الفهرس

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

{
  "cursor.contextSync.maxFiles": 10000,
  "cursor.contextSync.maxFileSize": 1048576,
  "cursor.contextSync.maxLinesPerFile": 5000
}

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

تكوين مراقب الملفات

في أنظمة Linux، حد مراقب inotify الافتراضي منخفض جداً غالباً للمشاريع الكبيرة. ارفعه لمنع أخطاء "file watcher limit reached":

# تحقق من الحد الحالي
cat /proc/sys/fs/inotify/max_user_watches

# ارفع الحد مؤقتاً
sudo sysctl fs.inotify.max_user_watches=524288

# ارفع الحد بشكل دائم
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

على Windows، الإعداد المكافئ هو قيمة التسجيل MaxExtendedTdiHandleCount، لكنها نادراً ما تحتاج إلى تعديل.

ضبط الأداء

قياس أداء الفهرس

قبل التحسين، أنشئ قياساً أساسياً لأداء الفهرس الحالي:

# لوحة الأوامر: Cursor: Show Index Statistics

يعرض هذا:

Index Statistics
================
Total files:      3,247
Indexed files:    2,891 (89%)
Excluded files:   356
Index size:       142 MB
Last full index:  2026-09-14 14:30:22
Index duration:   4m 32s
Incremental updates today: 127
Average update time: 1.2s
Embedding cache hit rate: 87%

تلميح

معدل إصابة عالٍ لذاكرة التخزين المؤقت للتضمين (فوق 80%) يعني أن معظم تغييرات الملفات لا تتطلب تضمينات جديدة. إذا كان معدل الإصابة منخفضاً، فقد يشير ذلك إلى أن الملفات يتم تعديلها بشكل متكرر جداً أو أن ذاكرة التخزين المؤقت صغيرة جداً.

تحسين المستودعات الأحادية الكبيرة

تطرح المستودعات الأحادية الكبيرة تحديات فريدة لـ Context Sync. إليك استراتيجيات للتعامل معها:

الاستراتيجية 1: فهرسة خاصة بالمشروع

بدلاً من فهرسة المستودع الأحادي بالكامل، افهرس فقط المشروع الذي تعمل عليه حالياً:

{
  "cursor.contextSync.workspaceRoot": "packages/web-app",
  "cursor.contextSync.exclude": [
    "packages/**",
    "!packages/web-app/**"
  ]
}

يخبر هذا Cursor باستبعاد جميع الحزم باستثناء الحزمة التي تعمل عليها بنشاط.

الاستراتيجية 2: فهرسة قائمة على الرموز

فعّل الفهرسة القائمة على الرموز، التي تركز على تعريفات الدوال والفئات بدلاً من محتوى الملف الكامل:

{
  "cursor.contextSync.indexingMode": "symbols",
  "cursor.contextSync.symbolTypes": [
    "function",
    "class",
    "interface",
    "type",
    "method",
    "variable"
  ]
}

الاستراتيجية 3: فهرسة قائمة على الأولوية

عيّن مستويات أولوية لدلائل مختلفة بحيث يتم فهرسة الشفرة الحرجة أولاً:

{
  "cursor.contextSync.priority": {
    "src/core/**": "high",
    "src/api/**": "high",
    "src/components/**": "medium",
    "src/utils/**": "medium",
    "src/tests/**": "low",
    "docs/**": "low"
  }
}

warning

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

تحسين التحديثات التزايدية

يتم تشغيل التحديثات التزايدية عندما تتغير الملفات. يمكنك التحكم في مدى قوة هذه التحديثات:

{
  "cursor.contextSync.incremental": {
    "enabled": true,
    "debounceMs": 2000,
    "batchSize": 10,
    "maxConcurrentUpdates": 3
  }
}

• debounceMs: انتظر هذه المدة بعد آخر تغيير ملف قبل تحديث الفهرس. القيم الأعلى تقلل تكرار التحديث ولكنها تجمع المزيد من التغييرات.
• batchSize: عدد الملفات المراد معالجتها في كل دفعة تحديث.
• maxConcurrentUpdates: الحد الأقصى لعدد عمال التحديث المتوازي.

تحسين المزامنة السحابية

إذا كنت قد فعّلت المزامنة السحابية، فقد تؤثر على الأداء على الاتصالات الأبطأ:

{
  "cursor.contextSync.cloud": {
    "enabled": true,
    "syncInterval": 300000,
    "compressBeforeSync": true,
    "maxSyncSize": 50000000
  }
}

تلميح

إذا كنت تعمل دون اتصال بشكل متكرر، ارفع فاصل المزامنة لتجنب محاولات الاتصال غير الضرورية. يظل الفهرس المحلي يعمل بكامل وظائفه دون المزامنة السحابية، لكنه لن يتم مشاركته عبر الأجهزة.

استكشاف الأخطاء المتقدم

تشخيص الفهرس القديم

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

# لوحة الأوامر: Cursor: Validate Index Integrity

يتحقق هذا الأمر من:

• ملفات في الفهرس لم تعد موجودة على القرص
• ملفات على القرص ليست في الفهرس
• ملفات لا يتطابق تجزئة محتواها مع النسخة المفهرسة
• إدخالات فهرس يتيمة

# نموذج إخراج
Index Integrity Report
======================
Total discrepancies: 14
  Missing from index:      3 files
  Stale entries:          8 files
  Orphaned entries:       3 files

Recommended action: Run "Cursor: Reindex Workspace" to fix all discrepancies.

تصحيح أخطاء مراقب الملفات

إذا لم يتم التقاط تغييرات الملف بواسطة Context Sync، فقد لا يكون مراقب الملفات يعمل بشكل صحيح:

# لوحة الأوامر: Cursor: Test File Watcher

ينشئ هذا الأمر ملف اختبار مؤقت ويراقب ما إذا كان المراقب يكتشفه:

File Watcher Test
=================
Creating test file: .cursor-test-watcher-12345.txt
Waiting for watcher response...
Watcher detected change: YES (after 0.3s)
File watcher is functioning correctly.

If you are experiencing sync issues, the problem may be with
specific directories. Check your exclude patterns.

التحقق من صحة خدمة التضمين

// في settings.json، فعّل تشخيصات التضمين
{
  "cursor.contextSync.debugEmbeddings": true
}

مع تفعيل هذا، ستعرض لوحة الإخراج معلومات تفصيلية عن التضمين:

[DEBUG] Embedding request: file=src/auth/login.ts, chunks=3, tokens=1842
[DEBUG] Embedding response: success, cache=hit, duration=12ms
[DEBUG] Embedding request: file=src/auth/register.ts, chunks=4, tokens=2103
[DEBUG] Embedding response: success, cache=miss, duration=894ms
[DEBUG] Embedding batch complete: 7 files, 24 chunks, 6 cache hits

warning

إذا أظهرت جميع طلبات التضمين cache=miss ومدد طويلة، فقد تكون ذاكرة التخزين المؤقت للتضمين تالفة أو صغيرة جداً. حاول زيادة حجم ذاكرة التخزين المؤقت في الإعدادات أو مسح ذاكرة التخزين المؤقت بالكامل.

تحليل السجلات

للمشكلات المستمرة، اجمع سجل تشخيصي وحلله:

# لوحة الأوامر: Cursor: Generate Diagnostic Report

ينشئ هذا تقريراً شاملاً يتضمن:

• تكوين Context Sync
• إحصائيات الفهرس
• سجل الأخطاء الأخيرة
• حالة مراقب الملفات
• صحة خدمة التضمين
• معلومات النظام

يتم حفظ التقرير في:

# Windows
%USERPROFILE%\Desktop\cursor-diagnostic-report.txt

# macOS / Linux
~/Desktop/cursor-diagnostic-report.txt

أفضل الممارسات لـ Context Sync

الصيانة الدورية

• أسبوعياً: شغل "Validate Index Integrity" لالتقاط التفاوتات مبكراً
• شهرياً: راجع وحدّث أنماط الاستبعاد بناءً على تغييرات المشروع
• بعد إعادة الهيكلة الكبرى: شغل إعادة فهرسة كاملة لضمان التقاط التغييرات الهيكلية
• بعد تحديثات التبعيات: امسح ذاكرة التخزين المؤقت لمنع التضمينات القديمة

تنظيم مساحة العمل

// إعدادات موصى بها لمعظم المشاريع
{
  "cursor.contextSync.exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.git/**",
    "**/*.log",
    "**/*.min.*",
    "**/coverage/**"
  ],
  "cursor.contextSync.maxFileSize": 1048576,
  "cursor.contextSync.incremental": {
    "enabled": true,
    "debounceMs": 2000
  }
}

تلميح

إذا كنت تعمل على مشاريع متعددة ضمن نفس مساحة العمل، استخدم ملفات مساحة عمل متعددة الجذور لفصل سياقات الفهرس. تحصل كل مجلد جذر على فهرسه الخاص، مما يحسن الصلة ويقلل حجم الفهرس.

التعامل مع الملفات المُنشأة الكبيرة

الملفات المُنشأة مثل تعريفات الأنواع والمخرجات المترجمة وعملاء API المُنشأين تلقائياً يمكن أن تنتفخ الفهرس. استخدم ملف .cursorignore منفصل للتحكم الدقيق:

# .cursorignore
# استبعد جميع ملفات الأنواع المُنشأة
src/types/generated/**
# استبعد ملفات المخطط الكبيرة
schema/**/*.json
# استبعد أدوات الاختبار
test/fixtures/**
# استبعد ملفات الترحيل (نادراً ما تكون ضرورية لسياق الذكاء الاصطناعي)
migrations/**

warning

إذا استبعدت ملفات الترحيل، تأكد من تضمينها عند العمل في مهام متعلقة بقاعدة البيانات. يمكنك إزالة الاستبعاد مؤقتاً أو استخدام أمر Cursor: Index File لفهرسة ملفات محددة عند الطلب.

الخلاصة

Context Sync هو العمود الفقري لمساعدة الشفرة الذكية في Cursor. من خلال فهم كيف تعمل الفهرسة، ومعرفة كيفية تشخيص وإصلاح المشكلات الشائعة، وتطبيق استراتيجيات التحسين في هذا الدليل، يمكنك ضمان أن مساعد الذكاء الاصطناعي لديك يمتلك دائماً سياقاً دقيقاً ومحدّثاً حول قاعدة الشفرة الخاصة بك.

النقاط الرئيسية هي: حافظ على تحديث أنماط الاستبعاد، وأجرِ فحوصات سلامة منتظمة، ولا تتردد في إجراء إعادة فهرسة كاملة عندما تبدو الأمور غير صحيحة. الفهرس الصحي يعني استجابات ذكاء اصطناعي أسرع وأكثر دقة، مما يترجم مباشرة إلى تحسين إنتاجية المطور.