وضع وكيل GitHub Copilot: مختبر خطوة بخطوة في VS Code

وضع Agent لـ GitHub Copilot في VS Code يخطط مهمة، يحرّر الملفات عبر ريبو، يشغّل أوامر الطرفية بموافقتك، ويبقى يسير حتى تنتهي المهمة أو يحتاج إليك. يعيّن هذا المختبر ذلك على ريبو صغير Python: ملف تعليمات واحد، مهمة وكيل واحدة، مراجعة فرق واحدة، تشغيل اختبار واحد. كل شيء أدناه متطابق ضد VS Code الحالي وتوثيق GitHub Copilot، مع مصادر مدرجة في الجزء الأمامي.

ما يفعله وضع Agent فعلاً

Chat الـ Copilot في VS Code له ثلاثة أوضاع مدمجة، محددة من dropdown أعلى مدخل المحادثة: Ask يجيب الأسئلة ولا يحرّر، Plan يكتب خطة خطوة بخطوة وينتظر موافقتك قبل أي تغيير، و Agent خطط بشكل مستقل، يحرّر الملفات، يشغّل أوامس الطرفية، ويستدعي الأدوات حتى تبدو المهمة منتهية. يمكنك بدّل الأوضاع وسط محادثة.

هذا انقسام مختلف من كتابات أقدم تصف “Ask / Edit / Agent.” اعتبارًا من أكتوبر 2026 وثائق VS Code تسرد Ask، Plan، و Agent كأوضاع المدمجة الثلاثة، بدون وضع “Edit” منفصل في محادثة UI. إذا تذكرت شيئًا واحدًا: Agent هو الوضع الذي يمس ملفاتك وطرفيتك بدون نقرة “apply” لكل قطعة.

وضع Agent يحتاج إلى موديل مع دعم tool-calling، مجلد مساحة عمل مفتوح، و chat.agent.enabled مفعّل (افتراضي true منذ VS Code 1.99). الجلسات يمكن أيضًا تشغيل Background (عبر CLI، دون إشراف) أو Cloud (على بنية GitHub، فتح pull request) بدلاً من Local؛ اختر نوع الجلسة بجانب picker الوضع. هذا المختبر يستخدم Local.

الخطوة 1 — افتح ريبو صغير وتحقق من الأساسيات

أنشئ مجلد قابل للرمي ومشروع Python ملف واحد:

# calculator.py
def total_with_discount(prices: list[float], discount_pct: float) -> float:
    """Return the total price after applying a percentage discount."""
    subtotal = sum(prices)
    return subtotal - discount_pct

# test_calculator.py
from calculator import total_with_discount

def test_discount_is_applied_as_percentage():
    assert total_with_discount([100.0, 50.0], 10) == 135.0

total_with_discount لديها خطأ حقيقي: تطرح discount_pct كمبلغ شامل بدلاً من نسبة مئوية، لذلك الاختبار أعلاه فاشل. افتح المجلد في VS Code، افتح Preferences: Open Settings (UI)، وتأكد chat.agent.enabled هو true. افتح عرض Chat مع Ctrl+Alt+I وتأكد Ask، Plan، و Agent تظهر في dropdown الوضع.

الخطوة 2 — اكتب ملف تعليمات مخصص للريبو

تعليمات مخصصة على مستوى الريبو تعيش في .github/copilot-instructions.md، في جذر الريبو، كـ Markdown عادي:

<!-- .github/copilot-instructions.md -->
This is a small Python project that uses pytest.

- Use type hints on every function signature.
- Keep business logic in calculator.py; keep tests in test_*.py files next to it.
- When you fix a bug, add or update a test that would have caught it.
- Run `pytest -q` after making a change and report the result.

بمجرد حفظ، VS Code و Copilot على GitHub.com كليهما يلتقطان هذا تلقائيًا لكل طلب محادثة في الريبو — لا toggle لتفليب. للقواعس التي تطبّق فقط على ملفات معينة، أضف ملف تعليمات خاص بـ path بدلاً من ذلك: أنشئ .github/instructions/python.instructions.md مع كتلة جزء أمامي applyTo:

---
applyTo: "**/*.py"
---
Prefer explicit return types. Avoid bare `except:` clauses.

تعليمات على مستوى الريبو وتعليمات خاصة بـ path مطابقة تُجمّع، وليس واحد-أو-الآخر — احتفظ بها غير متناقضة. على GitHub.com نفسه، ملفات تعليمات خاصة بـ path حاليًا تطبّق فقط على وكيل السحابة و على مراجعة الكود Copilot؛ في VS Code، كلا الملفين يطبّقان على محادثة وجلسات agent.

الخطوة 3 — اختياري: أضف ملف prompt قابل لإعادة الاستخدام

ملف prompt هو slash command مُحفوظ. أنشئ .github/prompts/fix-and-test.prompt.md:

