هذه سلسلة من 10 أجزاء تشرح كيف طوّرت Apidog أداة Apidog CLI، وهي أداة سطر أوامر لاختبار واجهات برمجة التطبيقات وإدارة دورة حياة API. يمكنك القراءة بالترتيب أو الانتقال مباشرة إلى الجزء الذي تحتاجه.
| # | العنوان | التركيز |
|---|---|---|
| 1 | لقد قمنا ببناء 126 أداة MCP. لكنها ليست الحل الأفضل للوكيل | اكتشاف المشكلة |
| 2 | لماذا قمنا بتطوير Apidog CLI الجديد تمامًا | تطوير البنية |
| 3 | القاعدة الذهبية: CLI تنتج حقائق، والنموذج يتصرف بناءً على الحقائق | الفلسفة الأساسية |
| 4 | agentHints: تعليم واجهات سطر الأوامر للتحدث إلى الوكلاء |
مخرجات منظمة |
| 5 | SKILL: شحن الخبرة التشغيلية كتعليمات برمجية | الخبرة التشغيلية |
| 6 | الأرقام لا تكذب: 30% مكالمات أدوات أقل، 25% رموز مميزة أقل | نتائج كمية |
| 7 | من وثيقة متطلبات المنتج PRD إلى حلقة الاختبار: سير عمل وكيل كامل باستخدام Apidog CLI | برنامج تعليمي عملي |
| 8 | لماذا لا يمكن التنازل عن توافق CI/CD لأدوات الوكيل | منظور DevOps |
| 9 | فرع الذكاء الاصطناعي: تغييرات مشروع أكثر أمانًا باستخدام وكلاء الذكاء الاصطناعي | طبقة الأمان |
| 10 | المواصفات أولاً كانت بالأمس. مرحبًا بكم في المهارة أولاً. | الرؤية والمستقبل |
في هذا الجزء نقارن MCP مقابل CLI + SKILL عبر مهام مستخدم شائعة. الهدف ليس عرض فلسفة معمارية فقط، بل قياس الأثر العملي: عدد استدعاءات الأدوات، استهلاك الرموز المميزة، وإعادة المحاولات الناتجة عن الأخطاء.
السؤال العملي
هل يؤدي تصميم CLI + SKILL إلى تحسين قابل للقياس عند استخدام وكلاء الذكاء الاصطناعي مع مهام API؟
اختبرنا داخليًا عدة مهام نموذجية:
| نوع المهمة | الوصف |
|---|---|
| إضافة حالة اختبار + التحقق | إنشاء حالة اختبار لنقطة نهاية ثم تشغيل الاختبارات |
| الحفاظ على سيناريوهات الاختبار | تحديث سيناريوهات متعددة الخطوات ومعقدة |
| استيراد/التحقق من أصول المشروع | استيراد البيانات، تأكيد البنية، وتشغيل الاختبارات |
النتيجة: التحسينات لم تكن انطباعية. ظهرت كتخفيضات قابلة للقياس في الاستدعاءات والرموز المهدرة وإعادة المحاولات.
المهمة 1: إضافة حالة اختبار بناءً على نقطة نهاية
طلب المستخدم:
"أضف اختبارًا لنقطة النهاية هذه وقم بتشغيل التحقق"
كيف يتصرف مسار MCP عادةً
| المرحلة | ما يحدث |
|---|---|
| اكتشاف الأداة | يبحث الوكيل في قائمة الأدوات المتاحة |
| اختيار الأداة | يجرب أو يقارن بين عدة أدوات |
| اكتشاف الحقول | يقرأ مخطط الأداة |
| تخمين الحقول | يستنتج الحقول المطلوبة والقيم المقبولة |
| محاولة الكتابة | يستدعي أداة الإنشاء |
| استجابة الخطأ | يرفض الخادم الطلب بسبب حقل خاطئ أو مفقود |
| إعادة المحاولة | يعدّل الوكيل الطلب |
| محاولات إضافية | يكرر حتى ينجح |
| تشغيل الاختبارات | يبحث عن أداة التشغيل ثم ينفذها |
النمط التنفيذي:
البحث عن الأدوات
→ تحديد الأداة
→ قراءة المخطط
→ تخمين الحقول
→ كتابة
→ خطأ
→ تعديل
→ كتابة
→ خطأ
→ تعديل
→ نجاح
→ البحث عن أداة التشغيل
→ تشغيل
كيف يتصرف مسار CLI + SKILL
| المرحلة | ما يحدث |
|---|---|
| إرشاد SKILL | تحدد SKILL نوع المهمة وتوفر سير العمل |
| قراءة نقطة النهاية | يعيد CLI حقائق نقطة النهاية |
| إنشاء حالة اختبار | ينشئ الوكيل حالة الاختبار بناءً على البيانات الفعلية |
| التحقق محليًا | يتحقق CLI من المخطط قبل الكتابة |
| كتابة | ينشئ CLI حالة الاختبار |
| القراءة مرة أخرى | يعيد CLI البنية المنشأة مع agentHints
|
| تشغيل الاختبارات | تقترح agentHints الخطوة التالية، ويتبعها الوكيل |
النمط التنفيذي:
توجيه SKILL
→ قراءة نقطة النهاية
→ إنشاء
→ تحقق محلي
→ كتابة
→ قراءة مرة أخرى
→ تشغيل
النتائج
| المقياس | مسار MCP | CLI + SKILL | التحسن |
|---|---|---|---|
| خطوات استدعاء الأداة | ~15-20 | ~10-12 | ↓ ~30% |
| الرموز المميزة من الأوصاف | ~50,000 محملة | ~2,000 محملة | ↓ ~96% |
| الرموز المميزة من إعادة المحاولات | ~5,000+ هدر | ~500 هدر | ↓ ~90% |
| إجمالي هدر الرموز المميزة | ~55,000 | ~2,500 | ↓ ~25% |
الخلاصة العملية: عندما يعرف الوكيل سير العمل مسبقًا، يقل وقت الاكتشاف والتخمين. وعندما يتحقق CLI محليًا قبل الكتابة، تقل إعادة المحاولات المكلفة.
المهمة 2: عمليات الكتابة المنظمة: المعالج، التأكيد، والمستخرج
طلب المستخدم:
"أضف تأكيدات ما بعد العملية واستخراج المتغيرات إلى حالة الاختبار هذه"
هذه المهمة حساسة لأن الحقول والقيم يجب أن تطابق البنية التي يتوقعها المنتج.
مسار MCP
| المرحلة | ما يحدث |
|---|---|
| تخمين أسماء الحقول | الوكيل لا يعرف دائمًا الاسم الدقيق |
| تخمين قيم التعداد | يستنتج قيمًا مثل نوع المقارنة أو نوع المتغير |
| محاولة الكتابة | يرسل الطلب إلى الخادم |
| رفض الخادم | القيم غير صحيحة أو غير مدعومة |
| إعادة محاولة الشبكة | كل إصلاح يتطلب ذهابًا وعودة |
| محاولات متعددة | 3-5 محاولات شائعة |
أخطاء نموذجية:
| تخمين خاطئ | القيمة الصحيحة | عدد المحاولات |
|---|---|---|
comparator: "contains" |
comparator: "include" |
1-2 |
type: "global" |
type: "globals" |
1-2 |
subject: "responseBody" |
subject: "responseJson" |
1-2 |
كل خطأ يعني:
طلب شبكة
+ استجابة خطأ
+ معالجة من الوكيل
+ تعديل
+ طلب جديد
مسار CLI + SKILL
| المرحلة | ما يحدث |
|---|---|
| قراءة حالة الاختبار | يحصل CLI على البنية الفعلية |
| إنشاء الإضافات | يبني الوكيل التعديلات وفق التنسيق الحقيقي |
| التحقق محليًا | يلتقط مخطط CLI الأخطاء قبل الشبكة |
| الإصلاح محليًا | يعدّل الوكيل بناءً على مخرجات التحقق |
| إعادة التحقق | يؤكد أن التعديل صالح |
| كتابة | تُرسل فقط البيانات الصالحة إلى الخادم |
النمط الأفضل هنا:
اقرأ البنية الحالية
→ أنشئ التعديل
→ تحقق محليًا
→ أصلح محليًا إن لزم
→ اكتب مرة واحدة
الفرق المهم: الأخطاء الهيكلية تُكتشف محليًا بدلًا من اكتشافها بعد استدعاء الخادم.
النتائج
| المقياس | مسار MCP | CLI + SKILL | التحسن |
|---|---|---|---|
| إعادة محاولات الشبكة من الأخطاء الهيكلية | 3-5 | 0 | ↓ ~100% |
| الرموز المميزة من استجابات الأخطاء | ~2,000 | ~0 | ↓ ~100% |
| إجمالي الاستدعاءات المتكررة | ~5 | ~1 | ↓ ~40% |
الخلاصة العملية: ضع التحقق قبل الشبكة. كل خطأ يمكن اكتشافه محليًا يجب ألا يصل إلى الخادم.
المهمة 3: العمليات المستمرة بعد الإنشاء
طلب المستخدم:
"أنشئ سيناريو اختبار باستخدام نقاط النهاية هذه"
هذه المهمة تكشف مشكلة شائعة في الوكلاء: بعد نجاح الإنشاء، يميل النموذج إلى المتابعة مباشرة دون قراءة المورد المنشأ.
مسار MCP
| المرحلة | ما يحدث |
|---|---|
| إنشاء سيناريو | يستدعي الوكيل أداة الإنشاء |
| استجابة النجاح | يرى الوكيل أن العملية نجحت |
| متابعة الكتابة | يبدأ في التحديث أو الإضافة مباشرة |
| تجاوز القراءة مرة أخرى | لا يقرأ البنية الفعلية التي أنشأها الخادم |
| الكتابة بالافتراض | يستخدم معرفات أو بنى متوقعة |
| خطأ أو نتيجة ناقصة | لا تطابق النتيجة التوقعات |
المشكلة هنا ليست فشلًا في الإنشاء، بل قصور في تسلسل التنفيذ.
النمط الخاطئ:
إنشاء
→ نجاح
→ متابعة مباشرة
→ افتراض البنية
→ خطأ
مسار CLI + SKILL
| المرحلة | ما يحدث |
|---|---|
| إنشاء سيناريو | ينشئ CLI السيناريو |
نجاح + agentHints
|
يعيد CLI النجاح مع اقتراحات الخطوة التالية |
agentHints: اقرأ مرة أخرى أولًا |
يحصل الوكيل على توجيه صريح |
| اتباع الاقتراح | يقرأ الوكيل المورد المنشأ |
| العمل بالبنية الحقيقية | يتابع باستخدام معرفات وبيانات دقيقة |
النمط الأفضل:
إنشاء
→ نجاح
→ agentHints تقترح القراءة مرة أخرى
→ قراءة المورد المنشأ
→ متابعة بناءً على البنية الحقيقية
النتائج
| المقياس | مسار MCP | CLI + SKILL | التحسن |
|---|---|---|---|
| النسبة التي قرأت مرة أخرى قبل المتابعة | ~20% | ~85% | ↑ ~425% |
| إعادة محاولات الأخطاء من القفزات المباشرة | ~3-5 | ~0-1 | ↓ ~21% |
الخلاصة العملية: بعد أي عملية إنشاء، اجعل القراءة مرة أخرى خطوة افتراضية. agentHints تجعل هذه الخطوة واضحة للوكيل بدل الاعتماد على تذكّره.
من أين تأتي الوفورات؟
| مصدر الوفورات | التفسير العملي |
|---|---|
| اكتشاف الأداة | أوامر CLI أوضح، وSKILL تقلل مساحة الاختيار |
| التحقق من المخطط | التحقق المحلي يكتشف الأخطاء قبل استدعاء الشبكة |
| استعادة الأخطاء |
agentHints تعطي اقتراحًا قابلًا للتنفيذ بدل رسالة فشل فقط |
| إرشاد القراءة مرة أخرى | يمنع الكتابة بناءً على افتراضات بعد الإنشاء |
| تسلسل سير العمل | SKILL تقلل قرارات الوكيل في منتصف المهمة |
يمكن تلخيص ذلك كالتالي:
بدلًا من:
النموذج يكتشف + يخمن + يجرّب + يعيد المحاولة
استخدم:
SKILL توجه + CLI يتحقق + agentHints تقترح الخطوة التالية
تحليل التكلفة الحقيقية
الرؤية الرئيسية:
تمكين الوكلاء داخل المنتجات لا يعني إضافة أدوات أكثر، بل تصميم أدوات أفضل.
ما يستهلكه النموذج ليس فقط استدعاء API، بل أيضًا:
| نوع التكلفة | عبء MCP | عبء CLI + SKILL |
|---|---|---|
| السياق | أوصاف الأدوات والمخططات | SKILL مركزة على المهمة |
| الانتباه | الاختيار من بين عدة أدوات | اتباع سير عمل موجه |
| اختيار المسار | تخمين التسلسل الصحيح | تسلسل محدد بواسطة SKILL |
| رموز المستخدم | إعادة المحاولات والمكالمات الفاشلة | كتابات متحقق منها ومكالمات أقل |
بعد زيادة عدد الأدوات، يصبح العبء الحقيقي هو الموازنة بين السياق والانتباه واختيار المسار وتكلفة الرموز المميزة.
المبدأ الهندسي
الهدف:
انقل التكلفة من سياق النموذج إلى النظام الهندسي حيث يمكن التحكم بها واختبارها.
| التكلفة | في MCP | في CLI + SKILL |
|---|---|---|
| اكتشاف الأداة | النموذج يبحث | SKILL توفر التوجيه |
| التحقق من الحقول | النموذج يجب أن يعرف | CLI يتحقق |
| إرشاد الخطوة التالية | النموذج يقرر |
agentHints تقترح |
| دلالات المنتج | النموذج يحاول الفهم | CLI يتعامل معها |
بهذا يصبح دور النموذج أوضح:
النموذج: يولّد ويحكم
النظام الهندسي: يتحقق ويوجه وينفذ
ماذا تعني هذه الأرقام؟
| الرؤية | المضمون |
|---|---|
| 30% عدد أقل من استدعاءات الأدوات | التعقيد انتقل من الاكتشاف إلى الإرشاد |
| 25% عدد أقل من الرموز المميزة المهدرة | الأخطاء تُكتشف قبل الشبكة |
| 40% عدد أقل من إعادة المحاولات الهيكلية | بوابة التحقق المحلي تعمل |
| 21% عدد أقل من أخطاء القفز |
agentHints تمنع المتابعة العمياء |
CLI + SKILL ليس مجرد اختيار معماري أنيق. إنه تحسين قابل للقياس في طريقة تشغيل الوكلاء.
ماذا بعد؟
بعد التحقق من النهج بالأرقام، الخطوة التالية هي رؤيته في سير عمل كامل.
في الجزء السابع، من وثيقة متطلبات المنتج PRD إلى حلقة الاختبار: سير عمل وكيل كامل، سنستعرض مثالًا عمليًا: فريق لديه PRD لميزة "استرداد الطلب"، ويستخدم الوكيل CLI + SKILL لإنشاء OpenAPI، وبناء الاختبارات، وتشغيل التحقق، ثم التأكد من النتيجة.
النقاط الرئيسية
- انخفضت خطوات استدعاء الأداة بنحو 30%.
- انخفض هدر الرموز المميزة من الأوصاف وإعادة المحاولات بنحو 25%.
- انخفضت إعادة محاولات الأخطاء الهيكلية بنحو 40%.
- انخفضت أخطاء القفز الناتجة عن تجاوز القراءة مرة أخرى بنحو 21%.
- تأتي الوفورات من الاكتشاف الموجه، والتحقق المحلي، و
agentHintsالقابلة للتنفيذ. - التصميم الأفضل ينقل التعقيد من سياق النموذج إلى النظام الهندسي.
حمّل Apidog من أجل تصميم، محاكاة، اختبار، وتوثيق واجهات برمجة التطبيقات في مساحة عمل واحدة. تعرّف أكثر على Apidog CLI لاختبار API عبر سطر الأوامر، وأتمتة CI، وسير عمل وكلاء الذكاء الاصطناعي.
Top comments (0)