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

مرجع MCP API

استكشف أدوات MCP في Maguyva وعددها 11، ومعلماتها، ومتى تستخدم كلًا منها. راجع استجابة tools/list من عميلك المتصل لمعرفة الوسيطات المتاحة لك.

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

#

تُنظَّم الأدوات في 4 فئات:

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

للأدوات التي تقبل مستودعًا، استخدم صيغة معرّف المستودع هذا: "owner/repo:branch". الفرع الافتراضي هو main إن لم تحدده.

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

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

#

استخدم هذه الصيغ عند تحديد مستودع:

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

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

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

تصفية اللغة

#

استخدم language_filter في أوضاع البحث التي تدعمه. مع text_pattern_search، اختر search_scope="content"؛ ومع get_task_context، استخدم scope="semantic" من دون نقاط بدء أو سياق مرتبط.

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

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

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

#

intelligent_search مستقر

ابدأ هنا لأي سؤال عن قاعدة الشيفرة. يوجّه الوضع الافتراضي auto/balanced أسئلة التعريف التي يمكن تحديد مقصدها بثقة إلى البحث البنيوي، وأسئلة المراجع أو التأثير إلى الرسم البياني، وأسئلة التطابق التام إلى النص. وتستخدم الأسئلة الأخرى البحث الدلالي والنص المفهرس. لطلب الأنماط الأربعة جميعًا، استخدم mode=hybrid أو auto مع quality=thorough. تكون الأولوية للوضع المحدد صراحةً على quality. يستبعد language_filter الرسم البياني من auto/hybrid، ويُرفض عند استخدام mode=graph صراحةً. فضّل هذه الأداة على Grep/Glob عندما لا تعرف المسار مسبقًا.

المعاملات:

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

الأنسب لـ:

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

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

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

semantic_search مستقر

اعثر على الشيفرة حسب المعنى، لا النص المطابق. استخدمها لاستعلامات مفاهيمية مثل «منطق إعادة المحاولة» أو «مسار تهيئة المستخدم» عندما تجهل الكلمة المفتاحية أو اسم الرمز. تُرجع مقاطع ذات صلة مع تنوع محدود للملفات؛ ويمكن تفعيل إعادة الترتيب حسب الأهمية في المخطط عبر boost_by_importance. فضّلها على Grep للبحث المفاهيمي.

المعاملات:

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

الأنسب لـ:

  • استعلامات مفاهيمية («كيف تعمل المصادقة؟»، «استراتيجية التخزين المؤقت»)
  • بحث التشابه عبر الحزم

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

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

text_pattern_search مستقر

ابحث في المحتوى المفهرس. يبحث الوضعان exact وregex بحثًا نصيًا شبيهًا بـgrep في مجموعة الملفات/blob كاملة؛ ويبحث fuzzy content في مجموعة محدودة من المقاطع الدلالية. يقتصر النطاقان file وsymbol على المطابقة الثلاثية، ويُحوّل mode=exact الافتراضي إلى fuzzy. تتطلب خيارات اللغة وحالة الأحرف والعتبة المخصصة النطاق content. يستخدم ترشيح المسارات نافذة محدودة من المرشحين ويبلّغ عن التغطية غير المكتملة. استخدم Grep محليًا للبحث في مجلد محدد النطاق موجود على القرص.

المعاملات:

query مطلوب
النوع
str minLength=1
الوصف
نمط نصي للبحث
repository اختياري
النوع
str
الوصف
المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُفضَّل الفروع المفهرَسة المطابقة تمامًا؛ وقد يعود الفرع غير المتاح إلى main أو إلى الفرع الوحيد القابل للوصول. تُظهِر بيانات تعريف الاستجابة الهوية المطلوبة والهوية الفعلية التي تم تحديدها، وتحذّر عند حدوث هذا الرجوع.
mode اختياري
النوع
Literal[fuzzy, exact, regex]
الافتراضي
exact
الوصف
وضع البحث. تُنفَّذ التعبيرات النمطية (Regex) باستخدام صياغة PostgreSQL المتقدمة/POSIX؛ استخدم \y لحدود الكلمات (\b تعني محرف الرجوع للخلف). كما تمر الأنماط عبر مدقق أمان JavaScript، لذلك تُرفض البُنى الخاصة بـ PostgreSQL فقط مثل أعلام (?i) المضمّنة؛ استخدم case_sensitive بدلاً من ذلك.
search_scope اختياري
النوع
Literal[content, symbols, files]
الافتراضي
content
الوصف
ما الذي تُجري عليه البحث
limit اختياري
النوع
int minimum=1, maximum=50
الافتراضي
5
الوصف
الحد الأقصى لعدد النتائج في الصفحة عند عدم استخدام cursor. تعتمد المتابعة على حجم الصفحة المخزَّن في cursor؛ احذف cursor لتبدأ بقيمة limit مختلفة.
offset اختياري
النوع
int minimum=0
الوصف
إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.
cursor اختياري
النوع
str
الوصف
cursor غير شفاف من pagination.next_cursor. مرِّره كما هو واحتفظ بـ query والمرشِّحات دون تغيير. يكون لموضعه وحجم صفحته الأولوية على offset و limit.
language_filter اختياري
النوع
str
الوصف
فلتر اللغة
path_filter اختياري
النوع
str
الوصف
تصفية بحسب بادئة مسار الملف
case_sensitive اختياري
النوع
bool
الافتراضي
false
الوصف
مطابقة حساسة لحالة الأحرف
branch اختياري
النوع
str
الوصف
تجاوز الفرع
fuzzy_algorithm اختياري
النوع
Literal[hybrid, trigram, levenshtein]
الافتراضي
hybrid
الوصف
خوارزمية المطابقة التقريبية
threshold اختياري
النوع
float minimum=0, maximum=1
الافتراضي
0.05
الوصف
حد التشابه الأدنى للمطابقة التقريبية
semantic_fallback اختياري
النوع
bool
الافتراضي
false
الوصف
يحاول إجراء semantic search بعد أن تكون الصفحة اللفظية الأولى فارغة؛ يميّز metadata.fallback_status بين حالات الرجوع used و empty و unavailable.

