كيفية تحديث مواصفات API بواسطة وكيل AI باستخدام Apidog CLI

تحرير مواصفات واجهة برمجة التطبيقات (API) يدوياً عمل دقيق وصعب. أعد تسمية حقل، أضف قيمة تعداد (enum)، شدّد على علامة مطلوبة. كل تغيير صغير، لكن يجب أن يستقر كل منها في مكانه الصحيح دون كسر نقاط النهاية (endpoints) التي تشير إليه. إنه دقيق وميكانيكي، وبالضبط نوع المهمة التي قد تسندها إلى وكيل ذكاء اصطناعي، لو فقط كان بإمكانك الوثوق به لعدم تدمير المخطط بأكمله.

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

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

ماذا يعني "تحديث المواصفات" في واجهة سطر الأوامر (CLI)

مواصفاتك في Apidog هي مجموعة نقاط النهاية ومخططات البيانات في مشروع. تحديثها يعني أحد الأوامر الثلاثة التالية:

• endpoint update: تغيير مسار، معامل، أو استجابة.
• schema update: تغيير نموذج بيانات تشير إليه نقاط النهاية.
• import: جلب ملف OpenAPI جديد بالكامل للمطابقة مع المشروع.

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

الخطأ الذي سيلحق بك الضرر: التحديث هو استبدال كامل

هذا هو أهم شيء يجب أن تعلمه لوكيلك. أوامر update في واجهة سطر الأوامر (CLI) ليست JSON Patch. إنها ترسل الحقول التي توفرها مباشرة؛ ولا تدمج عناصر المصفوفة بواسطة المعرف (ID). إذا أرسلت تحديثًا بمصفوفة parameters جزئية بقصد تغيير معلم واحد، فأنت لا تقوم بتحرير هذا المعامل. أنت تستبدل المصفوفة بأكملها بالمعامل الذي أرسلته فقط، ويختفي الباقي.

The correct sequence is always read-modify-write on the complete object:

# 1. Get the full current resource
apidog endpoint get <endpointId> --project <projectId>

# 2. Edit the complete structure locally (keep every field you're not changing)

# 3. Validate the whole object against the schema
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. Write the complete object back
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json

ضع هذا في تعليمات الوكيل بعبارات واضحة: *لا ترسل أبدًا كائنًا جزئيًا إلى update؛ احضر دائمًا المورد كاملاً، قم بتعديله، ثم أعد إرساله كاملاً.* الوكيل الذي يتخطى خطوة get سيحذف الحقول بصمت. الوكيل الذي يشغل cli-schema validate أولاً يكتشف أخطائه قبل أن تصل إلى المشروع.

المسار الآمن: دع الوكيل يعمل على فرع الذكاء الاصطناعي (AI branch)

يمكنك منح الوكيل إذن التحرير المباشر على فرعك الرئيسي. لا تفعل ذلك، على الأقل في البداية. لدى Apidog آلية عزل مصممة خصيصًا لهذا الغرض، وهي فرع الذكاء الاصطناعي (AI branch)، وهي مصممة بالضبط لهذا الغرض: يقوم الوكيل بتعديل الموارد دون لمس الفرع المصدر، ولا يتم دمج أي شيء حتى تأذن بذلك. فكر في الأمر كطلب سحب لمواصفات واجهة برمجة التطبيقات الخاصة بك.

الخطوة 1: إنشاء فرع الذكاء الاصطناعي

apidog branch create --project <projectId> --type ai \
  --from main --name "ai/20260713-from-main-refund-fields"

اصطلاح التسمية هو ai/YYYYMMDD-from-source-feature بحيث يكون أصل الفرع والغرض منه واضحين للوهلة الأولى. يجب أن تكون قيمة --from هي فرعك الرئيسي أو فرع سباق (sprint branch) عادي، وليس فرعًا عامًا أبدًا. تفصيل مفيد واحد: يتم أرشفة فرع الذكاء الاصطناعي الذي لا يختلف عن مصدره تلقائيًا بعد 24 ساعة، لذلك يتم تنظيف التجارب المهملة ذاتيًا.

الخطوة 2: استيراد الموارد التي سيقوم الوكيل بتحريرها

يبدأ فرع الذكاء الاصطناعي فارغًا. لا يستنسخ الفرع المصدر تلقائيًا. قبل أن يتمكن الوكيل من تحرير نقطة نهاية أو مخطط موجودين، اسحب هذا المورد إلى الفرع باستخدام pick-to:

apidog branch pick-to --project <projectId> --type ai \
  --from main --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>

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

الخطوة 3: دع الوكيل يقوم بالتغيير

الآن يقوم الوكيل بتشغيل حلقة القراءة-التعديل-الكتابة من قبل، ولكن مع توجيه --branch إلى فرع الذكاء الاصطناعي. كل تعديل محتوى ومحصور:

