مرجع MCP API

مرجع كامل لجميع أدوات Maguyva MCP الموجّهة للعملاء وعددها 11. تتضمن كل أداة المعاملات وإرشادات الاستخدام وتوصيات الاستخدام الأمثل.

نظرة عامة على API#

تكشف واجهة Maguyva MCP API حاليًا عن 11 أداة موجّهة للعملاء موزّعة على 4 فئات رئيسية:

أدوات البحث الأساسية - قدرات بحث متقدمة عبر قاعدة الكود الخاصة بك
أدوات البنية والرسم البياني - استعلامات AST، وبحث عن الرموز، وتحليل الاعتماديات
أدوات تحليل الكود - تحليل عميق للكود ورسم خرائط العلاقات
أدوات النظام والأدوات المساعدة - سياق المستودع، والحوسبة الحتمية، والإرشاد

تستخدم جميع الأدوات صيغة معرّف المستودع موحّدة: "owner/repo:branch". يكون الفرع افتراضيًا main إن لم يُحدَّد.

احذف repository عندما يوفّر عميل MCP قيمة افتراضية على مستوى الطلب أو عندما يمكن للمفتاح الوصول إلى مستودع واحد فقط؛ وإلا فمرِّره صراحةً. استخدم repository_context(action="info", repository="owner/repo") لفحص كيفية حلّ المستودع.

صيغة معامل المستودع#

تستخدم جميع أدوات MCP صيغة معرّف المستودع التالية:

مع فرع محدد: "owner/repo:branch" - مثال: "owner/repository:develop"
الفرع الافتراضي: "owner/repo" - يُستخدم الفرع الرئيسي main عند عدم تحديد فرع "owner/repository"
الإعداد الافتراضي للطلب أو للمستودع الوحيد: لا تمرّر معامل repository عندما يوفّر عميل MCP إعدادًا افتراضيًا للطلب أو عندما يستطيع المفتاح الوصول إلى مستودع واحد فقط؛ وإلا فمرِّره صراحةً.

أمثلة على المطالبات:

اسأل عن مستودع معيّن:     "ابحث في owner/my-repo عن وسيط المصادقة"
اسرد المستودعات المتاحة:  "ما المستودعات التي يمكن لمفتاح Maguyva هذا الوصول إليها؟"
تجاوز لاستعلام واحد:      "ابحث في owner/other-repo:develop عن أنماط المصادقة"

تصفية اللغة#

تدعم جميع أدوات البحث تصفية النتائج حسب لغة البرمجة:

language_filter="python" - التصفية لملفات Python فقط
language_filter="typescript" - التصفية لملفات TypeScript فقط
حساسية حالة الأحرف: استخدم أسماء اللغات بأحرف صغيرة
الافتراضي: سلسلة نصية فارغة (بلا تصفية) - تُعيد نتائج من جميع اللغات
التغطية المدعومة: تعمل عوامل تصفية اللغة عبر كامل 279+ من لغات وتقنيات نصية المدعومة. راجع التوافق للاطلاع على القائمة الكاملة.

"ابحث عن الطبقة الوسيطة للمصادقة في ملفات Python فقط"
"ابحث عن اتصالات قاعدة البيانات في TypeScript"

تم إنشاء مرجع API من المصدر بتاريخ 22 يوليو 2026.

أدوات البحث الأساسية#

intelligent_searchمستقر

ابدأ هنا لأي سؤال حول قاعدة التعليمات البرمجية. أعطه استعلامًا باللغة الطبيعية (على سبيل المثال، "كيف تعمل المصادقة"، "أين تتم معالجة الفواتير") ويتم توجيهه تلقائيًا عبر البحث الدلالي والرمزي والهيكلي والبحث عن التبعية في الريبو المفهرس. تفضل هذا على وكيل Explore وGrep/Glob للاستكشاف والتخطيط - فهو يبحث في الريبو المفهرس بالكامل مرة واحدة بدلاً من فحص الملفات.

المعاملات:

queryمطلوب

النوع: str
الوصف: استعلام البحث

repositoryاختياري

النوع: str
الوصف: المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.

modeاختياري

النوع: Literal[auto, hybrid, semantic, text, structural, ast, graph]
الافتراضي: auto
الوصف: نمط البحث

limitاختياري

النوع: int
الافتراضي: 10
الوصف: الحد الأقصى للنتائج في نافذة top-K المرتّبة هذه

language_filterاختياري

النوع: str
الوصف: فلتر اللغة

path_filterاختياري

النوع: str
الوصف: تصفية حسب بادئة مسار الملف

boost_by_importanceاختياري

النوع: bool
الافتراضي
الوصف: اختياري: أعِد الترتيب حسب المركزية باستخدام مقاييس الرسم البياني لكل رمز (is_articulation_point، bridge_count، k_core، centrality، إلخ). مُعطَّل افتراضيًا لترتيب آمن للوكلاء (قد تُغرِق المحاور العامة نتائج التنفيذ)؛ فعِّله لجولات المعمارية. ينطبق عبر جميع الأنماط الأربعة عندما تحمل كل نتيجة ارتباطًا رمزيًا.

branchاختياري

النوع: str
الوصف: تجاوز الفرع

qualityاختياري

النوع: Literal[quick, balanced, thorough]
الافتراضي: balanced
الوصف: قالب جودة البحث

include_contentاختياري

النوع: bool
الافتراضي: true
الوصف: تضمين المحتوى في النتائج

explain_routingاختياري

النوع: bool
الافتراضي
الوصف: تضمين شرح قرار التوجيه

importance_weightاختياري

النوع: float
الافتراضي: 0.3
الوصف: وزن تعزيز الأهمية (0=لا شيء، 1=كامل)

orphansاختياري

النوع: bool
الافتراضي
الوصف: تضمين الرموز اليتيمة (بدون إشارات واردة)

include_community_contextاختياري

النوع: bool
الافتراضي
الوصف: تضمين رموز ذات صلة من نفس مجتمع الكود

community_depthاختياري

النوع: int
الافتراضي: 1
الوصف: عمق توسيع سياق المجتمع

graph_viewاختياري

النوع: Literal[dependency, type, data_flow, control_flow]
الافتراضي: dependency
الوصف: عرض الرسم البياني للمقاييس

seed_symbol_idsاختياري

النوع: list[str]
الوصف: بذور المهام Tier-1: معرفات الرموز المركزية للمهمة الحالية. عند التعيين، يتم إعادة ترتيب النتائج المدمجة حسب القرب من اضمحلال العمق Approach A (تطابق البذور الدقيق + قفزات حافة الرسم البياني). المضافة - حذف التصنيف العالمي.

seed_file_pathsاختياري

النوع: list[str]
الوصف: بذور المهام Tier-1: مسارات الملفات المفهرسة التي فتحها الوكيل أو قام بتحريرها للتو. عند التعيين، قم بإعادة ترتيب النتائج المدمجة حسب قرب المسار باستخدام 1/(1+d) لتحلل العمق (نفس الملف → نفس الدليل → الحزم القريبة). المضافة - حذف التصنيف العالمي.

المعامل	النوع	مطلوب	الافتراضي	الوصف
`query`	`str`	نعم	-	استعلام البحث
`repository`	`str`	لا	-	المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.
`mode`	`Literal[auto, hybrid, semantic, text, structural, ast, graph]`	لا	`auto`	نمط البحث
`limit`	`int`	لا	`10`	الحد الأقصى للنتائج في نافذة top-K المرتّبة هذه
`language_filter`	`str`	لا	-	فلتر اللغة
`path_filter`	`str`	لا	-	تصفية حسب بادئة مسار الملف
`boost_by_importance`	`bool`	لا		اختياري: أعِد الترتيب حسب المركزية باستخدام مقاييس الرسم البياني لكل رمز (is_articulation_point، bridge_count، k_core، centrality، إلخ). مُعطَّل افتراضيًا لترتيب آمن للوكلاء (قد تُغرِق المحاور العامة نتائج التنفيذ)؛ فعِّله لجولات المعمارية. ينطبق عبر جميع الأنماط الأربعة عندما تحمل كل نتيجة ارتباطًا رمزيًا.
`branch`	`str`	لا	-	تجاوز الفرع
`quality`	`Literal[quick, balanced, thorough]`	لا	`balanced`	قالب جودة البحث
`include_content`	`bool`	لا	`true`	تضمين المحتوى في النتائج
`explain_routing`	`bool`	لا		تضمين شرح قرار التوجيه
`importance_weight`	`float`	لا	`0.3`	وزن تعزيز الأهمية (0=لا شيء، 1=كامل)
`orphans`	`bool`	لا		تضمين الرموز اليتيمة (بدون إشارات واردة)
`include_community_context`	`bool`	لا		تضمين رموز ذات صلة من نفس مجتمع الكود
`community_depth`	`int`	لا	`1`	عمق توسيع سياق المجتمع
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	لا	`dependency`	عرض الرسم البياني للمقاييس
`seed_symbol_ids`	`list[str]`	لا	-	بذور المهام Tier-1: معرفات الرموز المركزية للمهمة الحالية. عند التعيين، يتم إعادة ترتيب النتائج المدمجة حسب القرب من اضمحلال العمق Approach A (تطابق البذور الدقيق + قفزات حافة الرسم البياني). المضافة - حذف التصنيف العالمي.
`seed_file_paths`	`list[str]`	لا	-	بذور المهام Tier-1: مسارات الملفات المفهرسة التي فتحها الوكيل أو قام بتحريرها للتو. عند التعيين، قم بإعادة ترتيب النتائج المدمجة حسب قرب المسار باستخدام 1/(1+d) لتحلل العمق (نفس الملف → نفس الدليل → الحزم القريبة). المضافة - حذف التصنيف العالمي.

