# كيف يعمل Maguyva

Canonical source: https://maguyva.ai/ar/docs/how-it-works

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

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

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

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

يوفّر Maguyva عددًا من قدرات الاسترجاع يبلغ 5: semantic, AST, symbol, dependency, text. يتيح intelligent_search أربعة أنماط بحث: دلالي ونصي وبنيوي وعبر الرسم البياني. يوجّه الوضع الافتراضي auto/balanced أسئلة التعريف التي يمكن تحديد مقصدها بثقة إلى البحث البنيوي، وأسئلة المراجع أو التأثير إلى الرسم البياني، وأسئلة التطابق التام إلى النص. وتستخدم الأسئلة الأخرى البحث الدلالي والنص المفهرس. لطلب الأنماط الأربعة جميعًا، استخدم mode=hybrid أو auto مع quality=thorough. تكون الأولوية للوضع المحدد صراحةً على quality. يستبعد language_filter الرسم البياني من auto/hybrid، ويُرفض عند استخدام mode=graph صراحةً. تُدمج النتائج من الأنماط المتعددة وتُرتّب بحسب صلتها بالاستعلام.

توجد طرق عرض المستودع الخاص جنبًا إلى جنب مع بيانات مرجعية عامة لـlanguages and text-based technologies المدعومة. يصل وكيلك إلى النظام بأكمله عبر أدوات MCP، التي يمكنك الاعتماد عليها بكثافة أثناء التخطيط والتحقق، أو استخدامها كفحوصات سريعة أثناء التحرير.

### 1. استيعاب المستودع

- **تحليل بنية الشيفرة**: يحلّل الملفات إلى رموز ومراجع وحدود معمارية
- **حل التبعيات**: يرسم كيفية اعتماد الملفات والوحدات والرموز على بعضها البعض
- **دمج التوثيق**: يستقطب وثائق المستودع والمواد المرجعية ذات الصلة جنبًا إلى جنب مع الشيفرة

### التوجيه والترتيب

- **تقييم الصلة**: يختار أدلة الاسترجاع بحسب وضع البحث وإعداد الجودة، ثم يرتّب المطابقات بحسب صلتها بالاستعلام
- **تقليل الضجيج**: يقلّل المطابقات المكررة ويحدّ عدد المقاطع لكل ملف كي لا يملأ ملف واحد نافذة النتائج
- **ترتيب أولوية السياق**: يحافظ افتراضيًا على نتائج محدودة وذات صلة. يُفعَّل تعزيز الأهمية اختياريًا باستخدام boost_by_importance=true لاستكشاف المعمارية، وليس هو سياسة الترتيب الافتراضية

### التمثيلات المخزَّنة

- **الاسترجاع الدلالي**: يجد شيفرة ووثائق متشابهة من حيث المفهوم حتى لو اختلفت الكلمات الحرفية
- **عروض الرموز والبنية**: يدعم البحث الدقيق عن الرموز، والمراجع، والأسئلة المرتبطة بشكل AST
- **تحليل الرسم البياني للتبعيات**: يتتبّع المستدعين، والاستيرادات، ونطاق التأثير عبر قاعدة الشيفرة

### ميزات الأمان

- **أمان النقل**: تستخدم الاتصالات بالخدمة بروتوكول HTTPS/TLS
- **تخزين مُدار**: تُخزَّن البيانات المفهرَسة على بنية تحتية مُدارة مع تشفير على مستوى التخزين أثناء السكون
- **عزل مساحات الأسماء**: تُحصَر بيانات المستودع حسب مساحة العمل ومساحة الاسم عبر مسارات خط المعالجة واستعلامات قاعدة البيانات
- **ضوابط الوصول**: يُقيَّد الوصول إلى المستودع بحدود المؤسسة ومساحة الاسم

### ما الذي يمكن توقعه

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

### التحديثات التلقائية

- **مزامنة المستودع**: يُحدَّث من مهام مزامنة GitHub مع تغيّر الشيفرة
- **معالجة تزايدية**: يعالج الملفات المتغيّرة فقط تحقيقًا للكفاءة
- **سياق واعٍ بالفروع**: يحافظ على فهارس منفصلة لكل فرع git بحيث يرى الوكلاء السياق الصحيح لكل فرع

يُقدَّم Maguyva كخادم MCP مستضاف على السحابة. يستدعي وكيلك الأدوات الخاصة بالعدسة التي يحتاجها بدلًا من الاعتماد على النموذج ليتذكّر معماريتك من الصفر. الأسطح الأربعة أعلاه هي عروض مجمّعة للأدوات الملموسة: يشمل البحث الدلالي `semantic_search` و`intelligent_search`؛ ويشمل البحث عن الرموز `find_symbol` و`get_task_context`؛ ويشمل البحث البنيوي `structural_search` و`text_pattern_search`؛ ويشمل مخطط الاعتماديات `dependency_search` و`analyze_dependencies` — إلى جانب `get_file` و`repository_context` و`ask_maguyva` كأدوات مساندة. راجع [مرجع واجهة MCP البرمجية](https://maguyva.ai/docs/mcp-api) الكامل للاطّلاع على جميع الأدوات وعددها 11.

يختلف الأداء حسب حجم قاعدة الشيفرة وتعقيد الاستعلام. يركّز Maguyva على تقديم السياق الأكثر صلة بدلًا من إغراق السياق بملفات كاملة. راجع [التوافق](https://maguyva.ai/docs/compatibility) للاطلاع على اللغات والعملاء المدعومين.

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

اربط مستودعات GitHub الخاصة بك عبر بوابة Maguyva. تُحدَّث الفهارس عبر مهام مزامنة GitHub عند تغيّر الشيفرة. تتيح البوابة أيضًا الاطّلاع على استخدام API.