الأنسب لـ:

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

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

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

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

#

structural_search مستقر

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

المعاملات:

repository اختياري
النوع
str
الوصف
المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُفضَّل الفروع المفهرَسة المطابقة تمامًا؛ وقد يعود الفرع غير المتاح إلى main أو إلى الفرع الوحيد القابل للوصول. تُظهِر بيانات تعريف الاستجابة الهوية المطلوبة والهوية الفعلية التي تم تحديدها، وتحذّر عند حدوث هذا الرجوع.
preset اختياري
النوع
Literal[functions, classes, methods, imports, variables]
الوصف
المحدِّد البنيوي المُفضَّل. يتوسّع إلى أنواع عُقَد AST متعددة اللغات — functions (تعريفات function/arrow/method عبر اللغات)؛ classes (إعلانات class/struct/interface وأجسام الأنواع والتنفيذات)؛ methods (تعريفات method (وfunction_definition للغات التي لا تملك عُقدة method))؛ imports (عبارات import/use/include)؛ variables (تصريحات variable/let/const/static). يُفضَّل على pattern/node_type الحرّين لاستعلامات التصفّح.
pattern اختياري
النوع
str
الوصف
يملأ pattern الحر المحدِّدات الناقصة (اكتشاف تلقائي: 'def foo(' → node_type + name_pattern). يمكن دمجه مع preset؛ وللمحدِّدات الصريحة الأولوية. يُفضَّل استخدام preset= في استعلامات التصفّح.
name_pattern اختياري
النوع
str maxLength=256
الوصف
نمط اسم الرمز (محارف البدل لمفسّر الأوامر، أو تعبير POSIX regex محدود، أو نص تقريبي؛ 256 حرفًا كحد أقصى)
node_type اختياري
النوع
str
الوصف
نوع عُقدة AST (function_definition، class_definition، إلخ) — يُفضَّل استخدام preset= للأشكال الشائعة
decorator اختياري
النوع
str
الوصف
فلتر اسم الديكوريتور
base_class اختياري
النوع
str
الوصف
فلتر اسم الفئة الأساسية
language_filter اختياري
النوع
str
الوصف
مرشّح اللغة (python، typescript، إلخ)
limit اختياري
النوع
int minimum=1, maximum=50
الافتراضي
20
الوصف
الحد الأقصى لعدد النتائج في الصفحة عند عدم استخدام cursor. تعتمد المتابعة على حجم الصفحة المخزَّن في cursor؛ احذف cursor لتبدأ بقيمة limit مختلفة.
offset اختياري
النوع
int minimum=0
الوصف
إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.
cursor اختياري
النوع
str
الوصف
cursor غير شفاف من pagination.next_cursor. مرِّره كما هو واحتفظ بـ query والمرشِّحات دون تغيير. يكون لموضعه وحجم صفحته الأولوية على offset و limit.
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
الافتراضي
false
الوصف
اضبط true عند استخدام مرشحات المسار/ltree/الاستدعاءات المتقدمة عمدًا (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). عند ضبط false، تُطبَّق المرشحات المتقدمة المُقدَّمة مع تحذير في البيانات الوصفية. فضّل preset= للاستعلامات البنيوية الشائعة.
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). يتضمن dependents/impact افتراضيًا production_callers: مواضع استخدام فريدة في شيفرة الإنتاج بحسب النوع (call وinstantiate وvalue_reference للدوال الممرّرة كقيم)، إضافةً إلى مواضع IMPORT، مع استبعاد الاختبارات وبيان الثقة EXTRACTED/INFERRED — وليس مجرد سرد للمقاييس. لتأثير PR/diff: مرّر changed_paths و/أو patch (فروق موحّدة)، لتحديد الرموز لكل مسار وإرجاع بيانات موجزة عن المكونات التابعة الواردة بعمق محدود، من دون اشتراط اسم رمز. بعد التعديل، اضبط verify_after_edit=true مع targets و/أو changed_paths لإعادة استعلام موجزة من جذور متعددة عن الرموز المتأثرة. يدعم أيضًا dependencies وcentrality وorphans. يستخدم analyze_dependencies الاجتياز نفسه لتحليل التأثير عبر خطوات متعددة.