الأنسب لـ:

الاستكشاف على نطاق الفهرس بالكامل أو من نقطة الصفر عندما تكون الأداة المناسبة غير واضحة
ترتيب مدمج متعدد الأنماط عبر الدلالة والنص والبنية والرسم البياني

غير مُوصى به لـ:

اسم رمز معروف — استخدم find_symbol مباشرة
مسار معروف على القرص — استخدم Read/Grep المحلي أولاً

semantic_searchمستقر

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

المعاملات:

queryمطلوب

النوع: str
الوصف: استعلام البحث (مفاهيمي، قائم على المعنى)

repositoryاختياري

النوع: str
الوصف: المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.

limitاختياري

النوع: int
الافتراضي: 5
الوصف: الحد الأقصى للنتائج في نافذة top-K المرتّبة هذه

similarity_thresholdاختياري

النوع: float
الافتراضي: 0.6
الوصف: الحد الأدنى لدرجة التشابه

language_filterاختياري

النوع: str
الوصف: فلتر اللغة (python، typescript، إلخ)

path_filterاختياري

النوع: str
الوصف: تصفية بحسب بادئة مسار الملف

boost_by_importanceاختياري

النوع: bool
الافتراضي
الوصف: اختياري: أعِد الترتيب حسب مركزية PageRank (مُعطَّل افتراضيًا لترتيب آمن للوكلاء؛ فعِّله لجولات المعمارية)

branchاختياري

النوع: str
الوصف: تجاوز الفرع (افتراضي: من معامل repository أو main)

include_contentاختياري

النوع: bool
الافتراضي: true
الوصف: تضمين محتوى المقطع في النتائج

graph_viewاختياري

النوع: Literal[dependency, type, data_flow, control_flow]
الافتراضي: dependency
الوصف: عرض الرسم البياني للمقاييس

المعامل	النوع	مطلوب	الافتراضي	الوصف
`query`	`str`	نعم	-	استعلام البحث (مفاهيمي، قائم على المعنى)
`repository`	`str`	لا	-	المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.
`limit`	`int`	لا	`5`	الحد الأقصى للنتائج في نافذة top-K المرتّبة هذه
`similarity_threshold`	`float`	لا	`0.6`	الحد الأدنى لدرجة التشابه
`language_filter`	`str`	لا	-	فلتر اللغة (python، typescript، إلخ)
`path_filter`	`str`	لا	-	تصفية بحسب بادئة مسار الملف
`boost_by_importance`	`bool`	لا		اختياري: أعِد الترتيب حسب مركزية PageRank (مُعطَّل افتراضيًا لترتيب آمن للوكلاء؛ فعِّله لجولات المعمارية)
`branch`	`str`	لا	-	تجاوز الفرع (افتراضي: من معامل repository أو main)
`include_content`	`bool`	لا	`true`	تضمين محتوى المقطع في النتائج
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	لا	`dependency`	عرض الرسم البياني للمقاييس

الأنسب لـ:

استعلامات مفاهيمية ("how does auth work?", "caching strategy")
بحث التشابه عبر الحزم

غير مُوصى به لـ:

اسم رمز معروف — استخدم find_symbol بدلاً من ذلك
سلاسل نصية دقيقة أو رسائل خطأ — استخدم text_pattern_search

text_pattern_searchمستقر

ابحث في المحتوى المفهرَس. أوضاع exact وregex تفحص الملف/البلوب الكامل؛ وضع fuzzy يبحث في مقاطع دلالية محدودة. نطاقات الملف والرمز متاحة لطور fuzzy فقط. استخدم grep محليًا للمجلد الموجود على القرص.

المعاملات:

queryمطلوب

النوع: str
الوصف: نمط نصي للبحث

repositoryاختياري

النوع: str
الوصف: المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.

modeاختياري

النوع: Literal[fuzzy, exact, regex]
الافتراضي: exact
الوصف: نمط البحث

search_scopeاختياري

النوع: Literal[content, symbols, files]
الافتراضي: content
الوصف: ما الذي تُجري عليه البحث

limitاختياري

النوع: int
الافتراضي: 5
الوصف: الحد الأقصى للنتائج المُعادة في هذه الصفحة

offsetاختياري

النوع: int
الوصف: إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.

cursorاختياري

النوع: str
الوصف: مؤشّر معتِم (cursor) من pagination.next_cursor. مرِّره دون تغيير وأبقِ الاستعلام والفلاتر دون تغيير.

language_filterاختياري

النوع: str
الوصف: فلتر اللغة

path_filterاختياري

النوع: str
الوصف: تصفية بحسب بادئة مسار الملف

case_sensitiveاختياري

النوع: bool
الافتراضي
الوصف: مطابقة حساسة لحالة الأحرف

branchاختياري

النوع: str
الوصف: تجاوز الفرع

fuzzy_algorithmاختياري

النوع: Literal[hybrid, trigram, levenshtein]
الافتراضي: hybrid
الوصف: خوارزمية المطابقة التقريبية

thresholdاختياري

النوع: float
الافتراضي: 0.05
الوصف: حد التشابه الأدنى للمطابقة التقريبية

semantic_fallbackاختياري

النوع: bool
الافتراضي
الوصف: الرجوع إلى البحث الدلالي إذا لم توجد نتائج

المعامل	النوع	مطلوب	الافتراضي	الوصف
`query`	`str`	نعم	-	نمط نصي للبحث
`repository`	`str`	لا	-	المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.
`mode`	`Literal[fuzzy, exact, regex]`	لا	`exact`	نمط البحث
`search_scope`	`Literal[content, symbols, files]`	لا	`content`	ما الذي تُجري عليه البحث
`limit`	`int`	لا	`5`	الحد الأقصى للنتائج المُعادة في هذه الصفحة
`offset`	`int`	لا	-	إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.
`cursor`	`str`	لا	-	مؤشّر معتِم (cursor) من pagination.next_cursor. مرِّره دون تغيير وأبقِ الاستعلام والفلاتر دون تغيير.
`language_filter`	`str`	لا	-	فلتر اللغة
`path_filter`	`str`	لا	-	تصفية بحسب بادئة مسار الملف
`case_sensitive`	`bool`	لا		مطابقة حساسة لحالة الأحرف
`branch`	`str`	لا	-	تجاوز الفرع
`fuzzy_algorithm`	`Literal[hybrid, trigram, levenshtein]`	لا	`hybrid`	خوارزمية المطابقة التقريبية
`threshold`	`float`	لا	`0.05`	حد التشابه الأدنى للمطابقة التقريبية
`semantic_fallback`	`bool`	لا		الرجوع إلى البحث الدلالي إذا لم توجد نتائج

الأنسب لـ:

سلاسل نصية دقيقة ورسائل خطأ وتعبيرات نمطية (regex)
مطابقة تقريبية بالثلاثيات (trigram) للنص شبه المتطابق

غير مُوصى به لـ:

مسار معروف على القرص — يُفضَّل استخدام Grep المحلي
استعلامات مفاهيمية — استخدم semantic_search

أدوات البحث البنيوي والرسم البياني#

structural_searchمستقر

يُفضَّل استخدام preset=functions|classes|methods|imports|variables (أو pattern= الحر). ابحث عن الكود حسب شكل AST (لا النص). فلاتر المستوى المتوسط: name_pattern، node_type، decorator، parent_child. فلاتر path/ltree/call متقدمة — اضبط advanced=true عند استخدامها عمدًا؛ لا تزال مفاتيح advanced المسطّحة مقبولة للتوافق الخلفي. قدِّم محدِّدًا بنيويًا واحدًا على الأقل.

المعاملات:

repositoryاختياري

النوع: str
الوصف: المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.

presetاختياري

النوع: Literal[functions, classes, methods, imports, variables]
الوصف: المحدِّد البنيوي المُفضَّل. يتوسّع إلى أنواع عُقَد AST متعددة اللغات — functions (تعريفات function/arrow/method عبر اللغات)؛ classes (تعريفات class/struct/impl)؛ methods (تعريفات method (وfunction_definition للغات التي لا تملك عُقدة method))؛ imports (عبارات import/use/include)؛ variables (تصريحات variable/let/const/static). يُفضَّل على pattern/node_type الحرّين لاستعلامات التصفّح.

patternاختياري

النوع: str
الوصف: نمط حر عندما تكون الإعدادات المُسبقة خشنة أكثر من اللازم (يُكتشف تلقائيًا: 'def foo(' → node_type + name_pattern). يُفضَّل استخدام preset= لاستعلامات التصفّح.

name_patternاختياري

النوع: str
الوصف: نمط اسم الرمز (بدل shell، أو تعبير POSIX regex محدود، أو نص تقريبي؛ 256 حرفًا كحد أقصى)

