مهارة: خبرة تشغيل الشحن ككود

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

المهارة (SKILL) ليست مجرد مرجع للأوامر. إنها دليل تشغيل لوكلاء الذكاء الاصطناعي: متى تستخدم أمرًا، وما يأتي أولاً، وما هي الحقول التي لا ينبغي تخمينها، ومتى يتم التحقق، ومتى يتم إعادة القراءة.

CLI وحده لا يكفي

تمنح أوامر CLI الوكيل قوة التنفيذ.

لكن القوة بدون حكم تؤدي إلى مشاكل:

يحتاج الوكلاء إلى أكثر من الأوامر. إنهم يحتاجون إلى حكم تشغيلي.

ما هي المهارة (SKILL)؟

المهارة (SKILL) هي دليل تشغيل مكتوب لوكلاء الذكاء الاصطناعي.

إنها ليست:

• قائمة أوامر بسيطة
• دليل مرجعي
• صفحة مساعدة

إنها:

تمنح المهارة (SKILL) الوكلاء حكمًا تشغيليًا.

التثبيت

المهارة (SKILL) هي رفيق لـ Apidog CLI:

# تثبيت SKILL لوكيل الذكاء الاصطناعي الخاص بك
apidog skill install

يقوم هذا بتثبيت 8 مهارات مصاحبة تساعد الوكلاء على فهم:

• دلالات أوامر CLI
• هياكل الموارد
• سير عمل المهام
• معالجة الأخطاء
• أنماط التحقق

لماذا تهم المهارة (SKILL): سير العمل المخفي

لا يزال الوكيل بحاجة إلى معرفة كيفية تقسيم المهام إلى تدفقات تنفيذية عبر الأعمال.

لا يمكن أن تكون هذه التجربة:

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

يتطلب سير العمل المخفي و"المزالق التجارية" توجيهًا صريحًا.

مثال: صيانة سيناريو الاختبار

فكر في صيانة سيناريو اختبار معقد.

النهج الخاطئ (الوكيل يكتب يدويًا من الصفر):

الوكيل: "سأقوم بإنشاء بنية سيناريو الاختبار يدويًا"
الوكيل: يكتب مجموعة خطوات كاملة مع تأكيدات ومستخرجات ومعالجات
النتيجة: أخطاء حقل، مقارنات خاطئة، حقول مطلوبة مفقودة
CLI: يرفض الكتابة أو ينشئ سيناريو غير مكتمل

النهج الصحيح (مشفّر في SKILL):

لا تقول المهارة (SKILL) فقط "هناك أمر test-scenario update".

بل تقول:

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

الأوامر وراء إرشادات المهارة (SKILL)

فيما يلي الأوامر الفعلية التي توجه المهارة (SKILL) الوكلاء لاستخدامها:

# الخطوة 1: استيراد الخطوات من نقاط النهاية
apidog test-scenario import-steps <scenarioId> --project <projectId> \
  --source endpoint --ids <endpointIds> --sync manual

# الخطوة 2: إعادة القراءة مع التفاصيل الكاملة
apidog test-scenario get <scenarioId> --project <projectId> \
  --with-case-detail

# الخطوة 3: تحديث أجزاء معينة (الوكيل ينشئ JSON التحديث)

# الخطوة 4: التحقق قبل التحديث
apidog cli-schema validate test-scenario-update --file ./scenario-update.json

# الخطوة 5: تنفيذ التحديث
apidog test-scenario update <scenarioId> --project <projectId> \
  --file ./scenario-update.json

# الخطوة 6: تشغيل التحقق
apidog run --project <projectId> --test-scenario <scenarioId>

تخبر المهارة (SKILL) الوكيل متى يستخدم كل أمر ولماذا.

فكرة رئيسية: get--with-case-detail

تؤكد المهارة (SKILL) على:

"استخدم get--with-case-detail للحصول على الهيكل الحقيقي، وليس تخيل الحالة داخل الخطوات."

لماذا هذا مهم:

