هذه سلسلة من 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 | "Spec-First" كان بالأمس. مرحبًا بك في "Skill-First". | الرؤية والمستقبل |
المهارة (SKILL) ليست مجرد مرجع للأوامر. إنها دليل تشغيل لوكلاء الذكاء الاصطناعي: متى يستخدم الوكيل أمرًا، بأي ترتيب، ما الحقول التي يجب ألا يخمنها، ومتى يتحقق أو يعيد القراءة أو يشغل الاختبارات.
لماذا CLI وحده لا يكفي
أوامر CLI تمنح الوكيل قدرة التنفيذ، لكنها لا تمنحه بالضرورة حكم التنفيذ.
مثال سريع:
| ما يستطيع CLI فعله | ما قد يحدث بدون إرشاد تشغيلي |
|---|---|
| إنشاء حالة اختبار | ينشئها في مشروع خاطئ |
| تحديث سيناريو اختبار | يحدثه دون قراءة النسخة الحالية |
| استيراد خطوات | يستورد دون فهم البنية الموجودة |
| تشغيل اختبارات | يشغلها دون التحقق من التغييرات |
لذلك، لا يكفي أن يعرف الوكيل الأمر. يجب أن يعرف:
- متى يستخدمه
- ما الذي يسبقه
- ما الذي يجب التحقق منه بعده
- ما الذي لا يجب تخمينه
هذا هو دور SKILL.
ما هي المهارة (SKILL)؟
المهارة (SKILL) هي دليل تشغيل مكتوب لوكلاء الذكاء الاصطناعي.
هي ليست:
- قائمة أوامر
- صفحة
--help - مرجعًا ثابتًا
بل هي طبقة توجيه تشرح للوكيل كيفية تنفيذ مهمة بأمان.
| ما توضحه SKILL | الهدف العملي |
|---|---|
| متى تستخدم أمرًا | ربط نوع المهمة بالأمر الصحيح |
| أي أمر يأتي أولًا | فرض تسلسل تنفيذ آمن |
| ما الحقول التي لا تُخمن | تقليل أخطاء البيانات |
| متى يتم التحقق | إضافة بوابة جودة قبل الكتابة |
| متى تتم إعادة القراءة | العمل على الحالة الفعلية لا المتخيلة |
| متى تشغل الاختبارات | تأكيد السلوك بعد التغيير |
بصيغة مختصرة:
CLI ينفذ.
SKILL توجه التنفيذ.
التثبيت
تعمل SKILL كرفيق لـ Apidog CLI.
لتثبيتها للوكيل:
# تثبيت SKILL لوكيل الذكاء الاصطناعي
apidog skill install
بعد التثبيت، يحصل الوكيل على 8 مهارات مصاحبة تساعده على فهم:
- دلالات أوامر CLI
- هياكل الموارد
- تسلسل سير العمل
- معالجة الأخطاء
- أنماط التحقق
الفكرة ليست تحميل كل التفاصيل في المحادثة دائمًا، بل تمكين الوكيل من استدعاء الإرشادات المناسبة عند الحاجة.
لماذا تحتاج الوكلاء إلى SKILL؟
عند بناء وكيل يستخدم CLI، تظهر مشكلة متكررة: الوكيل يعرف الأمر، لكنه لا يعرف سياق استخدامه داخل المنتج.
هذه المعرفة لا تصلح أن تكون:
- داخل وصف كل أداة، لأنها ستستهلك سياقًا كبيرًا
- داخل محادثة واحدة، لأنها تضيع بين الجلسات
- معتمدة على ذاكرة النموذج، لأنها معرفة خاصة بالمنتج
لذلك تحتاج إلى دليل تشغيل قابل للتحميل والتحديث.
مثال:
المهمة: تعديل سيناريو اختبار متعدد الخطوات
المطلوب من الوكيل:
1. لا يكتب البنية يدويًا من الصفر
2. يستورد الخطوات أو يقرأ البنية الحالية
3. يعيد قراءة السيناريو بالتفاصيل
4. يطبق تعديلًا محليًا صغيرًا
5. يتحقق من JSON قبل التحديث
6. يشغل السيناريو بعد التحديث
هذه ليست معلومات مرجعية فقط. إنها سياسة تنفيذ.
مثال عملي: صيانة سيناريو اختبار
لنفترض أن لديك سيناريو اختبار معقدًا يتكون من عدة خطوات، تأكيدات، مستخرجات، ومعالجات.
النهج الخاطئ
أن يقرر الوكيل كتابة البنية كاملة يدويًا:
الوكيل: "سأبني سيناريو الاختبار من الصفر"
النتيجة المحتملة:
- أسماء حقول غير صحيحة
- مقارنات assertion خاطئة
- حقول مطلوبة مفقودة
- بنية غير متوافقة مع ما يتوقعه CLI
هذا النهج هش، خصوصًا في السيناريوهات متعددة الخطوات.
النهج الصحيح
SKILL توجه الوكيل إلى مسار أكثر أمانًا:
| الخطوة | السبب |
|---|---|
| 1. استيراد الخطوات الموجودة من Endpoint أو Test Case | تجنب كتابة هياكل معقدة يدويًا |
| 2. إعادة قراءة السيناريو كاملًا | الحصول على الشكل الفعلي للبيانات |
| 3. تعديل جزء محدد فقط | تقليل نطاق الخطأ |
| 4. التحقق قبل التحديث | التقاط أخطاء JSON أو schema محليًا |
| 5. تشغيل السيناريو | التحقق من السلوك بعد التغيير |
SKILL لا تقول فقط:
استخدم
test-scenario update.
بل تقول:
لا تكتب سيناريو معقدًا من الصفر. استورد أو اقرأ البنية الحالية أولًا، ثم عدّل محليًا، ثم تحقق، ثم نفذ.
أوامر Apidog CLI في هذا السيناريو
هذا تسلسل عملي يمكن للوكيل اتباعه:
# 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. إنشاء ملف تحديث محلي
# مثال: ./scenario-update.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 تحدد متى يستخدم الوكيل كل أمر، وليس فقط ما هو الأمر.
قاعدة مهمة: استخدم --with-case-detail
تؤكد SKILL على هذه القاعدة:
استخدم
--with-case-detailللحصول على الهيكل الحقيقي، بدل أن يتخيل الوكيل تفاصيل الحالة داخل الخطوات.
بدون هذا الخيار، قد يرى الوكيل مراجع أو معرفات فقط. ومعه، يرى البنية الفعلية التي يمكنه التعديل عليها.
بدون --with-case-detail
|
مع --with-case-detail
|
|---|---|
| الخطوات قد تظهر كمعرفات فقط | تظهر تفاصيل الحالة كاملة |
| الوكيل يخمن التنسيق الداخلي | الوكيل يرى تنسيقًا حقيقيًا |
| احتمال أعلى لأسماء حقول خاطئة | احتمال أقل للتحديثات المتخيلة |
القاعدة العملية:
apidog test-scenario get <scenarioId> --project <projectId> --with-case-detail
استخدم الناتج كأساس لأي تعديل لاحق.
التحقق قبل التحديث
قبل أن يكتب الوكيل أي تغيير، يجب أن يمر عبر بوابة تحقق.
مثال:
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
إذا فشل التحقق، لا يجب تنفيذ update.
تسلسل آمن:
apidog cli-schema validate test-scenario-update --file ./scenario-update.json && \
apidog test-scenario update <scenarioId> --project <projectId> --file ./scenario-update.json
هذا يقلل أخطاء:
- الحقول المفقودة
- أنواع البيانات غير الصحيحة
- البنية غير المتوافقة
- التحديثات الناتجة عن تخمين النموذج
قابلية التطور: SKILL ليست وثيقة ثابتة
Apidog SKILL تمثل خبرة تشغيلية قابلة للتحديث والإصدار.
| التحدي | كيف تساعد SKILL |
|---|---|
| تغير أوامر CLI | يمكن تحديث SKILL لتعكس السلوك الجديد |
| وجود سير عمل مخصص | يمكن تخصيص SKILL حسب طريقة الفريق |
| إضافة ميزات جديدة | يمكن توسيع SKILL لتغطيتها |
| تحسينات في التنفيذ | يمكن تنقيح التعليمات بناءً على الاستخدام |
إذا أصبحت SKILL غير دقيقة أو ناقصة، يمكن للوكيل:
- تعديلها
- اقتراح تحسينات
- تحديث سير العمل بناءً على أخطاء فعلية
لذلك، SKILL أقرب إلى رمز تشغيلي حي منها إلى توثيق مجمد.
طبقة التوافق: ماذا يبقى داخل CLI؟
ليست كل التفاصيل يجب أن يعرفها الوكيل.
مثال من أخطاء واقعية:
في بعض تحديثات السيناريو، تم تحديث الخطوات الخارجية بنجاح، لكن حالات HTTP الداخلية لم تُحدث بالشكل الصحيح.
السبب:
- بعض علامات تحديث الحالة الداخلية تحتاج معالجة خاصة
- الوكلاء لم يكونوا على علم بهذه العلامات
- دلالات المنتج تتطلب أعلامًا محددة
الحل لم يكن تحميل هذه التفاصيل كلها في النموذج.
بدلًا من ذلك:
- CLI يتعامل مع منطق التوافق داخليًا
- SKILL تخبر الوكيل بالأمر الصحيح وتسلسل استخدامه
- الوكيل لا يحتاج إلى فهم العلامات الداخلية
التقسيم الأفضل للمسؤوليات:
SKILL: متى تستخدم الأمر؟ وبأي ترتيب؟
CLI: كيف ينفذ الأمر دلالات المنتج داخليًا؟
التحميل عند الطلب
تتبع SKILL نفس مبدأ cli-schema:
يجب أن يمتص التنفيذ والتوثيق التعقيد، لا أن يُعرض كله على النموذج في كل مرة.
| النهج | المشكلة |
|---|---|
| تحميل كل المهارات في السياق | استهلاك رموز كبير |
وضع كل القواعد في --help
|
صعوبة التركيز على المهمة الحالية |
| كتابة القواعد في prompt فقط | صعوبة التحديث وإعادة الاستخدام |
نهج SKILL:
- يحدد الوكيل نوع المهمة
- يحمّل المهارة المناسبة فقط
- تدخل تعليمات سير العمل ذات الصلة إلى السياق
- يبقى السياق أصغر وأكثر ارتباطًا بالمهمة
SKILL مقابل التوثيق
| التوثيق | SKILL |
|---|---|
| مصمم للبشر | مصمم للوكلاء |
| يشرح ما تفعله الأوامر | يشرح متى وكيف تُستخدم |
| مرجع ثابت غالبًا | سير عمل قابل للتطور |
| شامل | مركز على المهمة |
| خارجي عن الوكيل | مدمج في سير عمل الوكيل |
لا تستبدل SKILL التوثيق. لكنها تحول جزءًا من الخبرة التشغيلية إلى تعليمات قابلة للتنفيذ بواسطة الوكيل.
المهارات الثمانية المصاحبة
يوفر Apidog 8 مهارات مصاحبة:
| المهارة | ما تغطيه |
|---|---|
| إدارة المشاريع | المشاريع، البيانات الوصفية، الموارد |
| تصميم واجهة برمجة التطبيقات | نقاط النهاية، المخططات، التعريفات |
| إدارة البيئة | البيئات، المتغيرات |
| إنشاء حالة الاختبار | اختبارات نقطة نهاية واحدة، التأكيدات |
| إدارة سيناريو الاختبار | اختبارات متعددة الخطوات، الاستيراد، التحديث |
| تنظيم مجموعة الاختبار | التجميع، التنفيذ |
| سير عمل الاستيراد/التصدير | ترحيل البيانات، النسخ الاحتياطي |
| تكامل CI/CD | أوامر خط الأنابيب، التقارير |
كل مهارة تحتوي عادةً على:
- طريقة تحديد نوع المهمة
- تسلسل الأوامر المناسب
- حدود أمان الحقول
- نقاط التحقق
- أنماط التأكيد بعد التنفيذ
نمط تنفيذ موصى به للوكلاء
عند بناء وكيل يستخدم Apidog CLI، استخدم هذا النمط:
1. حدد نوع المهمة
2. فعّل SKILL المناسبة
3. اقرأ الحالة الحالية من CLI
4. لا تخمن الحقول غير الظاهرة
5. أنشئ ملف تغيير محلي
6. تحقق من الملف باستخدام cli-schema validate
7. نفذ التحديث
8. أعد القراءة أو شغّل الاختبار للتأكيد
مثال عملي مختصر:
# اقرأ الحالة الفعلية
apidog test-scenario get <scenarioId> --project <projectId> --with-case-detail
# تحقق من التعديل
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
# اكتب التعديل
apidog test-scenario update <scenarioId> --project <projectId> --file ./scenario-update.json
# تحقق من السلوك
apidog run --project <projectId> --test-scenario <scenarioId>
هذا هو الفرق بين وكيل "يعرف أوامر" ووكيل "ينفذ سير عمل آمن".
ماذا بعد؟
حتى الآن، أصبح لدينا ثلاث طبقات أساسية:
-
cli-schema validate— بوابة جودة قبل الكتابة -
agentHints— إرشاد للخطوة التالية -
SKILL— حكم تشغيلي لسير العمل
السؤال التالي:
هل هذا يقلل فعلًا عدد مكالمات الأدوات والرموز؟
في الجزء السادس، الأرقام لا تكذب: مكالمات أدوات أقل بنسبة 30%، ورموز أقل بنسبة 25%، سنعرض النتائج الكمية من مقارناتنا الداخلية ونوضح مصدر التوفير.
النقاط الرئيسية
- CLI يمنح الوكيل القدرة على التنفيذ؛ SKILL تمنحه الحكم التشغيلي.
- SKILL ليست مرجع أوامر، بل دليل تشغيل.
- سير العمل المخفي يحتاج تعليمات صريحة.
- مسار الاستيراد ← إعادة القراءة ← التعديل المحلي أكثر أمانًا من الكتابة اليدوية.
- استخدام
--with-case-detailيقلل التحديثات المبنية على التخمين. -
cli-schema validateيجب أن يسبق أي تحديث مهم. - CLI يمتص دلالات المنتج الداخلية، وSKILL توجه سير العمل.
- التحميل عند الطلب يقلل عبء السياق على النموذج.
- SKILL قابلة للتحديث والتخصيص مع تطور المنتج وسير العمل.
قم بتنزيل Apidog من أجل تصميم، محاكاة، اختبار، و توثيق واجهات برمجة التطبيقات في مساحة عمل واحدة. تعلم المزيد عن Apidog CLI لاختبار واجهات برمجة التطبيقات عبر سطر الأوامر، وأتمتة CI، وسير عمل وكلاء الذكاء الاصطناعي.
Top comments (0)