يشهد نظام الإضافات في Codex CLI تطوراً سريعاً؛ حيث أصبح بإمكانك الآن عبر الأمر /plugins تصفح الإضافات حسب المتجر، وتثبيتها، وتشغيلها أو إيقافها. وبدأت فرق عمل كثيرة في حزم أدواتها الداخلية كإضافات Codex قابلة لإعادة الاستخدام. لكن، لا تزال بوابة النشر الذاتي في المتجر الرسمي (Marketplace) تعتمد على "نظام المراجعة"، مما يتطلب من المطورين فهم هيكلية ملف manifest، وطرق الاختبار المحلي، ثم إتمام عملية تقديم الطلب للمراجعة لضمان وصول الإضافة للمستخدمين. يستعرض هذا المقال المسار الكامل بدءاً من الإنشاء، والاختبار المحلي، والتوزيع عبر Git، وصولاً إلى المراجعة والنشر الرسمي، مع تسليط الضوء على أبرز التحديات.
مما تتكون إضافات Codex؟
تعد إضافة Codex في جوهرها وسيلة لحزم قدرات متنوعة في وحدة قابلة للتثبيت والتوزيع. ووفقاً لتوثيق OpenAI الرسمي، يمكن أن تحتوي الإضافات على "مهارات" (skills – تعليمات مهام قابلة لإعادة الاستخدام)، وتطبيقات مدعومة بـ MCP (لربط الأدوات الخارجية)، وخطافات (hooks) لدورة الحياة، بالإضافة إلى قوالب اختيارية لمتصفح الويب والمهام المجدولة. لا يشترط وجود كل هذه المكونات معاً؛ فإضافة خفيفة تحتوي على المهارات فقط يمكن تثبيتها واستخدامها بنجاح.
إن فهم حدود مسؤولية كل مكون هو شرط أساسي لكتابة ملف manifest سليم. يوضح الجدول التالي مسارات التخزين ووظائف المكونات الأربعة الأساسية لإضافات Codex:
| المكون | مسار التخزين | الوظيفة | هل هو إلزامي؟ |
|---|---|---|---|
| plugin.json | .codex-plugin/plugin.json |
تعريف هوية الإضافة وبياناتها الوصفية | نعم |
| المهارات (skills) | skills/<skill-name>/SKILL.md |
تعريف تعليمات المهام القابلة لإعادة الاستخدام | لا |
| خوادم MCP | .mcp.json |
إعداد الاتصال بخدمات الأدوات الخارجية | لا |
| الخطافات (hooks) | hooks/hooks.json |
الإعلان عن أوامر خطافات دورة الحياة | لا |
تجدر الإشارة إلى أنه إذا كانت الإضافة مجرد ملف SKILL.md للاستخدام الداخلي للفريق، فلا حاجة لاتباع عملية manifest الكاملة؛ إذ يكفي وضع الملف مباشرة في مجلد .agents/skills/ وسيقوم Codex باكتشافه تلقائياً. هذا هو الشكل الانتقالي الشائع للعديد من الفرق قبل التحول من "السكربتات الداخلية" إلى "الإضافات الرسمية".
تتجاوز قدرات الإضافات ما يتوقعه الكثيرون. فبالإضافة إلى المهارات وتطبيقات MCP، يشير التوثيق الرسمي إلى إمكانية حمل الإضافة لتعريفات القدرات اللازمة لمتصفحات الويب، وقوالب المهام المجدولة. وهذا يعني أن الإضافة يمكنها التعامل مع الطلبات التفاعلية التي يطلقها المستخدم، وكذلك تنفيذ المهام المؤتمتة في الخلفية بشكل دوري. إن اختيار المكونات التي ستدمجها في إضافة واحدة هو في جوهره موازنة بين تجربة التثبيت وتكلفة الصيانة؛ فكلما زادت المكونات، أصبحت الإضافة أكثر شمولاً، ولكنها تتطلب أيضاً مواد مراجعة وحالات اختبار أكثر. لذا، من الأفضل تحديد ما يحتاجه المستخدم المستهدف بدقة قبل البدء، بدلاً من حشو كل شيء في حزمة واحدة.
البدء بملف plugin.json: دليل شامل لملف قائمة الإضافات
يُعد ملف plugin.json بمثابة بطاقة الهوية للإضافة، فهو الذي يحدد كيفية تعرف Codex على هذه الإضافة وتحميلها وعرضها. يتطلب الحد الأدنى من ملف البيان (manifest) ثلاثة حقول أساسية فقط:
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}
يُنصح باستخدام صيغة kebab-case الثابتة لحقل name؛ حيث لا ينبغي تغيير هذا المعرف في الإصدارات اللاحقة، وإلا فلن يتمكن المتجر من التعرف عليها كإصدار جديد لنفس الإضافة. يتبع حقل version معيار الإصدار الدلالي (Semantic Versioning)، ويعتمد المتجر عليه لتحديد ما إذا كان يجب تنبيه المستخدم للتحديث. يجب أن تكون جميع المسارات المشار إليها في ملف البيان نسبية لمجلد جذر الإضافة، وأن تبدأ بـ ./، ولا يمكنها تجاوز نطاق مجلد الجذر.
بالإضافة إلى هذه الحقول الثلاثة الأساسية، يمكن أن يشير حقل skills إلى مصفوفة من مجلدات المهارات المتعددة، بينما تشير حقول hooks و mcpServers و apps إلى ملفات الإعداد المقابلة لـ hooks/hooks.json و .mcp.json و .app.json على التوالي. هذا التصميم الذي يعتمد على "الإشارة إلى الملفات" يجعل ملف البيان نفسه موجزاً، حيث يتم تقسيم وصف المهارات وإعدادات الأدوات إلى ملفات مستقلة، مما يسهل التعاون بين عدة أشخاص لتعديل مكونات مختلفة في وقت واحد دون حدوث تعارضات.
إذا كنت تخطط لإرسال الإضافة إلى المتجر الرسمي (Marketplace)، فستحتاج إلى إضافة مجموعة من البيانات الوصفية الموجهة للعرض. يوضح الجدول التالي الحقول الرئيسية التي يُنصح بإكمالها عند مرحلة النشر:
| الحقل | النوع | الوصف |
|---|---|---|
| author / repository | نص | يحدد مصدر الإضافة، ويُفضل أن يتطابق مع الهوية الموثقة |
| interface.displayName | نص | اسم الإضافة كما يظهر في قائمة المتجر |
| interface.category | نص | تصنيف الإضافة، مما يؤثر على مسار تصفح المستخدم |
| interface.capabilities | مصفوفة | وسوم تعلن عن القدرات التي تمتلكها الإضافة |
| mcpServers / apps / hooks | كائن | روابط لملفات الإعداد الخاصة بالمكونات المقابلة |
إن أكثر الأخطاء شيوعاً عند كتابة ملف البيان هو خطأ في مرجع المسار، مثل كتابة مسار مطلق لحقل skills أو نسيان البادئة ./، مما يؤدي إلى عمل الإضافة محلياً ولكن يتم اعتبارها قائمة غير صالحة عند إرسالها للمراجعة. يُنصح باستنساخ مستودع الإضافة في مجلد نظيف قبل الإرسال، ومحاكاة بيئة التثبيت الحقيقية لإجراء اختبار كامل.
الهيكل المحلي والتصحيح: تشغيل الإضافات (Plugins)
إن كتابة ملف manifest من الصفر ليست عملية فعالة، لذا توفر الأداة الرسمية ميزة $plugin-creator المدمجة لإتمام عملية بناء الهيكل الأساسي، حيث يمكنك توليده عبر محادثة مباشرة داخل واجهة سطر أوامر Codex:
codex "使用 $plugin-creator 脚手架生成一个名为 infra-monitor 的插件"
سيقوم هذا الأمر تلقائيًا بإنشاء ملف manifest ومهارة (skill) تجريبية وإدخال في السوق المحلي، مما يوفر عليك عناء إنشاء هيكل المجلدات يدويًا. بعد التوليد، ستكون الإضافة جاهزة للتثبيت والاختبار في بيئتك المحلية دون الحاجة لنشرها في أي مستودع بعيد.
في مرحلة التصحيح المحلي، إذا كانت المهارة داخل الإضافة تتضمن استدعاء نماذج لغة كبيرة من شركات مختلفة لإجراء اختبارات مقارنة، فإن استخدام بوابة API موحدة يمكن أن يقلل بشكل كبير من تكلفة تبديل إعدادات البيئة. عند التحقق من قدرات خادم MCP للإضافة، نقوم عادةً بتوجيه base_url إلى خدمة وكيل API التي توفرها APIYI عبر apiyi.com، حيث يمكنك بمفتاح API واحد التبديل بين استدعاء نماذج مختلفة داخل الإضافة، مما يسهل مقارنة أداء النماذج المختلفة تحت نفس منطق الإضافة:
from openai import OpenAI
client = OpenAI(
api_key="your-apiyi-key",
base_url="https://api.apiyi.com/v1"
)
🎯 نصيحة للتصحيح: أثناء تطوير إضافات Codex، تحتاج غالبًا إلى اختبار جودة استجابة خادم MCP مع نماذج مختلفة بشكل متكرر. نوصي باستخدام منصة APIYI (apiyi.com) لإدارة استدعاءات النماذج المتعددة بشكل موحد، لتجنب طلب مفاتيح API لكل نموذج على حدة أو صيانة منطق استدعاء مستقل، مما يتيح لك التركيز على صقل وظائف الإضافة نفسها.
بالإضافة إلى إنشاء إدخالات السوق المحلية يدويًا، يمكنك التصريح عن مسار الإضافة المحلية مباشرة في ملف ~/.agents/plugins/marketplace.json (على المستوى الشخصي) أو في ملف .agents/plugins/marketplace.json في المجلد الرئيسي للمستودع (على مستوى الفريق)، وتعيين حقل source إلى local للإشارة إلى المجلد المحلي، وبذلك تكتمل عملية التثبيت والتحقق دون الحاجة للنشر عن بُعد.
إذا كانت الإضافة تحتوي على تطبيق مدعوم بـ MCP يتطلب وضع المطور في ChatGPT للتصحيح، توفر الأداة الرسمية مسارًا آخر: قم بتفعيل وضع المطور في إعدادات ChatGPT، وأنشئ تطبيقًا مدعومًا بـ MCP واحصل على معرف التطبيق (app ID) المقابل، ثم اربط هذا المعرف عبر $plugin-creator. سيسمح لك ذلك بالتحقق من تدفق البيانات بين الإضافة والتطبيق في بيئة محادثة حقيقية، وهي خطوة أقرب إلى التجربة الفعلية بعد الإطلاق مقارنة بالتصحيح عبر سطر الأوامر، وننصح بتجربتها بالكامل قبل تقديم الإضافة للمراجعة.
التسجيل في سوق Git والتوزيع داخل الفريق
بعد التحقق من الإضافة محليًا، لا يتطلب التوزيع داخل الفريق عادةً انتظار المراجعة الرسمية، فاستخدام مستودع Git لإنشاء مصدر سوق كافٍ. توفر واجهة سطر أوامر Codex مجموعة من الأوامر الخاصة بإدارة السوق:
| الأمر | الغرض |
|---|---|
codex plugin marketplace add owner/repo |
إضافة مستودع GitHub كمصدر للسوق |
codex plugin marketplace add owner/repo --ref v2.1.0 |
قفل فرع أو وسم معين للتحكم في الإصدار التجريبي |
codex plugin marketplace list |
عرض قائمة الأسواق المضافة |
codex plugin marketplace upgrade |
سحب تحديثات السوق |
codex plugin marketplace remove |
إزالة مصدر السوق |
بالنسبة للفرق التي لديها مستودعات برمجية ضخمة، يمكن استخدام المعامل --sparse .agents/plugins لسحب المجلدات المتعلقة بالإضافة فقط، مما يمنع بطء التثبيت الناتج عن استنساخ المستودع بالكامل. يعد نمط سوق Git مثاليًا لأدوات المؤسسات الداخلية، حيث لا يحتاج الأمر إلى مراجعة عامة، ويكفي دفع وسم (tag) جديد لتحديث الإضافة، ليقوم أعضاء الفريق بتنفيذ أمر الترقية (upgrade) للمزامنة.
من الناحية العملية، يتمتع نمط سوق Git بميزة خفية: إمكانية فصل وتيرة تطوير الإضافة عن وتيرة الإصدار الداخلي للفريق. قد يتم دمج كود العمل عدة مرات في اليوم، لكن الإضافة كجزء من سلسلة أدوات المحادثة، قد يؤدي تحديثها المتكرر إلى إرباك المستخدم. نوصي بربط إصدارات الإضافة بوسم (tag) في نوافذ إصدار ثابتة، مثل الدمج أسبوعيًا أو كل أسبوعين، مما يضمن سرعة تطوير الوظائف دون إجبار أعضاء الفريق على التكيف المتكرر مع طرق تفاعل جديدة.
عملية تقديم المراجعة الكاملة لـ Marketplace الرسمي
لا يزال منفذ الإدراج الذاتي في Marketplace الرسمي غير مفتوح بالكامل حتى الآن، حيث تشير وثائق OpenAI بوضوح إلى أن هذا الجزء "قادم قريباً". في المرحلة الحالية، تمر عملية التقديم الرسمية للمستخدمين عبر بوابة تقديم الإضافات (Plugins) التي تخضع للمراجعة البشرية. قبل التقديم، يجب إكمال التحقق من الهوية؛ حيث يحتاج المطورون الأفراد إلى إكمال "التحقق الفردي" (individual verification)، بينما يتطلب النشر باسم شركة إكمال "التحقق التجاري" (business verification)، وسيقوم المراجعون بمطابقة هوية الناشر مع المواد المقدمة.
قائمة المواد المطلوبة للتقديم الرسمي هي كما يلي:
| فئة المواد | المتطلبات المحددة |
|---|---|
| معلومات الإضافة الأساسية | الاسم، الوصف، الشعار، التصنيف، الروابط ذات الصلة |
| خادم MCP | نطاق يمكن الوصول إليه عبر الإنترنت، سياسة CSP، إعدادات المصادقة |
| حساب تجريبي | يمكن تسجيل الدخول مباشرة، لا يتطلب MFA أو تحققاً ثانوياً عبر البريد الإلكتروني |
| حالات الاختبار | 5 سيناريوهات إيجابية + 3 سيناريوهات سلبية بالضبط |
| تصنيف الأدوات | يجب أن تتوافق readOnlyHint و openWorldHint و destructiveHint مع السلوك الفعلي |
تنقسم عملية التقديم إلى عدة أقسام في النموذج: Info (معلومات القائمة العامة)، MCP (إعدادات الخادم والمصادقة)، Skills (رفع حزمة المهارات النهائية)، Prompts (أمثلة للموجهات الأولية)، Testing (حالات الاختبار)، Global (الدول والمناطق المتاحة)، وأخيراً قسم Submit لكتابة ملاحظات الإصدار وتأكيد السياسات. بعد اجتياز المراجعة، يختار المطور وقت النشر بنفسه من خلال البوابة، وستظهر الإضافة في دليل الإضافات الموحد لـ ChatGPT و Codex.
إذا كانت الإضافة تحتوي على تطبيق مدعوم بـ MCP، فيجب التحقق من ملكية النطاق بشكل إضافي لضمان تطابق النطاق الذي تم نشر خادم MCP عليه مع النطاق المعلن عنه في الإضافة. سيركز فريق المراجعة على ما إذا كانت نتائج الأداة تحتوي على بيانات شخصية زائدة أو معلومات مفاتيح (API keys)، وهذا أمر يجب تجنبه مسبقاً عند تصميم تنسيق مخرجات الأداة، بدلاً من تعديله بعد رفض المراجعة.
إدارة الإصدارات والمشكلات الشائعة
بعد إطلاق الإضافة، تؤثر تفاصيل إدارة الإصدار بشكل مباشر على تجربة التحديث للمستخدمين. يعتمد السوق على حقل version لتحديد ما إذا كان هناك تحديث متاح، لذا من المهم جداً اتباع معايير الإصدار الدلالي (Semantic Versioning) بدقة؛ استخدم إصدار التصحيح (patch) لإصلاح الأخطاء، وإصدار ثانوي (minor) لإضافة قدرات جديدة، ولا ترفع الإصدار الرئيسي (major) إلا في حال وجود تغييرات جذرية.
يتم تخزين الإضافات المثبتة مؤقتاً في المسار المحلي ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/. عند استكشاف مشكلات مثل "تم تحديث الإضافة ولكن السلوك لم يتغير"، تأكد أولاً مما إذا كان التخزين المؤقت قد تم تحديثه إلى الإصدار الجديد، فغالباً ما يكون هذا أسرع في تحديد المشكلة من إعادة تصحيح منطق الكود. في بيئات الشركات، قد تواجه سياسات القائمة البيضاء الإلزامية في requirements.toml؛ حيث يحتاج خادم MCP إلى تطابق الاسم والهوية في آن واحد، وأي عدم تطابق سيؤدي إلى تعطيل الخدمة بصمت دون رسالة خطأ واضحة. يُنصح باختبار إعدادات السياسة في بيئة الاختبار قبل الانتقال إلى الإنتاج.
يلخص الجدول التالي بعض المشكلات الشائعة التي أبلغ عنها المطورون وطرق التعامل معها:
| المشكلة الشائعة | طريقة التعامل |
|---|---|
| كتابة مسار manifest كمسار مطلق | قم بتغييره إلى مسار نسبي يبدأ بـ ./ |
| الاستدعاء الضمني يؤدي إلى تشغيل إضافة غير مقصودة | استخدم @plugin-name لتحديد الإضافة صراحة |
| السلوك بعد التحديث لم يطبق | تحقق مما إذا كان دليل التخزين المؤقت المحلي للإضافة قد تم تحديثه |
| تعطيل MCP بصمت تحت سياسة الشركة | تأكد من تطابق الاسم والهوية في requirements.toml |
قبل التقديم الرسمي للمراجعة، يُنصح بتشغيل أداة codex-plugin-scanner التابعة لجهة خارجية، حيث تقوم بتقييم الإضافة بناءً على قابلية التثبيت، حالة الصيانة، أمان MCP، ومصدر النشر. خاصة بالنسبة للإضافات التي سيتم توزيعها على عملاء الشركات، فإن اكتشاف المشكلات مبكراً يوفر وقتاً أكثر من رفضها أثناء المراجعة.
تفصيل آخر غالباً ما يتم تجاهله هو الفرق بين الاستدعاء الصريح والاكتشاف الضمني. في حال عدم تحديد إضافة معينة، سيقوم Codex بمطابقة المهارة الأكثر صلة بناءً على السياق تلقائياً. إذا تم تثبيت إضافات متعددة ذات وظائف متشابهة في نفس مساحة العمل، فقد لا يختار هذا المطابق الضمني الإضافة التي تتوقعها. لذا، عوّد نفسك على استخدام @plugin-name للتصريح الصريح، خاصة في مساحات العمل المشتركة بين الفرق، لتقليل تكاليف استكشاف أخطاء "تضارب الإضافات".
الأسئلة الشائعة حول تطوير إضافات Codex (FAQ)
ما الفرق بين الإضافة وملف SKILL.md المستقل؟
يُعد SKILL.md أحد مكونات الإضافة، وعند استخدامه بشكل مستقل لا يتطلب ملف manifest، حيث يتم اكتشافه تلقائيًا بمجرد وضعه في المجلد .agents/skills/. أما الإضافة فهي حزمة تجمع بين المهارات (skills)، وخادم MCP، والخطافات (hooks)، وغيرها من المكونات في كيان واحد يحمل هوية محددة وقابل للإصدار، مما يجعله مناسبًا للسيناريوهات التي تتطلب توزيعًا رسميًا وتتبعًا للتحديثات.
ماذا أفعل إذا كنت بحاجة إلى حسابات نماذج متعددة لإجراء اختبارات مقارنة أثناء مرحلة التطوير؟
هذه مشكلة عملية شائعة في تطوير الإضافات، خاصة تلك التي تتضمن اختيار نموذج أو تحسين الموجه (prompt). بدلًا من فتح حسابات منفصلة لدى كل مزود نماذج وإدارة مفاتيح API الخاصة بهم، يمكنك استخدام بوابة موحدة مثل APIYI (apiyi.com)، حيث تتيح لك استدعاء النماذج الرئيسية عبر مفتاح API واحد لإجراء مقارنات A/B، مما يسمح لك بالتركيز على منطق الإضافة نفسه بدلًا من إدارة الحسابات.
هل يمكن أن يتواجد توزيع سوق Git و Marketplace الرسمي معًا؟
نعم، يمكن ذلك. تعتمد العديد من الفرق استخدام سوق Git للتحقق الداخلي والتجربة على نطاق ضيق أولًا، وبعد التأكد من الاستقرار يتم الانتقال إلى عملية التقديم الرسمية. هاتان الطريقتان للتوزيع لا تتعارضان، وهيكل ملف manifest موحد لكليهما.
كم تستغرق عملية مراجعة الإضافة؟
لا توجد فترة زمنية محددة في الوثائق الرسمية، حيث تشير فقط إلى أن عملية المراجعة لا تزال قيد التطوير والتوسع، ولا يوجد دعم للطلبات العاجلة. يُنصح باعتبار فترة المراجعة متغيرًا غير مؤكد في جدول المشروع، ومن الأفضل تجهيز كافة المواد المطلوبة بدقة قبل التقديم لتقليل المراسلات الناتجة عن نقص البيانات، فهذه هي الطريقة الأكثر واقعية لتقصير وقت الإطلاق الإجمالي.
كلمة أخيرة
لا تكمن الصعوبة الحقيقية في تطوير إضافات Codex في الكود البرمجي بحد ذاته، بل في فهم متطلبات ملف manifest وإعداد مواد عملية المراجعة؛ فهذه التفاصيل ليست معقدة كما تبدو، لكنها قد تتسبب في رفض طلبك بسبب خطأ في مسار ملف أو حقل مفقود. نوصي باتباع مسار "التحقق عبر بيئة التطوير المحلية ← التوزيع المحدود عبر سوق Git ← التقديم الرسمي للمراجعة"، مع تخصيص وقت كافٍ للاختبار في بيئة حقيقية في كل خطوة. وإذا كانت إضافتك تتضمن استدعاء نماذج متعددة أو تتطلب تبديلًا متكررًا بين النماذج للاختبار، فإن خدمة وكيل API التي توفرها APIYI (apiyi.com) ستوفر عليك الكثير من الوقت في إعداد البيئة، مما يتيح لك تركيز طاقتك على صقل الإضافة نفسها.
