Composer في Cursor: تحرير متعدد الملفات يعمل فعليًا

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

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

يغطي هذا الدليل سير عمل حقيقية من منتدى Cursor. لا كلام تسويقي. فقط ما يعمل.

Composer مقابل الدردشة العادية: الفرق الحقيقي

الدردشة العادية هي سؤال وجواب. تسأل، يجيب Cursor. أنت ما زلت من ينقل الكود إلى الملفات.

Composer هو فعل. تصف الهدف، يكتشف Cursor الملفات التي يجب تعديلها وما يجب تغييره. يعرض فرقًا. أنت تقرر ما يُطبق.

الميزة	الدردشة العادية	Composer
يقترح الكود	نعم	نعم
يحرر الملفات مباشرة	لا	نعم
تغييرات متعددة الملفات	لا	نعم
يعرض الفرق قبل التطبيق	لا	نعم
نقطة تحقق / استعادة	لا	نعم
الأفضل لـ	الأسئلة، المقتطفات الفردية	إعادة البناء، الميزات، التحديثات المجمعة

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

كيفية فتح Composer

اضغط Cmd/Ctrl + I أو انقر على أيقونة Composer في الشريط الجانبي الأيسر. إنه لوحة منفصلة عن الدردشة — لا تخلط بينهما.

متى تستخدم Composer

يتألق Composer عندما تلمس المهمة أكثر من ملف. السيناريوهات الشائعة:

• إعادة البناء -- إعادة تسمية خاصية عبر المكونات، استخراج أداة مشتركة
• عمل الميزات -- إضافة نقطة نهاية API جديدة تحتاج ملفات المسار، والتحكم، والخدمة، والاختبار
• تحديثات الأنماط -- التبديل من fetch إلى apiClient مخصص في كل مكان
• تغييرات الأنواع -- تحديث واجهة تتموج عبر عشرة ملفات
• تنظيف الاستيرادات -- إعادة تنظيم بنية الوحدة

إذا كنت تنسخ-تلصق كودًا من الدردشة إلى أكثر من ملفين، توقف. استخدم Composer بدلاً من ذلك.

Composer ليس لكل شيء

الأسئلة السريعة، والأسطر الفردية، أو "اشرح هذا regex" -- الدردشة العادية أسرع. Composer له نفقات عامة. احتفظ به للعمل متعدد الملفات.

سير عمل حقيقي 1: إعادة البناء عبر الملفات

لديك نوع User في types.ts. تريد إعادة تسمية name إلى fullName لأنك تضيف حقل displayName والتسمية أصبحت مربكة.

هذا يلمس:

• src/types.ts -- تعريف النوع
• src/components/UserCard.tsx -- يعرض الاسم
• src/components/UserProfile.tsx -- يعرضه أيضًا
• src/api/users.ts -- استدعاءات API التي تستقبل/ترسل الحقل
• src/lib/validators.ts -- مخطط Zod للتحقق من المستخدم

الخطوة 1: افتح Composer (Cmd/Ctrl + I).

الخطوة 2: صف التغيير:

أعد تسمية حقل `name` إلى `fullName` في نوع User وحدّث جميع الاستخدامات عبر قاعدة الكود. لا تغير أي سلوك -- هذه إعادة تسمية خالصة.

الخطوة 3: راجع الفرق المقترح. يعرض Composer كل ملف مع التغييرات مُبرزة. تحقق من أن:

• فقط name المتعلق بالمستخدمين تمت إعادة تسميته (لا خصائص name أخرى)
• طبقة API لا تزال ترسل/تستقبل البيانات الصحيحة
• لم تتسلل أي تغييرات منطقية

الخطوة 4: اقبل أو ارفض لكل ملف. إذا بدا ملف خاطئًا، ارفض فقط ذلك الملف وأصلحه يدويًا.

تحقق من الفرق بعناية

يميل Composer أحيانًا إلى المبالغة. قد يعيد تسمية خاصية name في مكون غير ذي صلة إذا بدا السياق مشابهًا. امسح الفرق دائمًا قبل القبول.

