GitHub Copilot

المورّد: GitHub / Microsoft اسم التثبيت: github-copilot الحالة: إتاحة عامة الإعداد الأصلي: <project>/.github/copilot-instructions.md

التثبيتCopy Anchor Link

apothem install --harness github-copilot --project /path/to/project

يشتقّ المحوّل ملف تعليمات المشروع من ملفك التعريفي المشترك ومن سطح القواعد والحوكمة المشترك في Apothem، ويكتب مساعِدات Apothem بوصفها ملفات تعريف مساعِدات لـ Copilot في المشروع (راجع ملفات تعريف المساعِدات)، ويسجّل خطّافين (راجع الخطّافات).

ويكتب أيضًا مهارات Apothem، والقواعد والقوالب التي تستشهد بها، في دليلك المنزلي، قبل أن يمسّ المشروع (راجع الملفات خارج المشروع).

الملفات المكتوبة:

• <project>/.github/copilot-instructions.md، ملف التعليمات.
• <project>/.github/agents/<name>.agent.md لكل مساعِد من Apothem، في المشروع.
• <project>/.github/hooks/apothem.json، ملف الخطّافات، في المشروع. ولا تُمَسّ ملفات الخطّافات الخاصة بك في ذلك المجلّد.
• <project>/.apothem/support/github-copilot/hooks/، سكربتات الخطّافات، في المشروع.
• ~/.agents/skills/<name>/SKILL.md لكل مهارة وأمر من Apothem، في دليلك المنزلي.
• ~/.config/apothem/rules/ و~/.config/apothem/templates/، في دليلك المنزلي.

الملفات خارج المشروعCopy Anchor Link

يكتب التثبيت أيضًا مهارات Apothem في دليلك المنزلي، قبل أن يغيّر أي شيء في المشروع:

هذه المجلّدات مشتركة، وليست خاصة بالمشروع:

• كل مشروع تثبّت فيه github-copilot، وكل تثبيت آخر لـ Apothem يسمّي المجلّد، يستخدم النسخة نفسها ويكتب الملفات نفسها، لذا لا يهمّ الترتيب الذي تثبّت به. وتقرأ أدوات أخرى عديدة ~/.agents/skills/ أيضًا؛ ويسردها سجلّ أُطُر العمل.
• يختار --project ملف التعليمات الذي يُكتَب والمشروعَ الذي ينتمي إليه التثبيت. ولا يغيّر المكان الذي تذهب إليه المهارات.
• لا يضيف التثبيت أي ملف مهارة أو قاعدة إلى مستودعك. ويحصل المشروع على ملف التعليمات، وملفات تعريف المساعِدات في .github/agents/، وملف الخطّافات .github/hooks/apothem.json، إضافةً إلى المجلّد .apothem/ الذي يُنشئه كل تثبيت على مستوى المشروع، والذي يحوي أيضًا سكربتات الخطّافات.
• تُكتَب المجلّدات المنزلية أولًا. فإن فشل ذلك، مثلًا لأن مجلّدًا في المسار رابطٌ يخرج من دليلك المنزلي (أما الرابط الذي يبقى داخله فيُتَّبَع) أو لا يمكن الكتابة فيه، يتوقّف التثبيت مع الخطأ قبل أن يتغيّر أي شيء في المشروع.
• مجلّد المهارة الذي يحمل اسم مهارة من Apothem ولم يكتبه Apothem يُترَك كما هو، ويطبع التثبيت تحذيرًا يسمّيه. أعد تسميته أو انقله، ثم شغّل apothem update. ويفشل apothem verify ما دام ذلك الاسم محجوزًا.
• يبلغ مجموع الملفات بضعة ميغابايتات.

يطبع التثبيت ملاحظة تسمّي المجلّدات التي يكتبها خارج --project، ويسردها --dry-run.

ملفات تعريف المساعِداتCopy Anchor Link

يقرأ Copilot ملف تعريف المساعِد من <project>/.github/agents/<name>.agent.md، وفق مرجع GitHub لهذه الملفات. ويكتب التثبيت ملفًا واحدًا لكل مساعِد من Apothem في ذلك المجلّد. وهو يثبّت للمشروع فقط، ولا يكتب أي مجلّد ~/.copilot/agents/.

