لماذا يُعد توافق CI/CD لا غنى عنه لأدوات الوكيل

هذه سلسلة من 10 أجزاء تشرح كيف طورت Apidog أداة Apidog CLI، وهي أداة سطر أوامر لاختبار واجهات برمجة التطبيقات وإدارة دورة حياة الـ API. يمكنك قراءة الأجزاء بالترتيب أو الانتقال مباشرة إلى الموضوع الذي تحتاجه.

جرّب Apidog اليوم

	العنوان	التركيز
1	بنينا 126 أداة MCP. لكنها ليست الحل الأفضل للعميل	اكتشاف المشكلة
2	لماذا قمنا بتطوير Apidog CLI جديدة تمامًا	تطوير المعمارية
3	القاعدة الذهبية: سطر الأوامر ينتج حقائق، والنموذج يتصرف بناءً على الحقائق	الفلسفة الأساسية
4	agentHints: تعليم أدوات سطر الأوامر التحدث مع الوكلاء	إخراج منظم
5	SKILL: شحن الخبرة التشغيلية كرمز	الخبرة التشغيلية
6	الأرقام لا تكذب: 30% أقل من استدعاءات الأدوات، 25% أقل من الرموز	نتائج كمية
7	من PRD إلى حلقة الاختبار: سير عمل كامل للوكيل مع Apidog CLI	برنامج تعليمي عملي
8	لماذا لا يمكن التنازل عن توافق CI/CD لأدوات الوكيل	منظور DevOps
9	فرع الذكاء الاصطناعي: تغييرات مشروع أكثر أمانًا مع وكلاء الذكاء الاصطناعي	طبقة الأمان
10	Spec-First كان بالأمس. مرحبًا بكم في Skill-First.	الرؤية والمستقبل

---

يجب بناء ودية الوكيل فوق ودية CI/CD. في هذا الجزء سنرى كيف يخدم الأمر apidog run مسارات CI ووكلاء الذكاء الاصطناعي في الوقت نفسه، ولماذا هذا التصميم مهم عند بناء أدوات CLI قابلة للأتمتة.

الجمهور المزدوج

عند بناء أدوات موجهة للوكلاء، من السهل التركيز فقط على تجربة المحادثة: ماذا يقول الوكيل؟ كيف يفسر النتيجة؟ ما الخطوة التالية؟

لكن Apidog CLI لديه جمهور أساسي لا يمكن كسره: مسارات CI/CD.

الجمهور الأصلي	الجمهور الجديد
مسارات CI/CD	وكلاء الذكاء الاصطناعي
أنظمة الجدولة الخارجية	سير العمل القائم على المحادثة
البرامج النصية والأتمتة	المهام التي يحركها المستخدم

تستخدم الفرق Apidog في المسارات من أجل:

• تشغيل اختبارات API المؤتمتة
• إنشاء تقارير قابلة للنشر
• الحفاظ على بوابات الجودة قبل النشر
• فشل المسار عند فشل الاختبارات

لذلك يجب أن تبقى واجهة CLI مناسبة للأتمتة:

المتطلب	لماذا
إخراج مستقر	حتى تستطيع البرامج النصية تحليل النتائج
أوامر قابلة للبرمجة النصية	حتى تعمل داخل CI بدون تفاعل يدوي
رموز خروج واضحة	لاتخاذ قرار نجاح/فشل المسار
معلمات قابلة للتكوين	لتشغيل الاختبارات حسب البيئة

الخلاصة العملية: لا تضف ميزات للوكيل تكسر ما تعتمد عليه CI/CD.

---

المبدأ الرئيسي

يجب بناء ودية الوكيل فوق ودية CI/CD.

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

أداة CLI الجيدة في عصر الوكلاء يجب أن تخدم أربعة أنواع من المستهلكين:

المستهلك	ما يحتاجه
البشر	إخراج قابل للقراءة، نص مساعدة، ميزات تفاعلية
البرامج النصية	إخراج مستقر وأوامر قابلة للتكرار
مسارات CI	رموز خروج، ملفات تقارير، إعدادات قابلة للتكوين
وكلاء الذكاء الاصطناعي	نتائج منظمة، تحقق، وتوجيهات قابلة للتنفيذ

---

apidog run: الأمر الأساسي

