Cursor Remote Control على Windows
يتيح لك Cursor Remote Control التحكم في مثيل Cursor من جهاز بعيد، مما يتيح التطوير بمساعدة الذكاء الاصطناعي على خوادم بلا واجهة، أو محطات عمل سحابية، أو أجهزة ثانوية. على Windows، يتضمن الإعداد عملية worker، وتكوين CLI، ومخزن حالة قائم على SQLite. يواجه مستخدمو المنتدى بشكل متكرر أعطالاً متعلقة بـ better-sqlite3 وعدم تطابق NODE_MODULE_VERSION. يغطي هذا الدليل الإعداد الكامل ويوفر حلولاً مختبرة لأكثر المشاكل الشائعة الخاصة بـ Windows.
ما هو Cursor Remote Control؟
يتكون Remote Control من مكونين:
- المضيف (Host) - مثيل Cursor الذي تريد التحكم فيه (عادةً على جهاز Windows بعيد أو سحابي)
- وحدة التحكم (Controller) - جهازك المحلي الذي يشغل Cursor CLI لإرسال الأوامر
يشغل المضيف عملية worker تقوم بـ:
- الاستماع للأوامر الواردة من CLI
- الحفاظ على الحالة في قاعدة بيانات SQLite محلية (
better-sqlite3) - تنفيذ عمليات الملفات، وأوامر الطرفية، ومهام agent
- بث النتائج إلى وحدة التحكم
حالات الاستخدام
| السيناريو | الفائدة |
|---|---|
| محطة عمل تطوير سحابية | استخدام الذكاء الاصطناعي على جهاز سحابي قوي من حاسوب محمول خفيف |
| إدارة خادم بلا واجهة | تشغيل Cursor agent على خادم بدون عرض |
| مسارات عمل متعددة الأجهزة | التحكم في مثيلات Cursor متعددة من جهاز واحد |
| تكامل CI/CD | تشغيل مهام agent من خطوط أنابيب آلية |
المتطلبات الأساسية
قبل إعداد Remote Control على Windows:
- Cursor مثبت على جهاز المضيف (الذي يتم التحكم فيه)
- Node.js 18+ مثبت على كل من المضيف ووحدة التحكم
- Windows 10 أو 11 مع PowerShell 5.1+ أو PowerShell 7
- وصول شبكي بين المضيف ووحدة التحكم (TCP مباشر أو نفق SSH)
- وصول المسؤول للإعداد الأولي على المضيف
إعداد Remote Control Worker
worker هو قلب جهاز المضيف. يعمل كعملية خلفية ويتعامل مع جميع الأوامر الواردة.
الخطوة 1: تثبيت Worker
على جهاز Windows المضيف:
# تثبيت Cursor Remote Control worker عالميًا
npm install -g @cursor/remote-worker
# التحقق من التثبيت
cursor-remote-worker --version
الخطوة 2: تهيئة Worker
# تهيئة worker مع مسار مشروع
cursor-remote-worker init --project "H:\Projects\my-app"
# هذا ينشئ ملف تكوين في:
# %USERPROFILE%\.cursor-remote\config.json
التكوين المُنشأ يبدو كالتالي:
{
"workerId": "win-worker-001",
"projectPath": "H:\\Projects\\my-app",
"port": 8473,
"authToken": "auto-generated-token-here",
"database": {
"type": "sqlite",
"path": "%USERPROFILE%\\.cursor-remote\\state.db"
},
"logLevel": "info",
"maxConcurrentTasks": 3
}
دوّن قيمة authToken. ستحتاج إليها لتكوين CLI وحدة التحكم. عاملها ككلمة مرور. إذا كنت بحاجة إلى إعادة إنشائها، شغل cursor-remote-worker regenerate-token.
الخطوة 3: بدء Worker
# بدء worker في المقدمة (للاختبار)
cursor-remote-worker start
# تثبيت worker كخدمة Windows (للإنتاج)
cursor-remote-worker install-service
cursor-remote-worker start-service
للاستخدام الإنتاجي، ثبتته كخدمة Windows ليبقى بعد إعادة التشغيل:
# التحقق من أن الخدمة تعمل
Get-Service -Name "CursorRemoteWorker"
# المخرجات المتوقعة:
# Status Name DisplayName
# ------ ---- -----------
# Running CursorRemoteWorker Cursor Remote Worker
الخطوة 4: تكوين جدار الحماية
يستمع worker على المنفذ 8473 افتراضيًا. افتح جدار الحماية:
# فتح المنفذ في جدار حماية Windows
New-NetFirewallRule -DisplayName "Cursor Remote Worker" -Direction Inbound -Protocol TCP -LocalPort 8473 -Action Allow
# التحقق من إنشاء القاعدة
Get-NetFirewallRule -DisplayName "Cursor Remote Worker"
لا تعرض المنفذ 8473 للإنترنت العام. مصادقة worker مبنية على الرموز ولكنها غير مصممة للشبكات غير الموثوقة. استخدم VPN، أو نفق SSH، أو قيد قواعد جدار الحماية لعناوين IP محددة. تعريض المنفذ علنًا هو خطر أمني.
تكوين CLI على وحدة التحكم
على جهازك المحلي (وحدة التحكم)، ثبت وكيّف CLI للتواصل مع المضيف.
الخطوة 1: تثبيت CLI
npm install -g @cursor/remote-cli
# التحقق
cursor-remote --version
الخطوة 2: إضافة مضيف بعيد
# إضافة تكوين المضيف البعيد
cursor-remote add-host `
--name "win-cloud-dev" `
--host "192.168.1.100" `
--port 8473 `
--token "auto-generated-token-here" `
--project "H:\Projects\my-app"
يخزن هذا التكوين في %USERPROFILE%\.cursor-remote\hosts.json:
{
"hosts": [
{
"name": "win-cloud-dev",
"host": "192.168.1.100",
"port": 8473,
"token": "auto-generated-token-here",
"project": "H:\\Projects\\my-app"
}
]
}
الخطوة 3: اختبار الاتصال
# اختبار اتصال المضيف البعيد
cursor-remote ping --host win-cloud-dev
# المخرجات المتوقعة:
# Connected to win-cloud-dev (192.168.1.100:8473)
# Worker version: 1.2.3
# Project: H:\Projects\my-app
# Status: ready
الخطوة 4: بدء جلسة بعيدة
# فتح جلسة تفاعلية
cursor-remote session --host win-cloud-dev
# أنت الآن في موجه تفاعلي متصل بمثيل Cursor البعيد
# الأوامر التي تكتبها تنفذ على جهاز المضيف
تشغيل مهام Agent عن بعد
بمجرد الاتصال، يمكنك تشغيل مهام agent على المضيف البعيد:
# تشغيل مهمة agent واحدة
cursor-remote agent --host win-cloud-dev --prompt "Refactor the authentication module to use JWT"
# التشغيل بنموذج محدد
cursor-remote agent --host win-cloud-dev --model claude-sonnet-4-0 --prompt "Add input validation to all API endpoints"
# التشغيل مع سياق ملف
cursor-remote agent --host win-cloud-dev --files "src/auth/auth.ts,src/api/routes.ts" --prompt "Add rate limiting to these routes"
إخراج البث
افتراضيًا، يُدفق إخراج agent إلى طرفيتك في الوقت الفعلي:
cursor-remote agent --host win-cloud-dev --prompt "Create a test file" --stream
يعرض هذا كل خطوة كما تحدث، بما في ذلك فروقات الملفات وتنفيذ الأدوات.
للمهام طويلة التشغيل، استخدم علامة --detach لتشغيل المهمة ف ي الخلفية على المضيف. يمكنك التحقق منها لاحقًا:
# بدء مهمة منفصلة
cursor-remote agent --host win-cloud-dev --prompt "Write comprehensive test suite" --detach
# التحقق من حالة المهمة
cursor-remote tasks --host win-cloud-dev --status running
# الحصول على إخراج المهمة
cursor-remote tasks --host win-cloud-dev --id task_abc123 --output
عطل better-sqlite3 NODE_MODULE_VERSION
هذه أكثر مشكلة حرجة يواجهها مستخدمو Windows. يستخدم worker قاعدة بيانات الحالة better-sqlite3، وعندما لا تتطابق نسخة Node.js على المضيف مع النسخة التي تم تجميع better-sqlite3 ضدها، يتعطل worker مع خطأ مثل:
Error: The module 'H:\Projects\my-app\node_modules\better-sqlite3\build\Release\better_sqlite3.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 127. This version of Node.js requires
NODE_MODULE_VERSION 137.
فهم الخطأ
better-sqlite3 هو إضافة أصلية. يقوم بتجيميع كود C++ إلى ملف ثنائي .node خاص بنسخة ABI محددة من Node.js. NODE_MODULE_VERSION هو رقم يقابل نسخة Node.js رئيسية محددة:
| NODE_MODULE_VERSION | نسخة Node.js |
|---|---|
| 115 | Node.js 18.x |
| 120 | Node.js 20.x |
| 127 | Node.js 22.x |
| 137 | Node.js 24.x |
عندما تم تثبيت worker بـ Node.js 22 (MODULE_VERSION 127) ولكنك لاحقًا قمت بالترقية إلى Node.js 24 (MODULE_VERSION 137)، الملف الثنائي المسبق التجميع لم يعد متطابقًا.
الحل 1: إعادة تجميع better-sqlite3 (موصى به)
# الانتقال إلى دليل تثبيت worker
cd "$env:APPDATA\npm\node_modules\@cursor\remote-worker"
# إعادة تجميع الوحدات الأصلية لنسخة Node.js الحالية
npm rebuild better-sqlite3
# أو فرض إعادة التجميع من المصدر
npm rebuild better-sqlite3 --build-from-source
تحتاج إلى Visual Studio Build Tools (أو Visual Studio كامل مع حمل C++) لإعادة تجميع الإضافات الأصلية. إذا لم تكن مثبتة لديك:
# تثبيت أدوات البناء عبر npm
npm install --global windows-build-tools
# أو تثبيت Visual Studio Build Tools يدويًا:
# https://visualstudio.microsoft.com/visual-cpp-build-tools/
بعد التثبيت، أعد تشغيل طرفيتك وأعد محاولة إعادة التجميع.
الحل 2: خفض نسخة Node.js
إذا لم تكن إعادة التجميع خيارًا، طابق نسخة Node.js مع ما يتوقعه worker:
# التحقق من نسخة Node.js التي بُني بها worker
# (انظر رسالة الخطأ للحصول على NODE_MODULE_VERSION)
# تثبيت nvm-windows لإدارة الإصدارات
# https://github.com/coreybutler/nvm-windows
nvm install 22.0.0
nvm use 22.0.0
# التحقق
node --version
# v22.0.0
# إعادة تشغيل worker
cursor-remote-worker stop-service
cursor-remote-worker start-service
الحل 3: استخدام ملف ثنائي مسبق التجميع
بعض إصدارات better-sqlite3 توفر ملفات ثنائية مسبقة التجميع للأنظمة الشائعة. إذا كان توليفك متاحًا:
# تثبيت نسخة من better-sqlite3 مع ملفات مسبقة التجميع
npm install [email protected] --build-from-source=false
# أو استخدام prebuild-install لجلب الملف الثنائي الصحيح
npx prebuild-install --runtime node --target $(node -v)
الحل 4: تثبيت نسخة Node.js لـ worker
لمنع تكرار هذا، ثبت نسخة Node.js التي يستخدمها worker، بشكل مستقل عن Node.js الخاص بالتطوير:
# إنشاء سكريبت غلاف يستخدم نسخة Node.js محددة
# C:\cursor-worker\start-worker.bat
@echo off
set PATH=C:\Program Files\nodejs-v22\;%PATH%
node "C:\Program Files\nodejs-v22\node_modules\@cursor\remote-worker\bin\worker.js" start
ثم كون خدمة Windows لاستخدام هذا الملف الدفعي بدلًا من نقطة الدخول الافتراضية.
إذا كنت تستخدم nvm-windows لتبديل نسخ Node.js للتطوير، يمكن لكل تبديل أن يعطل worker إذا غيّر نسخة Node.js النشطة على مستوى النظام. نهج سكريبت الغلاف (الحل 4) هو الحل الأكثر موثوقية على المدى الطويل لأنه يفصل نسخة Node.js الخاصة بـ worker عن بيئة التطوير الخاصة بك.
استكشاف أخطاء Worker
worker لا يبدأ
العرض: cursor-remote-worker start يخرج على الفور بدون إخراج.
التشخيص:
# فحص سجلات worker
Get-Content "$env:USERPROFILE\.cursor-remote\logs\worker.log" -Tail 50
# التحقق مما إذا كان المنفذ قيد الاستخدام بالفعل
netstat -ano | findstr :8473
# التحقق مما إذا كانت عملية worker أخرى قيد التشغيل
Get-Process -Name "node" | Where-Object { $_.CommandLine -like "*remote-worker*" }
الحلول:
- إنهاء أي عملية تستخدم المنفذ 8473:
Stop-Process -Id <PID> -Force - حذف ملف القفل:
Remove-Item "$env:USERPROFILE\.cursor-remote\.lock" - البدء بتسجيل مفصل:
cursor-remote-worker start --log-level debug
worker يبدأ لكن قاعدة البيانات تالفة
العرض: worker يبدأ، لكن جميع العمليات تفشل بأخطاء SQLite.
الحل:
# إيقاف worker
cursor-remote-worker stop-service
# نسخ احتياطي لقاعدة البيانات التالفة
Copy-Item "$env:USERPROFILE\.cursor-remote\state.db" "$env:USERPROFILE\.cursor-remote\state.db.bak"
# حذف قاعدة البيانات التالفة (سيقوم worker بإعادة إنشائها)
Remove-Item "$env:USERPROFILE\.cursor-remote\state.db"
# إعادة تشغيل worker
cursor-remote-worker start-service
قاعدة بيانات الحالة تخزن فقط تاريخ المهام، وحالة worker، والبيانات الوصفية للجلسة. حذفها لا يؤثر على ملفات مشروعك. ستفقد تاريخ المهام البعيدة السابقة، لكن worker سيعمل بشكل طبيعي بعد إعادة إنشاء قاعد ة البيانات.
worker يفقد الاتصال بشكل متقطع
العرض: يمكن لـ CLI الاتصال أحيانًا ولكنه يفشل بشكل عشوائي.
الأسباب والحلول:
- قواعد جدار الحماية مقيّدة جدًا - تأكد من أن القاعدة تسمح بنطاق IP الخاص بوحدة التحكم، وليس عنوان IP واحد فقط
- انتهاء مهلة NAT/الراوتر - إذا كنت تتصل عبر الإنترنت، قد تنتهي صلاحية إدخال جدول NAT. استخدم نفق SSH بدلًا من ذلك
- إدارة الطاقة - قد يضع Windows محول الشبكة في وضع السكون. عطل هذا:
# تعطيل إدارة الطاقة على محول الشبكة
powercfg /devicequery wake_from_any
# ابحث عن محول الشبكة الخاص بك، ثم:
powercfg /devicedisablewake "Your Network Adapter Name"
- تدخل برنامج مكافحة الفيروسات - بعض برامج مكافحة الفيروسات تعترض اتصالات TCP. أضف ملف worker القابل للتنفيذ والمنفذ 8473 إلى الاستثناءات.
مصفوفة توافق الإصدارات
ضمان توافق الإصدارات عبر جميع المكونات أمر حاسم لعمل Remote Control مستقر.
| المكون | الحد الأدنى للإصدار | ملاحظات |
|---|---|---|
| Cursor (المضيف) | 0.45+ | بدأ دعم Remote Control هنا |
| @cursor/remote-worker | 1.0.0+ | حزمة worker |
| @cursor/remote-cli | 1.0.0+ | حزمة CLI |
| Node.js (المضيف) | 18.x, 20.x, 22.x | تجنب 24.x حتى يوفر better-sqlite3 إصدارات 137 |
| Node.js (وحدة التحكم) | 18.x+ | أكثر مرونة، لا وحدات أصلية |
| better-sqlite3 | 11.0.0+ | تحقق من توفر الملفات المسبقة لنسخة Node الخاصة بك |
| Windows | 10 1903+ / 11 | PowerShell 5.1 كحد أدنى |
يجب أن تكون إصدارات worker و CLI متوافقة. قد لا يعمل worker بنسخة v1.0.0 مع CLI بنسخة v1.5.0 إذا كانت هناك تغييرات بروتوكولية. تحقق دائمًا من سجل التغييرات عند ترقية أي من المكونين. إذا قمت بترقية واحد، قم بترقية كليهما.
التحقق من توافق الإصدارات
# على المضيف، تحقق من إصدارات worker وقاعدة البيانات
cursor-remote-worker --version
cursor-remote-worker --check-deps
# على وحدة التحكم، تحقق من إصدار CLI
cursor-remote --version
# التحقق من إصدار Node.js ABI
node -e "console.log(process.versions.modules)"
علامة --check-deps تشغل تشخيصًا يتحقق من:
- توافق نسخة Node.js
- توافق ملف better-sqlite3 الثنائي
- التبعيات المطلوبة للنظام
- توفر المنفذ
- أذونات الكتابة على دليل التكوين
التكوين المتقدم
إعداد نفق SSH
للاتصالات الآمنة عبر الإنترنت، استخدم نفق SSH:
# على وحدة التحكم، إنشاء نفق SSH إلى المضيف
ssh -L 8473:localhost:8473 [email protected] -N
# ثم توصيل CLI بـ localhost
cursor-remote add-host `
--name "win-tunneled" `
--host "127.0.0.1" `
--port 8473 `
--token "auto-generated-token-here" `
--project "H:\Projects\my-app"
هذا ينفق جميع حركة المرور عبر تشفير SSH، وهو أكثر أمانًا بكثير من تعريض المنفذ مباشرة.
تكوين متعدد المضيفين
يمكنك التحكم في أجهزة مضيفة متعددة من وحدة تحكم واحدة:
{
"hosts": [
{
"name": "win-cloud-dev",
"host": "192.168.1.100",
"port": 8473,
"token": "token-1",
"project": "H:\\Projects\\my-app"
},
{
"name": "win-build-server",
"host": "192.168.1.101",
"port": 8473,
"token": "token-2",
"project": "C:\\Builds\\ci-pipeline"
}
]
}
التبديل بين المضيفين:
# تشغيل مهمة على مضيف محدد
cursor-remote agent --host win-build-server --prompt "Fix the failing CI pipeline test"
# سرد جميع المضيفين وحالتهم
cursor-remote hosts --status
حقن متغيرات البيئة
مرر متغيرات البيئة إلى worker لمهام agent:
cursor-remote agent `
--host win-cloud-dev `
--env "DATABASE_URL=Server=prod;Database=myapp;User=admin;Password=secret" `
--env "NODE_ENV=production" `
--prompt "Run the database migration and report results"
متغيرات البيئة الممررة عبر CLI مرئية في قائمة العمليات على كل من جهاز وحدة التحكم والمضيف. لا تمرر أسرار الإنتاج الحقيقية بهذه الطريقة أبدًا. استخدم مدير أسرار أو ملفات متغيرات بيئة بأذونات مقيدة بدلًا من ذلك.
أفضل ممارسات الأمان
- تدوير رمز المصادقة بانتظام:
cursor-remote-worker regenerate-token - استخدام أنفاق SSH لأي اتصال يعبر شبكات غير موثوقة
- تقييد قواعد جدار الحماية على عناوين IP محددة، وليس "أي"
- تشغيل worker كمستخدم غير مسؤول عندما يكون ذلك ممكنًا
- تمكين تسجيل worker ومراجعة السجلات أسبوعيًا للكشف عن أنماط وصول غير متوقعة
- تعطيل worker عند عدم الاستخدام على الأجهزة المشتركة أو السحابية
- الحفاظ على تحديث worker و CLI للحصول على تصحيحات الأمان
الخلاصة
Cursor Remote Control على Windows ميزة قوية توسع التطوير بمساعدة الذكاء الاصطناعي إلى الأجهزة البعيدة وبلا واجهة. يتضمن الإعداد عملية worker على المضيف وCLI على وحدة التحكم، مع التواصل عبر TCP. أكثر الأعطال شيوعًا، better-sqlite3 NODE_MODULE_VERSION 127 vs 137، ينتج عن عدم تطابق نسخ Node.js ويُحل إما بإعادة تجميع الإضافة الأصلية لنسخة Node.js الحالية أو تثبيت worker على تثبيت Node.js محدد. باتباع إرشادات توافق الإصدارات وأفضل ممارسات الأمان في هذا الدليل، يمكنك الحفاظ على إعداد Remote Control مستقر وآمن على Windows.