---
description: Fix a failing test and verify with pytest
agent: agent
---
Run `pytest -q`. Read the first failing test and the function it tests.
Fix the implementation, not the test, unless the test itself is wrong.
Re-run `pytest -q` and report the result.

حقل agent يثبّت هذا prompt على وضع Agent بغض النظر عن التحديد الحالي؛ حقل tools يمكن أن يحدّد أي أدوات أو أدوات MCP قد يستدعيها prompt. اكتب /fix-and-test في مدخل المحادثة لتشغيله.

الخطوة 4 — شغّل مهمة وكيل وافقِ على أمر الطرفية

رجوعًا في عرض Chat، مع Agent محدد، أرسل:

pytest is failing in test_calculator.py. Find out why and fix it.

الوكيل يقرأ كلا الملفين، يقترح تحرير total_with_discount، و — لأن pytest -q أمر جديد في هذه الجلسة — يتوقف مع رسالة تأكيد أولاً. راجع الأمر المُظهر، ثم اختر Allow لتشغيله أو Skip لإعادة توجيه الوكيل. لا شيء يعمل بدون تلك الرسالة إلا إذا تم الموافقة على الأمر مسبقًا عبر chat.tools.terminal.autoApprove.

إصلاح معقول للخطأ:

# calculator.py
def total_with_discount(prices: list[float], discount_pct: float) -> float:
    """Return the total price after applying a percentage discount."""
    subtotal = sum(prices)
    return subtotal * (1 - discount_pct / 100)

الخطوة 5 — راجع الفرق، ثم شغّل الاختبارات بنفسك

تحريرات وضع Agent تستقر كتغييرات معلقة في المحرّر، مُظهرة كفرق ضد الملف على القرص. راجعها في المكان واختر keep أو discard لكل واحد — الوثائق صريحة أنت تقرر أي التغييرات تقبل، الوكيل لا يلتزم لك. لا تتخطّ هذه الخطوة فقط لأن الوكيل أبلغ عن النجاح: اقرأ الفرق الفعلي، ليس ملخص المحادثة.

بمجرد أبقيت التحرير، تأكد بنفسك خارج المحادثة، مع الأمر نفسه الذي ستشغّله عادة:

pytest -q

إذا نجح، انتهيت مع الحلقة المحلية. إذا لا يزال فاشل، أرسل الوكيل مخرج الفشل الجديد بدلاً من إعادة وصف الخطأ من الذاكرة — stack trace مُلصق أو رسالة تأكيد أقوى بكثير من “لا يزال مكسور.”

الأدوات وخوادم MCP في VS Code

وضع Agent يستدعي أدوات: مدمجة (ملف قراءة، ملف تحرير، أمر طرفية تشغيل، بحث مساحة عمل) بالإضافة إلى أي شيء مكشوف بواسطة تمديدات أو بواسطة خوادم MCP تُعدّها. MCP هو البروتوكول المفتوح نفسه الذي غطّاه MCP servers guide — VS Code هي عميل آخر له.

شغّل MCP: Add Server من لوحة الأوامس، اختر HTTP لخادم مستند URL أو Command (stdio) لواحد محلي، واختر Workspace (يكتب .vscode/mcp.json، قابل للمشاركة عبر التحكم في المصدر) أو ملف التعريف المستخدم. ملف مساحة عمل صغير:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp"
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

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

الوكيل السحابي على مشاكل GitHub و pull requests

كل شيء أعلاه يعمل داخل VS Code، ضد ملفات على القرص. GitHub أيضًا تشحن وكيل مُستضاف سحابي يعمل مباشرة على GitHub.com. افتح مشكلة، انقر Assignees في اليمين sidebar، وحدّد Copilot. أضف إرشادات اختيارية في حقل prompt واختر الريبو المستهدف، فرع الأساس، والموديل. تعيين المشكلة دائمًا ينتج pull request — Copilot يعمل على فرع في الخلفية ويطلب مراجعتك عند انتهاء. يرى فقط عنوان المشكلة، وصف، وتعليقات كما كانت موجودة عند وقت التعيين، لذلك انشر تحديثات لاحقة كتعليق على pull request الناتجة، ليس المشكلة الأصلية.

مراجعة كود Copilot على pull request

بشكل منفصل عن وكيل السحابة، يمكنك طلب Copilot مراجعة أي فرق pull request. افتح PR، جد Copilot تحت Reviewers، واضغط Request. عادة يستجيب في أقل من 30 ثانية مع تعليقات مُسمّاة High، Medium، أو Low severity، غالبًا مع suggested fixes نقرة واحدة. من GitHub CLI:

gh pr create --reviewer @copilot
# or, on an existing PR:
gh pr edit PR-NUMBER --add-reviewer @copilot