node_typeاختياري

النوع: str
الوصف: نوع عُقدة AST (function_definition، class_definition، إلخ) — يُفضَّل استخدام preset= للأشكال الشائعة

decoratorاختياري

النوع: str
الوصف: فلتر اسم الديكوريتور

base_classاختياري

النوع: str
الوصف: فلتر اسم الفئة الأساسية

language_filterاختياري

النوع: str
الوصف: فلتر اللغة

limitاختياري

النوع: int
الافتراضي: 20
الوصف: الحد الأقصى للنتائج المُعادة في هذه الصفحة

offsetاختياري

النوع: int
الوصف: إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.

cursorاختياري

النوع: str
الوصف: مؤشّر معتِم (cursor) من pagination.next_cursor. مرِّره دون تغيير وأبقِ الاستعلام والفلاتر دون تغيير.

path_filterاختياري

النوع: str
الوصف: تصفية بحسب بادئة مسار الملف

branchاختياري

النوع: str
الوصف: تجاوز الفرع

query_typeاختياري

النوع: Literal[node_type, name_pattern, parent_child]
الوصف: نوع الاستعلام الصريح

parent_typeاختياري

النوع: str
الوصف: فلتر نوع عقدة الأصل في AST

relationshipاختياري

النوع: Literal[parent, ancestor]
الافتراضي: parent
الوصف: لـ parent_child: الأصل المباشر فقط، أو أي سلف (استخدم ancestor لطرق داخل كتلة فئة)

has_modifierاختياري

النوع: str
الوصف: تصفية حسب المُعدِّل (export، async، static، إلخ)

advancedاختياري

النوع: bool
الافتراضي
الوصف: قم بتعيين true عند استخدام مرشحات المسار المتقدم أو ltree أو مرشحات الاتصال عمدًا (ltree_ancestor، ltree_descendant، min_depth، max_depth، field_role، definition_name، callee_text، callee_name). بشكل افتراضي، تحافظ false على تركيز واجهة الوكيل على الإعدادات المسبقة. لا تزال المفاتيح المتقدمة ذات التنسيق المسطح تعمل من أجل التوافق مع الإصدارات السابقة، مع تحذير بشأن البيانات التعريفية.

callee_textاختياري

النوع: str
الوصف: متقدم — يُفضَّل استخدام preset=functions|classes|methods|imports|variables. فلتر نص المُستدعى (callee) في تعبير الاستدعاء. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.

callee_nameاختياري

النوع: str
الوصف: متقدم — يُفضَّل استخدام preset=functions|classes|methods|imports|variables. فلتر اسم المُستدعى (callee) في تعبير الاستدعاء. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.

field_roleاختياري

النوع: str
الوصف: متقدم — يُفضَّل استخدام preset=functions|classes|methods|imports|variables. فلتر دور حقل AST. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.

ltree_ancestorاختياري

النوع: str
الوصف: متقدم — يُفضَّل استخدام preset=functions|classes|methods|imports|variables. فلتر مسار السلف ltree في AST. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.

ltree_descendantاختياري

النوع: str
الوصف: متقدم — يُفضَّل استخدام preset=functions|classes|methods|imports|variables. فلتر مسار الخلف ltree في AST. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.

definition_nameاختياري

النوع: str
الوصف: متقدم — يُفضَّل استخدام preset=functions|classes|methods|imports|variables. فلتر اسم التعريف. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.

min_depthاختياري

النوع: int
الوصف: متقدم — يُفضَّل استخدام preset=functions|classes|methods|imports|variables. أدنى عمق لـ AST. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.

max_depthاختياري

النوع: int
الوصف: متقدم — يُفضَّل استخدام preset=functions|classes|methods|imports|variables. أقصى عمق لـ AST. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.

المعامل	النوع	مطلوب	الافتراضي	الوصف
`repository`	`str`	لا	-	المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.
`preset`	`Literal[functions, classes, methods, imports, variables]`	لا	-	المحدِّد البنيوي المُفضَّل. يتوسّع إلى أنواع عُقَد AST متعددة اللغات — functions (تعريفات function/arrow/method عبر اللغات)؛ classes (تعريفات class/struct/impl)؛ methods (تعريفات method (وfunction_definition للغات التي لا تملك عُقدة method))؛ imports (عبارات import/use/include)؛ variables (تصريحات variable/let/const/static). يُفضَّل على pattern/node_type الحرّين لاستعلامات التصفّح.
`pattern`	`str`	لا	-	نمط حر عندما تكون الإعدادات المُسبقة خشنة أكثر من اللازم (يُكتشف تلقائيًا: 'def foo(' → node_type + name_pattern). يُفضَّل استخدام preset= لاستعلامات التصفّح.
`name_pattern`	`str`	لا	-	نمط اسم الرمز (بدل shell، أو تعبير POSIX regex محدود، أو نص تقريبي؛ 256 حرفًا كحد أقصى)
`node_type`	`str`	لا	-	نوع عُقدة AST (function_definition، class_definition، إلخ) — يُفضَّل استخدام preset= للأشكال الشائعة
`decorator`	`str`	لا	-	فلتر اسم الديكوريتور
`base_class`	`str`	لا	-	فلتر اسم الفئة الأساسية
`language_filter`	`str`	لا	-	فلتر اللغة
`limit`	`int`	لا	`20`	الحد الأقصى للنتائج المُعادة في هذه الصفحة
`offset`	`int`	لا	-	إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.
`cursor`	`str`	لا	-	مؤشّر معتِم (cursor) من pagination.next_cursor. مرِّره دون تغيير وأبقِ الاستعلام والفلاتر دون تغيير.
`path_filter`	`str`	لا	-	تصفية بحسب بادئة مسار الملف
`branch`	`str`	لا	-	تجاوز الفرع
`query_type`	`Literal[node_type, name_pattern, parent_child]`	لا	-	نوع الاستعلام الصريح
`parent_type`	`str`	لا	-	فلتر نوع عقدة الأصل في AST
`relationship`	`Literal[parent, ancestor]`	لا	`parent`	لـ parent_child: الأصل المباشر فقط، أو أي سلف (استخدم ancestor لطرق داخل كتلة فئة)
`has_modifier`	`str`	لا	-	تصفية حسب المُعدِّل (export، async، static، إلخ)
`advanced`	`bool`	لا		قم بتعيين true عند استخدام مرشحات المسار المتقدم أو ltree أو مرشحات الاتصال عمدًا (ltree_ancestor، ltree_descendant، min_depth، max_depth، field_role، definition_name، callee_text، callee_name). بشكل افتراضي، تحافظ false على تركيز واجهة الوكيل على الإعدادات المسبقة. لا تزال المفاتيح المتقدمة ذات التنسيق المسطح تعمل من أجل التوافق مع الإصدارات السابقة، مع تحذير بشأن البيانات التعريفية.
`callee_text`	`str`	لا	-	متقدم — يُفضَّل استخدام preset=functions\|classes\|methods\|imports\|variables. فلتر نص المُستدعى (callee) في تعبير الاستدعاء. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.
`callee_name`	`str`	لا	-	متقدم — يُفضَّل استخدام preset=functions\|classes\|methods\|imports\|variables. فلتر اسم المُستدعى (callee) في تعبير الاستدعاء. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.
`field_role`	`str`	لا	-	متقدم — يُفضَّل استخدام preset=functions\|classes\|methods\|imports\|variables. فلتر دور حقل AST. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.
`ltree_ancestor`	`str`	لا	-	متقدم — يُفضَّل استخدام preset=functions\|classes\|methods\|imports\|variables. فلتر مسار السلف ltree في AST. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.
`ltree_descendant`	`str`	لا	-	متقدم — يُفضَّل استخدام preset=functions\|classes\|methods\|imports\|variables. فلتر مسار الخلف ltree في AST. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.
`definition_name`	`str`	لا	-	متقدم — يُفضَّل استخدام preset=functions\|classes\|methods\|imports\|variables. فلتر اسم التعريف. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.
`min_depth`	`int`	لا	-	متقدم — يُفضَّل استخدام preset=functions\|classes\|methods\|imports\|variables. أدنى عمق لـ AST. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.
`max_depth`	`int`	لا	-	متقدم — يُفضَّل استخدام preset=functions\|classes\|methods\|imports\|variables. أقصى عمق لـ AST. اضبط advanced=true عند استخدام فلاتر path/ltree/call عمدًا.

الأنسب لـ:

البنية على مستوى AST: الأصناف والمُزخرِفات والإعدادات المسبقة للدوال/الطرق
العثور على الكود حسب شكله بدلاً من نصّه

غير مُوصى به لـ:

استعلامات نص حر أو مفاهيمية — استخدم semantic_search أو intelligent_search

dependency_searchمستقر

