هذه سلسلة من 10 أجزاء تشرح كيف طوّرت Apidog أداة Apidog CLI، وهي أداة سطر أوامر لاختبار واجهات برمجة التطبيقات وإدارة دورة حياتها. يمكنك القراءة بالترتيب أو الانتقال مباشرة إلى الجزء الذي تحتاجه:
| العنوان | التركيز | |
|---|---|---|
| 1 | بنينا 126 أداة MCP. لكنها ليست الحل الأفضل للوكيل | اكتشاف المشكلة |
| 2 | لماذا طورنا Apidog CLI جديدة تمامًا | تطوير المعمارية |
| 3 | القاعدة الذهبية: CLI تنتج الحقائق، والنموذج يتصرف بناءً على الحقائق | الفلسفة الأساسية |
| 4 | `agentHints`: تعليم واجهات سطر الأوامر للتحدث إلى الوكلاء | الناتج المنظم |
| 5 | المهارة: شحن الخبرة التشغيلية ككود | الخبرة التشغيلية |
| 6 | الأرقام لا تكذب: 30% مكالمات أدوات أقل، 25% رموز أقل | النتائج الكمية |
| 7 | من PRD إلى حلقة الاختبار: سير عمل وكيل كامل مع Apidog CLI | دليل عملي |
| 8 | لماذا لا يمكن التنازل عن توافق CI/CD لأدوات الوكلاء | منظور DevOps |
| 9 | فرع الذكاء الاصطناعي: تغييرات مشروع أكثر أمانًا مع وكلاء الذكاء الاصطناعي | طبقة الأمان |
| 10 | Spec-First كان بالأمس. مرحباً بك في Skill-First. | الرؤية والمستقبل |
عندما يقوم الوكيل بتعديل موارد المشروع، لا يكفي أن يعمل الأمر بنجاح. يجب أن تكون التغييرات معزولة، قابلة للمراجعة، ولا تصل إلى الفرع المستهدف إلا بعد تأكيد بشري. هنا يأتي دور فرع الذكاء الاصطناعي.
تحدي الأمان
عند إدخال وكلاء الذكاء الاصطناعي في تطوير واختبار واجهات برمجة التطبيقات، يمكنهم استخدام CLI لإنشاء وتحديث وحذف موارد مثل:
- نقاط النهاية
- المخططات
- سيناريوهات الاختبار
- مجموعات الاختبار
- التوثيق والحقول الوصفية
هذه القدرة مفيدة، لكنها تفتح مخاطر مباشرة على المشروع.
| المخاطر | ما الذي قد يحدث؟ |
|---|---|
| مخرجات غير متوقعة | الوكيل يكتب محتوى أو بنية غير مقصودة |
| أخطاء في الحقول | تأكيدات خاطئة، معلمات مفقودة، أو مخططات غير صالحة |
| توسع النطاق | الوكيل يعدل موارد خارج المهمة المطلوبة |
| غياب سجل مراجعة واضح | التغييرات تظهر مباشرة في الفرع الرئيسي |
| تعطيل الفريق | فرع التعاون المشترك يتغير فجأة أثناء عمل الفريق |
السؤال العملي هو:
كيف تسمح للوكلاء بالعمل على مشروع حقيقي دون السماح لهم بالكتابة مباشرة إلى الفرع الرئيسي؟
فرع الذكاء الاصطناعي: طبقة الأمان
فرع الذكاء الاصطناعي هو نوع خاص من فروع السبرنت مصمم لعمليات الذكاء الاصطناعي وعمليات CLI الخارجية.
الفكرة الأساسية:
أي عملية تعديل تبدأ من Apidog CLI تُعامل افتراضيًا كعملية بدأت بواسطة الذكاء الاصطناعي أو وكيل ذكاء اصطناعي.
بدل أن يكتب الوكيل مباشرة إلى main، يكتب إلى فرع معزول:
الوكيل يجري تغييرات عبر CLI
↓
التغييرات تُحفظ في فرع الذكاء الاصطناعي
↓
المستخدم يراجع الفروقات
↓
المستخدم يؤكد نطاق الموارد
↓
الدمج مع الفرع المستهدف
الفرع الرئيسي يبقى دون تغيير حتى توافق أنت.
لماذا تحتاج إلى فرع الذكاء الاصطناعي؟
لأن تعديلات الذكاء الاصطناعي قد تكون صحيحة جزئيًا لكنها غير مناسبة للإدخال الفوري إلى المشروع.
مثال: قد يضيف الوكيل نقطة نهاية صحيحة، لكنه:
- يضعها في مجلد غير مناسب
- ينسى نموذج الاستجابة
- يضيف اختبارًا غير مكتمل
- يغير وصفًا موجودًا بطريقة غير مرغوبة
- يعدل موارد لم تطلبها منه
فرع الذكاء الاصطناعي يحول هذه التعديلات إلى تغييرات قابلة للمراجعة قبل الدمج.
| بدون فرع الذكاء الاصطناعي | مع فرع الذكاء الاصطناعي |
|---|---|
| الوكيل يكتب مباشرة إلى الفرع الرئيسي | الوكيل يكتب إلى فرع معزول |
| التغييرات تظهر فورًا | التغييرات تنتظر المراجعة |
| لا توجد شبكة أمان | تأكيد بشري مطلوب |
| خطر تعديلات غير مقصودة | نطاق الدمج يمكن تحديده صراحة |
ما هو فرع الذكاء الاصطناعي؟
فرع الذكاء الاصطناعي هو فرع سبرنت خاص لعمليات التحرير الخارجية القادمة من CLI/MCP.
الخصائص الرئيسية
| الخاصية | الوصف |
|---|---|
| تحرير معزول | التغييرات تُحفظ في فرع الذكاء الاصطناعي ولا تؤثر على الفرع الرئيسي أو فرع المصدر |
| مصدر واضح | لا يتم إنشاؤه من العميل؛ يجب أن يأتي من CLI/MCP مع تسجيل فرع المصدر |
| تأكيد بشري | لا يتم الدمج إلا بعد مراجعة وتأكيد من المستخدم |
| لا يوجد حد للكمية | يمكن إنشاء عدة فروع ذكاء اصطناعي لمهام مختلفة |
| أرشفة تلقائية | الفروع التي لا تحتوي على اختلافات تُؤرشف كل 24 ساعة |
كيف يعمل عمليًا؟
| العملية | أين تحدث؟ |
|---|---|
| الذكاء الاصطناعي ينشئ نقطة نهاية | داخل فرع الذكاء الاصطناعي |
| الذكاء الاصطناعي يحدث سيناريو اختبار | داخل فرع الذكاء الاصطناعي |
| الفريق يراجع التغييرات | من العميل أو عبر معاينة CLI |
| المستخدم يوافق على الدمج | إجراء بشري، وليس إجراءً من الوكيل |
| التغييرات تدخل الفرع المستهدف | بعد التأكيد فقط |
التحرير العادي من داخل عميل Apidog بواسطة المستخدمين يستمر في اتباع أذونات أعضاء المشروع وقواعد حماية الفروع.
حالات الاستخدام المناسبة
استخدم فرع الذكاء الاصطناعي عندما تريد من الوكيل تعديل المشروع مع إبقاء التغييرات قابلة للمراجعة.
| السيناريو | كيف يساعد فرع الذكاء الاصطناعي؟ |
|---|---|
| إنشاء مسودات API من الكود | الوكيل ينشئ نقاط نهاية في فرع منفصل، ثم يراجعها الفريق قبل الدمج |
| تنظيم موارد API بكميات كبيرة | تعديل المجلدات والأوصاف والنماذج دون التأثير على فرع التعاون |
| إنشاء مسودات اختبار تلقائية | إنتاج سيناريوهات أو حالات اختبار لمراجعتها من المختبرين |
| سد ثغرات وثائق API | إكمال الحقول الناقصة بناءً على التنفيذ أو تقارير الأخطاء |
| الكتابة المجمعة في CI/CD | تكتب مهام سير العمل التلقائية إلى فرع ذكاء اصطناعي وتنتظر دمج المستخدم |
سير العمل الأساسي
سير العمل الموصى به:
1. إنشاء فرع ذكاء اصطناعي من الفرع المستهدف
2. استيراد الموارد الموجودة عند الحاجة
3. جعل الوكيل يكتب التغييرات إلى فرع الذكاء الاصطناعي فقط
4. التحقق من الملفات قبل الكتابة
5. معاينة الفروقات
6. دمج الموارد المحددة أو إنشاء طلب دمج
7. تشغيل الاختبارات بعد الدمج
8. أرشفة الفرع
وبشكل أوضح:
┌──────────────────────────────────────────────────────────────┐
│ سير عمل فرع الذكاء الاصطناعي │
├──────────────────────────────────────────────────────────────┤
│ 1. إنشاء فرع الذكاء الاصطناعي │
│ apidog branch create --type ai --from main │
│ │
│ 2. استيراد موارد موجودة أو إنشاء موارد جديدة │
│ apidog branch pick-to │
│ أو │
│ apidog endpoint create │
│ │
│ 3. الوكيل يعدل الموارد عبر CLI │
│ باستخدام --branch لتحديد فرع الذكاء الاصطناعي │
│ │
│ 4. المستخدم يراجع الفروقات │
│ apidog merge-request preview │
│ │
│ 5. الدمج │
│ branch merge أو merge-request create │
└──────────────────────────────────────────────────────────────┘
إنشاء فرع للذكاء الاصطناعي
استخدم branch create --type ai:
apidog branch create \
--project 123456 \
--type ai \
--name "ai/20260312-from-main-userRegister" \
--from main
توصية التسمية:
ai/YYYYMMDD-from-sourceBranch-featureOrModule
مثال:
ai/20260312-from-main-userRegister
ai/20260312-from-dev-paymentTests
ai/20260312-from-main-orderDocs
أوامر مفيدة:
| الأمر | الغرض |
|---|---|
branch create --type ai |
إنشاء فرع ذكاء اصطناعي |
branch list --type ai |
عرض فروع الذكاء الاصطناعي في المشروع |
branch list --type all |
عرض جميع أنواع الفروع |
branch get --type ai |
عرض تفاصيل فرع الذكاء الاصطناعي |
تحرير الموارد في فرع الذكاء الاصطناعي
عند إنشاء أو تحديث موارد المشروع عبر CLI، استخدم --branch دائمًا لتوجيه الكتابة إلى فرع الذكاء الاصطناعي.
| المورد | مثال على الأمر |
|---|---|
| نقطة نهاية HTTP | apidog endpoint create --project <id> --branch <aiBranchName> --file ./endpoint.json |
| نموذج البيانات | apidog schema update <schemaId> --project <id> --branch <aiBranchName> --file ./schema.json |
| سيناريو الاختبار | apidog test-scenario update <scenarioId> --project <id> --branch <aiBranchName> --file ./scenario.json |
| مجموعة الاختبار | apidog test-suite create --project <id> --branch <aiBranchName> --file ./suite.json |
سير عمل آمن قبل الكتابة:
# 1. الحصول على مخطط الأمر
apidog cli-schema get endpoint-create
# 2. التحقق من ملف الإدخال قبل الكتابة
apidog cli-schema validate endpoint-create --file ./endpoint.json
# 3. الكتابة إلى فرع الذكاء الاصطناعي، وليس main
apidog endpoint create \
--project 123456 \
--branch "ai/20260312-from-main-userRegister" \
--file ./endpoint.json
الفكرة هنا بسيطة:
تحقق محليًا ← اكتب إلى فرع معزول ← راجع ← ادمج
استيراد الموارد الموجودة قبل تعديلها
إذا كان الوكيل سيعدل موارد موجودة، استوردها من فرع المصدر إلى فرع الذكاء الاصطناعي أولًا:
apidog branch pick-to \
--project 123456 \
--from main \
--to "ai/20260312-from-main-userRegister" \
--endpoint-ids 1001,1002
هذا يمنع الوكيل من العمل على نسخة غير صحيحة أو ناقصة من المورد.
استخدم هذا النمط عندما تريد:
- تعديل نقطة نهاية موجودة
- تحديث مخطط مستخدم بالفعل
- إضافة اختبارات لمورد موجود
- تحسين التوثيق الحالي
مراجعة التغييرات قبل الدمج
قبل الدمج، عاين الفروقات:
apidog merge-request preview \
--project 123456 \
--from "ai/20260312-from-main-userRegister" \
--to main
يمكنك أيضًا مراجعة الفروقات الكاملة من عميل Apidog.
| الأمر | الغرض |
|---|---|
merge-request preview |
فحص التغييرات المرشحة قبل الدمج |
branch get --type ai |
عرض معلومات فرع الذكاء الاصطناعي |
قائمة مراجعة سريعة قبل الدمج:
[ ] هل الموارد المعدلة ضمن نطاق المهمة؟
[ ] هل أسماء المجلدات والنماذج صحيحة؟
[ ] هل المخططات متوافقة مع التنفيذ؟
[ ] هل الاختبارات قابلة للتشغيل؟
[ ] هل توجد تبعيات يجب دمجها معًا؟
دمج فرع الذكاء الاصطناعي
بعد المراجعة، لديك خياران: دمج مباشر أو طلب دمج.
الدمج المباشر لفرع غير محمي
apidog branch merge \
--project 123456 \
--from "ai/20260312-from-main-userRegister" \
--to main \
--endpoint-ids 1001,1002
إنشاء طلب دمج لفرع محمي
apidog merge-request create \
--project 123456 \
--from "ai/20260312-from-main-userRegister" \
--to main \
--reviewer-ids 20001,20002 \
--endpoint-ids 1001,1002
| الأمر | الغرض |
|---|---|
branch merge |
دمج مباشر عندما يكون الفرع غير محمي |
merge-request create |
إنشاء طلب دمج للمراجعة |
merge-request approve |
الموافقة على طلب الدمج |
merge-request reject |
رفض طلب الدمج |
مهم: أوامر الدمج تعالج فقط الموارد التي تحددها صراحة. تأكد من دمج التبعيات المرتبطة، مثل:
- الدلائل
- النماذج
- مكونات الاستجابة
- سيناريوهات الاختبار
- مجموعات الاختبار
الأرشفة والحذف
بعد الدمج أو عند التخلي عن الفرع، أرشفه للحفاظ على قائمة الفروع نظيفة:
apidog branch archive "ai/20260312-from-main-userRegister" \
--project 123456 \
--type ai
إذا احتجت إلى الحذف بعد الأرشفة:
apidog branch delete "ai/20260312-from-main-userRegister" \
--project 123456 \
--type ai
أذونات التحرير الخارجية للذكاء الاصطناعي
افتراضيًا، يكتب CLI إلى فرع الذكاء الاصطناعي. هذا يحافظ على عزل التغييرات حتى يراجعها المستخدم.
لتمكين التحرير المباشر، استخدم إعدادات المشروع:
إعدادات المشروع
← إعدادات الميزات
← إعدادات ميزات الذكاء الاصطناعي
← أذونات تحرير الذكاء الاصطناعي الخارجي
| الإذن | ماذا يسمح به؟ |
|---|---|
| التحرير المباشر للفرع الرئيسي | يسمح لـ CLI بالكتابة مباشرة إلى الفرع الرئيسي وتجاوز فرع الذكاء الاصطناعي |
| التحرير المباشر لفرع السبرنت القياسي | يسمح لـ CLI بالكتابة مباشرة إلى فروع السبرنت |
| التحرير المباشر للفرع العام | يسمح لـ CLI بالكتابة مباشرة إلى الفروع العامة |
| التحرير المباشر لفرع الذكاء الاصطناعي | يسمح لـ CLI بالكتابة إلى فروع الذكاء الاصطناعي، وغالبًا يُترك مفعّلًا |
التوصية: أبقِ عزل فرع الذكاء الاصطناعي مفعّلًا. لا تفعّل التحرير المباشر إلا عندما يكون لديك سبب تشغيلي واضح، مثل سير عمل CI/CD مضبوط ومراجع.
أفضل الممارسات
| الممارسة | السبب |
|---|---|
| فرع ذكاء اصطناعي واحد لكل مهمة | يجعل النطاق واضحًا: تسجيل المستخدم، وثائق الطلبات، اختبارات الدفع |
| استيراد الموارد قبل تعديلها | استخدم pick-to للموارد الموجودة لتجنب العمل على مصدر خاطئ |
| التحقق قبل الكتابة | استخدم cli-schema validate لاكتشاف أخطاء البنية مبكرًا |
| المعاينة قبل الدمج | استخدم merge-request preview أو عرض الفروقات في العميل |
| تحديد نطاق الدمج صراحة | ادمج نقاط النهاية والنماذج والدلائل والاختبارات المرتبطة معًا |
| الإبقاء على المراجعة البشرية | تعريفات API ونصوص الاختبار يجب أن تُراجع قبل دخولها الفرع المستهدف |
| الأرشفة بعد الانتهاء | تحافظ على قائمة الفروع واضحة بعد الدمج أو التخلي عن المهمة |
فرع الذكاء الاصطناعي في سير عمل CLI + SKILL
يتكامل فرع الذكاء الاصطناعي مع سير عمل CLI + SKILL بهذه الصورة:
| المرحلة | CLI + SKILL + فرع الذكاء الاصطناعي |
|---|---|
| القراءة |
endpoint get من أي فرع |
| الإنشاء | الوكيل ينشئ ملفات JSON |
| التحقق |
cli-schema validate محليًا |
| الكتابة |
endpoint create --branch <aiBranchName> إلى فرع الذكاء الاصطناعي |
| المراجعة | merge-request preview |
| الدمج | المستخدم يؤكد، ثم يستخدم branch merge
|
| التحقق النهائي |
apidog run على الموارد المدمجة |
القاعدة التشغيلية:
كل كتابة من الوكيل
← فرع ذكاء اصطناعي
← مراجعة بشرية
← دمج
← اختبار
ملخص الأمان
| الطبقة | الحماية |
|---|---|
cli-schema validate |
يكتشف أخطاء البنية قبل الكتابة |
agentHints |
يوجه الوكيل إلى الخطوات الآمنة التالية |
| فرع الذكاء الاصطناعي | يعزل التغييرات عن الفرع الرئيسي |
| المراجعة البشرية | تؤكد المحتوى قبل الدمج |
| نطاق الدمج | يحدد المستخدم الموارد التي تدخل الفرع المستهدف |
معًا، تخلق هذه الطبقات حلقة أكثر أمانًا لتغييرات المشروع التي ينفذها الوكيل.
مثال عملي مختصر
سيناريو: تريد من وكيل ذكاء اصطناعي إنشاء نقطة نهاية لتسجيل المستخدم، لكنك لا تريد تعديل main مباشرة.
# 1. إنشاء فرع ذكاء اصطناعي
apidog branch create \
--project 123456 \
--type ai \
--name "ai/20260312-from-main-userRegister" \
--from main
# 2. التحقق من ملف نقطة النهاية
apidog cli-schema validate endpoint-create \
--file ./endpoint.json
# 3. إنشاء نقطة النهاية داخل فرع الذكاء الاصطناعي
apidog endpoint create \
--project 123456 \
--branch "ai/20260312-from-main-userRegister" \
--file ./endpoint.json
# 4. معاينة الفروقات
apidog merge-request preview \
--project 123456 \
--from "ai/20260312-from-main-userRegister" \
--to main
# 5. الدمج بعد المراجعة
apidog branch merge \
--project 123456 \
--from "ai/20260312-from-main-userRegister" \
--to main \
--endpoint-ids 1001
هذا يحافظ على main مستقرًا حتى تنتهي من المراجعة.
ماذا بعد؟
مع فرع الذكاء الاصطناعي، أصبحت طبقة الأمان موجودة ضمن سير العمل الكامل:
- MCP للاتصال بالأداة، الجزء 1
- CLI + SKILL لتنفيذ سير العمل، الأجزاء 2-5
- نتائج التحقق، الجزء 6
- مهام سير العمل العملية، الجزء 7
- أساس CI/CD، الجزء 8
- فرع الذكاء الاصطناعي للسلامة، الجزء 9
الخطوة التالية هي الرؤية الأوسع.
في الجزء 10، Spec-First كان بالأمس. مرحباً بك في Skill-First.، سنوضح كيف يتغير تطوير واجهات برمجة التطبيقات مع وكلاء الذكاء الاصطناعي، وما الذي يجب على الفرق فعله بعد ذلك.
النقاط الرئيسية
- فرع الذكاء الاصطناعي يوفر تحريرًا معزولًا لعمليات AI/CLI.
- التغييرات لا تؤثر على الفرع الرئيسي حتى يؤكدها مستخدم بشري.
- أنشئ الفرع باستخدام
branch create --type ai. - اكتب إلى الفرع باستخدام المعلمة
--branch. - استورد الموارد الموجودة باستخدام
branch pick-toقبل تعديلها. - راجع الفروقات باستخدام
merge-request preview. - ادمج مباشرة أو أنشئ طلب دمج حسب حماية الفرع.
- استخدم أذونات التحرير المباشر بحذر لأنها قد تتجاوز العزل.
- أفضل نمط تشغيلي: فرع واحد لكل مهمة، تحقق قبل الكتابة، مراجعة قبل الدمج.
قم بتنزيل Apidog من أجل تصميم، محاكاة، اختبار، و توثيق واجهات برمجة التطبيقات في مساحة عمل واحدة. تعرف على المزيد حول Apidog CLI لاختبار واجهات برمجة التطبيقات عبر سطر الأوامر، وأتمتة CI، وسير عمل وكلاء الذكاء الاصطناعي.
Top comments (0)