هذه الصفحة عبارة عن دليل تشغيل مُعد لمساعد AI: Claude Code أو Codex أو Cursor، أو أي مساعد قادر على قراءة صفحة ويب والعمل بشكل مثالي على نسخة محلية من مستودعك. يقوم هذا الدليل بإرشاد المساعد لإعداد CoRoid لمستودع واحد أو أكثر. يتوقف الدليل عند كل خطوة لا يمكن تنفيذها إلا بواسطة شخص: تسجيل الدخول، منح الصلاحيات، إدخال كلمة مرور، أو الموافقة على تغيير ما.
سلّمه إلى مساعدك
افتح مساعدك في المستودع الذي تريد أن يعمل عليه CoRoid، وأعطه هذا الأمر:
Set up CoRoid for this repository. Follow the runbook at
https://coroid.ai/docs/export/en-US/getting-started/assistant-setup.md
step by step. Ask me before you change anything, and never ask me to paste a
password or token into this chat.لعدة مستودعات، افتح المساعد في مجلد يحتوي عليها جميعًا، واذكر أسماءها في التوجيه. يقوم المساعد بالفحص والتحقق، ويخبرك بالضبط بما يجب فعله في كل خطوة تتطلب تدخلك.
قواعد أساسية للمساعد
أنت تقوم بإعداد CoRoid، وهو مصنع برمجيات مضيف من نوع AI. بمجرد إعداد المشروع، يمكن لأي شخص في شركة المستخدم وصف العمل بلغة بسيطة، وسيقوم CoRoid ببنائه واختباره ومراجعته وفقًا لمعايير المشروع، ثم فتح طلب سحب pull request في مستودع المستخدم. اتبع هذه القواعد في جميع الخطوات:
- المستخدم ينفذ؛ والمساعد يجهز. لا يمكنك الاشتراك أو تسجيل الدخول أو قبول الشروط أو تثبيت التطبيقات أو منح الصلاحيات نيابة عن المستخدم. أخبره بالضبط بما يجب فعله وأين، ثم انتظر حتى يؤكد لك إتمامه.
- ابقِ البيانات السرية بعيدًا عن المحادثة. لا تطلب أبداً كلمة مرور أو رمز وصول شخصي أو مفتاح مزود أو رمز MCP. يقوم المستخدم بإدخال المعلومات السرية في بوابة CoRoid أو في واجهة سطر الأوامر الخاصة به. وإذا تم لصق أحد هذه الرموز في الدردشة على أي حال، أخبر المستخدم بإلغائه وإنشاء رمز جديد.
- اسأل قبل كل تغيير: الالتزامات والفروع وطلبات السحب في مستودع المستخدم، ومشاريع CoRoid، بالإضافة إلى الدعوات.
- تحقق من كل خطوة قبل الانتقال للتي تليها. إذا فشلت عملية التحقق، استخدم الملاحظات الموجودة في تلك الخطوة، واستمر فقط بعد نجاحها أو إذا قرر المستخدم تخطيها.
- اتبع المنتج، لا افتراضاتك. إذا أظهرت البوابة شيئًا لا يصفه هذا الدليل، أخبر المستخدم بما تراه واتبع تعليمات البوابة. لا تختلق إعدادات.
- احتفظ بسجل للإعداد لكل خطوة ونتائجها، لاستخدامه في النهاية.
كل خطوة تربط الصفحات بالتفاصيل ذات الصلة.
https://coroid.ai/llms.txt يُفهرس الوثائق بأكملها.
الخطوة 1: الاتفاق على الخطة
اطرح على المستخدم هذه الأسئلة معًا، وليس واحدًا تلو الآخر:
| سؤال | لماذا هو مهم؟ |
|---|---|
| على أي مستودعات يجب أن يعمل CoRoid؟ | مشروع واحد لكل مستودع. |
| GitHub أم GitLab؟ هل يملكه فرد أم مؤسسة؟ | يحدد كيفية اتصال CoRoid ومن سيوافق على ذلك. |
| هل يجب على CoRoid فتح طلبات سحب (متزامن)، أم الاحتفاظ بالعمل داخل CoRoid في البداية (محلي فقط)؟ | وضع 'محلي فقط' لا يكتب أبداً في المستودع. |
| هل يوجد بالفعل تنظيم تابع لـ CoRoid، وعلى أي خطة؟ | النسخة المجانية تسمح بمشروع واحد ولا تدعم أعضاء آخرين. |
| من سيقوم بمراجعة العمل، وما هو دوره؟ | دعوة الأعضاء تتطلب خطة Professional. |
| هل يجب على CoRoid استخدام مفاتيح مزود النماذج الخاصة بالتنظيم؟ | اختياري. لا تحتاج النماذج الموجهة عبر CoRoid إلى مفاتيح. |
ثم أعد صياغة الخطة: الخطوات التالية التي تتطلب تدخل المستخدم، والمستودعات المشمولة.
اطلع على الخطط والأسعار، الحدود والحصص و متزامن أو محلي فقط.
الخطوة 2: التحقق من قدرة كل مستودع على البناء والاختبار من نسخة نظيفة
هذا هو أهم عمل يمكنك القيام به. يتم تشغيل كل مهمة من مهام CoRoid في بيئة عمل لينكس نظيفة وقابلة للتخلص منها: نسخة مكررة جديدة، بدون أي بيانات مؤقتة أو برامج مثبتة غير أدوات الصورة الأساسية. أي وكيل لا يستطيع بناء المشروع واختباره لا يمكنه التحقق من عمله، وبالتالي تفشل مهامه في عملية التحقق لأسباب لا علاقة لها بالتغيير نفسه.
إذا كنت تستطيع العمل على المستودع محليًا، فافعل ذلك لكل مستودع:
- حدد اللغات ومدير الحزم، وهل هو مستودع متعدد المشاريع (monorepo) أم لا.
- ابحث عن أوامر التثبيت والبناء والاختبار في ملف README وإعدادات التكامل المستمر والملفات الوصفية.
- اسأل قبل تنفيذ أي أمر. ثم انسخ المستودع إلى مجلد مؤقت فارغ ونفذ أوامر التثبيت والبناء والاختبار هناك دون أي إعدادات إضافية. نسخة المستخدم العاملة تحتوي على بيانات مؤقتة و
.envملفات تخفي المشاكل. - سجل كل ما احتاجه التنفيذ ولم تتوفر في النسخة النظيفة:
- خدمات يتوقعها الاختبار، مثل قاعدة بيانات أو ذاكرة تخزين مؤقت أو قائمة انتظار
- خطوات تسبق الاختبار، مثل توليد الكود أو عمليات الترحيل أو البيانات الاختبارية
- متغيرات بيئة أو ملف
.envغير ملتزم بتخزينه في المستودع - سجلات حزم خاصة
- بيئة تشغيل غير موجودة في بيئة المساعد
لا تقم أبداً بتنفيذ أوامر تنشر أو تنشر أو تلمس بيئات مشتركة. إذا كانت مجموعة الاختبارات بطيئة أو تستدعي خدمات مدفوعة، فاطلب من المستخدم الإذن أولاً.
قم بالإبلاغ عن فحص جاهزية مختصر لكل مستودع: الأوامر، المدة التي استغرقتها مجموعة الاختبارات، ما الذي نجح، وكل فجوة مع اقتراح لحلها.
| فجوة | اقتراح حل |
|---|---|
| تحتاج الاختبارات إلى قاعدة بيانات أو خدمة أخرى | ملف Dockerfile أو Compose يُشغّل مجموعة الاختبارات مع خدماتها |
عنصر مطلوب .env ملف غير مُلتزم به في المستودع | إعدادات اختبار افتراضية في الكود، أو ملف إعدادات اختبار مُلتزم به يحتوي على قيم غير سرية |
| تحتاج الاختبارات إلى معلومة سرية حقيقية | قم بمحاكاة ذلك الاعتماد في الاختبارات. لا تلتزم بأي معلومات سرية أبداً |
| الاعتمادات تأتي من سجل خاص | أخبر المستخدم. يحتاج CoRoid إلى بيانات اعتماد كجزء من إعدادات المشروع. |
| تعمل الأوامر فقط من مجلد فرعي | سجّل الدليل الدقيق وأي مرشح لمساحة العمل |
عدم وجود بيئة تشغيل لا يُعتبر عائقًا أيضًا: حاوية تحتوي على سلسلة الأدوات تحل هذه المشكلة. إذا لم تتمكن من الوصول إلى المستودع محليًا، جمع ما يمكنك من المستخدم وسجّل أن فحص الاستنساخ النظيف لم يحدث.
انظر إلى إعدادات البناء والاختبار و دعم اللغات وبيئة الوكلاء.
الخطوة 3: اكتب التعليمات التي يقرأها وكلاء CoRoid
قبل كل مهمة، يقرأ وكلاء CoRoid ملفات الذاكرة الموجودة في المستودع:
AGENTS.md، CLAUDE.md أو GEMINI.md في المسار الجذري، وقواعد Cursor في
.cursor/rules.
الأوامر التي تحققت منها في الخطوة 2 توضع هناك.
اقترح AGENTS.md، أو إضافة إلى الموجود، ينص على ما يلي:
- أوامر التثبيت والبناء والاختبار، التي تم التحقق منها من استنساخ نظيف، والمجلد الذي يتم تشغيلها فيه
- الخطوات والخدمات التي تحتاجها الاختبارات
- كيفية تشغيل أضيق مجموعة مفيدة من الاختبارات، مثل حزمة واحدة أو ملف واحد
- الأعراف والحدود التي لا تظهر في الكود: وحدات مجمدة، مناطق لا يجب المساس بها، اعتمادات لا يجب إضافتها
تجاهل ما يظهره الكود بالفعل، واجعل الملف قصيرًا. إذا CLAUDE.md
أو .cursor/rules تحتوي على نفس التعليمات، احتفظ بها مرة واحدة في AGENTS.md
وقم باستيرادها من الملف الآخر باستخدام سطر @AGENTS.md .
إذا وصفت سير عمل Git محلي، فانظر إلى
AGENTS.md لكل وكيل.
اعرض على المستخدم الفرق. بموافقته، قم بالالتزام به في فرع جديد وافتح طلب سحب pull request، أو اتركه ليقوم هو بالالتزام به. يجب أن يصل إلى الفرع الأساسي قبل أول مهمة، لأن كل مهمة تقرأ ملفات الذاكرة من نسختها الخاصة من ذلك الفرع. تعامل مع الإصلاحات من الخطوة 2 التي وافق عليها المستخدم بنفس الطريقة.
انظر إلى إعدادات سياق المشروع و سياق المشروع.
الخطوة 4: الحساب والتنظيم (المستخدم)
تجاوز هذه الخطوة إذا كان المستخدم ينتمي بالفعل إلى تنظيم CoRoid كمالك أو مشرف.
اطلب من المستخدم القيام بما يلي:
- التسجيل في
https://client.coroid.ai/auth/signupباستخدام بريده الإلكتروني للعمل، وتأكيد العنوان - قبول شروط الخدمة
- إنشاء التنظيم
تحقق من: أن المستخدم يستطيع فتح https://client.coroid.ai/projects. الشخص الذي يكمل هذا الإعداد يحتاج إلى دور مالك أو مشرف، لأن هؤلاء فقط يمكنهم ربط نظام التحكم بالمصادر وإضافة مفاتيح المزود.
انظر إلى إنشاء حسابك وتنظيمك.
الخطوة 5: ربط نظام التحكم بالمصادر (المستخدم)
مرر متطلبات الوصول مع المستخدم قبل أن يبدأ. التثبيت الذي يتوقف في منتصفه بانتظار موافقة شخص آخر هو السبب الشائع لاستغراق هذه الخطوة يومًا بدلاً من دقيقة.
GitHub
يفتح المستخدم إعدادات → اتصالات → التحكم في المصدر
(https://client.coroid.ai/settings/connections/source-control).
| خيار | استخدمه عندما | ما يحتاجه المستخدم على GitHub |
|---|---|---|
| تطبيق GitHub (موصى به) | في معظم الأحوال | تصريح لتثبيت التطبيقات على الحساب أو التنظيم الذي يملك المستودعات. في التنظيم، يكون عادةً المالك؛ ويمكن لأعضاء آخرين طلب التثبيت ليقوم المالك بالموافقة عليه. |
| رمز وصول شخصي | لا يستطيع التطبيق الحصول على الموافقة التي يحتاجها المستخدم | رمز تقليدي يحتوي على نطاق repo ، أو رمز دقيق له صلاحيات القراءة والكتابة على محتويات و طلبات السحب للمستودعات المختارة |
| الربط عبر الرابط، بدون اتصال | مستودع عام، تم تجربته في محلي فقط | لا شيء |
تطبيق GitHub: على شاشة تثبيت GitHub، يختار المستخدم حدد المستودعات فقط ويختار الخيارات المتفق عليها في الخطوة 1. يستمر التطبيق في العمل حتى بعد مغادرة الشخص الذي قام بتركيبه، حيث يستقبل أحداث الويبهوك ويمكنه تمكين CoRoid من نشر عمليات التحقق الخاصة به على طلبات السحب. لا يمكن لرمز الوصول نشر عمليات تحقق من نوع GitHub.
رمز الوصول الشخصي: يقوم المستخدم بإنشائه على GitHub مع تحديد تاريخ انتهاء صلاحيته، ثم يلصقه في بوابة CoRoid. يُفضل استخدام رمز وصول دقيق يقتصر على المستودعات المتفق عليها. تُنسب طلبات السحب إلى مالك الرمز، وينقطع الاتصال إذا فقد ذلك الشخص صلاحياته.
GitLab
GitLab في مرحلة معاينة خاصة ولا يظهر إلا على الحسابات التي تم تفعيله فيها.
يتصل برمز وصول شخصي يحتوي على api النطاق. إذا لم يظهر GitLab ضمن قسم التحكم في المصدر، أخبر المستخدم بالتواصل مع CoRoid، ولا تخطط لتنفيذ أي إجراءات بناءً عليه.
حماية الفرع
يقوم CoRoid بفتح طلبات سحب عادية، لذا تظل قواعد حماية الفروع وعمليات التحقق المطلوبة وقواعد المراجعة سارية المفعول. يُنصح بالحفاظ على هذه القواعد. إذا كانت القواعد تتطلب التزامات موقعة أو عملية تحقق من نوع CoRoid لا يمكنه إنتاجها، فستُفتح طلبات السحب وتظل غير قابلة للدمج. أخبر المستخدم بذلك، ولا تغير قواعده.
عملية التحقق: يظهر المزود متصلاً تحت قسم التحكم في المصدر. الدليل الحقيقي يأتي في الخطوة 6، عندما تظهر المستودعات في قائمة المشاريع.
انظر ربط الكود الخاص بك، GitHub، GitLab و إعدادات المستودع والفرع.
الخطوة 6: إنشاء المشاريع (المستخدم)
أنشئ مشروعًا واحدًا لكل مستودع، ولا تنشئ مشروعين لنفس المستودع. يفتح المستخدم مشاريع ← جديد (https://client.coroid.ai/projects/new) و، لكل مستودع:
- يختاره من المزود المتصل، أو يستخدم الربط عبر عنوان URL لمستودع عام
- يختار وضع المستودع: متزامن، حيث يدفع CoRoid بالفروع ويفتح طلبات سحب، أو محلي فقط، حيث لا يكتب CoRoid في المستودع حتى يختار أحدهم بدء المزامنة
- يتحقق من الفرع الافتراضي
- ينشئ المشروع
إذا قام الفريق بدمج التغييرات في فرع غير الفرع الافتراضي، مثل
develop، قم بضبط الفرع الأساسي في إعدادات مستودع المشروع. فرع أساسي خاطئ يؤدي إلى إرسال طلبات السحب إلى فرع لا يقوم أحد بمراجعته.
إذا اختفى مستودع من القائمة، فالسبب غالبًا أحد هذه الأمور:
- لم يتم منح تطبيق GitHub صلاحية الوصول إلى ذلك المستودع
- نطاق رمز الوصول ضيق جدًا لعرضه
- ينتمي المستودع إلى منظمة مختلفة عن المنظمة المتصلة
انظر إنشاء أول مشروع لك و إعدادات المستودع والفرع.
الخطوة 7: تحقق مما وجده CoRoid
اطلب من المستخدم فتح نظرة عامة كل مشروع وقراءة المستودع التفاصيل وأي شيء مدرج تحت إنهاء الإعداد:
- الحالة و الفرع: تم استنساخ المستودع، وهو على الفرع الأساسي الذي اتفقتما عليه. إذا أظهرت النظرة العامة أن المستودع لم يتم استنساخه بعد، يختار المستخدم استنساخ المستودع.
- المجموعة: اللغات والأطر وأداة إدارة الحزم وأدوات الاختبار التي اكتشفها CoRoid. قارنها بفحص الجاهزية لديك. إذا كانت المجموعة فارغة أو غير صحيحة بعد المزامنة الأولى، يمكن للمستخدم إعادة الفحص من هناك.
- إنهاء الإعداد: العناصر مثل "لم تُثبت التبعيات بشكل نظيف" تشير إلى نفس الثغرات الموجودة في الخطوة 2. تعامل معها مع المستخدم.
ثم يفتح المستخدم إعدادات المشروع إعدادات ← معرفة → سياق. يجب أن يظهر ملف الذاكرة من الخطوة 3 تحت مصادر المستودع ويكون مفعلاً. إذا ظهر إنشاء بدلاً من ذلك، فهذا يعني أن الملف لم يصل بعد إلى الفرع المتصل.
انظر إعدادات سياق المشروع و إعدادات البناء والاختبار.
الخطوة 8: إعدادات المنظمة (اختياري)
اسأل المستخدم عما إذا كان يريد تفعيل أي من هذه الخيارات الآن. جميعها لها إعدادات افتراضية قابلة للعمل:
- أعضاء، تحت إعدادات → أعضاء: الأشخاص الذين سيقومون بمراجعة طلبات السحب، كمالك أو مشرف أو عضو أو مراجع. يُنصح باختيار مشرف فقط للأشخاص الذين يجب أن يغيروا السياسات ومفاتيح المزود. يتطلب اشتراك Professional.
- مفاتيح المزود، تحت إعدادات → مفاتيح المزود: للاستخدام فقط مع حسابات مزود النماذج الخاصة بالمنظمة. يدخل المستخدم المفتاح في البوابة. يُنصح باستخدام مفتاح محدود مع حد إنفاق لدى المزود.
- إعدادات من منظمة أخرى: قم بتصدير حزمة إعدادات إلى هنا و
استوردها تحت إعدادات → بيانات → تصدير الإعدادات. تنتقل البيانات السرية كـ
عناصر نائبة، لذا يجب الانتباه إلى كل
needsRebindعنصر في المعاينة.
اطلع على إنشاء حسابك ومنظمتك، مفاتيح المزود و تصدير الإعدادات واستيرادها.
الخطوة 9: اتصل بنفسك بـ CoRoid (اختياري)
إذا كان عميلك يدعم خوادم MCP عن بُعد، فيمكنك الوصول إلى CoRoid عبر خادم MCP الخاص به على https://api.coroid.ai/mcp. لا يعتمد الإعداد عليه، لكنه
يتيح لك فحص المشاريع بنفسك ومساعدة المستخدم في تنفيذ المهام لاحقًا.
- يفتح المستخدم إعدادات → اتصالات → خادم MCP الخاص بـ CoRoid
(
https://client.coroid.ai/settings/connections/coroid-mcp). إذا لم يكن متاحًا لمنظمته، تجاوز هذه الخطوة. - إعداد العميل يعرض الأوامر حسب العميل. باستخدام OAuth، يوافق المستخدم على وصولك في متصفحه. وباستخدام رمز وصول شخصي، ينشئه تحت رموز الوصول ويخزنه في متغير بيئة ضمن شلّه الخاص. لن تحتاج أبدًا إلى رؤية القيمة.
- نوصي بأقل مستوى من الصلاحيات الذي يعمل:
mcp.readللتحقق من الإعداد، بالإضافة إلىmcp.work.writeفقط إذا كنت ستقوم بإنشاء مهام. حدّد نطاق الرمز لهذه المشاريع، وحدد تاريخ انتهائه، واضبط سياسات الأتمتة قبل أن يقوم أي عميل بتنفيذ المهام تلقائيًا.
تحقق من: اتصل بـ list_projects، ثم get_project لكل مشروع من الخطوة 6،
وتأكد من المستودع والفرع.
استخدم فقط api.coroid.ai لـ MCP. لا يعمل اسم مضيف بوابة العميل معه.
اطلع على CoRoid كخادم MCP.
الخطوة 10: مسودة مهمة أولى
اختتم الأمر بمسودة مهمة أولى صغيرة مع المستخدم ضمن أحد المشاريع الجديدة. المهمة الجيدة تكون حقيقية وصغيرة وقريبة من اختبارات موجودة ولها خط نهاية واضح. تجنّب عمليات المصادقة والمدفوعات وتحويلات البيانات والمهام غير المحددة النطاق وتنظيف البيانات، وأي شيء يتطلب قرار تصميم لم يتخذه أحد بعد.
صف النتيجة وليس طريقة التنفيذ: ما الذي يجب أن يكون صحيحًا عندما
تنتهي المهمة، وما هي الملفات ذات الصلة، وما الذي لا يجب لمسه. يقدمها المستخدم من عمل جديد (https://client.coroid.ai/work/new)، ويقرأ المواصفة ويوافق على الخطة. تنفيذ المهام يستهلك ساعات العمل بالوكالة، وتشمل الخطة المجانية ساعتين يوميًا بتوقيت UTC، لذا دع المستخدم يقرر متى يتم تنفيذها.
اطلع على نفّذ مهمتك الأولى و مواصفات.
الخطوة 11: التسليم
قدّم لمستخدمك سجل الإعداد:
- كل مستودع ومشروعه ووضعه ونوعه والفرع الأساسي
- كيفية ربط نظام التحكم بالمصادر، ومن يملك الاتصال: مثبت التطبيق، أو مالك الرمز وتاريخ انتهائه
- لكل مستودع، الفجوات التي تم إصلاحها، والفجوات المتبقية (مثل طلب سحب مفتوح يحتوي على
AGENTS.md)، والفجوات التي اختار المستخدم تركها - الإعدادات الاختيارية التي تم تنفيذها وتجاهلها، ومسودة المهمة الأولى
ثم وجّه المستخدم إلى مراجعة النتيجة ودمجها لمعرفة ما يصل مع أول pull request.
التالي
إنشاء حسابك ومنظمتك — نفس الإعداد، يتم يدويًا.