المعاملات:

repository اختياري
النوع
str
الوصف
المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُفضَّل الفروع المفهرَسة المطابقة تمامًا؛ وقد يعود الفرع غير المتاح إلى main أو إلى الفرع الوحيد القابل للوصول. تُظهِر بيانات تعريف الاستجابة الهوية المطلوبة والهوية الفعلية التي تم تحديدها، وتحذّر عند حدوث هذا الرجوع.
query اختياري
النوع
str
الوصف
اسم الرمز أو مصطلح البحث
target اختياري
النوع
str
الوصف
اسم الرمز (اسم بديل للمعامل query)
symbol_id اختياري
النوع
UUID
الوصف
اختر بواسطة UUID ظهورًا محددًا من بين المرشحين المطابقين للاسم المحدد في query/target، بعد التصفية حسب نطاق الأسماء والمسار واللغة. استخدم ID أعاده find_symbol أو النتائج البديلة للرسم البياني. يقتصر الاستخدام على الاجتياز باسم محدد؛ يؤدي ID خارج نافذة المرشحين المحدودة إلى خطأ.
changed_paths اختياري
النوع
list[str] maxItems=50
الوصف
مسارات ملفات دقيقة نسبية إلى جذر المستودع لتحليل تأثير PR/diff (افتراضيًا)، أو جذور للتحقق بعد التعديل عند ضبط verify_after_edit=true. قد تُعيد المسارات غير القابلة للتحليل اقتراحات موسومة؛ ولا تصبح الملفات المقترحة أبدًا نقاط بدء للتأثير. في تحليل PR/diff: عند غياب معلومات الأسطر، تُجتاز التعريفات ذات المستوى الأعلى في كل مسار (المُصدَّرة أولًا، بترتيب الملف) ويُبلَّغ عن changed_lines_unknown؛ مرِّر patch= للحصول على الرموز المتغيرة على مستوى السطر. في التحقق: حتى 5 تعريفات من المستوى الأعلى لكل مسار كنقاط بدء للتحقق (مع حد أقل داخل وضع التحقق). لا يتطلب تأثير PR/diff تمرير query/target.
patch اختياري
النوع
str maxLength=500000
الوصف
تأثير PR/diff: نص بصيغة unified diff / git patch. تُؤخذ المسارات من رؤوس diff --git / --- / +++؛ وتُربط أسطر كتل التغيير (الجانب القديم = الإيداع المفهرس) بالدوال أو التوابع أو الأصناف التي تحتويها، ثم تُجتاز هذه للحصول على العناصر المعتمدة بدقة، و public_api_changed، والمستدعين الذين لا تمسّهم التغييرات.
head_commit اختياري
النوع
str pattern=^[0-9a-fA-F]{7,64}$
الوصف
قيمة SHA للإيداع الخاص بالكود الذي تسأل عنه (git rev-parse HEAD، أو الإيداع الأساسي للتصحيح). يتطلب complete:true أن يكون الفهرس عند هذا الإيداع وأن يكون قد بُني بالمحلّل الحالي؛ وإلا تبقى القيمة complete:false مع index_stale / index_freshness_unverified / index_built_by_older_resolver، ويوضّح index_basis.statement النطاق الذي تكون الإجابة كاملة ضمنه. يوفّرها أيضًا سطر 'base-commit:' في التصحيح (git format-patch --base).
analysis_type اختياري
النوع
Literal[centrality, dependencies, dependents, impact, orphans]
الافتراضي
dependencies
الوصف
وضع التحليل. impact = نطاق التأثير (العناصر المعتمدة الواردة؛ عمق ضحل عند إغفال depth). dependents يجيب أيضًا عن التأثير. عند ضبط changed_paths أو patch، يُفرَض التحليل على تأثير PR/diff. لا يتطلّب centrality/orphans هدفًا. إن orphans مرشّحات لكود غير مستخدَم، وليست دليلًا على أن حذفه آمن؛ تحقّق من المراجع في الشيفرة المصدرية.
depth اختياري
النوع
Literal[shallow, balanced, deep]
الوصف
عمق الاجتياز. القيمة الافتراضية balanced؛ يستخدم impact و PR/diff impact القيمة shallow افتراضيًا. يؤدي تحديد depth صراحةً إلى تجاوز هذه الإعدادات الافتراضية. يستخدم وضع التحقق دائمًا shallow.
limit اختياري
النوع
int minimum=1, maximum=50
الافتراضي
20
الوصف
الحد الأقصى لعدد النتائج في الصفحة عند عدم استخدام cursor. تعتمد المتابعة على حجم الصفحة المخزَّن في cursor؛ احذف cursor لتبدأ بقيمة limit مختلفة.
offset اختياري
النوع
int minimum=0
الوصف
إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.
cursor اختياري
النوع
str
الوصف
cursor غير شفاف من pagination.next_cursor. مرِّره كما هو واحتفظ بـ query والمرشِّحات دون تغيير. يكون لموضعه وحجم صفحته الأولوية على offset و limit.
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
الافتراضي
false
الوصف
استبعاد التصريحات المُولَّدة ومسارات نواتج البناء وتقارير التغطية والتخزين المؤقت وخرائط المصدر والملفات المُصغَّرة من نتائج الاجتياز
include_module_symbols اختياري
النوع
bool
الافتراضي
false
الوصف
افتراضيًا، يستبعد false حواف الرسم البياني عندما يكون from_name أو to_name هو رمز __module__ الاصطناعي (ضوضاء على مستوى الوحدة النمطية). قم بتعيين true لتضمين حواف مستوى الوحدة النمطية في نتائج العناصر المعتمدة والتبعيات.
include_isolated اختياري
النوع
bool
الوصف
لتحليل orphan فقط. الافتراضي false. اضبطه على true لإرجاع الرموز التي ليس لها صف في مقاييس الرسم البياني أيضًا (أي بلا أي حواف في الرسم البياني على الإطلاق). ما دام exclude_test_paths مضبوطًا على true، تظل رموز أوراق الأنماط والترميز والبيانات (CSS وHTML و...) وتصريحات .d.ts ومسارات test/fixture/vendor/example مستبعدة حيث تدعم الواجهة الخلفية ذلك، ما لم يحدّد language_filter تلك اللغة؛ وقد تظل خصائص الكائنات الحرفية في TypeScript تظهر كدوال معزولة.
exclude_exported اختياري
النوع
bool
الافتراضي
false
الوصف
للرموز اليتيمة فقط. القيمة الافتراضية false: تُعاد الرموز المُصدَّرة (API العامة) التي لا يستخدمها شيء في المستودع مع is_exported=true. اضبطها على true لحصر النتائج في المرشحين الداخليين.
branch اختياري
النوع
str
الوصف
تجاوز الفرع
per_hop_limit اختياري
النوع
int minimum=1, maximum=300
الوصف
الحد الأقصى للعلاقات لكل قفزة (1-300)
include_metrics اختياري
النوع
bool
الافتراضي
false
الوصف
مقاييس رسم بياني اختيارية على صفوف النتائج (مُدمجة مع refactor_risk). تُجلب المقاييس أيضًا داخليًا عندما يكون min_centrality>0 لكنها لا تُعاد ما لم يكن هذا true.
metrics_detail اختياري
النوع
Literal[summary, full]
الافتراضي
summary
الوصف
عندما include_metrics=true: summary (افتراضي) يُرجع إشارات القرار + refactor_risk؛ تقوم full بإرجاع مجموعة المقاييس المنسقة الأكبر
include_edge_metadata اختياري
النوع
bool
الافتراضي
false
الوصف
تضمين البيانات الوصفية الخام للحواف وأوزانها (كبيرة الحجم). تظلّ هذه الميزة معطّلة في الاستجابات الموجزة لتحليل التأثير.
symbol_types اختياري
النوع
list[str]
الوصف
يُصفّي الرموز المُعادة حسب النوع (function، class، method، إلخ). غير مدعوم في تحليل orphan؛ استخدم بدلًا منه path_filter أو language_filter. لا تطبّق القائمة الفارغة أي تصفية حسب النوع.
exact_match اختياري
النوع
bool
الافتراضي
false
الوصف
اشتراط تطابق اسم الرمز تطابقًا تامًا
find_similar_patterns اختياري
النوع
bool
الافتراضي
false
الوصف
إيجاد أنماط استخدام مشابهة
min_centrality اختياري
النوع
float minimum=0
الافتراضي
0
الوصف
أدنى درجة PageRank لاجتياز الرموز المسمّاة ولتحليل أثر PR/diff. لا تُدعم العتبات الموجبة في وضعَي التصفح centrality/orphans. تُجلب المقاييس داخليًا للتصفية؛ ولا تُعاد graph_metrics إلا عندما يكون include_metrics=true. ويتجاهلها verify_after_edit الذي يستخدم ضوابط مضغوطة ثابتة.
graph_view اختياري
النوع
Literal[dependency, type, data_flow, control_flow]
الافتراضي
dependency
الوصف
عرض الرسم البياني المُستخدَم لافتراضيات علاقات التجوال والمقاييس وترتيب المركزية؛ يُحسب تحليل orphan عبر جميع العروض
verify_after_edit اختياري
النوع
bool
الافتراضي
false
الوصف
يُعيد استعلام رسم impact المُفهرَس للرموز التي جرى تعديلها ضمن استجابة واحدة مُدمَجة متعددة الجذور. يتطلب targets و/أو changed_paths (أو target/query). يستخدم اجتيازًا ثابتًا من نوع shallow وميزانيات مُدمَجة؛ لا تنطبق ضوابط depth/limit/cursor/metrics. تُعاد افتراضيًا العناصر المعتمدة الواردة؛ وتعكس النتائج الرسم المُفهرَس (قد تتأخر عن التعديلات المباشرة). عندما تكون القيمة true، تُعطى الأولوية على PR/diff impact لنفس changed_paths.
targets اختياري
النوع
list[str] maxItems=15
الوصف
عند 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]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُفضَّل الفروع المفهرَسة المطابقة تمامًا؛ وقد يعود الفرع غير المتاح إلى main أو إلى الفرع الوحيد القابل للوصول. تُظهِر بيانات تعريف الاستجابة الهوية المطلوبة والهوية الفعلية التي تم تحديدها، وتحذّر عند حدوث هذا الرجوع.
scope اختياري
النوع
Literal[definitions, references, both]
الافتراضي
both
الوصف
نطاق البحث؛ يتطلب references قيمة symbol_name غير فارغة.
limit اختياري
النوع
int minimum=1, maximum=50
الافتراضي
15
الوصف
الحد الأقصى لعدد النتائج في الصفحة عند عدم استخدام cursor. تعتمد المتابعة على حجم الصفحة المخزَّن في cursor؛ احذف cursor لتبدأ بقيمة limit مختلفة.
offset اختياري
النوع
int minimum=0
الوصف
إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.
cursor اختياري
النوع
str
الوصف
cursor غير شفاف من pagination.next_cursor. مرِّره كما هو واحتفظ بـ query والمرشِّحات دون تغيير. يكون لموضعه وحجم صفحته الأولوية على offset و limit.
find_similar اختياري
النوع
bool
الافتراضي
false
الوصف
تضمين أسماء رموز مشابهة
include_metrics اختياري
النوع
bool
الافتراضي
false
الوصف
تضمين مقاييس المركزية
metrics_detail اختياري
النوع
Literal[summary, full]
الافتراضي
summary
الوصف
عندما include_metrics=true: summary (افتراضي) يُرجع إشارات القرار + refactor_risk؛ تقوم full بإرجاع مجموعة المقاييس المنسقة الأكبر
path_filter اختياري
النوع
str
الوصف
تصفية بحسب بادئة مسار الملف
branch اختياري
النوع
str
الوصف
تجاوز الفرع
symbol_type اختياري
النوع
str minLength=1
الوصف
التصفية حسب نوع الرمز المفهرس، مثل function وclass وstruct وenum أو trait. استخدم النوع الذي تُعيده نتيجة الرمز؛ يختلف النوع حسب اللغة.
high_impact اختياري
النوع
bool
الافتراضي
false
الوصف
تصفّح الرموز المهمة معماريًا (أغفِل symbol_name). الوضع الافتراضي هو الشعبية (أعلى عُشْر من PageRank ناقص المحاور الضخمة المساعِدة). اضبط high_impact_mode=risk لرؤوس القطع والجسور.
high_impact_mode اختياري
النوع
Literal[popularity, risk]
الافتراضي
popularity
الوصف
عند high_impact=true: ‏popularity = أعلى عُشر من درجات PageRank مع استبعاد المحاور الضخمة والوحدات المساعدة؛ risk = نقاط القطع مرتبة حسب SMV bridge_count ثم k_core (خطر إعادة الهيكلة البنيوية، لا شعبية المحور)
in_cycle اختياري
النوع
bool
الافتراضي
false
الوصف
يُصفّي الرموز التي جرى تسجيل عضويتها في دورة تبعية.
exclude_test_paths اختياري
النوع
bool
الافتراضي
true
الوصف
عند التصفح بحسب مقاييس الرسم البياني، تُستبعد الاختبارات وحالات الاختبار وكود الأطراف الثالثة والأمثلة قبل الترتيب؛ ولا يتغير البحث عن الرموز بالاسم
reference_views اختياري
النوع
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
الوصف
عروض الرسم البياني التي تملأ حوافها الواردة references/reference_count (عند scope بقيمة references/both). القيمة الافتراضية ["dependency", "type"] تشمل الاستدعاءات والاستيراد والتصدير والمراجع وإنشاء الكائنات والوراثة وإعادة التعريف والمزيّنات واستخدام الأنواع. ما لم يُحدَّد data_flow، تُعاد استخدامات data_flow المحلولة بدقة (دوال رد النداء والمعالجات ومفاتيح الفرز) منفصلةً في value_references/value_reference_count، دون تطابقات مستنتجة من الاسم وحده. أضف data_flow أو control_flow، أو مرّر ["all"] لكل أنواع الحواف ومستوياتها. عائلات العروض هي نفسها في graph_view لأداة dependency_search.
relationship_types اختياري
النوع
list[str]
الوصف
أنواع حواف المراجع المحددة صراحةً (CALL وIMPORT وREADS وغيرها). تحل القائمة غير الفارغة محل reference_views.