السطح الأساسي لنطاق التأثير / الرسم البياني. أجِب عن "ما الذي يستدعي هذا؟" / "ما الذي يستخدمه هذا؟" عبر رسم الاستدعاء/الاستيراد الحقيقي. للتأثير قبل التعديل: analysis_type="dependents" أو analysis_type="impact" (وارد، والعمق الضحل هو الافتراضي لـ impact)، وinclude_metrics=false افتراضيًا (اختَر تضمينه للمركزية + refactor_risk). تأثير PR/diff (P1-8): مرِّر changed_paths و/أو patch (فرق موحّد) — يحلّ الرموز لكل مسار ويعيد حمولة dependents وارِدة ضحلة مُدمجة دون الحاجة إلى اسم رمز. بعد التعديل، اضبط verify_after_edit=true مع targets و/أو changed_paths لإعادة استعلام مُدمجة متعددة الجذور للرموز المتأثرة. يدعم أيضًا dependencies وcentrality وorphans. analyze_dependencies هو اسم مستعار رفيع لمسار impact — يُفضَّل استخدام هذه الأداة للوكلاء الجدد.

المعاملات:

repositoryاختياري

النوع: str
الوصف: المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.

queryاختياري

النوع: str
الوصف: اسم الرمز أو مصطلح البحث

targetاختياري

النوع: str
الوصف: اسم الرمز (اسم بديل للمعامل query)

changed_pathsاختياري

النوع: list[str]
الوصف: المسارات النسبية لتأثيرات PR/diff (افتراضي) أو، باستخدام verify_after_edit=true، التحقق من الجذور بعد التحرير. PR/diff: يحل الرموز لكل مسار ويمشي على التابعين القادمين الضحلين؛ يمكن دمجها مع patch=. التحقق: يحل ما يصل إلى 5 رموز لكل مسار كجذور تحقق (متوجة بالأسفل داخل وضع التحقق). لا يتطلب query/target لتأثير PR/diff.

patchاختياري

النوع: str
الوصف: تأثير PR/diff: نص التصحيح الموحد / git. يتم تحليل المسارات من رؤوس diff --git / --- / +++؛ نفس مسار التأثير المدمج مثل changed_paths.

analysis_typeاختياري

النوع: Literal[centrality, dependencies, dependents, impact, orphans]
الافتراضي: dependencies
الوصف: وضع التحليل. impact = نطاق التأثير (dependents الواردة؛ عمق ضحل عند إغفال depth). dependents يجيب أيضًا عن التأثير. عند ضبط changed_paths أو patch، يُفرَض التحليل على تأثير PR/diff. لا يتطلّب centrality/orphans هدفًا.

depthاختياري

النوع: Literal[shallow, balanced, deep]
الافتراضي: balanced
الوصف: عمق التجوال. بالنسبة إلى analysis_type=impact وتأثير PR/diff، يكون الافتراضي الفعلي هو الضحل (shallow) ما لم تضبط depth صراحةً.

limitاختياري

النوع: int
الافتراضي: 20
الوصف: الحد الأقصى للنتائج المُعادة في هذه الصفحة

offsetاختياري

النوع: int
الوصف: إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.

cursorاختياري

النوع: str
الوصف: مؤشّر معتِم (cursor) من pagination.next_cursor. مرِّره دون تغيير وأبقِ الاستعلام والفلاتر دون تغيير.

path_filterاختياري

النوع: str
الوصف: قصْر تحديد الرمز الهدف على بادئة مسار الملف؛ قد تتجاوز علاقات الرسم البياني المُعادة ذلك المسار

language_filterاختياري

النوع: str
الوصف: تصفية تحديد الهدف ونتائج التصفّح حسب اللغة

directionاختياري

النوع: Literal[outgoing, incoming, both]
الوصف: اتجاه التجاوز (يتجاوز استنتاج analysis_type)

relationship_typesاختياري

النوع: list[str]
الوصف: تصفية أنواع الحواف (CALL، IMPORT، INHERITS_FROM، إلخ). القائمة غير الفارغة تتجاوز افتراضيات graph_view.

exclude_test_pathsاختياري

النوع: bool
الافتراضي: true
الوصف: الافتراضي true: استبعاد مسارات test وfixture وvendor والأمثلة من نتائج التجوال والمركزية. اضبطه على false لتضمينها. يطبّق تحليل orphan دائمًا استبعادات ضجيج أكثر صرامة خاصة به.

exclude_generated_pathsاختياري

النوع: bool
الافتراضي
الوصف: استبعاد الإعلانات التي تم إنشاؤها بالإضافة إلى البناء والتغطية وذاكرة التخزين المؤقت وخريطة المصدر ومسارات العناصر المصغرة من نتائج الاجتياز

include_module_symbolsاختياري

النوع: bool
الافتراضي
الوصف: افتراضيًا، يستبعد false حواف الرسم البياني عندما يكون from_name أو to_name هو رمز __module__ الاصطناعي (ضوضاء على مستوى الوحدة النمطية). قم بتعيين true لتضمين حواف مستوى الوحدة النمطية في نتائج العلاقات التابعة والتبعية.

branchاختياري

النوع: str
الوصف: تجاوز الفرع

per_hop_limitاختياري

النوع: int
الوصف: الحد الأقصى للعلاقات لكل قفزة (1-300)

include_metricsاختياري

النوع: bool
الافتراضي
الوصف: مقاييس رسم بياني اختيارية على صفوف النتائج (مُدمجة مع refactor_risk). تُجلب المقاييس أيضًا داخليًا عندما يكون min_centrality>0 لكنها لا تُعاد ما لم يكن هذا true.

metrics_detailاختياري

النوع: Literal[summary, full]
الافتراضي: summary
الوصف: عندما include_metrics=true: summary (افتراضي) يُرجع إشارات القرار + refactor_risk؛ تقوم full بإرجاع مجموعة المقاييس المنسقة الأكبر

include_edge_metadataاختياري

النوع: bool
الافتراضي
الوصف: قم بتضمين البيانات التعريفية والأوزان الأولية (كبيرة). الحمولات ذات التأثير المضغوط تترك هذا الأمر خارجًا.

symbol_typesاختياري

النوع: list[str]
الوصف: تصفية الرموز المُعادة حسب النوع (function، class، method، إلخ)

exact_matchاختياري

النوع: bool
الافتراضي
الوصف: مطالبة بمطابقة حرفية لاسم الرمز (يعطّل المطابقة التقريبية)

find_similar_patternsاختياري

النوع: bool
الافتراضي
الوصف: إيجاد أنماط استخدام مشابهة

min_centralityاختياري

النوع: float
الافتراضي: 0
الوصف: أدنى درجة PageRank. تُجلب المقاييس داخليًا للتصفية؛ ولا تُعاد graph_metrics إلا عندما يكون include_metrics=true.

graph_viewاختياري

النوع: Literal[dependency, type, data_flow, control_flow]
الافتراضي: dependency
الوصف: عرض الرسم البياني المُستخدَم لافتراضيات علاقات التجوال والمقاييس وترتيب المركزية؛ يُحسب تحليل orphan عبر جميع العروض

verify_after_editاختياري

النوع: bool
الافتراضي
الوصف: وضع التحقق بعد التحرير P2-7: إعادة الاستعلام عن الرسم البياني للتأثير المفهرس للرموز التي تم تحريرها مؤخرًا في استجابة واحدة مدمجة متعددة الجذور. يتطلب targets و/أو changed_paths (أو target/query). الافتراضيات للمعالين الضحلة ؛ تعكس النتائج الرسم البياني المفهرس (قد تتأخر التعديلات المباشرة). عندما يكون صحيحًا، يكون له الأسبقية على تأثير PR/diff على نفس changed_paths.

targetsاختياري

النوع: list[str]
الوصف: عند verify_after_edit=true: أسماء الرموز لإعادة التحقق (المتصلون/المعالون). يتم دمجها مع target/query إذا تم توفير كليهما.