apidog endpoint get <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

apidog endpoint update <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json

فرعك الرئيسي لم يمس طوال هذا الوقت. إذا أخطأ الوكيل، فإن نطاق الضرر يقتصر على فرع واحد يمكن التخلص منه.

الخطوة 4: المراجعة، ثم الدمج

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

apidog merge-request --help
apidog branch merge --project <projectId> --type ai \
  --from "ai/20260713-from-main-refund-fields" --to main --endpoint-ids <ids>

راجع الفروقات، وافق، وستصل التغييرات التي تمت مراجعتها إلى الفرع الرئيسي. يتطلب الدمج المباشر من واجهة سطر الأوامر (CLI) إذن تحرير مباشر على كل من الفرع المصدر والفرع الهدف؛ إذا كان الفرع الرئيسي محميًا، ففضل استخدام merge-request ووافق عليه في عميل Apidog.

مثال عملي: إعادة تسمية حقل بأمان

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

تخبر الوكيل: *“أعد تسمية حقل amount في مخطط Refund إلى amountCents واجعله عددًا صحيحًا.”* وفقًا لقواعده، يقوم الوكيل بما يلي:

# 1. Fetch the FULL current schema on the AI branch
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"

يستعيد الكائن الكامل ويحرر jsonSchema *بأكمله*، مع الاحتفاظ بكل حقل لا يلمسه:

{
  "name": "Refund",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amountCents"],
    "properties": {
      "orderId": { "type": "string" },
      "amountCents": { "type": "integer" },
      "reason": { "type": "string" }
    }
  }
}

لاحظ ما لم يحدث: لم يرسل الخاصية المتغيرة الواحدة فقط. لقد أرسل المخطط بأكمله مع بقاء orderId و reason كما هما، لأن update يستبدل. ثم:

# 2. Validate the complete object
apidog cli-schema validate schema-create --file ./refund-full.json

# 3. Write it back to the AI branch
apidog schema update <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields" --file ./refund-full.json

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

وضع علامة على التغييرات المسببة للأعطال قبل الدمج

إعادة تسمية حقل مطلوب هو تغيير مسبب للأعطال (breaking change): أي عميل يرسل amount سيفشل الآن في التحقق من الصحة. مجموعة تعليمات وكيل جيدة تجعل النموذج *يصرح بذلك* بدلاً من الدمج بصمت. أضف هذا إلى قواعد الوكيل:

Before merging any spec change, classify it:
- Non-breaking (new optional field, new endpoint, loosened constraint) → summarize and proceed to merge-request.
- Breaking (renamed/removed field, new required field, tightened type) → STOP.
  Report the breaking change and the affected endpoints, and wait for explicit human approval.

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

التحديث من ملف OpenAPI بدلاً من ذلك

أحيانًا يكون التغيير موجودًا بالفعل كملف OpenAPI، تم إنشاؤه من التعليمات البرمجية، أو تم تحريره في مكان آخر، أو تم تسليمه إليك من قبل فريق آخر. بدلاً من إعادة تشغيل التعديلات حقلًا بحقل، يمكن للوكيل استيراد الملف لمطابقته مع المشروع:

apidog import --project <projectId> --format openapi --file ./openapi.json \
  --branch "ai/20260713-from-main-refund-fields"

يقبل import ملفات OpenAPI 3.x، Swagger 2.0، Postman، والمزيد. شغله على فرع الذكاء الاصطناعي أولاً حتى تتمكن من مراجعة تغييرات المواصفات الواردة قبل أن تصل إلى الفرع الرئيسي. بعد الدمج، قم بتصدير المواصفات المدمجة مرة أخرى لتأكيد النتيجة:

apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json

هذا المسار هو الأفضل عندما يكون مصدر الحقيقة خارج Apidog وتقوم بمزامنته. مسار update لكل حقل هو الأفضل عندما يكون Apidog هو مصدر الحقيقة وتقوم بإجراء تغيير دقيق.

عندما يخطئ الوكيل: التراجع

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

apidog branch archive "ai/20260713-from-main-refund-fields" --project <projectId> --type ai

نظرًا لأن فرع الذكاء الاصطناعي الذي لا يحتوي على اختلاف مقبول يتم أرشفته تلقائيًا بعد 24 ساعة على أي حال، فإن حتى التجربة المنسية تنظف نفسها. قارن ذلك بوكيل يقوم بتحرير الفرع الرئيسي مباشرة، حيث يكون التحديث update السيئ مباشرًا على الفور، وملاذك الوحيد هو سلة المحذوفات أو التراجع اليدوي. الفرع ليس بيروقراطية؛ إنه زر التراجع.

ملاحظة حول الأذونات

