القاعدة الذهبية: CLI تولد الحقائق، النموذج يطبق الحقائق

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

لا تجعل النموذج يحفظ جميع القواعد — دع القواعد تُنفذ في الأماكن الصحيحة. تحول cli-schema validate المخطط من معرفة إلى بوابة جودة.

المبدأ الأساسي: دع القواعد تُنفذ في الأماكن الصحيحة.

لقد استخلصنا مبدأً أساسيًا واحدًا من تجربتنا:

لا تجعل النموذج يحفظ جميع القواعد. دع القواعد تُنفذ في الأماكن الصحيحة.

هذا يشبه درسًا مستفادًا من تقييم الوكيل:

في Apidog CLI + SKILL:

دع CLI تتحقق من البنية. دع الوكلاء يولدون المحتوى.

مشكلة ذاكرة النموذج

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

الجزء الخطير هو كتابة المحتوى الذي تم توليده في مشروع حقيقي دون بنية أو تحقق كافيين.

موارد Apidog منظمة. فكر فيما يتضمنه حالة اختبار أو سيناريو اختبار:

إذا خمن الوكيل البنية:

• اسم حقل خاطئ ← فشل الكتابة
• قيمة تعداد غير صالحة ← رفض الخادم
• حقل إلزامي مفقود ← مورد غير مكتمل
• نوع خاطئ ← مشاكل في عرض واجهة المستخدم
• تداخل غير صحيح ← الاختبارات لا تعمل كما هو متوقع

cli-schema validate: بوابة الجودة

التجسيد الأكثر مباشرة لمبدئنا هو cli-schema validate.

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

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

يقوم أمر validate بما يلي:

• يؤكد أسماء الحقول
• يتحقق من صحة البنية
• يتحقق من فعالية قيم التعداد
• يتحقق من قيود النوع

كل ذلك قبل بدء طلب الكتابة.

الأخطاء الشائعة التي يلتقطها cli-schema

فيما يلي أمثلة حقيقية لأخطاء يرتكبها الوكلاء عادةً — ويلتقطها cli-schema validate:

هذه ليست نظرية. اكتشفناها من خلال تفاعلات الوكلاء الحقيقية.

كل خطأ كان سيسبب:

• فشل طلب الكتابة
• استجابة خطأ من API
• ارتباك الوكيل حول الخطأ الذي حدث
• محاولات إعادة متعددة
• إهدار الرموز (Tokens) في المكالمات المتكررة

باستخدام cli-schema validate، يتم اكتشاف هذه الأخطاء محليًا، قبل استدعاء الشبكة.

فلسفة التصميم

دعونا ننظر في البدائل:

البديل الأول: كتابة القواعد في التوجيه (Prompt)

إذا كتبنا جميع قواعد الحقول في توجيه الوكيل:

• توثيق كل اسم حقل
• سرد كل قيمة تعداد
• شرح كل قيد نوع
• وصف كل بنية متداخلة

النتيجة: عبء سياقي هائل.

يمكن أن يتطلب مخطط سيناريو الاختبار الشامل بسهولة أكثر من 5000 رمز وصفي (tokens). وهذا هو السياق الذي يجب أن يحمله النموذج لكل مهمة، حتى عندما لا تكون معظم القواعد ذات صلة.

البديل الثاني: الاعتماد على ذاكرة النموذج

إذا اعتمدنا على النموذج "ليعرف" البنية الصحيحة:

• نموذج مدرب على بعض أنماط API
• ولكن ليس على مخططات Apidog تحديدًا
• تختلف أسماء الحقول عبر المنتجات
• قيم التعداد خاصة بالمنتج

النتيجة: معدلات خطأ عالية.

النموذج لا يمتلك ذاكرة مثالية للاتفاقيات الخاصة بـ Apidog. سيخمن — والتخمينات ستكون خاطئة.

نهج أفضل: التحقق محليًا

دع الوكيل يولد المسودات. دع CLI ينفذ التحقق قبل الكتابة.

# الوكيل يولد JSON
# (الوكيل لا يحتاج لحفظ جميع القواعد)

# CLI يتحقق
apidog cli-schema validate test-case-create --file ./test-case-create.json

# CLI يخرج أخطاء محددة إن وجدت
# الوكيل يعدل بناءً على الأخطاء

# فقط عمليات الكتابة الصالحة تستمر
apidog test-case create --project <projectId> --file ./test-case-create.json

تحويل المخطط (Schema Transformation)

cli-schema validate يحول معنى المخطط:

لا يتم استهلاك المشكلات في طلبات الشبكة عديمة المعنى ذهابًا وإيابًا.

يتم إتمام فحوصات الجودة عبر الأوامر المحلية.

مثال عملي

دعونا نستعرض سير عمل حقيقي:

# الوكيل يقرأ نقطة النهاية
apidog endpoint get <endpointId> --project <projectId>

# الوكيل يولد JSON لحالة الاختبار
# (ينشئ ./test-case-create.json)

# التحقق قبل الكتابة
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

اقتراح: قم بإصلاح هذه الحقول وأعد التحقق قبل الكتابة.

الوكيل:

1. يقرأ الأخطاء المحددة
2. يفهم بالضبط ما هو الخطأ
3. يعدل ملف JSON
4. يعيد تشغيل التحقق
5. يستمر فقط عندما يكون صالحًا

لا توجد كتابات فاشلة. لا توجد محاولات إعادة مرتبكة. لا توجد رموز مهدرة (wasted tokens).

الدرس الأوسع

يمتد هذا المبدأ إلى ما هو أبعد من التحقق.

القواعد الحتمية ← نظام هندسي

الحكم الدلالي ← الوكيل

ماذا بعد

الآن بعد أن وضعنا مبدأ التحقق، السؤال التالي هو:

بعد التحقق، كيف يوجه CLI الوكيل إلى الخطوة التالية؟

في الجزء الرابع، agentHints: تعليم واجهات سطر الأوامر (CLIs) للتحدث إلى الوكلاء، سنستكشف كيف تحول المخرجات المنظمة مع اقتراحات الخطوة التالية CLI من منفذ أوامر إلى ملاح لسير العمل.

النقاط الرئيسية المستفادة

• المبدأ الأساسي: القواعد تنتمي إلى التنفيذ، وليس إلى السياق
• cli-schema validate هي بوابة الجودة قبل الكتابة
• الأخطاء الشائعة: أسماء حقول خاطئة، تعدادات غير صالحة، أنواع خاطئة
• التحقق يكتشف الأخطاء محليًا، مما يوفر رحلات الشبكة ذهابًا وإيابًا
• المخطط يتحول من "معرفة للحفظ" إلى "بوابة للمرور"
• القواعد الحتمية ← الهندسة؛ الحكم الدلالي ← الوكيل

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