يُبقي كل ملف تعليمات المساعِد دون تغيير ويحمل مفاتيح البيانات الأمامية التالية:

المفتاح tools في Copilot قائمة سماح بالأسماء المستعارة، ولا مفتاح فيه يحظر أداة. لذا تُدمَج الأدوات المسموح بها للمساعِد والأدوات المحظورة عليه في تلك القائمة الواحدة:

لدى Copilot اسم مستعار آخر، هو الذي يتيح للمساعِد بدء مساعِدات أخرى؛ ولا يُسمَح لأي مساعِد من Apothem بذلك، لذا لا يُكتَب أبدًا. ويُستبعَد الاسم المستعار حين يحظر المساعِد أي أداة يغطّيها، لأن الاسم المستعار سيتيح للمساعِد استخدام تلك الأداة. والأداة التي لا اسم مستعار لها (مثلًا Monitor) تُستبعَد. والأداة ذات النمط، مثل Bash(git status)، ليس لها صيغة اسم مستعار: فبوصفها أداة مسموحًا بها تُستبعَد، وبوصفها أداة محظورة تحظر الأداة كلها. والمساعِد الذي لا يستطيع تعديل الملفات يحتفظ بذلك القيد: فلا يحصل أبدًا على edit. وإن استُبعِدت كل أداة في قائمة المساعِد، يقول الملف tools: []، الذي لا يمنح المساعِد أي أدوات، بدلًا من حذف المفتاح، الذي سيمنحه كل الأدوات.

لا يكتب التثبيت أي مفتاح model، لذا يستخدم المساعِد النموذج الافتراضي، ولا أيًّا من المفاتيح الأخرى التي يوثّقها Copilot (target، وdisable-model-invocation، وuser-invocable، وmcp-servers، وmetadata)، ولا حدًّا لعدد الأدوار، ولا مفاتيح Apothem version وupdated وportability.

أمور ينبغي معرفتها:

• المجلّد .github/agents/ جزء من مستودعك. إذ يقرأ زملاؤك وخدمة البرمجة السحابية في Copilot الملفات نفسها، لذا أودِعها مع المشروع أو أدرِج .github/agents/ في .gitignore؛ ولا يختار Apothem نيابةً عنك.
• لا تحترم خدمة البرمجة السحابية الاسمين المستعارين web وtodo. ويغطّي الاسم المستعار web كلًّا من البحث على الويب وجلب الصفحات، لذا يستطيع citation-auditor وfact-checker وresearch-scout قراءة الملفات والبحث فيها هناك، لكنها لا تستطيع البحث على الويب ولا جلب الصفحات.
• تقرأ واجهة سطر أوامر Copilot أيضًا المجلّد .claude/agents/ في المستودع، لكن لا تقرأ ~/.claude/agents/، لذا لا يصل تثبيت Claude Code إلى Copilot.
• الملف الخاص بك الذي يحمل اسم مساعِد من Apothem (<name>.agent.md) يُحفَظ تحت ~/.apothem/backups/ ثم يُستبدَل. ولا يُعيده إلغاء التثبيت. ولا تُمَسّ الملفات ذات الأسماء الأخرى أبدًا. ولا تقول وثائق Copilot ما يحدث حين يحوي المجلّد كلًّا من <name>.md و<name>.agent.md.
• لم يتحقّق Apothem مما إذا كان Copilot يفضّل .github/agents/ أو .claude/agents/ للاسم الواحد، ولا من كيفية تعامل خدمة البرمجة السحابية وVS Code مع مفتاح بيانات أمامية لا تسردانه.

الخطّافاتCopy Anchor Link

يُشغِّل Copilot الخطّافات من ملفات JSON في <project>/.github/hooks/، وفق مرجع الخطّافات في Copilot. ويكتب التثبيت ملفًا واحدًا هناك، apothem.json (الإصدار 1)، فيه خطّافان:

يضيف كلاهما سياقًا للنموذج. ولا يحجب أيٌّ منهما استدعاء أداة أو جلسة.