المعامل	النوع	مطلوب	الافتراضي	الوصف
`repository`	`str`	لا	-	المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.
`query`	`str`	لا	-	اسم الرمز أو مصطلح البحث
`target`	`str`	لا	-	اسم الرمز (اسم بديل للمعامل query)
`changed_paths`	`list[str]`	لا	-	المسارات النسبية لتأثيرات PR/diff (افتراضي) أو، باستخدام verify_after_edit=true، التحقق من الجذور بعد التحرير. PR/diff: يحل الرموز لكل مسار ويمشي على التابعين القادمين الضحلين؛ يمكن دمجها مع patch=. التحقق: يحل ما يصل إلى 5 رموز لكل مسار كجذور تحقق (متوجة بالأسفل داخل وضع التحقق). لا يتطلب query/target لتأثير PR/diff.
`patch`	`str`	لا	-	تأثير PR/diff: نص التصحيح الموحد / git. يتم تحليل المسارات من رؤوس diff --git / --- / +++؛ نفس مسار التأثير المدمج مثل changed_paths.
`analysis_type`	`Literal[centrality, dependencies, dependents, impact, orphans]`	لا	`dependencies`	وضع التحليل. impact = نطاق التأثير (dependents الواردة؛ عمق ضحل عند إغفال depth). dependents يجيب أيضًا عن التأثير. عند ضبط changed_paths أو patch، يُفرَض التحليل على تأثير PR/diff. لا يتطلّب centrality/orphans هدفًا.
`depth`	`Literal[shallow, balanced, deep]`	لا	`balanced`	عمق التجوال. بالنسبة إلى analysis_type=impact وتأثير PR/diff، يكون الافتراضي الفعلي هو الضحل (shallow) ما لم تضبط depth صراحةً.
`limit`	`int`	لا	`20`	الحد الأقصى للنتائج المُعادة في هذه الصفحة
`offset`	`int`	لا	-	إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.
`cursor`	`str`	لا	-	مؤشّر معتِم (cursor) من pagination.next_cursor. مرِّره دون تغيير وأبقِ الاستعلام والفلاتر دون تغيير.
`path_filter`	`str`	لا	-	قصْر تحديد الرمز الهدف على بادئة مسار الملف؛ قد تتجاوز علاقات الرسم البياني المُعادة ذلك المسار
`language_filter`	`str`	لا	-	تصفية تحديد الهدف ونتائج التصفّح حسب اللغة
`direction`	`Literal[outgoing, incoming, both]`	لا	-	اتجاه التجاوز (يتجاوز استنتاج analysis_type)
`relationship_types`	`list[str]`	لا	-	تصفية أنواع الحواف (CALL، IMPORT، INHERITS_FROM، إلخ). القائمة غير الفارغة تتجاوز افتراضيات graph_view.
`exclude_test_paths`	`bool`	لا	`true`	الافتراضي true: استبعاد مسارات test وfixture وvendor والأمثلة من نتائج التجوال والمركزية. اضبطه على false لتضمينها. يطبّق تحليل orphan دائمًا استبعادات ضجيج أكثر صرامة خاصة به.
`exclude_generated_paths`	`bool`	لا		استبعاد الإعلانات التي تم إنشاؤها بالإضافة إلى البناء والتغطية وذاكرة التخزين المؤقت وخريطة المصدر ومسارات العناصر المصغرة من نتائج الاجتياز
`include_module_symbols`	`bool`	لا		افتراضيًا، يستبعد false حواف الرسم البياني عندما يكون from_name أو to_name هو رمز __module__ الاصطناعي (ضوضاء على مستوى الوحدة النمطية). قم بتعيين true لتضمين حواف مستوى الوحدة النمطية في نتائج العلاقات التابعة والتبعية.
`branch`	`str`	لا	-	تجاوز الفرع
`per_hop_limit`	`int`	لا	-	الحد الأقصى للعلاقات لكل قفزة (1-300)
`include_metrics`	`bool`	لا		مقاييس رسم بياني اختيارية على صفوف النتائج (مُدمجة مع refactor_risk). تُجلب المقاييس أيضًا داخليًا عندما يكون min_centrality>0 لكنها لا تُعاد ما لم يكن هذا true.
`metrics_detail`	`Literal[summary, full]`	لا	`summary`	عندما include_metrics=true: summary (افتراضي) يُرجع إشارات القرار + refactor_risk؛ تقوم full بإرجاع مجموعة المقاييس المنسقة الأكبر
`include_edge_metadata`	`bool`	لا		قم بتضمين البيانات التعريفية والأوزان الأولية (كبيرة). الحمولات ذات التأثير المضغوط تترك هذا الأمر خارجًا.
`symbol_types`	`list[str]`	لا	-	تصفية الرموز المُعادة حسب النوع (function، class، method، إلخ)
`exact_match`	`bool`	لا		مطالبة بمطابقة حرفية لاسم الرمز (يعطّل المطابقة التقريبية)
`find_similar_patterns`	`bool`	لا		إيجاد أنماط استخدام مشابهة
`min_centrality`	`float`	لا	`0`	أدنى درجة PageRank. تُجلب المقاييس داخليًا للتصفية؛ ولا تُعاد graph_metrics إلا عندما يكون include_metrics=true.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	لا	`dependency`	عرض الرسم البياني المُستخدَم لافتراضيات علاقات التجوال والمقاييس وترتيب المركزية؛ يُحسب تحليل orphan عبر جميع العروض
`verify_after_edit`	`bool`	لا		وضع التحقق بعد التحرير P2-7: إعادة الاستعلام عن الرسم البياني للتأثير المفهرس للرموز التي تم تحريرها مؤخرًا في استجابة واحدة مدمجة متعددة الجذور. يتطلب targets و/أو changed_paths (أو target/query). الافتراضيات للمعالين الضحلة ؛ تعكس النتائج الرسم البياني المفهرس (قد تتأخر التعديلات المباشرة). عندما يكون صحيحًا، يكون له الأسبقية على تأثير PR/diff على نفس changed_paths.
`targets`	`list[str]`	لا	-	عند verify_after_edit=true: أسماء الرموز لإعادة التحقق (المتصلون/المعالون). يتم دمجها مع target/query إذا تم توفير كليهما.

الأنسب لـ:

تحليل نطاق التأثير قبل تعديل رمز مشترك
تأثير PR/diff عبر changed_paths أو patch
التحقق بعد التعديل عبر verify_after_edit

غير مُوصى به لـ:

عمليات بحث نصية أو رمزية بسيطة — استخدم text_pattern_search أو find_symbol

أدوات تحليل الكود#

find_symbolمستقر

انتقل إلى مكان تعريف دالة أو فئة أو متغيّر وإلى مواضع استخدامه. استخدم عندما تعرف الاسم (مثال: "getCurrentUser") — أسرع وأكثر دقة من Grep ويغطي المستودع المفهرَس بأكمله. يمكن أن يعيد مراجع ومقاييس الأهمية اختياريًا.

المعاملات:

symbol_nameاختياري

النوع: str
الوصف: اسم الرمز للبحث عنه (اختياري — اتركه لتصفح عبر المقاييس)

repositoryاختياري

النوع: str
الوصف: المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.

scopeاختياري

النوع: Literal[definitions, references, both]
الافتراضي: both
الوصف: نطاق البحث

limitاختياري

النوع: int
الافتراضي: 15
الوصف: الحد الأقصى للنتائج المُعادة في هذه الصفحة

offsetاختياري

النوع: int
الوصف: إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.

cursorاختياري

النوع: str
الوصف: مؤشّر معتِم (cursor) من pagination.next_cursor. مرِّره دون تغيير وأبقِ الاستعلام والفلاتر دون تغيير.

find_similarاختياري

النوع: bool
الافتراضي
الوصف: تضمين أسماء رموز مشابهة

include_metricsاختياري

النوع: bool
الافتراضي
الوصف: تضمين مقاييس المركزية

metrics_detailاختياري

النوع: Literal[summary, full]
الافتراضي: summary
الوصف: عندما include_metrics=true: summary (افتراضي) يُرجع إشارات القرار + refactor_risk؛ تقوم full بإرجاع مجموعة المقاييس المنسقة الأكبر

path_filterاختياري

النوع: str
الوصف: تصفية بحسب بادئة مسار الملف

branchاختياري

النوع: str
الوصف: تجاوز الفرع

symbol_typeاختياري

النوع: Literal[function, class, variable, method, constant, module, interface, type]
الوصف: تصفية حسب نوع الرمز

high_impactاختياري

النوع: bool
الافتراضي
الوصف: تصفّح الرموز المهمة معماريًا (أغفِل symbol_name). الوضع الافتراضي هو الشعبية (أعلى عُشْر من PageRank ناقص المحاور الضخمة المساعِدة). اضبط high_impact_mode=risk لرؤوس القطع والجسور.

high_impact_modeاختياري

النوع: Literal[popularity, risk]
الافتراضي: popularity
الوصف: عندما high_impact=true: الشعبية = أعلى عشري PageRank ناقص المحاور/الوحدات الضخمة المساعدة؛ المخاطرة = نقاط القطع مرتبة حسب SMV bridge_count ثم k_core (خطر إعادة البناء الهيكلي، وليس شعبية المحور)

in_cycleاختياري

النوع: bool
الافتراضي
الوصف: تصفية للرموز الموجودة في دورات اعتماد فقط

exclude_test_pathsاختياري

النوع: bool
الافتراضي: true
الوصف: عند التصفح حسب مقاييس الرسم البياني، استبعد الاختبارات وfixtures ورمز الطرف الثالث والأمثلة قبل الترتيب. البحث عن طريق رمز مسمى لم يتغير.

المعامل	النوع	مطلوب	الافتراضي	الوصف
`symbol_name`	`str`	لا	-	اسم الرمز للبحث عنه (اختياري — اتركه لتصفح عبر المقاييس)
`repository`	`str`	لا	-	المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.
`scope`	`Literal[definitions, references, both]`	لا	`both`	نطاق البحث
`limit`	`int`	لا	`15`	الحد الأقصى للنتائج المُعادة في هذه الصفحة
`offset`	`int`	لا	-	إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.
`cursor`	`str`	لا	-	مؤشّر معتِم (cursor) من pagination.next_cursor. مرِّره دون تغيير وأبقِ الاستعلام والفلاتر دون تغيير.
`find_similar`	`bool`	لا		تضمين أسماء رموز مشابهة
`include_metrics`	`bool`	لا		تضمين مقاييس المركزية
`metrics_detail`	`Literal[summary, full]`	لا	`summary`	عندما include_metrics=true: summary (افتراضي) يُرجع إشارات القرار + refactor_risk؛ تقوم full بإرجاع مجموعة المقاييس المنسقة الأكبر
`path_filter`	`str`	لا	-	تصفية بحسب بادئة مسار الملف
`branch`	`str`	لا	-	تجاوز الفرع
`symbol_type`	`Literal[function, class, variable, method, constant, module, interface, type]`	لا	-	تصفية حسب نوع الرمز
`high_impact`	`bool`	لا		تصفّح الرموز المهمة معماريًا (أغفِل symbol_name). الوضع الافتراضي هو الشعبية (أعلى عُشْر من PageRank ناقص المحاور الضخمة المساعِدة). اضبط high_impact_mode=risk لرؤوس القطع والجسور.
`high_impact_mode`	`Literal[popularity, risk]`	لا	`popularity`	عندما high_impact=true: الشعبية = أعلى عشري PageRank ناقص المحاور/الوحدات الضخمة المساعدة؛ المخاطرة = نقاط القطع مرتبة حسب SMV bridge_count ثم k_core (خطر إعادة البناء الهيكلي، وليس شعبية المحور)
`in_cycle`	`bool`	لا		تصفية للرموز الموجودة في دورات اعتماد فقط
`exclude_test_paths`	`bool`	لا	`true`	عند التصفح حسب مقاييس الرسم البياني، استبعد الاختبارات وfixtures ورمز الطرف الثالث والأمثلة قبل الترتيب. البحث عن طريق رمز مسمى لم يتغير.

