استخدام وكلاء Cursor مع WSL على Windows

يسمح Windows Subsystem for Linux (WSL) بتشغيل بيئة Linux مباشرة على Windows، مما يجمع بين أفضل ما في المنصتين. يتيح تشغيل وكلاء Cursor داخل WSL استخدام أدوات Linux الأصلية ومديري الحزم وأنظمة البناء مع الاحتفاظ بسطح مكتب Windows المألوف. ومع ذلك، فإن التفاعل بين مضيف Windows وبيئة WSL يقدم تحديات فريدة، خاصة حول معالجة الطرفية وتنفيذ الوكلاء. يغطي هذا الدليل كل شيء من الإعداد الأولي إلى استكشاف الأخطاء المتقدم.

المتطلبات الأساسية

قبل إعداد Cursor مع WSL، تأكد من توفر ما يلي:

• Windows 11 (موصى به) أو Windows 10 مع أحدث التحديثات
• WSL 2 مثبت ومُعد (شغل wsl --install في PowerShell مرتفع الصلاحيات)
• توزيعة Linux مثبتة (Ubuntu هي الافتراضية والأكثر اختباراً)
• Cursor مثبت على مضيف Windows (وليس داخل WSL)
• موارد نظام كافية: لا أقل من 8 غيغابايت RAM و20 غيغابايت مساحة قرص فارغة

تلميح

استخدم WSL 2 بدلاً من WSL 1. يوفر WSL 2 نواة Linux كاملة بأداء وتوافق أفضل. تحقق من إصدارك باستخدام wsl -l -v في PowerShell. إذا رأيت الإصدار 1، قم بالترقية باستخدام wsl --set-version <DistroName> 2.

إعداد WSL لـ Cursor

تثبيت وتكوين WSL

إذا لم تكن قد قمت بتثبيت WSL بعد، اتبع هذه الخطوات:

# شغل في PowerShell مرتفع الصلاحيات (تشغيل كمسؤول)
wsl --install

# يقوم هذا بتثبيت WSL 2 مع توزيعة Ubuntu الافتراضية
# أعد تشغيل الكمبيوتر عندما يُطلب منك ذلك

# بعد إعادة التشغيل، قم بإعداد مستخدم Linux وكلمة المرور الخاصة بك
# ثم تحقق من التثبيت
wsl --list --verbose

الإخراج المتوقع:

  NAME      STATE           VERSION
* Ubuntu    Running         2

تثبيت أدوات التطوير في WSL

بمجرد إعداد WSL، قم بتثبيت أدوات التطوير التي يحتاجها مشروعك داخل بيئة Linux:

# داخل WSL، حدّث قوائم الحزم
sudo apt update && sudo apt upgrade -y

# ثبت أدوات التطوير الشائعة
sudo apt install -y build-essential git curl wget unzip

# ثبت Node.js عبر Node Version Manager
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

# ثبت Python
sudo apt install -y python3 python3-pip python3-venv

# ثبت Go
wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# ثبت Docker (اختياري، للتطوير المُحَوٍّ)
sudo apt install -y docker.io
sudo usermod -aG docker $USER

warning

لا تقم بتثبيت Cursor داخل WSL. يجب تثبيت Cursor على مضيف Windows. يتصل بـ WSL كبيئة بعيدة، بشكل مشابه لكيفية اتصاله بـ SSH البعيدة. تثبيت Cursor داخل WSL سيؤدي إلى مشكلات عرض ووظائف GUI مفقودة.

توصيل Cursor بـ WSL

يحتوي Cursor على دعم WSL مدمج من خلال امتداد Remote Development:

1. افتح Cursor على Windows
2. افتح لوحة الأوامر (Ctrl+Shift+P)
3. اكتب وحدد: WSL: Connect to WSL
4. اختر التوزيعة المثبتة لديك (مثل Ubuntu)
5. سيعيد Cursor التحميل ويتصل ببيئة WSL

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

# من Windows PowerShell أو موجه الأوامر
cd \\wsl$\Ubuntu\home\username\my-project
cursor .