لا يسجّل Apothem أي حارس preToolUse على Copilot. فللحدث preToolUse يقرأ Copilot حقول الأذونات ومُدخَل أداة مُعاد كتابته فقط، ولا يقرأ أبدًا additionalContext (الحقل الذي تتحدّث عبره حُرّاس Apothem). والحارس المسجَّل هناك سيكلّف بدء عملية في كل استدعاء أداة ولا يوصل شيئًا، لذا تبقى حُرّاس الكتابة والتعديل والصدفة، وفحص AskUserQuestion، وبروتوكول نهاية الجلسة، على الأدوات التي توصلها. وتستخدم الخطّافات أسماء أحداث Copilot بصيغة camelCase، لأن المرجع يسرد حقول المُخرَج لتلك الأسماء؛ أما ما إذا كان Copilot يقرأ additionalContext من حدث بصيغة PascalCase فغير موثَّق.

أين تذهب الملفات

لكل خطّاف أمر bash وأمر powershell. ويُشغِّلان المُوزِّع نفسه؛ وأمام أمر powershell مُعامِل استدعاء (&)، يحتاجه PowerShell قبل مسار برنامج مقتبس. ويبدو أمر bash هكذا، مع المُفسِّر ومسار المشروع لديك في موضع المسارين:

"/path/to/python" "/path/to/project/.apothem/support/github-copilot/hooks/dispatch.py" --contract copilot sessionStart

يجعل --contract copilot المُوزِّعَ يقرأ مُدخَل Copilot بصيغة camelCase ويطبع {"additionalContext": ...}، وهو ما يقرؤه Copilot لهذين الحدثين.

أودِع بحذر، والعامل السحابي. المجلّد .github/hooks/ جزء من مستودعك، وتقرؤه خدمة البرمجة السحابية في Copilot. وتسمّي الأوامر المُفسِّر الذي عثر عليه Apothem حين عمل والمسار المطلق للمشروع، والسكربتات موجودة في .apothem/، الذي يتجاهله مقتطف .gitignore الخاص بالمشروع. فعلى أي جهاز آخر، وفي الخدمة السحابية (التي لا تُشغِّل إلا أمر bash)، لا يجد الأمر شيئًا ليُشغِّله. ويسجّل Copilot الفشل ويستمر التشغيل، لأن فشل خطّاف sessionStart أو postToolUse لا يحجب شيئًا. أضِف .github/hooks/apothem.json إلى .gitignore، أو أودِعه فقط لفريق يتشارك التخطيط نفسه. ولا يعدّل التثبيت .gitignore، ويطبع هذا بوصفه ملاحظة.

خطّافاتك الخاصة. لا تُقرأ ملفات الخطّافات الخاصة بك في .github/hooks/ ولا تُغيَّر أبدًا. والخطّاف الذي تضيفه إلى apothem.json نفسه يبقى: إذ لا يستبدل التحديث وإلغاء التثبيت، أو يُزيلان، إلا المُدخَلات التي يُشغِّل أمرها مُوزِّع Apothem (.apothem/support/github-copilot/hooks/dispatch.py مع --contract copilot، أيًّا كان مسار المشروع الذي كُتِب تحته). والخطّاف الخاص بك الذي يشاركه الاسم فقط، أو الذي يُشغِّل python -m apothem.conformity.gate، لا يُعَدّ أبدًا خطّافًا لـ Apothem. والملف الذي ليس JSON صالحًا يُحفَظ تحت ~/.apothem/backups/ ثم يُستبدَل.

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

إيقاف الخطّافات. اضبط APOTHEM_HOOKS_DISABLE=1 في البيئة التي يعمل فيها Copilot لإسكات خطّافات Apothem، أو اضبط "disableAllHooks": true في apothem.json، الذي يتخطّى ذلك الملف الواحد.

عقد الخطّافات المحلّي الأقدم في VS Code (أحداث بالحقول command وwindows وlinux وosx) صيغة مختلفة لا يستهدفها ملف من الإصدار 1.

تعيين الملف التعريفي إلى الإعداد الأصليCopy Anchor Link

يقرأ المحوّل الملف التعريفي المشترك لـ Apothem ويُجسِّد ملف تعليمات Copilot على مستوى المستودع في كل تشغيل لـ apothem install أو apothem update. الملف التعريفي المشترك هو مصدر الحقيقة؛ وتُنسَخ التعديلات المحلية للمشروع على الملف المُولَّد احتياطيًا قبل أن تستبدل المزامنة التالية المحتوى الذي يديره Apothem.