الأنسب لـ:

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

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

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

analyze_dependencies مستقر

حلّل نطاق التأثير باستخدام الاجتياز نفسه في dependency_search (dependents/incoming). فضّل dependency_search مع analysis_type="dependents" أو "impact" لتحليل التأثير. يعيد استجابة تأثير عبر خطوات متعددة تتضمن graph وconnection_summary ومقاييس اختيارية مع refactor_risk. يحسب connection_summary الحوافّ المحصورة بعائلة العلاقات للجذر المختار قبل أي تصفية بالاختبارات أو المسارات. وتعني الحقول القديمة incoming_production/outgoing_production الحوافّ غير المرتبطة بالوحدات، بما في ذلك الاختبارات؛ وهي ليست أعدادًا لمستدعيات الإنتاج. استخدم graph_view لحصر عائلة العلاقات: dependency (الافتراضي)، type، data_flow، control_flow.

المعاملات:

repository اختياري
النوع
str
الوصف
المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُفضَّل الفروع المفهرَسة المطابقة تمامًا؛ وقد يعود الفرع غير المتاح إلى main أو إلى الفرع الوحيد القابل للوصول. تُظهِر بيانات تعريف الاستجابة الهوية المطلوبة والهوية الفعلية التي تم تحديدها، وتحذّر عند حدوث هذا الرجوع.
target مطلوب
النوع
str minLength=1
الوصف
اسم الرمز لتحليله
symbol_id اختياري
النوع
UUID
الوصف
اختر بواسطة UUID ظهورًا محددًا من بين مرشحي target، بعد التصفية حسب نطاق الأسماء والمسار واللغة؛ تؤدي قيم ID خارج نافذة المرشحين المحدودة إلى خطأ.
depth اختياري
النوع
Literal[shallow, balanced, deep]
الافتراضي
balanced
الوصف
عمق التحليل
limit اختياري
النوع
int minimum=1, maximum=50
الافتراضي
10
الوصف
الحد الأقصى لعدد النتائج في الصفحة عند عدم استخدام cursor. تعتمد المتابعة على حجم الصفحة المخزَّن في cursor؛ احذف cursor لتبدأ بقيمة limit مختلفة.
offset اختياري
النوع
int minimum=0
الوصف
إزاحة توافقية مهملة. يُفضَّل استخدام cursor من pagination.next_cursor.
cursor اختياري
النوع
str
الوصف
cursor غير شفاف من pagination.next_cursor. مرِّره كما هو واحتفظ بـ query والمرشِّحات دون تغيير. يكون لموضعه وحجم صفحته الأولوية على offset و limit.
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 عندما يكون relationship_types محذوفًا أو فارغًا. يطابق اسم المعامل graph_view الموجود مسبقًا في dependency_search، تحقيقًا للاتساق بين الأدوات.
path_filter اختياري
النوع
str
الوصف
قصْر تحديد الرمز الهدف على بادئة مسار الملف؛ قد تتجاوز علاقات الرسم البياني المُعادة ذلك المسار
language_filter اختياري
النوع
str
الوصف
فلتر اللغة
branch اختياري
النوع
str
الوصف
تجاوز الفرع
per_hop_limit اختياري
النوع
int minimum=1, maximum=300
الوصف
الحد الأقصى للعلاقات لكل قفزة (1-300)
include_metrics اختياري
النوع
bool
الافتراضي
false
الوصف
قم بتضمين مقاييس الرسم البياني في النتائج، مع تعزيز كل منها بكتلة 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
الافتراضي
false
الوصف
تضمين البيانات الوصفية الخام للحواف وأوزانها. معطّل افتراضيًا لأن البيانات الوصفية للاستخراج قد تكون كبيرة الحجم؛ ويُبلَّغ عن مدى توفر البيانات الإضافية عند تفعيله.
exclude_test_paths اختياري
النوع
bool
الافتراضي
true
الوصف
الافتراضي true: استبعاد مسارات الاختبارات وحالات الاختبار وكود الأطراف الثالثة والأمثلة من حواف الرسم البياني المُعادة. اضبط false لتضمينها.
include_module_symbols اختياري
النوع
bool
الافتراضي
false
الوصف
افتراضيًا، يستبعد false حواف الرسم البياني عندما يكون from_name أو to_name هو رمز __module__ الاصطناعي. قم بتعيين true ليشمل حواف مستوى الوحدة.
head_commit اختياري
النوع
str pattern=^[0-9a-fA-F]{7,64}$
الوصف
قيمة SHA للإيداع الخاص بالكود الذي تسأل عنه (git rev-parse HEAD، أو الإيداع الأساسي للتصحيح). يتطلب complete:true أن يكون الفهرس عند هذا الإيداع وأن يكون قد بُني بالمحلّل الحالي؛ وإلا تبقى القيمة complete:false مع index_stale / index_freshness_unverified / index_built_by_older_resolver، ويوضّح index_basis.statement النطاق الذي تكون الإجابة كاملة ضمنه. يوفّرها أيضًا سطر 'base-commit:' في التصحيح (git format-patch --base).