سير عمل حقيقي 2: إضافة ميزة عبر عدة ملفات

تريد إضافة "أدوار المستخدمين" إلى تطبيقك. مستخدمي الإدارة يرون عناصر واجهة إضافية ويمكنهم الوصول إلى نقاط نهاية API إضافية.

الملفات المعنية:

• src/types.ts -- إضافة role: 'user' | 'admin' إلى User
• src/api/auth.ts -- تضمين الدور في حمولة JWT
• src/components/Navbar.tsx -- إظهار رابط الإدارة فقط للمشرفين
• src/components/AdminPanel.tsx -- مكون جديد
• src/hooks/useAuth.ts -- إتاحة علم isAdmin
• src/middleware/auth.ts -- وسيط جديد للتحقق من دور المشرف

الخطوة 1: افتح Composer.

الخطوة 2: أعطه خطة، لا مجرد أمنية:

أضف أدوار المستخدمين إلى التطبيق:

1. أضف `role: 'user' | 'admin'` إلى نوع User في src/types.ts
2. حدّث استجابة تسجيل الدخول في src/api/auth.ts لتتضمن الدور في حمولة JWT
3. أضف قيمة محسوبة `isAdmin` في src/hooks/useAuth.ts
4. حدّث Navbar.tsx ليعرض رابط "Admin" شرطيًا عندما يكون isAdmin صحيحًا
5. أنشئ src/components/AdminPanel.tsx مع لوحة تحكم إدارية مؤقتة
6. أنشئ src/middleware/auth.ts مع وسيط requireAdmin يتحقق من دور JWT

استخدم الأنماط الموجودة في قاعدة الكود. اتبع نفس أسلوب معالجة الأخطاء كملفات API الأخرى.

الخطوة 3: يولد Composer فرقًا متعدد الملفات. راجع كل ملف.

الخطوة 4: إذا بدا AdminPanel.tsx الجديد خاطئًا، ارفضه واحتفظ بالباقي. تعديلات Composer دقيقة.

اطلب خطة أولاً

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

سير عمل حقيقي 3: تحديث استدعاءات API بالجملة

بدأت باستدعاءات fetch خام متناثرة عبر الواجهة الأمامية. الآن لديك apiClient مخصص مع رؤوس المصادقة، ومعالجة الأخطاء، وعنوان URL الأساسي مُهيأ. تحتاج ترحيل كل شيء.

الملفات: عشرات مواقع استدعاء API.

الخطوة 1: تأكد من أن apiClient موجود ويُستورد بشكل صحيح في ملف واحد أولاً. يعمل Composer بشكل أفضل عندما يكون لديه تنفيذ مرجعي.

الخطوة 2: افتح Composer وحدد نطاق المهمة:

استبدل جميع استدعاءات `fetch` الخام في src/ بـ `apiClient` من src/lib/apiClient.ts.

القواعد:
- استخدم طرق `apiClient.get` و `.post` و `.put` و `.delete` الموجودة
- أزل معالجة JSON.stringify و response.json() اليدوية -- يقوم apiClient بذلك
- احتفظ بنفس مسارات نقاط النهاية
- احتفظ بأي رؤوس مخصصة غير موجودة بالفعل في apiClient

ابدأ بدليل src/api/، ثم src/hooks/ إذا لزم الأمر.

الخطوة 3: راجع دفعة بدفعة. لا تقبل 20 ملفًا دفعة واحدة دون النظر. Composer جيد، لكنه ليس مثاليًا.

الخطوة 4: شغل مجموعة الاختبارات بعد القبول. يمكن أن تتباعد أخطاء الأنواع والسلوك في وقت التشغيل حتى عندما يبدو الفرق نظيفًا.

لا ترحل كل شيء دفعة واحدة

إذا كان لديك 50+ ملفًا، قسّمها إلى أجزاء. "رحّل src/api/ أولاً." ثم "رحّل src/hooks/ بعد ذلك." الدفعات الكبيرة أصعب في المراجعة وأسهل في الخطأ.

