هذه سلسلة من 10 أجزاء تشرح كيف طوّرت Apidog أداة Apidog CLI، وهي أداة سطر أوامر لاختبار واجهات برمجة التطبيقات وإدارة دورة حياة API. يمكنك قراءتها بالترتيب أو الانتقال مباشرة إلى الجزء الذي يهمك:
| العنوان | التركيز | |
|---|---|---|
| 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 | التصميم أولاً كان بالأمس. مرحبًا بك في "المهارة أولاً". | الرؤية والمستقبل |
لا تجعل النموذج يحفظ جميع القواعد. اجعل القواعد تُنفذ في المكان الصحيح. يحوّل
cli-schema validateالمخطط من معرفة يجب تذكّرها إلى بوابة جودة قابلة للتنفيذ.
المبدأ الأساسي: دع القواعد تُنفذ في الأماكن الصحيحة
من تجربة بناء Apidog CLI + SKILL، وصلنا إلى قاعدة عملية واحدة:
لا تجعل النموذج يحفظ جميع القواعد. دع القواعد تُنفذ في الأماكن الصحيحة.
قسّم العمل بين النظام والوكيل بهذه الطريقة:
| نوع المؤشر | مكان الانتماء |
|---|---|
| مؤشرات حتمية | سكريبتات، أكواد، فحوصات آلية |
| أحكام دلالية | نماذج لغوية كبيرة، استدلال النموذج |
وفي سياق Apidog CLI + SKILL:
| ماذا | أين |
|---|---|
| التحقق الحتمي من البنية | CLI عبر cli-schema
|
| حكم المهمة والتوليد | الوكلاء |
الخلاصة التنفيذية:
دع CLI تتحقق من البنية. دع الوكلاء يولدون المحتوى.
المشكلة: ذاكرة النموذج ليست نظام تحقق
عندما يساعد وكيل ذكاء اصطناعي في إنشاء أو تحديث موارد داخل Apidog، فالمخاطرة ليست في توليد النص فقط.
المخاطرة الحقيقية هي:
كتابة محتوى مولّد داخل مشروع حقيقي بدون تحقق بنيوي كافٍ.
موارد Apidog منظمة. على سبيل المثال، حالة اختبار أو سيناريو اختبار قد يحتوي على:
| المكون | التعقيد |
|---|---|
| بيانات الطلب | الأسلوب Method، الرابط URL، الرؤوس headers، الجسم body، المصادقة auth
|
| التأكيدات | المقارن Comparator، الموضوع subject، القيمة المستهدفة، الشروط |
| استخلاص المتغيرات | اسم المتغير، النوع، مسار الاستخلاص |
| المعالجات المسبقة | سكريبتات قبل الطلب |
| المعالجات اللاحقة | سكريبتات بعد الاستجابة |
| ترتيب الخطوات | التسلسل، التبعيات |
| مراجع البيئة | معرف البيئة، تجاوزات المتغيرات |
إذا خمن الوكيل البنية، قد تحصل على أخطاء مثل:
- اسم حقل خاطئ ← فشل الكتابة
- قيمة تعداد غير صالحة ← رفض الخادم
- حقل إلزامي مفقود ← مورد غير مكتمل
- نوع بيانات خاطئ ← مشاكل في عرض واجهة المستخدم
- تداخل غير صحيح ← الاختبارات لا تعمل كما هو متوقع
الحل ليس زيادة حجم الـ prompt. الحل هو إضافة تحقق محلي قبل الكتابة.
cli-schema validate: بوابة الجودة قبل الكتابة
الاستخدام الأساسي:
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
استخدم هذا الأمر عندما يولّد الوكيل ملف JSON لإنشاء أو تحديث مورد، مثل سيناريو اختبار أو حالة اختبار.
يقوم validate بالتحقق من:
- أسماء الحقول
- بنية JSON
- قيم التعداد
- قيود النوع
- الحقول الإلزامية
- التداخلات المتوقعة داخل المورد
والأهم:
يحدث ذلك قبل إرسال أي طلب كتابة إلى الخادم.
أين تضع validate في سير العمل؟
النمط العملي هو:
# 1. الوكيل يولد ملف JSON
# مثال: ./test-case-create.json
# 2. تحقق محلي قبل الكتابة
apidog cli-schema validate test-case-create --file ./test-case-create.json
# 3. إذا نجح التحقق، نفّذ الكتابة
apidog test-case create --project <projectId> --file ./test-case-create.json
إذا فشل التحقق، لا ترسل طلب الكتابة. أصلح الملف أولًا، ثم أعد التحقق.
أخطاء شائعة يلتقطها cli-schema
فيما يلي أمثلة لأخطاء يرتكبها الوكلاء عادةً أثناء توليد JSON:
| قيمة خاطئة | قيمة صحيحة | السياق |
|---|---|---|
global |
globals |
نوع نطاق المتغير |
contains |
include |
مقارن التأكيد |
responseBody |
responseJson |
موضوع جسم الاستجابة |
"500" نص |
500 رقم |
التأخير بالمللي ثانية |
equals |
equal |
مقارن التأكيد |
header |
headers |
حقل رؤوس الطلب |
هذه الأخطاء ليست نظرية. تم رصدها من تفاعلات وكلاء حقيقية.
بدون تحقق محلي، قد تؤدي إلى:
- طلب كتابة فاشل
- استجابة خطأ من API
- محاولة الوكيل تفسير خطأ غير واضح
- إعادة محاولات متعددة
- استهلاك توكنات إضافية في حلقات تصحيح غير ضرورية
مع cli-schema validate، يتم اكتشافها محليًا قبل استدعاء الشبكة.
لماذا لا نضع كل القواعد في الـ Prompt؟
هناك بديلان شائعان، وكلاهما أقل كفاءة.
البديل الأول: كتابة كل القواعد داخل التوجيه
قد تحاول وضع كل شيء داخل prompt الوكيل:
- كل أسماء الحقول
- كل قيم التعداد
- كل قيود الأنواع
- كل البنى المتداخلة
المشكلة:
هذا يضيف عبئًا سياقيًا كبيرًا.
مخطط سيناريو اختبار شامل قد يحتاج بسهولة إلى أكثر من 5000 توكن وصفي. وسيحمل النموذج هذا السياق في كل مهمة، حتى عندما لا تكون معظم القواعد مطلوبة.
البديل الثاني: الاعتماد على ذاكرة النموذج
قد تفترض أن النموذج “يعرف” البنية الصحيحة.
لكن في الواقع:
- النموذج قد يعرف أنماط API عامة
- لكنه لا يعرف بالضرورة مخططات Apidog الخاصة
- أسماء الحقول تختلف بين المنتجات
- قيم التعداد خاصة بالسياق
- الاتفاقيات الداخلية ليست معرفة عامة ثابتة
النتيجة:
النموذج سيخمن. وبعض التخمينات ستكون خاطئة.
النهج الأفضل: تحقق محلي قابل للتكرار
اجعل الوكيل مسؤولًا عن توليد المسودة، واجعل CLI مسؤولًا عن التحقق.
# الوكيل يولد JSON
# لا يحتاج الوكيل إلى حفظ جميع القواعد
# CLI يتحقق من البنية
apidog cli-schema validate test-case-create --file ./test-case-create.json
# إذا ظهرت أخطاء، يعدّل الوكيل الملف بناءً عليها
# فقط الملفات الصالحة تصل إلى مرحلة الكتابة
apidog test-case create --project <projectId> --file ./test-case-create.json
بهذا الشكل:
- يقل حجم السياق المطلوب
- تصبح الأخطاء محددة وقابلة للإصلاح
- لا تُهدر طلبات الشبكة
- لا يدخل الوكيل في حلقات إعادة محاولة غير واضحة
تحويل المخطط: من معرفة إلى بوابة جودة
cli-schema validate يغيّر دور المخطط:
| قبل | بعد |
|---|---|
| المخطط = معرفة يجب على النموذج حفظها | المخطط = بوابة جودة يجب اجتيازها |
| الأخطاء تُكتشف عبر كتابات فاشلة | الأخطاء تُكتشف عبر تحقق محلي |
| إعادة المحاولة تتم عبر استدعاءات شبكة | الإصلاح يتم عبر تعديل محلي |
| عبء على السياق | بوابة تنفيذ |
بدل أن تُستهلك الأخطاء في طلبات شبكة ذهابًا وإيابًا، تصبح عملية الجودة خطوة محلية واضحة.
مثال عملي: إنشاء حالة اختبار بأمان
سير العمل التالي يوضح الاستخدام الكامل:
# 1. قراءة نقطة النهاية
apidog endpoint get <endpointId> --project <projectId>
# 2. الوكيل يولد ملف JSON لحالة الاختبار
# الناتج: ./test-case-create.json
# 3. التحقق قبل الكتابة
apidog cli-schema validate test-case-create --file ./test-case-create.json
إذا نجح التحقق:
apidog test-case create --project <projectId> --file ./test-case-create.json
إذا فشل التحقق، يمكن أن تكون المخرجات مثل:
خطأ: الحقل "assertions[0].comparator" يحتوي على قيمة غير صالحة "contains"
القيم الصالحة: equal, not_equal, greater, less, include, not_include, exists, not_exists
خطأ: الحقل "extractors[0].type" يحتوي على قيمة غير صالحة "global"
القيم الصالحة: globals, environment, collection, local
اقتراح: قم بإصلاح هذه الحقول وأعد التحقق قبل الكتابة.
عندها يتبع الوكيل حلقة بسيطة:
- يقرأ الأخطاء المحددة
- يحدد الحقول غير الصالحة
- يعدّل ملف JSON
- يعيد تشغيل التحقق
- يكتب إلى المشروع فقط عندما ينجح التحقق
النتيجة:
لا كتابات فاشلة. لا إعادة محاولات مرتبكة. لا توكنات مهدرة.
قاعدة تصميم أوسع
المبدأ لا يقتصر على cli-schema.
قسّم المسؤوليات بهذا الشكل:
| نوع القاعدة | مكان الانتماء |
|---|---|
| قواعد أسماء الحقول | cli-schema |
| قواعد قيم التعداد | cli-schema |
| قيود النوع | cli-schema |
| تسلسل سير العمل | SKILL |
| إرشادات الخطوة التالية | agentHints |
| تفكيك المهام | الوكيل |
الصيغة المختصرة:
القواعد الحتمية ← نظام هندسي
الحكم الدلالي ← الوكيل
قائمة تحقق للتطبيق
عند بناء سير عمل وكيل يكتب إلى API أو نظام حقيقي، استخدم هذه القائمة:
- هل يولّد الوكيل ملفًا وسيطًا قابلًا للفحص؟
- هل توجد خطوة تحقق محلية قبل الكتابة؟
- هل رسائل الخطأ قابلة للقراءة من قبل الوكيل؟
- هل يمكن للوكيل تعديل الملف وإعادة التحقق؟
- هل تُمنع الكتابة عند فشل التحقق؟
- هل القواعد الحتمية خارج الـ prompt قدر الإمكان؟
إذا كانت الإجابة “نعم”، فأنت تقلل اعتمادك على ذاكرة النموذج وتزيد موثوقية التنفيذ.
ماذا بعد؟
بعد التحقق، يظهر سؤال عملي جديد:
بعد أن يتأكد CLI من صحة البنية، كيف يوجه الوكيل إلى الخطوة التالية؟
في الجزء الرابع، agentHints: تعليم واجهات سطر الأوامر (CLIs) للتحدث إلى الوكلاء، سنستكشف كيف تحول المخرجات المنظمة مع اقتراحات الخطوة التالية CLI من منفذ أوامر إلى ملاح لسير العمل.
النقاط الرئيسية
- القواعد الحتمية يجب أن تعيش في التنفيذ، لا في سياق النموذج.
-
cli-schema validateيعمل كبوابة جودة قبل الكتابة. - أكثر الأخطاء شيوعًا: أسماء حقول خاطئة، تعدادات غير صالحة، وأنواع بيانات غير صحيحة.
- التحقق المحلي يقلل طلبات الشبكة الفاشلة وحلقات إعادة المحاولة.
- المخطط يتحول من “معرفة يجب حفظها” إلى “بوابة يجب اجتيازها”.
- الوكيل يولّد ويحكم دلاليًا، بينما CLI يتحقق حتميًا.
قم بتنزيل Apidog لـ تصميم، محاكاة، اختبار، وتوثيق واجهات برمجة التطبيقات في مساحة عمل واحدة. تعرّف على المزيد حول Apidog CLI لاختبار API عبر سطر الأوامر، وأتمتة CI، وسير عمل وكلاء الذكاء الاصطناعي.
Top comments (0)