إذا تم حظر عملية update أو import، فهذا يعني أن المشروع قد قام بإيقاف تشغيل "أذونات تحرير الذكاء الاصطناعي الخارجي". هذا حاجز متعمد، وسير عمل فرع الذكاء الاصطناعي المذكور أعلاه هو الحل له: يقوم الوكيل بتحرير فرع معزول وتوافق أنت على الدمج. إذا كنت تفضل منح التعديلات المباشرة، فالمفتاح موجود في Project Settings → Feature Settings → AI Feature Settings (عميل Apidog 2.8.32+). عندما يصطدم الوكيل بجدار أذونات، لا تدعه يختار حلاً بديلًا بصمت؛ أظهر الخيار لإنسان.

المشاكل الشائعة

• التحديث الجزئي يمسح الحقول. الخطأ الأكثر ضررًا والأكثر شيوعًا. update يستبدل؛ ولا يدمج. قم بجلب الكائن بالكامل، ثم حرره بالكامل، وتحقق من صحته، ثم اكتب. إذا اختفى حقل، فقد أرسل الوكيل حمولة جزئية.
• تحرير مورد موجود على فرع ذكاء اصطناعي دون استيراده. يبدأ الفرع فارغًا. قم باستخدام pick-to للمورد أولاً، وإلا فلن يكون لدى الوكيل شيء ليحرره.
• قيمة --from خاطئة لفرع الذكاء الاصطناعي. يجب أن يكون المصدر هو الفرع الرئيسي (main) أو فرع سباق (sprint branch)، وليس فرعًا عامًا أبدًا. سيشتكي أمر branch create إذا أخطأت في ذلك.
• تجاوز التحقق من الصحة (validation). يكتشف cli-schema validate حمولة غير صحيحة على جهازك. الوكيل الذي يكتب دون التحقق من الصحة يحول خطأ مطبعيًا إلى استدعاء API فاشل، أو ما هو أسوأ، دمج سيء.
• دمج تغيير مسبب للأعطال بصمت. بدون قاعدة "التصنيف أولاً"، سيقوم الوكيل بكل سرور بإعادة تسمية حقل مطلوب ودمجه. اجعل اكتشاف التغييرات المسببة للأعطال نقطة تفتيش صريحة.

الأسئلة الشائعة

• هل يمكنني السماح للوكيل بتحرير الفرع الرئيسي مباشرة؟ يمكنك ذلك، عن طريق تمكين "أذونات تحرير الذكاء الاصطناعي الخارجي"، ولكن البدء بفرع ذكاء اصطناعي أكثر أمانًا: لا يتم إرسال أي شيء إلى الفرع الرئيسي حتى توافق على الدمج. خصص التعديلات المباشرة للأتمتة منخفضة المخاطر وعالية الثقة.
• ما الفرق بين branch merge و merge-request؟ يقوم branch merge بكتابة التغيير فورًا ويحتاج إلى إذن تحرير مباشر على كلا الفرعين. يفتح merge-request طلبًا قابلاً للمراجعة، وهو الخيار الصحيح عندما يكون الفرع الرئيسي محميًا.
• هل يحتاج الوكيل إلى تطبيق سطح المكتب Apidog؟ لا، واجهة سطر الأوامر (CLI) مستقلة. التطبيق مهم فقط لتبديل إعداد "أذونات تحرير الذكاء الاصطناعي الخارجي"، وهو إعداد يتم مرة واحدة.
• كيف أتأكد من أن الوكيل لا يختلق اسم حقل؟ حلقة cli-schema get ← validate هي وسيلة الحماية. الحمولة التي تحتوي على حقل مخترع تفشل في التحقق من الصحة محليًا، قبل أن تصل إلى المشروع.

خاتمة

السماح لوكيل بتحديث مواصفات واجهة برمجة التطبيقات الخاصة بك آمن عندما تتحقق ثلاثة أمور: أنه يعمل على فرع ذكاء اصطناعي معزول، ويعامل كل تحديث على أنه عملية قراءة-تعديل-كتابة كاملة بدلاً من تصحيح (patch)، ويوافق إنسان على الدمج. يوفر لك Apidog CLI كل هذه الأمور الثلاثة كأوامر، مما يعني أن الحلقة بأكملها (التحرير، التحقق، المراجعة) قابلة للبرمجة والتدقيق، والتغيير السيئ على بعد أمر archive واحد من الاختفاء.

قم بإعداد فرع الذكاء الاصطناعي، وامنح الوكيل قاعدة القراءة-التعديل-الكتابة ونقطة تفتيش التغييرات المسببة للأعطال، وستصبح صيانة المواصفات فرقًا توافق عليه بدلاً من العمل الدقيق الذي تستمر في تأجيله. قم بتنزيل Apidog للحصول على واجهة سطر الأوامر (CLI)، واقرن هذا بـ السماح لوكيل بإنشاء وثائقك لتغطية دورة التأليف والصيانة الكاملة.