Composer + وضع الوكيل: الثنائي القوي

يحل Composer ووضع الوكيل مشاكل مختلفة. Composer للتعديلات متعددة الملفات المستهدفة حيث تعرف ما تريد. وضع الوكيل للمهام المفتوحة حيث يحتاج الذكاء الاصطناعي للاستكشاف، وتشغيل الأوامر، ومعرفة الأشياء.

لكنهما يعملان معًا.

النمط: الوكيل يخطط، Composer ينفذ

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

أريد الترحيل من React Context إلى Zustand لإدارة الحالة. اذكر جميع الملفات التي تستخدم AuthContext والتغييرات التي يحتاج كل منها.

يقوم وضع الوكيل بالبحث في قاعدة الكود ويعطيك التفصيل. ثم تفتح Composer وتنفذ التغييرات ملفًا بملف، مع مراجعة الفرق الكامل.

النمط: Composer لإعادة البناء، الوكيل للتحقق

بعد إعادة بناء كبيرة في Composer، حوّل إلى وضع الوكيل:

شغل مجموعة الاختبارات وأصلح أي استيرادات مكسورة أو أخطاء أنواع ناتجة عن إعادة البناء الأخيرة.

يتولى وضع الوكيل التنظيف بينما تراجع تغييرات Composer.

وضع الوكيل يمكنه استخدام Composer

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

الأخطاء الشائعة وكيفية تجنبها

1. موجهات غامضة

سيئ: "اجعل المصادقة أفضل."

جيد: "أضف حقل role إلى نوع User، حدّث API تسجيل الدخول لتضمينه في JWT، واعرض رابطًا للإدارة في Navbar لمستخدمي الإدارة."

التحديد يقلل المفاجآت.

2. القبول دون مراجعة

قد تبدو فرق Composer نظيفة، لكنها قد:

• تحذف تعليقًا أردت الاحتفاظ به
• تغير التنسيق في أسطر غير ذات صلة
• تفوت حالة حافة في ملف واحد

امسح الفرق دائمًا. يستغرق 30 ثانية ويوفر إعادة العمل.

3. ملفات كثيرة جدًا دفعة واحدة

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

4. عدم استخدام نقاط التحقق

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

نقاط التحقق ليست عمليات Git Commit

نقاط تحقق Composer تعيش داخل Cursor. إنها لا تحل محل git. قم بالتزام git أيضًا قبل عمل Composer كبير. استخدم كلا شبكتي الأمان.

5. تجاهل أخطاء الأنواع بعد التغييرات

تترجم تعديلات Composer ربما 90% من الوقت. الـ 10% الأخرى تُدخل عدم تطابقات أنواع دقيقة، خاصة عند إعادة التسمية أو تغيير الواجهات. شغّل tsc أو linter بعد قبول التغييرات.

مرجع سريع

الإجراء	الاختصار
فتح Composer	Cmd/Ctrl + I
قبول التغيير	Cmd/Ctrl + Y
رفض التغيير	Cmd/Ctrl + N
إنشاء نقطة تحقق	انقر على أيقونة نقطة التحقق في لوحة Composer
الاستعادة إلى نقطة تحقق	انقر على أيقونة الاستعادة بجانب نقطة التحقق

الملخص

• استخدم Composer للتعديلات متعددة الملفات. استخدم الدردشة العادية للأسئلة.
• صف بالضبط ما تريد. تضمين مسارات الملفات والقيود.
• راجع كل فرق قبل القبول.
• أنشئ نقاط تحقق قبل الجلسات الكبيرة.
• قسّم المهام الكبيرة إلى أجزاء.
• اجمع Composer مع وضع الوكيل: الوكيل يستكشف، Composer ينفذ.

Composer ليس سحرًا. إنه أداة تزيل ضريبة النسخ-للصق من العمل متعدد الملفات. عند استخدامه بشكل صحيح، يوفر ساعات. عند الاستخدام بإهمال، يخلق عمل تنظيف. الفرق يكمن في خطوة المراجعة -- لا تتخطاها.