الأنسب لـ:

  • تحليل التأثير عبر خطوات متعددة عندما تحتاج إلى حقلي الاستجابة graph وconnection_summary

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

  • تحليل التأثير العام؛ فضّل dependency_search لاجتياز مرن وفحوص من جذور متعددة

get_task_context مستقر

هل تبدأ العمل في منطقة غير مألوفة؟ صِف المهمة (مثل "أضِف دعم SSO"، "أصلِح webhook الفوترة") واحصل، في استدعاء واحد، على مجموعة محدودة من الملفات والكود والرموز والتبعيات ذات الصلة. تُسهم الملفات المُمرَّرة كنقطة انطلاق بمحتوى مُفهرَس مباشرةً حتى لو لم تُعرِّف أي رموز. تُوسَم الطبقات الفاشلة؛ ويُعيد الفشل الكامل في الاسترجاع خطأ أداة. لمزيد من النتائج، تابع باستخدام أداة البحث المتخصصة لتلك الطبقة.

المعاملات:

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

الأنسب لـ:

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

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

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

get_file مستقر

قراءة ملف من المستودع المفهرس عبر المسار. يُفضَّل استخدام أدوات الملفات المحلية للملفات الموجودة على القرص؛ استخدم هذا للقطات المفهرسة عن بُعد. تابع الاستجابات المحدودة باستخدام metadata.next_line_start وnext_character_start. أزل حرف السطر الجديد الأخير وعلامة [truncated] فقط عندما تكون metadata.truncated=true؛ وإلا فقد يكون نصًا مصدريًا حرفيًا.