الحصول على الهيكل الحقيقي يمنع التحديثات القائمة على التخيل.

قابلية التطور: يمكن للمهارة (SKILL) أن تتغير

Apidog SKILL هي خبرة تشغيلية قابلة للتطور والإصدار.

لماذا هذا مهم

كيف تعمل

يتم منح الوكلاء أذونات الكتابة للمهارة (SKILL).

إذا تخلفت المهارة (SKILL) أو أصبحت صعبة الاستخدام:

• يمكن للوكيل تعديلها
• يمكن للوكيل اقتراح تحسينات
• تتطور المهارة (SKILL) من خلال الاستخدام

المهارة (SKILL) ليست وثائق مجمدة. إنها رمز تشغيلي حي.

طبقة التوافق

لقد تعلمنا هذا من الأخطاء الحقيقية:

مشكلة تم اكتشافها:

بعض خطوات السيناريو، أثناء التحديثات الثانوية، تم تحديث الخطوات الخارجية بنجاح، لكن حالات HTTP الداخلية لم يتم تحديثها بشكل صحيح.

السبب الجذري:

• علامات تحديث الحالة الداخلية تتطلب معالجة خاصة
• الوكلاء لم يكونوا على علم بهذه العلامات
• تتطلب دلالات المنتج أعلامًا محددة

الحل:

• منطق التوافق موضوع في CLI
• يتعامل CLI مع العلامات الداخلية تلقائيًا
• لا يحتاج المستخدمون والوكلاء إلى معرفة التفاصيل الداخلية

يتم وضع معنى القيد في طبقة داخل SKILL:

تخبر المهارة (SKILL) الوكيل باستخدام الأوامر الصحيحة. يتعامل CLI مع دلالات المنتج وراء تلك الأوامر. لا يحتاج الوكيل إلى فهم العلامات الداخلية.

التحميل عند الطلب

تتبع المهارة (SKILL) نفس مبدأ cli-schema:

يجب أن يتم استيعاب التعقيد عن طريق التنفيذ والتوثيق، وليس عرضه بالكامل على النموذج.

نهج المهارة (SKILL):

• يقوم الوكيل بتنشيط المهارة (SKILL) عند الطلب
• يتم تحميل المهارة (SKILL) عند تحديد نوع المهمة
• تدخل إرشادات سير العمل ذات الصلة فقط في السياق

المهارة (SKILL) مقابل التوثيق

المهارات الثمانية المصاحبة

يوفر Apidog 8 مهارات مصاحبة:

تحتوي كل مهارة (SKILL) على:

• تحديد نوع المهمة
• إرشادات تسلسل الأوامر
• حدود أمان الحقل
• نقاط التحقق من الصحة
• أنماط التحقق

ماذا بعد؟

الآن بعد أن أنشأنا جميع المكونات الأساسية الثلاثة:

• cli-schema validate — بوابة الجودة
• agentHints — التنقل للخطوة التالية
• SKILL — حكم سير العمل

السؤال التالي هو:

هل هذا يعمل بالفعل؟ وما هي الأرقام؟

في الجزء السادس، الأرقام لا تكذب: مكالمات أدوات أقل بنسبة 30%، ورموز أقل بنسبة 25%، سنشارك النتائج الكمية من مقارناتنا الداخلية - ونشرح من أين تأتي التوفيرات.

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

• يمنح CLI قوة التنفيذ؛ وتمنح المهارة (SKILL) حكمًا تشغيليًا
• المهارة (SKILL) هي دليل تشغيل، وليست مرجعًا للأوامر
• يتطلب سير العمل المخفي توجيهًا صريحًا
• خطوات الاستيراد ← إعادة القراءة ← التحديث محليًا أكثر أمانًا من الكتابة اليدوية
• --with-case-detail يمنع التحديثات القائمة على التخيل
• المهارة (SKILL) قابلة للتطور — يمكن للوكلاء تعديلها
• يمتص CLI دلالات المنتج، وتوجه المهارة (SKILL) سير العمل
• التحميل عند الطلب يمنع عبء السياق

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