الأمر المركزي هو:

apidog run --project <معرف المشروع> \
  --test-scenario <معرف السيناريو> \
  --environment <معرف البيئة> \
  -r "cli,html,junit" \
  --out-dir ./apidog-reports

هذا الأمر يخدم أكثر من سيناريو في الوقت نفسه:

• يقرأه المطور من الطرفية
• تشغله CI داخل المسار
• يحلله الوكيل بعد تنفيذ مهمة
• تستخدمه البرامج النصية ضمن أتمتة أكبر

---

ما يهم CI

في CI، لا يهم أن يكون الإخراج “ذكيًا” بقدر ما يهم أن يكون حتميًا وقابلًا للمعالجة.

متطلب CI	ميزة CLI
رموز الخروج	0 للنجاح و1 للفشل
ملفات التقارير	HTML وJUnit وJSON داخل --out-dir
معلمات مستقرة	خيارات يمكن استخدامها عبر الإصدارات
تشغيلات قابلة للتكوين	التكرارات -n، التأخير --delay-request، البيئة -e

مثال عملي باستخدام GitHub Actions:

# GitHub Actions
- name: تشغيل اختبارات واجهة برمجة التطبيقات
  run: |
    apidog run --project $PROJECT_ID \
      --test-scenario $SCENARIO_ID \
      --environment $ENV_ID \
      -r "junit" \
      --out-dir ./reports
  env:
    PROJECT_ID: ${{ secrets.APIDOG_PROJECT_ID }}
    SCENARIO_ID: ${{ secrets.APIDOG_SCENARIO_ID }}
    ENV_ID: production

- name: نشر تقرير الاختبار
  uses: mikepenz/action-junit-report@v3
  with:
    report_paths: './reports/junit.xml'

ما يحدث هنا بسيط:

1. المسار يشغّل apidog run
2. Apidog CLI ينشئ تقرير JUnit
3. CI تقرأ رمز الخروج
4. المسار ينجح أو يفشل
5. التقرير يُنشر للرجوع إليه

---

ما يهم الوكلاء

الوكيل لا يحتاج فقط إلى معرفة أن الاختبار فشل. يحتاج إلى معرفة:

• أي خطوة فشلت؟
• ما سبب الفشل؟
• ما السياق المرتبط بالاستجابة؟
• ما الإجراء التالي المقترح؟

متطلب الوكيل	ميزة CLI
نتائج منظمة	إخراج JSON مع كائن data
أسباب الفشل	تفاصيل محددة داخل كائن error
اقتراحات الخطوة التالية	agentHints مع nextSteps
التحقق	cli-schema validate قبل الكتابة

مثال على إخراج يمكن للوكيل تحليله:

{
  "success": true,
  "stats": {
    "total": 10,
    "passed": 8,
    "failed": 2
  },
  "failures": [
    {
      "step": "معالجة الدفع",
      "error": "فشل التأكيد: status != 'success'",
      "response": {}
    }
  ],
  "agentHints": {
    "summary": "فشل اختباران. راجع تفاصيل الفشل.",
    "nextSteps": [
      "تصحيح خطأ خطوة معالجة الدفع.",
      "التحقق من التأكيد: الحالة المتوقعة 'success'.",
      "تحديث حالة الاختبار أو نقطة النهاية بعد الإصلاح."
    ]
  }
}

سير العمل الخاص بالوكيل يصبح:

1. يشغّل الاختبارات
2. يقرأ JSON
3. يحدد الإخفاقات
4. يتبع agentHints.nextSteps
5. يكرر التعديل والتحقق

---

نفس الأمر، مستهلكون مختلفون

apidog run --project <معرف المشروع> --out-dir ./apidog-reports

المستهلك	ما يستخرجه
مسار CI	رمز الخروج 0/1 وموقع التقرير
الوكيل	إخراج JSON وagentHints وتفاصيل الفشل
البشري	إخراج وحدة التحكم ورابط تقرير HTML
البرنامج النصي	الناتج القياسي/الخطأ القياسي وتنسيق قابل للتكوين

نقطة التصميم المهمة: لا تحتاج إلى أمر منفصل لكل مستهلك. الأمر نفسه ينتج حقائق، وكل مستهلك يستخدم الجزء الذي يحتاجه.