المعاملات:

file_path مطلوب
النوع
str
الوصف
مسار الملف بالنسبة لجذر المستودع
repository اختياري
النوع
str
الوصف
المستودع بصيغة owner/repo[:branch]. اختياري — احذفه لاستخدام الافتراضي الموفَّر على مستوى الطلب من عميلك (عند توفّره) أو المستودع الوحيد القابل للوصول؛ مرِّره صراحةً فقط عند استهداف مستودع مفهرَس مختلف. تُفضَّل الفروع المفهرَسة المطابقة تمامًا؛ وقد يعود الفرع غير المتاح إلى main أو إلى الفرع الوحيد القابل للوصول. تُظهِر بيانات تعريف الاستجابة الهوية المطلوبة والهوية الفعلية التي تم تحديدها، وتحذّر عند حدوث هذا الرجوع.
line_start اختياري
النوع
int minimum=1
الوصف
سطر البداية (يبدأ الترقيم من 1)
line_end اختياري
النوع
int minimum=1
الوصف
سطر النهاية (مفهرس من 1، شامل؛ يجب أن يكون عند line_start أو بعده)
character_start اختياري
النوع
int minimum=0
الافتراضي
0
الوصف
إزاحة بوحدات ترميز UTF-16 داخل سطر البداية فقط (تبدأ من 0). استخدم metadata.next_character_start لمتابعة سطر جزئي.
branch اختياري
النوع
str
الوصف
تجاوز الفرع
max_tokens اختياري
النوع
int minimum=1, maximum=50000
الافتراضي
5000
الوصف
ميزانية تقريبية للمحتوى (4 وحدات ترميز UTF-16 لكل توكن؛ ليست حدًا دقيقًا لأداة تقسيم التوكنات).
include_metadata اختياري
النوع
bool
الافتراضي
true
الوصف
تضمين البيانات الوصفية التعريفية للملف. تُرجع بيانات الاقتطاع والاستكمال دائمًا.