بشكل افتراضي هذا يترك تعليق Comment review، ليس Approve أو Request-changes review، لذلك بنفسه لا يرضي قاعدة required-approvals.

اختيار موديل

picker الموديل يجلس في أسفل مدخل المحادثة، مستقل عن أي وضع أنت فيه. Auto يوجّه كل طلب إلى موديل بناءً على مركبة المهمة والتوفّر الحالي — مرّر الماوس على الرد لترى أي واحد أجاب. افتح Manage Language Models (gear icon في picker، أو أمر Chat: Manage Language Models) لفحص حجم السياق والقدرة لكل موديل، أخفِ غير المستخدمة، أو أضف موديل عبر مفتاح API الخاص بك.

مثالب

وافقتَ على أمر مرة، ليس للأبد. chat.tools.terminal.autoApprove تطابق أوامس محددة أو أنماط regex؛ ليست “توقف السؤال” شامل. إعداد chat.tools.global.autoApprove العام يزيل خطوة الموافقة لكل أداة، ووصف VS Code نفسه يدعوها كتعطيل حماية أمان حرجة — لا تفعّل على آلة لديها أي شيء تهتم به.

ملفات التعليمات لا تصحح تشغيل سيء بأثر رجعي. .github/copilot-instructions.md يشكّل طلبات جديدة؛ لا يعيد كتابة خطة الوكيل الملتزمة بها بالفعل وسط مهمة. إذا جلسة ذهبت بشكل معوج، اصحح التعليمات وابدأ جديدًا بدلاً من دفع السياق نفسه.

تعليمات خاصة بـ path ليست عالمية حتى الآن. على GitHub.com، ملفات .github/instructions/*.instructions.md حاليًا تطبّق على وكيل السحابة و على مراجعة كود Copilot، ليس كل سطح Copilot على الموقع. في VS Code تطبّق بشكل أوسع، على محادثة وجلسات agent. لا تفترض عميل واحد يطابق آخر — تمامًا نوع التفصيل المغطّى في Claude Code vs. Copilot vs. Cursor.

“Reviewed by Copilot” ليس “approved by a human.” مراجعة كود Copilot تترك تعليقات، ليس موافقة ترضي فرع protection. تعاملها كتمريرة أولى سريعة، نفس الطريقة تعاملت AI-assisted TDD workflow: إشارة مفيدة، ليس بوابة merge.

الوكيل السحابي لا يستطيع رؤية تعليقات مشكلة جديدة. يجمّد محتوى المشكلة وقت التعيين. أضف متابعات إلى pull request الناتجة، ليس المشكلة، أو الوكيل لا يقرأها أبدًا.

الأسئلة الشائعة

ما هو وضع وكيل GitHub Copilot في VS Code؟

Agent هو أحد أوضاع المحادثة المدمجة في VS Code، جنبًا إلى جنب مع Ask و Plan. في وضع Agent، Copilot Chat يخطط العمل، يحرّر الملفات عبر مساحة العمل، يشغّل أوامس الطرفية، ويتكرر على النتيجة مع الحكم الكامل، بدلاً من انتظارك لتوافق على كل تحرير على حدة.

كيف أفعّل وضع agent في VS Code؟

افتح عرض Chat واختر Agent من dropdown agent/mode أعلى مدخل المحادثة. الإعداد الأساسي هو chat.agent.enabled، الذي يتجاوز بشكل افتراضي في VS Code 1.99 وأحدث. إذا لم تر Agent في dropdown، افحص ذلك الإعداد وحدّث VS Code.

هل وضع copilot agent يشغّل أوامس الطرفية بدون سؤال؟

لا، ليس بشكل افتراضي. المرة الأولى التي يريد وكيل تشغيل أمر طرفية جديد يتوقف ويطلب منك Allow أو Skip. يمكنك قبول مسبقًا أوامس محددة مع chat.tools.terminal.autoApprove، لكن إعداد auto-approve العام يعطّل حماية أمان حرجة ومعطّل بشكل افتراضي.

ما الفرق بين .github/copilot-instructions.md وملف .instructions.md؟

.github/copilot-instructions.md يحمل تعليمات على مستوى الريبو تطبّق على كل طلب Copilot في ذلك الريبو. ملف NAME.instructions.md تحت .github/instructions/ يحمل glob applyTo في جزئه الأمامي ويطبّق فقط على مسارات ملفات مطابقة، مما يبقي قواعس خاصة بـ framework أو لغة خارج ملف التعليمات الرئيسي.

هل يستطيع Copilot فتح pull request بنفسه؟

نعم. عيّن مشكلة GitHub إلى Copilot من قائمة Assignees، أو ابدأ مهمة وكيل سحابة من لوحة الوكلاء، و Copilot يعمل على فرع ويفتح pull request لك لمراجعتها. يمكنك أيضًا طلب مراجعة Copilot على أي pull request موجود من شريط Reviewers.