---

نقاط التكامل

يدعم Apidog CLI التكامل مع أدوات CI الشائعة عبر نفس الأساس: تشغيل apidog run داخل خطوة المسار، ثم نشر التقارير أو استخدام رمز الخروج لاتخاذ القرار.

أداة CI	نمط التكامل
Jenkins	خطوات Pipeline ونشر التقارير
GitLab CI	تكوين YAML ومرفقات artifacts
GitHub Actions	خطوات workflow وإدارة الأسرار
CircleCI	تكوين workflow
Azure DevOps	مهام Pipeline ونتائج الاختبار

مثال عام يمكن تكييفه مع أي نظام CI:

apidog run \
  --project "$APIDOG_PROJECT_ID" \
  --test-scenario "$APIDOG_SCENARIO_ID" \
  --environment "$APIDOG_ENV_ID" \
  -r "cli,junit,html" \
  --out-dir ./apidog-reports

بعدها يمكن للمسار:

• فحص رمز الخروج
• رفع ./apidog-reports كمرفقات
• نشر تقرير JUnit
• إيقاف النشر إذا فشلت الاختبارات

---

بوابة الجودة مقابل التحقق

الأمر نفسه يخدم سياقين مختلفين:

حالة الاستخدام	المعنى
بوابة جودة CI	النجاح أو الفشل يحدد هل يستمر المسار
تحقق الوكيل	التشغيل بعد تعديلات الوكيل للتأكد من الصحة

السياق	متى يستخدم	الغرض
CI	بعد دفع الكود	منع نشر كود غير صالح
الوكيل	بعد إنشاء أو تعديل اختبار	تأكيد أن عمل الوكيل صحيح

هذا يجعل apidog run نقطة تحقق مشتركة بين الإنسان، CI، والوكيل.

---

المبدأ الأساسي

كل ما وصفناه في هذه السلسلة — cli-schema، وagentHints، وSKILL — يبنى فوق أساس CI/CD:

┌─────────────────────────────────────────┐
│              ميزات الوكيل              │
│      (cli-schema, agentHints, SKILL)    │
├─────────────────────────────────────────┤
│              أساس CI/CD                 │
│   (apidog run, رموز الخروج، التقارير)  │
├─────────────────────────────────────────┤
│              CLI الأساسي                │
│      (الأوامر، المعلمات، التنفيذ)      │
└─────────────────────────────────────────┘

ميزات الوكيل لا تستبدل ميزات CI. بل توسعها.

---

ماذا بعد

غطينا حتى الآن الصورة الكاملة: من اكتشاف المشكلة، إلى سير العمل العملي، إلى المبادئ التأسيسية لبناء CLI يخدم CI والوكلاء معًا.

القطعة التالية هي: الأمان.

عندما يبدأ الوكلاء في تعديل موارد المشروع، كيف تمنعهم من التأثير مباشرة على الفرع الرئيسي؟

في الجزء 9، فرع الذكاء الاصطناعي: تغييرات مشروع أكثر أمانًا مع وكلاء الذكاء الاصطناعي، سنستكشف كيف يوفر فرع الذكاء الاصطناعي بيئة تحرير معزولة، بحيث تبقى التغييرات في فرع منفصل حتى تتم مراجعتها بشريًا.

---

النقاط الرئيسية

• توافق CI/CD هو الأساس، وليس ميزة اختيارية.
• ودية الوكيل يجب أن تبنى فوق ودية CI.
• الأمر نفسه، apidog run، يخدم CI والوكلاء والبشر والبرامج النصية.
• CI تحتاج إلى رموز خروج، تقارير، ومعلمات مستقرة.
• الوكلاء يحتاجون إلى إخراج منظم، تفاصيل فشل، وخطوات تالية.
• بوابة الجودة في CI والتحقق بعد عمل الوكيل يمكن أن يعتمدا على نفس الأمر.

---

قم بتنزيل Apidog من أجل تصميم، محاكاة، اختبار، وتوثيق واجهات برمجة التطبيقات في مساحة عمل واحدة. تعرف على المزيد حول Apidog CLI لاختبار واجهات برمجة التطبيقات عبر سطر الأوامر، وأتمتة CI، وسير عمل وكلاء الذكاء الاصطناعي.