الأنسب لـ:

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

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

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

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

#

repository_context مستقر

يسرد المستودعات التي يمكنك البحث فيها، أو يحصل على معلومات الهوية لمستودع واحد (namespace/branch، indexed_commit_sha / حداثة الفهرس). استخدم action:"list" عندما يكون slug المستودع غير معروف؛ تقبل أدوات البحث slug معروفًا مباشرةً أو تستخدم افتراضيًا المستودع الوحيد لمفتاحك. يستخدم list كلًا من pattern والترقيم الصفحي؛ ويتطلب info وجود repository ويدعم branch وخيار include_statistics=true.

المعاملات:

action مطلوب
النوع
Literal[list, info]
الوصف
الإجراء: عرض المستودعات المتاحة أو الحصول على معلومات عن مستودع
repository اختياري
النوع
str
الوصف
لـ info فقط: المستودع بصيغة owner/repo أو owner/repo:branch (مطلوب لـ info)
branch اختياري
النوع
str
الوصف
لـ info فقط: تجاوز الفرع
pattern اختياري
النوع
str
الوصف
لـ list فقط: سلسلة فرعية من اسم المستودع لا تُميّز بين حالة الأحرف
include_statistics اختياري
النوع
bool
الافتراضي
false
الوصف
للعرض فقط: يتضمن أعداد بيانات مفهرسة محدودة. أعداد file/blob دقيقة؛ أما أعداد الفهرسة الأكبر فهي تقديرية. راجع count_accuracy وestimate_analyzed_at. القيمة الافتراضية false.
limit اختياري
النوع
int minimum=1, maximum=50
الافتراضي
20
الوصف
الحد الأقصى لعدد النتائج في الصفحة عند عدم استخدام cursor. تعتمد المتابعة على حجم الصفحة المخزَّن في cursor؛ احذف cursor لتبدأ بقيمة limit مختلفة.
offset اختياري
النوع
int minimum=0
الوصف
إزاحة قديمة متاحة للتوافق. يُفضَّل استخدام cursor من pagination.next_cursor.
cursor اختياري
النوع
str
الوصف
cursor غير شفاف من pagination.next_cursor. مرِّره كما هو واحتفظ بـ query والمرشِّحات دون تغيير. يكون لموضعه وحجم صفحته الأولوية على offset و limit.

