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

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

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

يُرجى توفير إجابة واضحة

يقدّم الوكيل أفضل أداء عند تزويده بتعليمات واضحة ومحدّدة. إذا كانت هناك مكتبات أو واجهات برمجة تطبيقات أو نُهج معيّنة تريد استخدامها، يمكنك تضمينها في سؤالك أو في ملف AGENTS.md الجذر لمشروعك للاحتفاظ بها في جميع التفاعلات. يمكنك اعتبار ذلك بمثابة تقديم تقرير خطأ: كلما زادت المعلومات التي تقدمها، زادت سرعة وفعالية حل المشكلة.

تنفيذ وظائف جديدة:

الإجراءات المطلوبة

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

الإجراءات غير المُوصى بها

كيف يمكنني إضافة ميزة استخدام الكاميرا إلى تطبيقي؟

إنشاء الرموز البرمجية:

الإجراءات المطلوبة

اكتب دالة تعليق في Kotlin تستخدم مكتبة Coil لتنزيل صورة من سلسلة عنوان URL معيّن.

يجب أن تكون الدالة باسم fetchImageAsBitmap. يجب أن تأخذ الدالة عنوان URL من النوع Context وString كوسيطات وأن تعرض قيمة Bitmap يمكن أن تكون فارغة. في حال حدوث أي خطأ في الشبكة أو في فك الترميز، يجب أن يرصد الاستثناء ويسجّله ويعرض null.

الإجراءات غير المُوصى بها

اكتُب دالة لتنزيل صورة.

شرح مفهوم:

الإجراءات المطلوبة

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

ما هي الخيارات المتاحة لي لإبقاء تطبيقي قيد التشغيل أثناء قيام المستخدم بأشياء أخرى على الجهاز؟ ما هي متطلبات مستوى واجهة برمجة التطبيقات وتأثيرات عمر البطارية لكل نهج؟

الإجراءات غير المُوصى بها

شرح خدمات Android

وصف بنية الإجابة

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

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

تنظيم الردّ:

الإجراءات المطلوبة

أنشئ كيان غرفة لملف مستخدم شخصي. ويجب أن يحتوي على الحقول id وuserName وemail وmemberSince. يجب إنشاء حقل id تلقائيًا. يجب أن يمثّل الحقل memberSince طابعًا زمنيًا.

الإجراءات غير المُوصى بها

أنشئ كيان غرفة لملف مستخدم شخصي.

إذا كنت تطرح سؤالاً مفتوحًا، اطلب من Gemini تقديم عدد x من الخيارات.

تحديد الردّ:

الإجراءات المطلوبة

ما هي الأدوات المتاحة لتحسين أداء التطبيق؟ أريد قائمة بأفضل ثلاثة.

الإجراءات غير المُوصى بها

ما هي الأدوات المتاحة لتحسين أداء التطبيق؟

تقسيم الطلبات المعقّدة إلى مهام أصغر

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

تطبيق الطلبات المتسلسلة:

الإجراءات المطلوبة

الطلب 1: نموذج البيانات
أولاً، أنشئ فئة بيانات Kotlin باسم User. ويجب أن يتضمّن ثلاث سمات: id (عدد صحيح) وname (سلسلة) وemail (سلسلة).

الطلب 2: طبقة الشبكة
الآن، أنشئ واجهة برمجة تطبيقات Retrofit باسم ApiService. يجب أن تتضمّن دالة suspend fun واحدة تُسمى getUsers() وتعرض List<User>.

الطلب 3: إدارة الحالة
بعد ذلك، اكتب UsersViewModel يعتمد على ApiService. يجب أن يعرض UsersViewModel StateFlow لفئة UiState مغلقة يمكنها تمثيل حالات Loading, Success(users: List) وError(message: String). أنشئ دالة في ViewModel لجلب المستخدمين وتعديل الحالة. اكتب اختبارات الوحدة للوظيفة الجديدة.

الطلب 4: طبقة واجهة المستخدم
أخيرًا، اكتب دالة Jetpack Compose باسم UserListScreen تقبل UiState كمَعلمة. استخدِم عبارة when لعرض CircularProgressIndicator لحالة التحميل، و LazyColumn لأسماء المستخدمين لحالة النجاح، وعنصر Text مع رسالة الخطأ لحالة الخطأ. أضِف اختبارات للتحقّق من الوظائف الجديدة.

الإجراءات غير المُوصى بها

أنشئ شاشة Jetpack Compose تجلب قائمة بالمستخدمين من واجهة برمجة تطبيقات JSON وتعرضهم في قائمة. يجب أن يتضمّن ViewModel يستخدم Retrofit والروتينات المرافقة، ومستودعًا لمعالجة منطق البيانات، وفئة بيانات User، ويجب أن يعرض حالات التحميل والخطأ.

إدارة السياق

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

  • أرفِق صورًا لتقديم عرض مرئي لواجهة المستخدم التي تتصوّرها أو بنية التطبيق التي تحاول فهمها.
  • أرفِق ملفات لإبراز الأجزاء ذات الصلة من قاعدة الرموز البرمجية.
  • استخدِم ملفات .aiexclude لجعل الوكيل يتجاهل أجزاء معيّنة من قاعدة الرموز البرمجية.
  • استخدِم ملفات AGENTS.md لتقديم تعليمات خاصة بالمشروع ومشاركتها مع فريقك. عند استخدام ملفات AGENTS.md، استخدِم عناوين وتنسيقات Markdown لتوضيح تعليماتك.
  • عند استخدام "وضع الوكيل"، يمكنك ضبط خوادم MCP لتوسيع نطاق معرفة الوكيل وإمكاناته من خلال البيئة الخارجية.

طلب تفسيرات

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

تكرار التعليمات

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