تخطَّ إلى المحتوى

دليل الوصفات

وصفات عملية للعمل اليومي باستخدام Maguyva MCP. تحدد كل وصفة الأدوات وتسلسلها، وليست مرجعًا كاملًا للمعاملات. راجع مرجع MCP API لمعاملات الأدوات، واستخدم البدء السريع للإعداد لأول مرة.

اختر الأداة المناسبة#

تبدأ معظم الأسئلة باستدعاء واحد. انتقل إلى خطوة أعمق فقط عندما تكون الإجابة الأولى واسعة جدًا أو محدودة جدًا.

  • intelligent_search — ابدأ هنا لأي سؤال بلغة طبيعية عن قاعدة الشفرة؛ فهو يوجّه الطلب بين البحث الدلالي والرمزي والبنيوي وبحث التبعيات.
  • find_symbol — عندما تعرف مسبقًا اسم الدالة أو الفئة أو المتغير.
  • dependency_search — لمعرفة نطاق التأثير: المستدعون والتابعون والأثر قبل التعديل وبعده.
  • get_task_context — لمنطقة غير مألوفة؛ يعيد حزمة محدودة من الملفات والرموز والتبعيات بناءً على وصف المهمة.
  • repository_context — لسرد المستودعات المتاحة أو فحص كيفية تحليل اسم مستودع.
  • ask_maguyva مع operation="guidance" — مساعدة محلية لاختيار الأدوات واستخدام Maguyva من دون تعديل المستودع.

ثبّت العميل وتحقق منه#

أضف Maguyva إلى عميل MCP وتأكد من الاتصال باستخدام قائمة مستودعات حقيقية.

  1. أنشئ مفتاح API في app.maguyva.ai؛ تبدأ المفاتيح بـ mgv_.
  2. صِل مستودع GitHub واحدًا على الأقل تعرفه جيدًا وأنشئ فهرسه.
  3. اضبط عميلك باستخدام دليل التثبيت: إضافة Claude Code أو الإعداد البعيد الأصلي لـ Cursor وVS Code وWindsurf وZed وغيرها.
  4. اسأل وكيلك "ما المستودعات المتصلة لدي؟" — فهذا يختبر المصادقة وrepository_context من البداية إلى النهاية.
  5. اطرح سؤالًا حقيقيًا عن ذلك المستودع يمكنك تقييم إجابته. ينبغي أن ترى مسارات الملفات وأرقام الأسطر من الشجرة المفهرسة.

هل تعطلت عند المفاتيح أو الجسور أو المستودعات المفقودة؟ راجع استكشاف الأخطاء.

اسأل قبل أن تعدّل#

حدّد الرموز ونطاق التأثير قبل تغيير الشفرة المشتركة. لا تعدّل أدوات Maguyva مستودعاتك؛ بل توفّر الأدلة للتعديل الذي يطبقه عميلك محليًا.

  1. إذا كنت تعرف اسم الرمز، فاستدعِ find_symbol للوصول إلى التعريفات ومواضع الاستخدام.
  2. إذا لم يكن لديك سوى وصف للمهمة، مثل «إضافة SSO» أو «إصلاح webhook للفوترة»، فابدأ بـ get_task_context أو intelligent_search.
  3. قبل تعديل رمز مشترك، استدعِ dependency_search لتحليل التابعين أو التأثير، أو مرّر المسارات المتغيرة لتحليل شبيه بطلبات PR، حتى ترى نطاق التأثير.
  4. افتح الملفات المشار إليها — قراءة محلية للملفات على القرص، وget_file للمسارات البعيدة أو عبر المستودعات — ثم طابق الخطة مع الشفرة الفعلية.
  5. بعد التعديل، أعد فحص الرموز نفسها باستخدام dependency_search، بما في ذلك خيارات التحقق بعد التعديل إن دعمها عميلك، للتأكد من استمرار تحليل المستدعين كما هو متوقع.

جميع المعاملات: مرجع MCP API.

ابحث ثم غيّر#

حلقة الوكيل الافتراضية: استكشاف ← تثبيت الرموز ← تعديل مدعوم بالأدلة.

  1. ابدأ بـ intelligent_search واستعلام بلغة عادية، مثل «كيف يعمل انتهاء الجلسة؟» أو «أين منطق إعادة المحاولة؟».
  2. ضيّق النتائج بمرشحات اللغة أو المسار عندما تكون النافذة الأولى مليئة بالضوضاء.
  3. انقل النتائج الواعدة إلى find_symbol أو dependency_search بدل إعادة السؤال الغامض نفسه.
  4. استخدم get_file فقط عندما تحتاج إلى مسار مفهرس محدد غير موجود على القرص.
  5. عدّل بأدوات عميلك المعتادة. Maguyva مخصص للاكتشاف والتحقق، لا للكتابة.

لماذا تنجح هذه الحلقة: كيف يعمل.

نتائج فارغة أو محدودة#

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

  1. تأكد في app.maguyva.ai من اتصال المستودع واكتمال فهرسته.
  2. تحقق من نص المستودع: يستخدم "owner/repo" الفرع الافتراضي، بينما يثبت "owner/repo:branch" فرعًا محددًا. المطابقة لا تميّز حالة الأحرف لكنها ليست تقريبية، لذلك لا تُصحح الأخطاء المطبعية تلقائيًا.
  3. استدعِ repository_context مع action="info" وافحص بيانات التحليل، مثل metadata.resolution_reason.
  4. احذف repository فقط إذا كان عميل MCP يوفّر قيمة افتراضية للطلب أو كان المفتاح يصل إلى مستودع واحد فقط؛ وإلا فمرّره صراحة.
  5. أعد المحاولة باستعلام أدق أو اسم رمز معروف عبر find_symbol أو مرشح لغة/مسار. إذا كان الاتصال نفسه معطلًا، فاستخدم استكشاف الأخطاء.

أعطال الإعداد: استكشاف الأخطاء.

العمل عبر مستودعات متعددة#

استهدف المستودع المفهرس الصحيح عندما يستطيع المفتاح رؤية أكثر من مستودع.

  1. استدعِ repository_context مرة واحدة مع action="list" لمعرفة الأسماء الدقيقة التي يمكن لمفتاحك البحث فيها.
  2. مرّر repository صراحة إلى أدوات البحث والرموز عندما تحتاج إلى مستودع غير افتراضي، مثل "owner/other-repo" أو "owner/other-repo:develop".
  3. اجعل كل سؤال لمستودع واحد، إلا إذا كنت تقارن عمدًا بين المستودعات في استدعاءات منفصلة.
  4. استخدم get_file عندما يكون الملف في مستودع مفهرس لا في شجرة العمل الحالية.
  5. تذكّر: لا تكتب الأدوات إلى GitHub مطلقًا؛ سياق المستودعات المتعددة للقراءة والتخطيط فقط.

تفاصيل تنسيق المستودع: مرجع MCP API.

هل تستخدم Maguyva لأول مرة؟ أكمل البدء السريع أولًا، ثم عُد إلى هنا لحلقات العمل اليومية.

الخطوات التالية#