أو من داخل WSL:

# انتقل إلى دليل مشروعك
cd ~/my-project

# شغل Cursor متصلاً بمسار WSL هذا
cursor .

تلميح

أنشئ اختصار Windows أو اسماً مستعاراً يفتح Cursor في دليل home الخاص بـ WSL للوصول السريع:

# أضف إلى ملف PowerShell الشخصي
function cursor-wsl { wsl -e bash -c "cd ~ && cursor ." }

يتيح لك هذا كتابة cursor-wsl في PowerShell لفتح Cursor في دليل home الخاص بـ WSL فوراً.

تكوين الطرفية

فهم سلوك الطرفية في WSL

عندما يعمل Cursor في وضع WSL، يمكن للطرفية المدمجة العمل في وضعين:

• طرفية WSL: تشغل الأوامر داخل بيئة Linux (افتراضي)
• طرفية Windows: تشغل الأوامر على مضيف Windows

يؤثر وضع الطرفية على كيفية تفاعل الوكلاء مع النظام. يقوم الوكلاء عادةً بتنفيذ الأوامر في طرفية WSL، لكن بعض العمليات قد تحتاج إلى التشغيل على مضيف Windows.

تكوين الطرفية الافتراضية

// في settings.json (قابل للوصول عبر Ctrl+, > Open Settings JSON)
{
  "terminal.integrated.defaultProfile.linux": "bash",
  "terminal.integrated.profiles.linux": {
    "bash": {
      "path": "bash",
      "args": ["-l"],
      "icon": "terminal-bash"
    },
    "zsh": {
      "path": "zsh",
      "args": ["-l"],
      "icon": "terminal-zsh"
    }
  },
  // ضمان استخدام Cursor لـ shell WSL لأوامر الوكيل
  "cursor.agent.shell": "wsl",
  "cursor.agent.shellPath": "/bin/bash"
}

استعادة طرفية معطلة

مشكلة شائعة في إعدادات WSL هي طرفية معطلة أو غير مستجيبة. قد تعرض الطرفية رسائل خطأ، أو تفشل في البدء، أو تعرض مخرجات مشوهة. إليك كيفية إصلاحها:

# الخطوة 1: تحقق مما إذا كانت عملية الطرفية قيد التشغيل
# لوحة الأوامر: Terminal: Select Default Profile

# الخطوة 2: تحقق من أن مسار shell صحيح
# يجب أن يشير المسار إلى shell صالح داخل WSL

// إصلاح شائع: تعيين مسار shell بشكل صريح
{
  "terminal.integrated.shell.linux": "/bin/bash",
  "terminal.integrated.env.linux": {
    "TERM": "xterm-256color",
    "COLORTERM": "truecolor",
    "LANG": "en_US.UTF-8"
  }
}

إذا كانت الطرفية غير مستجيبة تماماً:

1. أغلق جميع مثيلات الطرفية في Cursor
2. افتح لوحة الأوامر وشغل: Terminal: Restart Terminal Server
3. إذا لم يعمل ذلك، أعد تحميل النافذة: Developer: Reload Window
4. كملاذ أخير، أعد تشغيل Cursor بالكامل

warning

إذا عرضت الطرفية "The terminal process failed to launch" أو "exec bash: no such file or directory"، فإن تكامل WSL معطل. يحدث هذا عادةً بعد تحديث Windows أو تغيير توزيعة WSL. شغل wsl --shutdown في PowerShell، ثم أعد توصيل Cursor إلى WSL.

حل توقف الوكلاء في gatherTerminalSelections

فهم المشكلة

واحدة من أكثر المشكلات التي يتم الإبلاغ عنها مع WSL ووكلاء Cursor هي توقف gatherTerminalSelections. عندما يحاول الوكيل التفاعل مع الطرفية، فإنه يستدعي دالة داخلية تسمى gatherTerminalSelections لتحديد أي طرفية لاستخدامها. في بيئات WSL، يمكن أن تتوقف هذه الدالة إلى أجل غير مسمى، مما يؤدي إلى تجمد الوكيل.

