# يرى Copilot مساحة عملك. وترسم Maguyva خريطة المستودع.

Canonical source: https://maguyva.ai/ar/for-vscode

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

يقرأ الوكيل في VS Code الملفات التي ترفقها والملفات التي يجدها ببحثه. تفهرس Maguyva المستودع كله وتقدّمه عبر MCP، فيسأل الوكيل أين يقع الرمز ومن يستدعيه قبل أن يعدّل.

> إدخال servers واحد في ‎.vscode/mcp.json: رابط URL وترويسة Authorization.

## ما يجب معرفته عن VS Code

أربع حقائق خاصة بـVS Code.

### .vscode/mcp.json

توضع الخوادم تحت `servers` وليس تحت `mcpServers`. لاستخدامها في كل مساحات العمل، شغّل `MCP: Open User Configuration` وأضف الإدخال نفسه إلى `mcp.json` في ملف تعريفك.

### type: http

يتصل VS Code بنقطة نهاية Maguyva عبر Streamable HTTP، ولا يعود إلى SSE إلا عندما لا يدعمه الخادم. لا شيء يعمل محليًا.

### مرجع إلى متغير بيئة

تكون الترويسة `Bearer ${env:MAGUYVA_API_KEY}`، ويحلّها VS Code من البيئة التي بدأ منها، فيبقى المفتاح خارج الملف الذي تودعه في Git. تفضّل أن يُطلب منك؟ متغير إدخال يسأل مرة واحدة ويحفظ المفتاح.

### ثقة مساحة العمل

تبدأ الخوادم في `.vscode/mcp.json` من دون طلب منفصل بمجرد أن تثق بمساحة العمل، ولا تبدأ أبدًا في الوضع المقيّد. ويشغّل Configure Tools في حقل الدردشة الأدوات أو يوقفها كلًّا على حدة.

## التعليمات المخصصة هي اتفاقية عمل. استخدمها.

```text
# .github/copilot-instructions.md
- شغّل npm test قبل أن تعدّ التغيير مكتملًا.
- لا تعدّل أبدًا الملفات المولَّدة في src/gen/.
```

يقرأ VS Code تعليمات المشروع كله من `.github/copilot-instructions.md` أو `AGENTS.md`، والتعليمات الموجّهة من ملفات `.github/instructions/*.instructions.md` ذات نمط `applyTo`. استخدمها من أجل:

- أوامر البناء والاختبار والفحص (lint).
- الأعراف التي يخطئ فيها الوكيل باستمرار.
- المجلدات التي يجب ألا يقترب منها الوكيل.

تخبر التعليمات الوكيل كيف يعمل. لكنها لا تستطيع أن تخبره أيّ ملفات من بين أربعة آلاف تستورد النوع الذي يوشك على إعادة تسميته.

## حين لا يكفي ما تعرضه مساحة العمل

ثلاثة أشياء لا يستطيع الوكيل تعلّمها من الملفات المفتوحة.

### ‏// المرفق ليس كل شيء

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

### ‏// تطابق النص ليس مرجعًا

يجد البحث في مساحة العمل السلسلة النصية. لكنه لا يميّز الاستدعاء الحقيقي من تعليق أو mock أو تابع بالاسم نفسه في صنف آخر.

### ‏// كل قراءة تكلّف سياقًا

كل ملف يفتحه الوكيل ليتوجّه يستهلك سياقًا يحتاجه للتغيير. إجابة واحدة مرتّبة مع file:line أرخص من عشر قراءات استكشافية.

## Maguyva كخادم MCP في VS Code

إدخال servers واحد يمنح الوكيل:

- **11 أداة على مستودعك المفهرس**: بحث دلالي وهيكلي (AST) وبالرسم البياني ونصي، إضافة إلى البحث عن الرموز والعناصر المعتمدة واسترجاع الملفات.
- **إجابات مع مسارات الملفات وأرقام الأسطر**: عبر أكثر من 285 لغة، فيفتح الوكيل الملف الصحيح من المرة الأولى.
- **أدوات للقراءة فقط**: أدوات Maguyva تستعلم الفهرس فقط. لا تعدّل أيّ منها ملفاتك، فكل موافقة تتعلق بالقراءة لا بالكتابة.

> يمنح VS Code الوكيل *مساحة عملك*.
> تمنح Maguyva الوكيل *خريطة للمستودع*.

## سيرا عمل

اسأل الخريطة أولًا، ثم عدّل.

### 01. اعثر على الاختبارات قبل تغيير المحلّل

```text
vscode agent> أيّ الاختبارات تمرّ عبر parseConfig؟

dependency_search("parseConfig", dependents)
  tests/config/parse.test.ts:12
  tests/cli/flags.test.ts:88

→ يشغّل الوكيل هذين الملفين بعد التعديل، لا المجموعة كلها.
[exit 0]
```

تسمّي الإجابة ملفَّي الاختبار اللذين يصلان إلى المحلّل، فيتحقق الوكيل من التغيير حيث يمكن أن ينكسر.

### 02. قدّر حجم إعادة التسمية قبل أول تعديل

```text
vscode agent> أعد تسمية OrderStatus.PENDING إلى OrderStatus.QUEUED

find_symbol("OrderStatus", references)
  23 مرجعًا في 9 ملفات

→ يخطط الوكيل لمرور واحد على الملفات التسعة.
[exit 0]
```

يصل عدد المراجع قبل التعديل، لا بعد أن يفشل مدقق الأنواع.

## الإعداد في VS Code

ثلاث خطوات. خطة Free: 3 مستودعات, حتى 50 ألف سطر مُفهرَس من المستودع، بلا بطاقة.

### 01. افهرس مستودعًا على maguyva.ai

اختر واحدًا تعرفه جيدًا، لتتمكَّن من التحقق من الإجابات.

### 02. أضف Maguyva إلى ‎.vscode/mcp.json

`.vscode/mcp.json`

```json
{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. اضبط مفتاحك وشغّل الخادم

اضبط `MAGUYVA_API_KEY` في البيئة التي تشغّل منها VS Code، ثم شغّل الخادم من عدسة الكود فوق إدخاله. اطرح على الوكيل سؤالًا واحدًا تعرف إجابته مسبقًا.

تشرح [وثائق MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers) الخاصة بـVS Code متغيرات الإدخال وصيغة ‎.mcp.json المحمولة والثقة بالخوادم.

## افهرس مستودعًا واحدًا تعرفه جيدًا.

اتصل بـVS Code عبر MCP، ثم اطرح سؤالًا واحدًا يمكنك التحقق منه.