داخل كتلة Apothem، يأتي أولًا القسم المُجسَّد من ملفك التعريفي (المُشغِّل، والتفضيلات، والقواعد المخصّصة، والسلوكيات المُختارة بالاشتراك، وأسماء خوادم MCP)، قبل نص الحوكمة المشترك. يُشير GitHub إلى أن ملفات التعليمات الأقصر أرجح أن تُعالَج بالكامل في مراجعة الشيفرة (تخصيص مراجعة الشيفرة)، لذا يتصدّر الملفَّ الجزءُ الخاص بك.

ملاحظات التوافقCopy Anchor Link

لا يكشف GitHub Copilot عن مسار تعليمات عامّ على مستوى المستخدم قائم على الملفات كي يديره هذا المحوّل. يستهدف Apothem ملف التعليمات الموثَّق بنطاق المشروع، ويترك إعدادات المستخدم على مستوى بيئة التطوير المتكاملة ملكًا للمُشغِّل. ويكتب ملف خطّافات واحدًا، .github/hooks/apothem.json، ولا يكتب أي ملف آخر في .github/hooks/.

داخل مستودع Apothem، يُعَدّ .github/copilot-instructions.md صوتًا واحدًا بين أسطح تعليمات المساعد في ذلك المستودع. وفي نسخة مسحوبة من ذلك المستودع، يقارن فحص التماسك متعدّد الأسطح في بوابة المطابقة الادّعاءات المشتركة في AGENTS.md وCLAUDE.md و.github/copilot-instructions.md. ويُبلِغ عن ادّعاء مشترك يُغفله أحد الملفات الثلاثة، وعن ملف يناقض ادّعاءً يقوم به AGENTS.md. لا يقرأ الفحص ملف التعليمات الذي يكتبه Apothem في مشروعك. البوابة استشارية افتراضيًا: تُبلِغ عن النتائج وتخرج بالرمز 0.

يسرد GitHub Copilot المجلّد ~/.agents/skills/ ضمن مواقع المهارات الشخصية لديه، لذا تكون المهارات التي يكتبها التثبيت على جهازك كي يُحمِّلها Copilot. أما الأسطح التي تعمل على GitHub، أي خدمة البرمجة السحابية ومراجعة الشيفرة، فتعمل في مكان آخر ولا ترى دليلك المنزلي، ولهذا يحمل ملف التعليمات الانضباطات بنفسه. ولم يتحقّق Apothem من كيفية تعامل Copilot مع مفتاح ترويسة في SKILL.md لا يسرده؛ وتحمل المهارات user-invocable، وdisable-model-invocation، وallowed-tools، وargument-hint، وخريطة metadata.

التحقّقCopy Anchor Link

apothem verify --harness github-copilot --project /path/to/project

يؤكّد أمر التحقّق ما يلي:

1. الإعداد الأصلي موجود في المسار المتوقَّع.
2. كل هدف مُدار موجود، بما في ذلك المجلّد .github/agents/؛ والملفات المُدارة غير فارغة، وتُحلَّل إعدادات JSON أو YAML. أضِف --profile PATH لتتحقّق كذلك من أن الملفات المثبّتة تطابق ذلك الملف التعريفي. وبالنسبة إلى .github/agents/ يتحقّق الفحص من وجود المجلّد، لا من وجود كل ملف مساعِد فيه؛ ويسرد apothem diff --harness github-copilot --project /path/to/project ملفات المساعِدات المفقودة أو القديمة. ويجب أن يكون ملف الخطّافات .github/hooks/apothem.json موجودًا، وغير فارغ، وقابلًا للتحليل بوصفه JSON، وأن يحوي مُدخَلًا يُشغِّل مُوزِّع Apothem، ويجب أن تكون سكربتات الخطّافات في .apothem/support/github-copilot/hooks/. ولا يُشغِّل الفحص الخطّافات.
3. كل مجلّد مهارة من Apothem في مكانه ومعه SKILL.md، أيًّا كان التثبيت الذي كتبه، ولا يوجد مجلّد مهارة يحمل اسمًا من Apothem ويعود إلى شيء لم يكتبه Apothem. ويسمّي الفحص الفاشل المجلّدات المفقودة أو الدخيلة.
4. روتين التحقّق الخاص بالمحوّل يُبلِغ عن النجاح.