الأنسب لـ:

تحديد تعريف رمز معروف ومراجعه ومقاييس الرسم البياني الخاصة به
التصفح حسب centrality أو high_impact أو in_cycle عند حذف symbol_name

غير مُوصى به لـ:

استعلامات مفاهيمية أو مناطق غير معروفة — استخدم intelligent_search أو semantic_search

analyze_dependenciesمستقر

اسم مستعار لنطاق التأثير عبر dependency_search (dependents/وارد). يُفضَّل استخدام dependency_search مع analysis_type="dependents" أو "impact" للوكلاء الجدد. يحافظ على شكل استجابة impact القديم متعدد القفزات (graph وconnection_summary ومقاييس اختيارية مع refactor_risk). استخدم graph_view لتحديد نطاق عائلة العلاقات: dependency (افتراضي)، type، data_flow، control_flow.

المعاملات:

repositoryاختياري

النوع: str
الوصف: المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.

targetمطلوب

النوع: str
الوصف: اسم الرمز لتحليله

depthاختياري

النوع: Literal[shallow, balanced, deep]
الافتراضي: balanced
الوصف: عمق التحليل

limitاختياري

النوع: int
الافتراضي: 10
الوصف: الحد الأقصى للنتائج المُعادة في هذه الصفحة

offsetاختياري

النوع: int
الوصف: إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.

cursorاختياري

النوع: str
الوصف: مؤشّر معتِم (cursor) من pagination.next_cursor. مرِّره دون تغيير وأبقِ الاستعلام والفلاتر دون تغيير.

directionاختياري

النوع: Literal[incoming, outgoing, both]
الافتراضي: incoming
الوصف: اتجاه التجاوز

relationship_typesاختياري

النوع: list[str]
الوصف: تصفية أنواع الحواف (CALL، IMPORT، INHERITS_FROM، إلخ). تتجاوز دائمًا الافتراضي المستمد من graph_view عند تمريرها.

graph_viewاختياري

النوع: Literal[dependency, type, data_flow, control_flow]
الافتراضي: dependency
الوصف: عرض الرسم البياني: يحدّد أنواع الحواف الافتراضية للتنقّل وأي مقاييس العرض تُستخدم عند include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (افتراضي)، type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE]، data_flow=[READS,WRITES,ASSIGNS_TO]، control_flow=[CONTROL_FLOW,THROWS,CATCHES]. يُستخدم هذا فقط كقيمة افتراضية لـ relationship_types عند عدم تمريرها صراحةً. يتطابق اسم المعامل مع dependency_search للاحتفاظ بالاتساق عبر الأدوات.

path_filterاختياري

النوع: str
الوصف: قصْر تحديد الرمز الهدف على بادئة مسار الملف؛ قد تتجاوز علاقات الرسم البياني المُعادة ذلك المسار

language_filterاختياري

النوع: str
الوصف: فلتر اللغة

branchاختياري

النوع: str
الوصف: تجاوز الفرع

per_hop_limitاختياري

النوع: int
الوصف: الحد الأقصى للعلاقات لكل قفزة (1-300)

include_metricsاختياري

النوع: bool
الافتراضي
الوصف: قم بتضمين مقاييس الرسم البياني في النتائج، مع تعزيز كل منها بكتلة refactor_risk مشتقة ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk هي "low" عندما لا تكون نقطة مفصلية (في العرض المحدد)، "medium" عندما تكون نقطة مفصلية تجسر بعض الحواف، "high" عندما تجسر العديد من الحواف (العتبة الإرشادية، لم يتم التحقق من صحتها تجريبيًا). تم حذفه لكل رمز في حالة عدم وجود صف مقاييس لهذا الرمز/العرض.

metrics_detailاختياري

النوع: Literal[summary, full]
الافتراضي: summary
الوصف: عندما include_metrics=true: summary (افتراضي) يُرجع إشارات القرار + refactor_risk؛ تقوم full بإرجاع مجموعة المقاييس المنسقة الأكبر

include_edge_metadataاختياري

النوع: bool
الافتراضي
الوصف: قم بتضمين البيانات الوصفية والأوزان الأولية. يتم تعطيله بشكل افتراضي لأن بيانات تعريف المستخرج يمكن أن تكون كبيرة؛ يتم الإبلاغ عن تغطية التخصيب عند التمكين.

exclude_test_pathsاختياري

النوع: bool
الافتراضي: true
الوصف: الافتراضي true: استبعاد مسارات الاختبار والتركيب والبائعين والأمثلة من حواف الرسم البياني التي تم إرجاعها. قم بتعيين false لتضمينها.

include_module_symbolsاختياري

النوع: bool
الافتراضي
الوصف: افتراضيًا، يستبعد false حواف الرسم البياني عندما يكون from_name أو to_name هو رمز __module__ الاصطناعي. قم بتعيين true ليشمل حواف مستوى الوحدة.