الأعراض

• يبدأ الوكيل في تنفيذ مهمة لكنه يتوقف عند خطوة التفاعل مع الطرفية
• يعرض شريط الحالة "Agent is working..." إلى أجل غير مسمى
• لا تظهر مخرجات طرفية
• ينتهي الأمر بالوكيل إلى انتهاء المهلة أو يتطلب إلغاءً يدوياً
• قد تعرض وحدة تحكم مطور Cursor وعد gatherTerminalSelections معلقاً

الأسباب الجذرية

يحدث التوقف عادةً بسبب أحد الأسباب التالية:

1. ملفات تعريف طرفية متعددة: لا يستطيع Cursor تحديد ملف تعريف الطرفية الذي يجب استخدامه
2. نصوص تكامل shell: فشل تحميل نص تكامل shell في WSL
3. مشكلات تخصيص PTY: يختلف تخصيص الطرفية الزائفة في WSL عن Linux الأصلي
4. تعارضات متغيرات البيئة: تتسرب متغيرات بيئة Windows إلى WSL وتسبب تعارضات

الحل 1: تبسيط ملفات تعريف الطرفية

قلل عدد ملفات تعريف الطرفية لتجنب غموض الاختيار:

// في settings.json
{
  "terminal.integrated.profiles.linux": {
    "bash": {
      "path": "/bin/bash",
      "args": ["-l"]
    }
  },
  "terminal.integrated.defaultProfile.linux": "bash",
  // تعطيل ملفات التعريف الأخرى التي قد تربك الوكيل
  "terminal.integrated.profiles.windows": {},
  "terminal.integrated.detectableProfiles": false
}

تلميح

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

الحل 2: إصلاح تكامل Shell

يمكّن تكامل shell الوكيل من تتبع مخرجات الأوامر. في WSL، قد لا يتم تحميل نص التكامل بشكل صحيح. تحقق وأصلح:

# داخل WSL، تحقق مما إذا كان تكامل shell محملاً
echo $TERM_PROGRAM

# يجب أن يخرج: cursor أو vsoc (إذا كنت تستخدم طرفية Cursor/VS Code)
# إذا كان فارغاً، فإن تكامل shell غير محمل