التحديثCopy Anchor Link

apothem update --harness github-copilot --project /path/to/project

يُعيد اشتقاق ملف تعليمات المشروع من الحالة الراهنة للملف التعريفي المشترك.

ويُعيد التحديث أيضًا كتابة أي مجلّد مهارة تختلف ملفاته عن الملفات الحالية. وإن كنت قد ثبّتّ بإصدار سابق لم يكتب أي مهارات، فإن التحديث يضيفها. ويُعيد كتابة ملفات تعريف المساعِدات التي تختلف عن الحالية، ويضيف أي ملفات مفقودة منها. ويُحدِّث كذلك سكربتات الخطّافات وخطّافات Apothem في .github/hooks/apothem.json، مُبقيًا أي خطّاف خاص بك في ذلك الملف.

إلغاء التثبيتCopy Anchor Link

apothem uninstall --harness github-copilot --project /path/to/project

يُزيل كتلة Apothem من <project>/.github/copilot-instructions.md ويُبقي أي نص خارجها. لا يُحذَف الملف إلا حين لا يتبقّى فيه شيء آخر. قبل التغيير، تُحفَظ نسخة بطابع زمني من الملف تحت ~/.apothem/backups/. لا يتأثّر ملف YAML الخاص بالملف التعريفي المشترك ولا محرّك Apothem.

ويُزيل إلغاء التثبيت أيضًا ملفات تعريف المساعِدات التي كتبها في <project>/.github/agents/ ويُبقي أي ملف آخر هناك؛ ويُزال المجلّد حين يبقى فارغًا. ويُزيل خطّافات Apothem من <project>/.github/hooks/apothem.json، متعرّفًا عليها من مسار المُوزِّع في أمرها، لذا يعمل دون سجلّ تثبيت، ويُبقي أي خطّاف خاص بك في ذلك الملف. ويُحذَف الملف حين لا يتبقّى فيه شيء آخر، ولا تُمَسّ ملفات الخطّافات الأخرى الخاصة بك. وإن كان الملف يحوي تعليقات لا يستطيع إلغاء التثبيت قراءتها، فإنه يترك الملف كما هو ويُبلِغ عن الخطّافات بوصفها متخطّاة، مع ذكر السبب؛ أزِل مُدخَلات Apothem يدويًا. وتُزال كذلك سكربتات الخطّافات في <project>/.apothem/support/github-copilot/hooks/. ويُزيل مجلّدات المهارات التي كتبها في ~/.agents/skills/ والقواعد والقوالب في ~/.config/apothem/، ولكن فقط حين لا يعود أي تثبيت آخر لـ Apothem يستخدمها. فقد يستخدمها مشروع آخر، أو أداة أخرى تشارك المجلّد. وفي تلك الحالة يُبقي إلغاء التثبيت المجلّدات، ويطبع التثبيت الذي يستخدمها، ويُزيلها آخر إلغاء تثبيت. وتبقى الملفات التي أضفتها إلى تلك المجلّدات، ويُزال المجلّد الذي يبقى فارغًا. ويُنسَخ كل مجلّد احتياطيًا تحت ~/.apothem/backups/ قبل إزالته.

بوابة المطابقةCopy Anchor Link

python -m apothem.conformity.gate --all .

يغطّي التشغيل --all المدقّقات المستقلّة، ولا يُشغّل فحص الاتساق متعدّد الأسطح المذكور ضمن ملاحظات التوافق. ولتشغيل ذلك الفحص باسمه من نسخة مسحوبة:

python -m apothem.conformity.gate --check multi-surface-coherence-grep AGENTS.md

استكشاف الأخطاء وإصلاحهاCopy Anchor Link

مفاتيح الضبطCopy Anchor Link

انظر أيضًاCopy Anchor Link

• كل أُطُر العمل — الفهرس الكامل للأدوات المدعومة
• دليل التثبيت — ثبّت Apothem في إطار العمل هذا
• مرجع apothem harnesses — اسرد المحوّلات وافحصها من واجهة سطر الأوامر