المعامل	النوع	مطلوب	الافتراضي	الوصف
`repository`	`str`	لا	-	المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.
`target`	`str`	نعم	-	اسم الرمز لتحليله
`depth`	`Literal[shallow, balanced, deep]`	لا	`balanced`	عمق التحليل
`limit`	`int`	لا	`10`	الحد الأقصى للنتائج المُعادة في هذه الصفحة
`offset`	`int`	لا	-	إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.
`cursor`	`str`	لا	-	مؤشّر معتِم (cursor) من pagination.next_cursor. مرِّره دون تغيير وأبقِ الاستعلام والفلاتر دون تغيير.
`direction`	`Literal[incoming, outgoing, both]`	لا	`incoming`	اتجاه التجاوز
`relationship_types`	`list[str]`	لا	-	تصفية أنواع الحواف (CALL، IMPORT، INHERITS_FROM، إلخ). تتجاوز دائمًا الافتراضي المستمد من graph_view عند تمريرها.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	لا	`dependency`	عرض الرسم البياني: يحدّد أنواع الحواف الافتراضية للتنقّل وأي مقاييس العرض تُستخدم عند include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (افتراضي)، type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE]، data_flow=[READS,WRITES,ASSIGNS_TO]، control_flow=[CONTROL_FLOW,THROWS,CATCHES]. يُستخدم هذا فقط كقيمة افتراضية لـ relationship_types عند عدم تمريرها صراحةً. يتطابق اسم المعامل مع dependency_search للاحتفاظ بالاتساق عبر الأدوات.
`path_filter`	`str`	لا	-	قصْر تحديد الرمز الهدف على بادئة مسار الملف؛ قد تتجاوز علاقات الرسم البياني المُعادة ذلك المسار
`language_filter`	`str`	لا	-	فلتر اللغة
`branch`	`str`	لا	-	تجاوز الفرع
`per_hop_limit`	`int`	لا	-	الحد الأقصى للعلاقات لكل قفزة (1-300)
`include_metrics`	`bool`	لا		قم بتضمين مقاييس الرسم البياني في النتائج، مع تعزيز كل منها بكتلة refactor_risk مشتقة ({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk هي "low" عندما لا تكون نقطة مفصلية (في العرض المحدد)، "medium" عندما تكون نقطة مفصلية تجسر بعض الحواف، "high" عندما تجسر العديد من الحواف (العتبة الإرشادية، لم يتم التحقق من صحتها تجريبيًا). تم حذفه لكل رمز في حالة عدم وجود صف مقاييس لهذا الرمز/العرض.
`metrics_detail`	`Literal[summary, full]`	لا	`summary`	عندما include_metrics=true: summary (افتراضي) يُرجع إشارات القرار + refactor_risk؛ تقوم full بإرجاع مجموعة المقاييس المنسقة الأكبر
`include_edge_metadata`	`bool`	لا		قم بتضمين البيانات الوصفية والأوزان الأولية. يتم تعطيله بشكل افتراضي لأن بيانات تعريف المستخرج يمكن أن تكون كبيرة؛ يتم الإبلاغ عن تغطية التخصيب عند التمكين.
`exclude_test_paths`	`bool`	لا	`true`	الافتراضي true: استبعاد مسارات الاختبار والتركيب والبائعين والأمثلة من حواف الرسم البياني التي تم إرجاعها. قم بتعيين false لتضمينها.
`include_module_symbols`	`bool`	لا		افتراضيًا، يستبعد false حواف الرسم البياني عندما يكون from_name أو to_name هو رمز __module__ الاصطناعي. قم بتعيين true ليشمل حواف مستوى الوحدة.

الأنسب لـ:

المستدعون القدامى المرتبطون بالفعل بشكل استجابته (graph, connection_summary)

غير مُوصى به لـ:

حلقات الوكلاء الجديدة — يُفضَّل dependency_search الذي يشترك في نفس نواة الاجتياز

get_task_contextمستقر

هل تبدأ العمل في منطقة غير مألوفة؟ صِف المهمة (مثل: "إضافة دعم SSO"، "إصلاح webhook الفوترة") واحصل في استدعاء واحد على حزمة من الشيفرة والرموز والتبعيات ذات الصلة — أي السياق الذي كنت ستجمعه من عدة عمليات بحث منفصلة.

المعاملات:

task_descriptionمطلوب

النوع: str
الوصف: وصف المهمة التي تحتاج سياقًا لها

repositoryاختياري

النوع: str
الوصف: المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.

limitاختياري

النوع: int
الافتراضي: 15
الوصف: الحد الأقصى للعناصر لكل طبقة

scopeاختياري

النوع: Literal[semantic, symbols, dependencies, all]
الافتراضي: all
الوصف: أي طبقات السياق تضمّن

language_filterاختياري

النوع: str
الوصف: فلتر اللغة

path_filterاختياري

النوع: str
الوصف: تصفية حسب بادئة مسار الملف

branchاختياري

النوع: str
الوصف: تجاوز الفرع

include_related_contextاختياري

النوع: bool
الافتراضي
الوصف: تضمين سياق ذي صلة من الرموز المجاورة

seed_symbol_idsاختياري

النوع: list[str]
الوصف: بذور صريحة من المستوى الأول: معرّفات الرموز التي يعرف الوكيل مسبقًا أنها محورية للمهمة (مثل الرموز في الملفات المفتوحة لديه). تُرتَّب قبل البذور المستمدّة من الكلمات المفتاحية ضمن طبقات dependencies/related_context. تراكمية — اتركها للإبقاء على سلوك الكلمات المفتاحية فقط المعمول به اليوم.

seed_file_pathsاختياري

النوع: list[str]
الوصف: بذور صريحة من المستوى الأول (Tier-1): مسارات ملفات مفهرسة فتحها الوكيل أو عدّلها للتو. يعيد أدلة ملفات مباشرة محدودة ويحلّ حتى 5 رموز لكل ملف لسياق الرسم البياني، بما في ذلك المستندات والإعدادات (config) الخالية من الرموز. تراكمي — أغفِله للسلوك القائم على الكلمات المفتاحية فقط.

المعامل	النوع	مطلوب	الافتراضي	الوصف
`task_description`	`str`	نعم	-	وصف المهمة التي تحتاج سياقًا لها
`repository`	`str`	لا	-	المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.
`limit`	`int`	لا	`15`	الحد الأقصى للعناصر لكل طبقة
`scope`	`Literal[semantic, symbols, dependencies, all]`	لا	`all`	أي طبقات السياق تضمّن
`language_filter`	`str`	لا	-	فلتر اللغة
`path_filter`	`str`	لا	-	تصفية حسب بادئة مسار الملف
`branch`	`str`	لا	-	تجاوز الفرع
`include_related_context`	`bool`	لا		تضمين سياق ذي صلة من الرموز المجاورة
`seed_symbol_ids`	`list[str]`	لا	-	بذور صريحة من المستوى الأول: معرّفات الرموز التي يعرف الوكيل مسبقًا أنها محورية للمهمة (مثل الرموز في الملفات المفتوحة لديه). تُرتَّب قبل البذور المستمدّة من الكلمات المفتاحية ضمن طبقات dependencies/related_context. تراكمية — اتركها للإبقاء على سلوك الكلمات المفتاحية فقط المعمول به اليوم.
`seed_file_paths`	`list[str]`	لا	-	بذور صريحة من المستوى الأول (Tier-1): مسارات ملفات مفهرسة فتحها الوكيل أو عدّلها للتو. يعيد أدلة ملفات مباشرة محدودة ويحلّ حتى 5 رموز لكل ملف لسياق الرسم البياني، بما في ذلك المستندات والإعدادات (config) الخالية من الرموز. تراكمي — أغفِله للسلوك القائم على الكلمات المفتاحية فقط.

الأنسب لـ:

سياق مدرك للمهمة يمزج الملفات الأولية مع طبقات الدلالة والرموز والاعتماديات

غير مُوصى به لـ:

عمليات بحث بأداة واحدة حيث تجيب أداة أكثر تحديدًا على السؤال بالفعل

get_fileمستقر

اقرأ ملفًا من المستودع المفهرس عبر المسار. يُفضَّل استخدام أداة Read المحلية للملفات الموجودة على القرص — استخدم هذه للبحث عبر المستودعات أو عن بُعد حيث لا يكون الملف في شجرة عملك. تدعم نطاق أسطر اختياريًا؛ تابِع استجابة مقطوعة بسبب حدّ الرموز من metadata.next_line_start.

المعاملات:

file_pathمطلوب

النوع: str
الوصف: مسار الملف بالنسبة لجذر المستودع

repositoryاختياري

النوع: str
الوصف: المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.

line_startاختياري

النوع: int
الوصف: سطر البداية (مؤشّر 1)

line_endاختياري

النوع: int
الوصف: سطر النهاية (مفهرس من 1، شامل؛ يجب أن يكون عند line_start أو بعده)

branchاختياري

النوع: str
الوصف: تجاوز الفرع

max_tokensاختياري

النوع: int
الافتراضي: 5000
الوصف: الحد الأقصى للرموز المعادة

include_metadataاختياري

النوع: bool
الافتراضي: true
الوصف: تضمين بيانات وصفية للملف في الاستجابة

المعامل	النوع	مطلوب	الافتراضي	الوصف
`file_path`	`str`	نعم	-	مسار الملف بالنسبة لجذر المستودع
`repository`	`str`	لا	-	المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُظهِر الاستجابة أيّ مستودع استُخدِم.
`line_start`	`int`	لا	-	سطر البداية (مؤشّر 1)
`line_end`	`int`	لا	-	سطر النهاية (مفهرس من 1، شامل؛ يجب أن يكون عند line_start أو بعده)
`branch`	`str`	لا	-	تجاوز الفرع
`max_tokens`	`int`	لا	`5000`	الحد الأقصى للرموز المعادة
`include_metadata`	`bool`	لا	`true`	تضمين بيانات وصفية للملف في الاستجابة

الأنسب لـ:

لقطات لملفات بعيدة أو مفهرسة (نطاقات الأسطر، حدود الرموز)

غير مُوصى به لـ:

مسار موجود بالفعل على القرص المحلي — استخدم أداة Read المحلية

أدوات النظام والأدوات المساعدة#

repository_contextمستقر

اسرد المستودعات التي يمكنك البحث فيها، أو احصل على معلومات هوية أحدها (namespace/branch، indexed_commit_sha / حداثة الفهرس). استدعِ مع action:"list" مرة واحدة لمعرفة معرّف المستودع (slug) الدقيق الذي تقبله أدوات البحث. (إذا كان مفتاحك يحتوي على مستودع واحد، فإن أدوات البحث تعتمده افتراضيًا — يمكنك تخطّي هذا.) أعداد file/blob/edge على مستوى namespace اختيارية عبر include_statistics=true.

المعاملات:

actionمطلوب

النوع: Literal[list, info]
الوصف: الإجراء: عرض المستودعات المتاحة أو الحصول على معلومات عن مستودع

repositoryاختياري

النوع: str
الوصف: المستودع بصيغة owner/repo أو owner/repo:branch (مطلوب لـ action="info")

branchاختياري

النوع: str
الوصف: تجاوز الفرع

patternاختياري

النوع: str
الوصف: تصفية قائمة المستودعات بنمط

include_statisticsاختياري

النوع: bool
الافتراضي
الوصف: اختياري: تضمين أعداد البيانات المفهرسة على مستوى namespace (file/blob/edge). الافتراضي false — لا تتطلّب هوية المستودع هذا التجميع الأبطأ.

limitاختياري

النوع: int
الافتراضي: 20
الوصف: الحد الأقصى للنتائج المُعادة في هذه الصفحة

offsetاختياري

النوع: int
الوصف: إزاحة التوافق المهملة. تفضل cursor من pagination.next_cursor.

cursorاختياري

النوع: str
الوصف: cursor غير شفاف من pagination.next_cursor. قم بتمريرها دون تغيير واحتفظ بالاستعلام وعوامل التصفية دون تغيير.

المعامل	النوع	مطلوب	الافتراضي	الوصف
`action`	`Literal[list, info]`	نعم	-	الإجراء: عرض المستودعات المتاحة أو الحصول على معلومات عن مستودع
`repository`	`str`	لا	-	المستودع بصيغة owner/repo أو owner/repo:branch (مطلوب لـ action="info")
`branch`	`str`	لا	-	تجاوز الفرع
`pattern`	`str`	لا	-	تصفية قائمة المستودعات بنمط
`include_statistics`	`bool`	لا		اختياري: تضمين أعداد البيانات المفهرسة على مستوى namespace (file/blob/edge). الافتراضي false — لا تتطلّب هوية المستودع هذا التجميع الأبطأ.
`limit`	`int`	لا	`20`	الحد الأقصى للنتائج المُعادة في هذه الصفحة
`offset`	`int`	لا	-	إزاحة التوافق المهملة. تفضل cursor من pagination.next_cursor.
`cursor`	`str`	لا	-	cursor غير شفاف من pagination.next_cursor. قم بتمريرها دون تغيير واحتفظ بالاستعلام وعوامل التصفية دون تغيير.

الأنسب لـ:

سرد المستودعات المتاحة
تحديد هوية المستودع والفرع ومدى حداثة HEAD مقارنةً بالفهرس

غير مُوصى به لـ:

إحصاءات على مستوى مساحة الأسماء بالكامل افتراضيًا — مرِّر include_statistics=true صراحةً، لأنه قد يكون أبطأ من التحديد

ask_maguyvaمستقر

مساعدة Maguyva والملاحظات. الأساسي: احصل على إرشاد الأدوات، أو أرسِل تقرير خطأ / طلب ميزة يُخزَّن لمشرفي Maguyva. لا تُضمِّن أبدًا أسرارًا أو بيانات شخصية حسّاسة في الملاحظات. تبقى عملية evaluate للتوافق الخلفي فقط — يُفضَّل الحوسبة المحلية أو أدوات المضيف لأعمال الرياضيات/التجزئة/السلاسل.

المعاملات:

operationمطلوب

النوع: Literal[guidance, report_bug, request_feature, evaluate]
الوصف: الأساسي: guidance، report_bug، request_feature. للإرث/التوافق فقط: evaluate (محرّك تعبيرات حتمي؛ ليس جزءًا من سير عمل الوكيل الأساسي).

queryاختياري

النوع: str
الوصف: موضوع الإرشاد (مثل tool_selection، semantic_search). لـ evaluate القديمة فقط: سلسلة التعبير.

descriptionاختياري

النوع: str
الوصف: مطلوب لـ report_bug وrequest_feature. ملاحظات حرة لمشرفي Maguyva. لا تُضمِّن أبدًا أسرارًا أو بيانات شخصية حسّاسة.

related_toolاختياري

النوع: Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
الوصف: أداة Maguyva الاختيارية الأكثر ارتباطًا بالتعليقات

المعامل	النوع	مطلوب	الافتراضي	الوصف
`operation`	`Literal[guidance, report_bug, request_feature, evaluate]`	نعم	-	الأساسي: guidance، report_bug، request_feature. للإرث/التوافق فقط: evaluate (محرّك تعبيرات حتمي؛ ليس جزءًا من سير عمل الوكيل الأساسي).
`query`	`str`	لا	-	موضوع الإرشاد (مثل tool_selection، semantic_search). لـ evaluate القديمة فقط: سلسلة التعبير.
`description`	`str`	لا	-	مطلوب لـ report_bug وrequest_feature. ملاحظات حرة لمشرفي Maguyva. لا تُضمِّن أبدًا أسرارًا أو بيانات شخصية حسّاسة.
`related_tool`	`Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]`	لا	-	أداة Maguyva الاختيارية الأكثر ارتباطًا بالتعليقات

الأنسب لـ:

إرشادات الأدوات (operation="guidance")
تقارير أخطاء دائمة وطلبات ميزات لمشرفي Maguyva

غير مُوصى به لـ:

حسابات الرياضيات/التجزئة/السلاسل النصية — عملية evaluate قديمة/للتوافق الخلفي فقط؛ يُفضَّل الحساب المحلي على المضيف

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

استخدم التجاوزات الصريحة بعناية: لا تمرّر repository عندما يوفّر عميل MCP قيمة افتراضية على مستوى الطلب أو عندما يستطيع المفتاح الوصول إلى مستودع واحد بالضبط؛ وإلا فمرِّره صراحةً.
اختر وضع البحث المناسب: استخدم intelligent_search مع mode="auto" في معظم الحالات. حدِّد وضعًا عندما تعرف بالضبط ما تحتاجه.
استفد من فلاتر اللغة: استخدم language_filter لتضييق النتائج وتحسين الأداء.
تعزيز GraphRAG: تعزيز الأهمية عبر GraphRAG معطَّل افتراضيًا في البحث الدلالي (boost_by_importance=false) للحفاظ على ترتيب آمن للوكلاء. مرِّر boost_by_importance=true لتفعيل إعادة ترتيب واعية بالمركزية عند جولات استكشاف المعمارية.
مطابقة المستودعات غير حسّاسة لحالة الأحرف، وليست تقريبية: يطابق repository_context أسماء المستودعات دون حسّاسية لحالة الأحرف — لكنه لا يصحّح الأخطاء الإملائية. تحقّق من metadata.resolution_reason في إجراء info ("exact" مقابل "corrected") لمعرفة كيف جرى حلّ الاسم.
ادمج الأدوات: استخدم عدة طرق API معًا للحصول على تحليل شامل.
تعامل مع النتائج الكبيرة: استخدم limit وعناصر تحكّم التصفّح الخاصة بكل أداة (مثل line_start/line_end في get_file).
استخدم ask_maguyva للحصول على إرشادات الأدوات: عملية evaluate في ask_maguyva (hash وbase64 وJSON والرياضيات) قديمة وللتوافق الخلفي فقط. استدعِ ask_maguyva مع operation="guidance" وquery="tool_selection" بدلًا من ذلك للحصول على مصفوفة "الأداة المحلية تفوز" وورقة مرجعية كاملة أداةً بأداة.
تحقّق من الأثر قبل التعديل وبعده: قبل تعديل رمز مشترك، استدعِ dependency_search مع analysis_type="impact" (أو مرِّر changed_paths لقياس أثر PR/diff) لرؤية نطاق تأثيره. وبعد التعديل، عيِّن verify_after_edit=true مع targets و/أو changed_paths لإعادة فحص موجزة للرموز نفسها.

خصائص الأداء#

العملية	ملاحظات الأداء
البحث الدلالي	أقل من ثانية، لكنه يتضمّن استدعاءً حيًّا إلى واجهة API للتضمين في كل مرة (بدون تخزين مؤقت) — توقّع زمن استجابة إضافيًا فوق استعلام المتجهات
البحث النصي	أقل من ثانية للمطابقة الدقيقة/regex؛ أما البحث التقريبي في المحتوى فيُصفّح من جهة العميل، لذا تكلّف الإزاحات العميقة أكثر — ضيّق النطاق باستخدام path_filter/language_filter
البحث البنيوي	مفهرَس عبر AST — تتناسب التكلفة مع حجم النتائج، لا مع حجم المستودع
بحث الاعتماديات	تتناسب التكلفة مع العمق — فضّل depth="shallow" ما لم تكن بحاجة إلى سياق متعدّد القفزات؛ ويحدّ per_hop_limit من التوسّع
استرجاع الملفات	شبه فوري لملف واحد — صفّح الملفات الكبيرة باستخدام line_start/line_end أو max_tokens بدلًا من سحبها دفعةً واحدة
سياق المستودع	يُخزَّن حلّ مساحة الأسماء مؤقتًا ضمن الطلب الواحد فقط، لا عبر الاستدعاءات — فكل استدعاء لأداة يعيد الحلّ من جديد
ask_maguyva (guidance / evaluate)	شبه فوري — يعمل داخل Worker بلا أي استدعاء لقاعدة البيانات

معالجة الأخطاء#

تُعيد جميع طرق API غلاف استجابة منظّمًا:

status: سلسلة نصية — "success" أو "error". أما إشارات المطابقة المنقوصة والحداثة فتوجد في حقول متداخلة مثل metadata.resolution_reason في repository_context أو metadata.index_freshness.status.
tool: اسم الأداة التي أنشأت الاستجابة
data: حمولة النتيجة عند النجاح (تختلف البنية حسب الأداة)
error: كائن خطأ منظّم عندما تكون status هي "error" — يتضمّن type وmessage وsuggestions وrecovery_actions
metadata: معلومات إضافية عن العملية (التوجيه، التخزين المؤقت، تعديلات المعاملات)
pagination: موجود في استجابات القوائم — يتضمّن has_more وnext_cursor

تحقّق دائمًا من حقل status قبل معالجة النتائج — فقيمته لا تكون إلا "success" أو "error". وللاطّلاع على إشارات المطابقة المنقوصة أو الحداثة، اقرأ الحقل المتداخل بدلًا من ذلك: metadata.resolution_reason في repository_context، أو metadata.index_freshness.status (known/partial/unknown/unavailable).

البدء#

تهيئة عميل MCP: وجّه عميل MCP إلى نقطة نهاية خادم Maguyva
تحقّق من الوصول إلى المستودع: استعمل repository_context مع action="list" أو action="info" لفحص المستودعات المتاحة لمفتاح API
ابدأ البحث: استخدم intelligent_search كبداية واستكشف الأدوات المتخصصة حسب الحاجة
ادمج الأدوات: استعمل أدوات متعددة معًا لتحليل كود شامل

للحصول على تعليمات تكامل مفصّلة، راجع دليل التثبيت.