الأنسب لـ:

  • سرد المستودعات المتاحة
  • تحديد هوية المستودع والفرع ومدى حداثة 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 maxLength=500
الوصف
موضوع الإرشادات (مثل tool_selection وsemantic_search)، أو سلسلة نصية لتعبير يُنفَّذ عبر evaluate.
description اختياري
النوع
str minLength=1, maxLength=4000
الوصف
مطلوب لـ 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

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

  • حسابات الرياضيات والتجزئة والسلاسل النصية؛ فضّل الحساب المحلي أو أدوات البيئة المضيفة

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

#
  1. استخدم التجاوزات الصريحة بعناية: لا تمرّر repository عندما يوفّر عميل MCP قيمة افتراضية على مستوى الطلب أو عندما يستطيع المفتاح الوصول إلى مستودع واحد بالضبط؛ وإلا فمرِّره صراحةً.
  2. اختر وضع البحث المناسب: استخدم intelligent_search مع mode="auto" في معظم الحالات. حدِّد وضعًا عندما تعرف بالضبط ما تحتاجه.
  3. استفد من فلاتر اللغة: استخدم language_filter لتضييق النتائج وتحسين الأداء.
  4. تعزيز GraphRAG: تعزيز الأهمية عبر GraphRAG معطَّل افتراضيًا في البحث الدلالي (boost_by_importance=false) للحفاظ على ترتيب آمن للوكلاء. مرِّر boost_by_importance=true لتفعيل إعادة ترتيب واعية بالمركزية عند جولات استكشاف المعمارية.
  5. مطابقة المستودعات غير حسّاسة لحالة الأحرف، وليست تقريبية: يطابق repository_context أسماء المستودعات دون حسّاسية لحالة الأحرف — لكنه لا يصحّح الأخطاء الإملائية. وعندما تختلف الهوية المقدَّمة عن المطلوبة، يبلّغ metadata.resolution_reason عن "defaulted" (لم يُطلب أي فرع) أو "fallback" (الفرع أو المستودع المطلوب غير متاح). ويُحذف هذا الحقل عندما يتطابق الطلب تمامًا.
  6. ادمج الأدوات: استخدم عدة طرق API معًا للحصول على تحليل شامل.
  7. تعامل مع النتائج الكبيرة: استخدم limit وعناصر تحكّم التصفّح الخاصة بكل أداة (مثل line_start/line_end في get_file).
  8. استخدم ask_maguyva للحصول على إرشادات الأدوات: استدعِ ask_maguyva مع operation="guidance" وquery="tool_selection" للحصول على نصائح وأمثلة لاختيار الأدوات. استخدم أدواتك المحلية للحسابات وتحويل السلاسل النصية.
  9. تحقّق من الأثر قبل التعديل وبعده: قبل تعديل رمز مشترك، استدعِ dependency_search مع analysis_type="impact" (أو مرّر changed_paths لتحليل أثر PR/diff) لمعرفة نطاق التأثير. بعد التعديل، اضبط verify_after_edit=true مع targets و/أو changed_paths لإعادة فحص موجزة للمخطط المفهرس. لا يقرأ هذا التغييرات المحلية التي لم تُودَع بعد، ولا يحلّ محل الاختبارات المحلية. تحقّق من indexed_commit_sha وحداثة الفهرس قبل اعتبار النتائج دليلًا على نسخة جديدة من الكود.

خصائص الأداء

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

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

#

تحتوي استجابات الأدوات على حقول حالة مشتركة وحقول بيانات خاصة بكل أداة في المستوى الأعلى. تعيد عمليات البحث results؛ ويعيد get_file الحقل content. تشمل الحقول المشتركة:

  • status: سلسلة نصية — "success" أو "error". ولإشارات المطابقة المنقوصة وحداثة الفهرس حقولها الخاصة: metadata.resolution_reason ضمن metadata، وindex_freshness.status في المستوى الأعلى من إجراء info في repository_context.
  • timing_ms: الوقت المنقضي لتنفيذ الأداة بالمللي ثانية
  • applied_filters: معلمات الطلب الفعلية المسجّلة للعملية
  • error: نص رسالة خطأ عندما تكون status هي "error"؛ وقد يتضمن إرشادات للتعافي.
  • metadata: معلومات إضافية عن العملية (التوجيه، التخزين المؤقت، تعديلات المعاملات)
  • pagination: يظهر في استجابات المجموعات المقسّمة إلى صفحات باستخدام مؤشر — ويضم has_more وnext_cursor. نوافذ البحث المرتّبة هي نتائج top-K محدودة، وليست مجموعات شاملة مقسّمة إلى صفحات.

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

البدء

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

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

ذو صلة

اقرأ أيضاً