# لغة PowerShell في Maguyva: رسوم بيانية للشيفرة في النصوص والوحدات

Canonical source: https://maguyva.ai/ar/languages/powershell

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).

يدعم Maguyva لغة PowerShell بشجرة AST والرموز والرسم البياني، ليتمكن وكلاء الذكاء الاصطناعي من تتبّع الدوال والفئات واستدعاءات cmdlet عبر النصوص والوحدات.

## لمحة عن الدعم

- المستوى: دعم AST والرموز
- واجهات الأوامر
- الامتدادات: .ps1, .psd1, .psm1
- تحليل AST حقيقي لبحث واعٍ بالصياغة النحوية وسياق بنيوي.
- تُغذّي الرموز المسمّاة البحث الدلالي والمراجع المتقاطعة. ويتوفر التنقل عبر الرسم البياني عند تمكين استخراج العلاقات.
- تُسهم هذه اللغة بالرموز والعلاقات في البحث المراعي لبنية الرسم البياني؛ وتختلف أنواع الحواف المدعومة بحسب التراكيب الأصلية في اللغة.
- يتوفر كل من تحليل AST واستخلاص الرموز.

## الأنسب لـ

- فرق البنية التحتية والتشغيل التي تملك أصولًا كبيرة من ملفات `.ps1` و`.psm1` تستدعي نصوصها دوال بعضها بعضًا.
- وحدات PowerShell المبنية من دوال متقدمة وفئات وتعدادات.
- أدلة تشغيل الأتمتة التي يحتاج فيها الوكلاء إلى معرفة النصوص التي تمسّ خدمة أو مشاركة ملفات أو مفتاح سجل قبل أي تغيير.

## سير عمل الوكلاء

- العثور على كل مستدعٍ لدالة متقدمة قبل تغيير معاملاتها.
- سرد النصوص التي تستدعي cmdlet مثل `Restart-Service` قبل تغيير دليل تشغيل.
- رسم خريطة للدوال التي تكتب في متغير مشترك قبل إعادة هيكلة وحدة.

## أين تُربك PowerShell أدوات الذكاء الاصطناعي السطحية

تتبع دوالّك وأوامر cmdlet المدمجة أسلوب التسمية نفسه. يبدو `Get-Invoice` و`Get-ChildItem` متشابهين، لذا فإن الأداة التي تستبعد "المدمج" بحسب الفعل ترمي دوالّك أنت أيضًا. كما تمزج النصوص شيفرة مستوى الوحدة والدوال والفئات وكتل النصوص في ملف واحد، فيصعب معرفة الدالة التي ينتمي إليها سطر ما.

يحتفظ Maguyva بنوعي الاستدعاء معًا، وينسب كل استدعاء إلى الدالة التي يقع فيها.

## ما الذي يستخرجه Maguyva من PowerShell

يغطي Maguyva ملفات `.ps1` و`.psm1` و`.psd1`. تُستخرج الدوال وتوابع الفئات بوصفها كيانات قابلة للاستدعاء، والفئات والتعدادات بوصفها أنواعًا. وتُتتبّع معاملات النصوص والتوابع، وتُنسب القراءة والكتابة داخل الدالة إلى تلك الدالة لا إلى الوحدة.

تبقى استدعاءات cmdlet في الرسم البياني. لا تطبّق PowerShell مرشّح المكتبة القياسية الذي تستخدمه معظم اللغات، لذا تظهر `Write-Host` و`Get-ChildItem` و`Restart-Service` بوصفها حواف استدعاء بجانب دوال `Get-*` و`Set-*` الخاصة بك. ويستطيع الوكيل أن يسأل أي النصوص تعيد تشغيل خدمة، أو أي الدوال تكتب إلى وحدة التحكم، فيحصل على إجابة قائمة على البنية.

لا يوجد في PowerShell نوع علاقة معلَّم بأنه غير قابل للتطبيق، لذا يسجّل الرسم البياني أيضًا وراثة الفئات وتنفيذ الواجهات وإنشاء النُسخ وتدفق التحكم والقراءة والكتابة.

## أمثلة على مطالبات الوكلاء

- "من يستدعي `Invoke-Backup`، ومن أي نصوص مجدولة؟" (`find_symbol` ثم `dependency_search` في الاتجاه الوارد)
- "ما الدوال التي تستدعي `Restart-Service`؟" (`dependency_search`)
- "تتبّع ما يفعله `Deploy-Site` من البداية إلى النهاية." (`get_task_context`)

## القيود المعروفة

- لأن استدعاءات cmdlet تبقى، فإن الشائعة جدًا منها مثل `Write-Host` و`Select-Object` لها عدد كبير من الحواف الواردة. ابدأ من دالتك أنت عندما تريد رسم استدعاءات مركّزًا.
- `Import-Module` والتحميل بالنقطة أوامر عادية، لذا لا يختار الإعداد المسبق `imports` في `structural_search` شيئًا. استخدم `text_pattern_search` لسردها.

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

اربط مستودعًا عبر [دليل البدء السريع](/ar/docs/quickstart)، ثم راجع مصفوفة الدعم في [صفحة التوافق](/ar/docs/compatibility). ولشيفرة .NET التي تستدعيها نصوصك، اقرأ [دليل لغة C#](/ar/languages/csharp).

## تفاصيل المحرك

- يغطي دعم PowerShell الملفات `.ps1` و`.psm1` و`.psd1`. الدوال وتوابع الفئات كيانات قابلة للاستدعاء، والفئات والتعدادات أنواع.
- مرشّح المكتبة القياسية معطّل في PowerShell، لذا تبقى استدعاءات cmdlet مثل `Get-ChildItem` في الرسم البياني بجانب دوالّك.
- تُنسب القراءة والكتابة داخل الدالة إلى تلك الدالة لا إلى الوحدة.

## نقاط دخول مفيدة عبر MCP

- `find_symbol`: استخدمه لدالة متقدمة أو فئة عندما تحتاج إلى التعريف والمستدعين.
- `dependency_search`: استخدم الاجتياز الوارد على cmdlet مثل `Restart-Service` لرؤية النصوص البرمجية التي تستدعيه.
- `get_task_context`: استخدمه لمطالبات مثل "تتبّع ما يفعله `Deploy-Site` من البداية إلى النهاية".