# مصدر نص التكامل يدوياً
# ابحث عن المسار الصحيح:
ls /mnt/c/Users/*/AppData/Local/Programs/cursor/resources/app/out/vs/shell/integration/

# أو أضف هذا إلى ~/.bashrc
if [ -n "$CURSOR_IPC_HANDLE" ]; then
  export CURSOR_INTEGRATION_ENABLED=1
fi

الحل 3: تخصيص طرفية مسبقاً

إنشاء طرفية مخصصة للوكيل قبل إطلاقه يمكن أن يمنع توقف الاختيار:

// في settings.json
{
  "cursor.agent.terminal": {
    "autoCreate": true,
    "profile": "bash",
    "waitForIntegration": true,
    "integrationTimeout": 5000
  }
}

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

الحل 4: تعطيل مطالبة اختيار Shell

إذا كان التوقف ناتجاً عن مطالبة اختيار لا تُحل أبداً، فعطل المطالبة:

{
  "cursor.agent.terminal.selectionMode": "auto",
  "cursor.agent.terminal.skipSelection": true
}

warning

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

توحيد مهارات الوكيل بين مضيف Windows وWSL

التحدي

عند العمل مع كل من Windows وWSL، قد يكون لديك أدوات وتكوينات وتعريفات مهارات مختلفة على كل جانب. هذا يخلق تجربة مجزأة حيث قد يعرف الوكيل كيف يفعل شيئاً على مضيف Windows ولكن ليس في WSL، أو العكس.

مشاركة ملفات التكوين

النهج الأكثر فعالية هو مشاركة ملفات تكوين الوكيل بين البيئتين. بما أن WSL يمكنه الوصول إلى نظام ملفات Windows عبر /mnt/c/، يمكنك تخزين التكوين المشترك في موقع يمكن الوصول إليه من Windows.

// في Cursor settings.json (جانب Windows)
{
  "cursor.agent.skillsDirectory": "\\\\wsl$\\Ubuntu\\home\\username\\.cursor\\skills",
  "cursor.agent.sharedConfig": true
}

// في Cursor settings.json (جانب WSL)
{
  "cursor.agent.skillsDirectory": "~/.cursor/skills",
  "cursor.agent.sharedConfig": true
}

إنشاء دليل مهارات موحد

أنشئ دليل مهارات يمكن لكلا البيئتين الوصول إليه:

# داخل WSL
mkdir -p ~/.cursor/skills

# أنشئ رابطاً رمزياً إلى موقع يمكن الوصول إليه من Windows
# هذا يتيح لك تحرير المهارات من أي من البيئتين
ln -s ~/.cursor/skills /mnt/c/Users/username/.cursor/skills-wsl

# مثال: ملف مهارة يعمل في كلتا البيئتين
cat > ~/.cursor/skills/shared-git-workflow.md << 'EOF'
# Shared Git Workflow Skill

## Applies to: Windows Host and WSL

When performing git operations:

1. Always check the current branch first
2. Use conventional commit messages
3. Run tests before committing
4. Push only to feature branches, never to main

## Environment-specific notes:
- On Windows: use Git for Windows (git.exe)
- On WSL: use native Linux git
- Both should reference the same repository
EOF

تلميح

خزن مهاراتك في مستودع Git واستنسخه إلى كلا البيئتين. هذا يضمن أن المهارات مُصدرة ومتزامنة. استخدم وحدة فرعية .cursor/skills في مستودع مشروعك الرئيسي للمشاركة على مستوى الفريق.

معالجة اختلافات المسار

واحدة من أكبر التحديات في إعداد البيئة المزدوجة هي معالجة المسار. يستخدم Windows أحرف محركات الأقراص (C:\) بينما يستخدم WSL مسارات التحميل (/mnt/c/). تحتاج إلى مراعاة ذلك في تكوينات الوكيل:

// في settings.json
{
  "cursor.agent.pathMappings": {
    "windows": {
      "C:\\Users\\username\\projects": "/home/username/projects"
    },
    "wsl": {
      "/home/username/projects": "C:\\Users\\username\\projects"
    }
  }
}

# مثال على مهارة مع تعليمات معالجة المسار

## عند العمل مع مسارات الملفات:

- إذا كان الوكيل يعمل في WSL، حول مسارات Windows إلى مسارات WSL
  - يصبح `C:\Users\username\project` هو `/mnt/c/Users/username/project`
- إذا كان الوكيل يعمل على مضيف Windows، حول مسارات WSL إلى مسارات Windows
  - يبقى `/home/username/project` كما هو (دليل home في WSL)
  - يصبح `/mnt/c/Users/username/project` هو `C:\Users\username\project`

## اكتشاف البيئة الحالية:
- تحقق مما إذا كان `/proc/version` موجوداً (WSL/Linux)
- تحقق مما إذا كان `$OS` هو `Windows_NT` (Windows)

warning

لا تقم أبداً بتثبيت مسارات مطلقة في مهارات الوكيل. استخدم دائماً مسارات نسبية أو متغيرات تكوين. تتعطل المسارات المثبتة عند التبديل بين مضيف Windows وبيئة WSL.

أنماط التطوير عن بُعد

النمط 1: تطوير WSL الأساسي

في هذا النمط، يحدث كل التطوير في WSL، ويعمل Cursor على Windows كعميل رفيع:

// settings.json
{
  "remote.WSL.defaultDistro": "Ubuntu",
  "cursor.agent.executionEnvironment": "wsl",
  "cursor.agent.preferWslTerminal": true,
  "files.eol": "\n"
}

هذا هو أبسط إعداد ويعمل بشكل جيد للمشاريع المبنية بالكامل على Linux، مثل تطبيقات Node.js أو Python أو Go أو Rust.

النمط 2: التطوير الهجين

في هذا النمط، تعمل بعض الأدوات على Windows وأخرى في WSL:

// settings.json
{
  "cursor.agent.executionEnvironment": "auto",
  "cursor.agent.shellRouting": {
    "bash": "wsl",
    "powershell": "windows",
    "cmd": "windows",
    "node": "wsl",
    "python": "wsl",
    "dotnet": "windows"
  }
}

تلميح

النهج الهجين مفيد عندما تحتاج إلى أدوات Windows المحددة (مثل .NET SDK أو SQL Server أو أطر اختبار حصرية لـ Windows) جنباً إلى جنب مع أدوات Linux. قم بتكوين توجيه shell لاختيار البيئة المناسبة تلقائياً بناءً على الأمر.

النمط 3: تطوير Docker أولاً

استخدم WSL مع Docker لتجربة تطوير مُحَوًاة بالكامل:

// settings.json
{
  "cursor.agent.executionEnvironment": "wsl",
  "docker.host": "wsl",
  "cursor.agent.preferredContainer": "dev-container",
  "remote.containers.defaultProfile": "WSL: Ubuntu"
}

# مثال على Dockerfile للتطوير المتوافق مع الوكيل
FROM mcr.microsoft.com/devcontainers/typescript-node:20

# تثبيت أدوات إضافية
RUN apt-get update && apt-get install -y \
    git \
    curl \
    vim \
    && rm -rf /var/lib/apt/lists/*

# تثبيت حزم npm العامة
RUN npm install -g typescript ts-node nodemon

# إعداد مساحة العمل
WORKDIR /workspace

النمط 4: تطوير متعدد التوزيعات

إذا كنت تعمل مع توزيعات Linux متعددة، يمكنك تكوين Cursor لاستخدام توزيعات مختلفة لمشاريع مختلفة:

// settings.json
{
  "remote.WSL.distros": {
    "Ubuntu": {
      "defaultProfile": "bash",
      "startupCommand": "source ~/.nvm/nvm.sh"
    },
    "Debian": {
      "defaultProfile": "bash",
      "startupCommand": "source /etc/profile.d/rvm.sh"
    }
  }
}

# سرد التوزيعات المثبتة
wsl --list --verbose

# تبديل التوزيعة الافتراضية
wsl --set-default Ubuntu

استكشاف مشكلات WSL الشائعة

الوكيل لا يجد الملفات

إذا أبلغ الوكيل عن عدم العثور على الملفات، فتحقق من تنسيق المسار:

# تنسيق مسار WSL الصحيح
ls /home/username/project/src/

# غير صحيح: استخدام تنسيق مسار Windows في WSL
# سيفشل هذا أو يصل إلى موقع خاطئ
ls C:\Users\username\project\src\

warning

الوصول عبر أنظمة الملفات (الوصول إلى ملفات WSL من Windows أو العكس) أبطأ بكثير من الوصول الأصلي. للعمليات الحرجة للأداء مثل الفهرسة والبناء، احتفظ بجميع الملفات داخل نظام ملفات WSL (/home/...) بدلاً من نظام ملفات Windows (/mnt/c/...).

مشكلات اتصال الشبكة

إذا لم يتمكن الوكيل من الوصول إلى الإنترنت من WSL:

# اختبار الاتصال من WSL
ping 8.8.8.8
curl -s https://api.github.com | head -5

# إذا فشل تحليل DNS، تحقق من /etc/resolv.conf
cat /etc/resolv.conf

# إذا كان فارغاً أو مُعداً بشكل خاطئ، أصلحه:
sudo tee /etc/resolv.conf << 'EOF'
nameserver 8.8.8.8
nameserver 1.1.1.1
EOF

# إذا لم يتمكن WSL من الوصول إلى خدمات localhost على Windows
# تحقق من IP مضيف Windows من WSL
ip route show | grep -i default | awk '{print $3}'
# استخدم هذا IP للوصول إلى خدمات Windows من WSL

حدود الذاكرة والموارد

يستخدم WSL 2 جهازاً ظاهرياً بحدود موارد قابلة للتكوين. إذا كان الوكلاء يعملون ببطء أو ينفد ذاكرتهم:

# إنشاء أو تحرير ملف .wslconfig
# الموقع: C:\Users\username\.wslconfig

# .wslconfig
[wsl2]
memory=12GB
processors=6
swap=4GB
localhostForwarding=true

بعد إنشاء أو تحرير هذا الملف:

# في PowerShell
wsl --shutdown
# ثم أعد تشغيل Cursor وأعد الاتصال بـ WSL

تلميح

راقب استخدام موارد WSL من مضيف Windows باستخدام مدير المهام. ابحث عن عملية "vmmem"، التي تمثل جهاز WSL 2 الظاهري. إذا كان يستخدم باستمرار 90%+ من الذاكرة المخصصة، ارفع حد الذاكرة في .wslconfig.

أداء نظام الملفات

يختلف أداء نظام الملفات بشكل كبير اعتماداً على مكان تخزين الملفات:

الموقع	سرعة القراءة	سرعة الكتابة	التوصية
home في WSL (/home/)	سريع	سريع	خزن ملفات المشروع هنا
Windows عبر WSL (/mnt/c/)	بطيء	بطيء جداً	تجنب لملفات المشروع
Windows الأصلي	سريع	سريع	فقط لأدوات Windows

# قياس أداء نظام الملفات
# داخل WSL، على نظام ملفات WSL
dd if=/dev/zero of=/home/$USER/testfile bs=1M count=100 oflag=direct
rm /home/$USER/testfile

# داخل WSL، الوصول إلى نظام ملفات Windows
dd if=/dev/zero of=/mnt/c/Users/$USER/testfile bs=1M count=100 oflag=direct
rm /mnt/c/Users/$USER/testfile

إذا رأيت فرقاً بمقدار 5-10 أضعاف (شائع)، انقل ملفات مشروعك إلى نظام ملفات WSL.

ملخص أفضل الممارسات

• استخدم دائماً WSL 2، وليس WSL 1، لعمل وكيل Cursor
• ثبت Cursor على Windows، وليس داخل WSL
• خزن ملفات المشروع في نظام ملفات WSL (/home/...) للحصول على أفضل أداء
• بسّط ملفات تعريف الطرفية لتجنب توقف gatherTerminalSelections
• عيّن cursor.agent.terminal.autoCreate لتجاوز مشكلات اختيار الطرفية
• شارك مهارات الوكيل عبر دليل متزامن أو مستودع Git
• لا تقم أبداً بتثبيت مسارات مطلقة في مهارات الوكيل
• قم بتكوين .wslconfig مع تخصيص ذاكرة ووحدة معالجة كافية
• استخدم wsl --shutdown لإعادة تعيين بيئة WSL عندما تسوء الأمور
• حافظ على تحديث توزيعة WSL باستخدام sudo apt update && sudo apt upgrade

warning

قد لا تعمل بعض امتدادات Cursor المثبتة على مضيف Windows بشكل صحيح في وضع WSL. تحتاج الامتدادات إلى التثبيت بشكل منفصل لـ WSL البعيد. تحقق من لوحة Extensions عن زر "Install in WSL" بجانب كل امتداد.

الخلاصة

ي combine تشغيل وكلاء Cursor في WSL بين قوة أدوات تطوير Linux وراحة سطح مكتب Windows. في حين أن إعداد البيئة المزدوجة يقدم تحديات حول معالجة الطرفية وإدارة المسار وتخصيص الموارد، فإن الاستراتيجيات في هذا الدليل تساعدك في التغلب عليها.

مفتاح تجربة WSL السلسة هو اتساق التكوين: أبقِ ملفات تعريف الطرفية بسيطة، وتأكد من تحميل تكامل shell بشكل صحيح، وحافظ على دليل مهارات موحد. عندما تسوء الأمور، يحل wsl --shutdown متبوعاً بإعادة اتصال Cursor جديدة معظم المشكلات. مع الإعداد الصحيح، يصبح WSL بيئة تطوير من الدرجة الأولى لوكلاء Cursor، مما يمنحك الوصول إلى نظام Linux البيئي الكامل دون مغادرة Windows.