هذه سلسلة مكونة من 10 أجزاء تشارك كيف طورت Apidog أداة Apidog CLI، وهي أداة سطر أوامر لاختبار واجهات برمجة التطبيقات وإدارة دورة حياة واجهة برمجة التطبيقات. اقرأ بالترتيب أو انتقل إلى أي منشور يثير اهتمامك:
| العنوان | التركيز | |
|---|---|---|
| 1 | لقد قمنا ببناء 126 أداة MCP. لكنها ليست الحل الأفضل للوكيل | اكتشاف المشكلة |
| 2 | لماذا قمنا بتطوير Apidog CLI الجديد تمامًا | تطوير البنية |
| 3 | القاعدة الذهبية: CLI تنتج حقائق، والنموذج يتصرف بناءً على الحقائق | الفلسفة الأساسية |
| 4 | agentHints: تعليم واجهات سطر الأوامر (CLIs) للتحدث إلى الوكلاء |
مخرجات منظمة |
| 5 | SKILL: شحن الخبرة التشغيلية كتعليمات برمجية | الخبرة التشغيلية |
| 6 | الأرقام لا تكذب: 30% مكالمات أدوات أقل، 25% رموز مميزة أقل | نتائج كمية |
| 7 | من وثيقة متطلبات المنتج (PRD) إلى حلقة الاختبار: سير عمل وكيل كامل باستخدام Apidog CLI | برنامج تعليمي عملي |
| 8 | لماذا لا يمكن التنازل عن توافق CI/CD لأدوات الوكيل | منظور DevOps |
| 9 | فرع الذكاء الاصطناعي: تغييرات مشروع أكثر أمانًا باستخدام وكلاء الذكاء الاصطناعي | طبقة الأمان |
| 10 | المواصفات أولاً كانت بالأمس. مرحبًا بكم في المهارة أولاً. | الرؤية والمستقبل |
لقد قارنا MCP مقابل CLI + SKILL عبر مهام المستخدم النموذجية. النتائج: عدد أقل من استدعاءات الأدوات، وهدر أقل للرموز المميزة، واستعادة أفضل للأخطاء—وتوضح البيانات السبب.
السؤال المهم
كل الفلسفة ومبادئ التصميم التي شاركناها—هل تعمل حقًا؟
لقد قمنا داخليًا بمقارنة العديد من مهام المستخدم النموذجية عبر كلا النهجين:
| نوع المهمة | الوصف |
|---|---|
| إضافة حالة اختبار + التحقق | إنشاء حالة اختبار لنقطة نهاية، تشغيل الاختبارات |
| الحفاظ على سيناريوهات الاختبار | تحديث سيناريوهات معقدة متعددة الخطوات |
| استيراد/التحقق من أصول المشروع | استيراد البيانات، تأكيد البنية، تشغيل الاختبارات |
النتائج لم تكن مجرد تحسينات ذاتية. بل كانت تخفيضات قابلة للقياس.
المهمة 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% |
انخفضت خطوات استدعاء الأداة بنحو 30%. وانخفض استهلاك الرموز المميزة من أوصاف الأدوات غير الصالحة وإعادة المحاولات الناتجة عن الأخطاء بنحو 25%.
المهمة 2: عمليات الكتابة المنظمة (المعالج، التأكيد، المستخرج)
طلب المستخدم:
"أضف تأكيدات ما بعد العملية واستخراج المتغيرات إلى حالة الاختبار هذه"
مسار MCP
| المرحلة | ماذا يحدث |
|---|---|
| تخمين أسماء الحقول | الوكيل لا يعرف الأسماء الدقيقة |
| تخمين قيم التعداد | يخمّن الوكيل المقارنة، النوع |
| محاولة الكتابة | يرفض الخادم القيم الخاطئة |
| إعادة محاولة الشبكة | ذهاب وعودة لكل خطأ |
| محاولات متعددة | 3-5 محاولات شائعة |
الأخطاء الشائعة:
| تخمين خاطئ | قيمة صحيحة | عدد المحاولات |
|---|---|---|
comparator: "contains" |
comparator: "include" |
1-2 |
type: "global" |
type: "globals" |
1-2 |
subject: "responseBody" |
subject: "responseJson" |
1-2 |
كل خطأ = 1 رحلة شبكة ذهاب وعودة + استجابة + معالجة الوكيل.
مسار CLI + SKILL
| المرحلة | ماذا يحدث |
|---|---|
| قراءة حالة الاختبار | يحصل CLI على البنية الفعلية |
| إنشاء إضافات | ينشئ الوكيل بناءً على التنسيق الحقيقي |
| التحقق محليًا | يلتقط مخطط cli الأخطاء قبل الشبكة |
| الإصلاح محليًا | يعدّل الوكيل بناءً على مخرجات التحقق |
| إعادة التحقق | تأكيد الإصلاح |
| كتابة | فقط الكتابات الصالحة تذهب إلى الخادم |
تم اكتشاف جميع الأخطاء محليًا. لا توجد إعادة محاولات للشبكة لأخطاء الحقول.
النتائج
| المقياس | مسار MCP | CLI + SKILL | التحسن |
|---|---|---|---|
| إعادة محاولات الشبكة من الأخطاء الهيكلية | 3-5 | 0 | ↓ ~100% |
| الرموز المميزة من استجابات الأخطاء | ~2,000 | ~0 | ↓ ~100% |
| إجمالي الاستدعاءات المتكررة | ~5 | ~1 | ↓ ~40% |
انخفضت الاستدعاءات المتكررة الناتجة عن الأخطاء الهيكلية بنحو 40%.
المهمة 3: العمليات المستمرة بعد الإنشاء
طلب المستخدم:
"أنشئ سيناريو اختبار باستخدام نقاط النهاية هذه"
مسار MCP
| المرحلة | ماذا يحدث |
|---|---|
| إنشاء سيناريو | يستدعي الوكيل أداة الإنشاء |
| استجابة النجاح | يرى الوكيل "تم الإنشاء" |
| متابعة الكتابة | يقوم الوكيل بالتحديث/الإضافة فورًا |
| تجاوز القراءة مرة أخرى | الوكيل لا يقرأ البنية الفعلية |
| الكتابة بناءً على الافتراض | يكتب الوكيل باستخدام معرفات/بنية مخمنة |
| خطأ أو غير مكتمل | النتيجة لا تتطابق مع التوقع |
المشكلة: قصور التنفيذ.
يميل النموذج إلى الاستمرار مباشرة بعد النجاح، متجاوزًا خطوة القراءة مرة أخرى.
مسار CLI + SKILL
| المرحلة | ماذا يحدث |
|---|---|
| إنشاء سيناريو | ينشئ CLI السيناريو |
| نجاح + agentHints | يعيد CLI النجاح + اقتراحات الخطوة التالية |
agentHints: "اقرأ مرة أخرى أولاً" |
يرى الوكيل الاقتراح |
| اتباع الاقتراح | يقرأ الوكيل مرة أخرى |
| العمل بالبنية الحقيقية | يتابع الوكيل ببيانات دقيقة |
تقترح agentHints صراحة القراءة مرة أخرى. يتبع الوكيل ذلك.
النتائج
| المقياس | مسار MCP | CLI + SKILL | التحسن |
|---|---|---|---|
| النسبة التي قرأت مرة أخرى قبل المتابعة | ~20% | ~85% | ↑ ~425% |
| إعادة محاولات الأخطاء من القفزات المباشرة | ~3-5 | ~0-1 | ↓ ~21% |
زادت نسبة الوكلاء الذين يقرأون البيانات بشكل استباقي، ويتحققون منها، ويجرون التحقق بشكل كبير. وانخفضت إعادة محاولات الأخطاء الناتجة عن القفز مباشرة إلى الخطوة التالية بنحو 21%.
الملخص: من أين تأتي الوفورات
| مصدر الوفورات | التفسير |
|---|---|
| اكتشاف الأداة | أوامر CLI لها أسماء واضحة؛ SKILL توجه الاختيار |
| التحقق من المخطط | التحقق المحلي يكتشف الأخطاء قبل استدعاء الشبكة |
| استعادة الأخطاء | توفر agentHints اقتراحات قابلة للتنفيذ، وليس فقط "فشل" |
| إرشاد القراءة مرة أخرى | يمنع عمليات الكتابة القائمة على الافتراضات |
| تسلسل سير العمل | SKILL يقلل من نقاط القرار |
تحليل التكلفة الحقيقية
الرؤية الرئيسية:
تمكين الوكيل للمنتجات لا يتعلق بزيادة عدد الأدوات، بل يتعلق بالأفضل.
ما يستهلكه النموذج حقًا:
| نوع التكلفة | عبء 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%
- تأتي الوفورات من: الاكتشاف الموجه، والتحقق المحلي، والتلميحات القابلة للتنفيذ
- انتقل التعقيد من السياق إلى النظام الهندسي
حمّل Apidog لـ تصميم، محاكاة، اختبار، و توثيق واجهات برمجة التطبيقات في مساحة عمل واحدة. تعرف على المزيد حول Apidog CLI لاختبار واجهة برمجة التطبيقات عبر سطر الأوامر، وأتمتة CI، وسير عمل وكيل الذكاء الاصطناعي.