💻 computer science

HarnessAPI: A Skill-First Framework for Unified Streaming APIs and MCP Tools

HarnessAPI هو إطار عمل بلغة بايثون يقضي على تكرار الكود عبر التعامل مع مجلدات المهارات المحددة النوع (typed skill folders) كمصدر وحيد للحقيقة لتوليد نقاط نهاية HTTP تدفقية موحدة، وتوثيق OpenAPI تفاعلي، وأدوات بروتوكول سياق النموذج (MCP) بدون تهيئة مسبقة، وذلك تلقائياً من معالج واحد ونماذج Pydantic.

المؤلفون الأصليون: Edwin Jose

نُشر 2026-05-22

📖 4 دقيقة قراءة☕ قراءة في استراحة قهوة

CC BY 4.0

المؤلفون الأصليون: Edwin Jose

البحث الأصلي مرخَّص بموجب CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ هذا شرح مولَّده بالذكاء الاصطناعي للبحث أدناه. لم يكتبه المؤلفون ولم يصادقوا عليه. وللتحقق من الدقة التقنية، يرجى الرجوع إلى البحث الأصلي. اقرأ إخلاء المسؤولية الكامل

تخيل أنك طاهٍ اخترعت وصفة جديدة لذيذة (وهي بمثابة "مهارة"). في عالم الذكاء الاصطناائي والبرمجيات، يجب تقديم هذه الوصفة إلى نوعين مختلفين تماماً من الزبائن:

١. زبون الويب: يأتي إلى موقع مطعمك الإلكتروني، ويملأ نموذجاً، ويتوقع استلام إيصال سريع ومنسق (نقطة نهاية HTTP).
٢. الروبوت الخادم: هو مساعد ذكاء اصطناعي (مثل خادم رقمي) يحتاج إلى أخذ وصفتك مباشرة من رف مطبخك لاستخدامها أثناء الطهي (أداة MCP).

المشكلة: كابوس "الإدخال المزدوج"
في الوقت الحالي، إذا أردت خدمة كلا الزبونين، عليك كتابة وصفتك مرتين.

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

يسمي الورق هذا "مشكلة المكدس المزدوج" (dual-stack). والأسوأ من ذلك، أنه إذا غيرت مكوناً في مطبخك (حدثت الكود الخاص بك)، فسيتعين عليك تذكر تحديث كلا السجلين. إذا نسيت، فقد يقول الموقع الإلكتروني "أضف بيضتين"، بينما يظن الروبوت الخادم "أضف كوبين من الدقيق". هذا يؤدي إلى الارتباك، والأخطاء، والكثير من الأعمال الورقية الإضافية.

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

فكر في HarnessAPI كمترجم وطابعة عالمية تجلس في مطبخك.

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

كيف يعمل الأمر (الخدع السحرية)

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

لما لماذا يهم هذا الأمر (النتائج)
اختبر المؤلف ذلك من خلال بناء ست "مهارات" مختلفة (مثل تلخيص النصوص أو ترجمة اللغات) بطريقتين:
١. الطريقة القديمة: كتابة الكود للموقع الإلكتروني وللروبوت بشكل منفصل يدوياً.
٢. طريقة HarnessAPI: كتابة المهارة مرة واحدة فقط.

النتائج:

٧٤٪ أقل جهداً: تطلبت طريقة HarnessAPI كوداً "نمطياً" (boilerplate) أقل بنسبة ٧٤٪ (أي أعمال الإعداد المملة والمتكررة).
لا يوجد تباين: في الطريقة القديمة، كان من الممكن أن تبتعد النسختان عن بعضهما وتصبحا غير متسقتين. في الطريقة الجديدة، هما متطابقتان رياضياً لأن كلتيهما تأتيان من نفس المصدر.
عملية واحدة: بدلاً من تشغيل خادمين منفصلين (واحد للويب وآخر للروبوت)، يقوم HarnessAPI بتشغيل كل شيء في عملية واحدة، مما يجعله أخف وأسهل في الإدارة.

العقبة (القيود)
الورقة صريحة بشأن بعض قواعد السلامة:

ميزة "التبديل الساخن" (Hot-Swap): هناك ميزة تسمح لك بتحديث الكود أثناء تشغيل الخادم (وهي رائعة للاختبار)، لكن المؤلف يحذر من أن هذا يشبه إعطاء شخص ما جهاز تحكم عن بعد لمطبخك. يجب استخدامها فقط على جهاز الكمبيوتر الخاص بك (localhost) ولا ينبغي أبداً تفعيلها للمواقع العامة، وإلا فقد يتمكن المخترقون من السيطرة على خادمك.
التعقيد: يعمل بشكل رائع مع الوصفات القياسية، ولكن إذا كانت وصفتك تتضمن هياكل معقدة للغاية ومتداخلة، فقد يحتاج المترجم التلقائي إلى القليل من المساعدة.

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

ملخص تقني: HarnessAPI – إطار عمل قائم على "المهارة أولاً" لتوحيد واجهات برمجة تطبيقات البث وأدوات MCP

1. بيان المشكلة

تحدد الورقة احتكاكاً هيكلياً حرجاً في نشر أدوات النماذج اللغوية الكبيرة (LLM). في الوقت الحالي، يتعين على المطورين صيانة تمثيلين متوازيين لكل دالة Python مخصصة كأداة لـ LLM:

نقطة نهاية HTTP: للعملاء الذين يواجهون البشر، ولوحات التحكم عبر الويب، وخطوط أنابيب CI، والتي تُنفذ عادةً باستخدام أطر عمل مثل FastAPI.
أداة MCP: لبيئات تشغيل الوكلاء (مثل Claude Desktop أو Cursor) باستخدام بروتوكول سياق النموذج (Model Context Protocol - MCP)، والتي تُنفذ عادةً باستخدام أطر عمل مثل FastMCP.

بينما تتشارك هاتان الواجهتان في نفس المنطق التجاري الأساسي، إلا أنهما تختلفان في الآليات المحيطة بهما (التوجيه، التحقق من الصحة، التسلسل، البث، وصيانة المخطط Schema). هذا النهج "ثنائي المكدس" (dual-stack) يجبر المطورين على صيانة تعريفات مخطط منفصلة لكل منهما (واحد لـ HTTP/Pydantic، وآخر لـ MCP). ومع تطور الكود، تبتعد هذه التعريفات عن بعضها البعض، مما يؤدي إلى تقادم المخطط. وتستشهد الورقة بـ Patil et al. [9] للإشارة إلى أن النماذج اللغوية الكبيرة تهلوس باستدعاءات واجهة برمجة التطبيقات (API) عندما تغيب مخططات النوع أو تصبح قديمة، مما يجعل هذا التباعد خطراً على الموثوقية. علاوة على ذلك، وجد Mastouri et al. [10] تجريبياً أن 88.6% من خوادم MCP مدعومة بخدمات REST موجودة بالفعل، مما يعني أن الغالبية العظمى من عمليات النشر تحمل بالفعل عبء الصيانة المزدوجة هذه.

تعامل أطر العمل الحالية إما المسار (FastAPI) أو الأداة (FastMCP) ككيان أساسي، مما يتطلب عملية تسجيل منفصلة للأخرى. وهذا يجبر المطور على العمل كطبقة مزامنة بين الاثنين.

2. المنهجية: بنية "المهارة أولاً" (Skill-First Architecture)

يقترح HarnessAPI بنية "المهارة أولاً" التي تعكس التبعية. بدلاً من أن يقوم المطور بتعريف مسار ثم أداة (أو العكس)، يصبح مجلد المهارة (skill folder) هو المصدر الوحيد للحقيقة.

المبادئ التصميمية الأساسية

المصدر الوحيد للحقيقة: تُعرف المهارة كمجلد يحتوي على handler.py مُنمط ونماذج models.py من نوع Pydantic.
التمثيلات المشتقة: يستنتج الإطار تلقائياً كلاً من نقطة نهاية HTTP وتسجيل أداة MCP من هذا الهيكل المجلدي الوحيد.
الثابت الهيكلي: نظرًا لأن كلا النقلين (transports) يحلان إلى نموذج Pydantic نفسه وقت التشغيل، فإن اتساق المخطط يُفرض من خلال البناء وليس من خلال انضباط المطور.

الآليات التقنية الرئيسية

اكتشاف المهارة وعزلها:
- يقوم الإطار بفحص مجلد المهارات، وتحديد المجلدات الفرعية التي تحتوي على handler.py و models.py.
- لمنع تصادم الأسماء (على سبيل المثال، وجود مهارات متعددة تُعرف فئة باسم Input)، يقوم HarnessAPI بإنشاء مساحة اسم حزمة اصطناعية (synthetic package namespace) لكل مهارة باستخدام types.ModuleType. وهذا يسمح لعدة مهارات بالتعايش دون أن تحجب إحداها فئات الأخرى.
التفاوض على المحتوى ثنائي الوضع:
- يدعم الإطار الاستجابات التي تدعم البث وغير التي تدعم البث من معالج واحد.
- البث (SSE): إذا لم يطلب العميل application/json في الطلب، يفتح الإطار تدفق أحداث الخادم (Server-Sent Events - SSE). حيث يقوم بإنتاج أجزاء (chunks) بشكل تدريجي، مُصدراً أحداث chunk و result و done و error.
- الدفعات (JSON): إذا أرسل العميل Accept: application/json ، يقوم الإطار بتخزين مخرجات المعالج مؤقتاً وإرجاع استجابة JSON واحدة.
- يتيح هذا للمعالج نفسه خدمة جلسات الوكلاء التفاعلية (البث) وخطوط أنابيب الدفعات (JSON) دون تغيير في الكود.
توليد غلاف MCP الديناميكي:
- التحدي التقني الكبير الذي تمت معالجته هو فحص المخطط في FastMCP، والذي يعتمد على قراءة __annotations__ للدالة وحل الأنواع مقابل __globals__. تفشل الدوال المغلقة (closures) البسيطة لأن نموذج Pydantic لا يكون في النطاق العالمي (global scope) للدالة.
- الحل: يقوم HarnessAPI بتجميع دالة غلاف ديناميكياً باستخدام exec داخل مساحة اسم تتضمن صراحةً نموذج Pydantic. يضمن هذا إمكانية حل النوع بواسطة طبقة الفحص الخاصة بـ FastMCP، مما يسمح بتسجيل الأداة بشكل صحيح دون تكرار يدوي للمخطط.
إدارة دورة الحياة:
- يقوم HarnessAPI بوراثة FastAPI ويقوم بتركيب تطبيق FastMCP كتطبيق فرعي من نوع ASGI.
- يقوم بتنفيذ مدير سياق حياة مدمج (merged lifespan context manager) يجمع بين خطافات بدء التشغيل والإيقاف (startup/shutdown hooks) لتطبيق المستخدم (مثل اتصالات قاعدة البيانات) وخادم FastMCP، مما يتيح النشر في عملية واحدة (single-process deployment).
القدرة على التبديل السريع (للتطوير فقط):
- توجد نقطة نهاية اختيارية تسمح بإرسال نصوص برمجية لاستبدال منطق المعالج ديناميكياً. يتم تقييد هذا الصارم بعناوين الـ loopback (localhost) لمنع تنفيذ الكود عن بُعد في بيئة الإنتاج.

3. المساهمات الرئيسية

تحدد الورقة المساهمات التالية:

نمط بنية المهارة أولاً: نمط رسمي حيث يكون مجلد المهارة هو التعريف المرجعي، على عكس أنماط "المسار أولاً" (FastAPI) و"الأداة أولاً" (FastMCP).
آليات التنفيذ:
- توليد المسارات الديناميكية والتفاوض على المحتوى ثنائي الوضع.
- تقنية توليد الكود لنقل تعليقات (annotations) Pydemic إلى طبقة الفحص في FastMCP.
- استراتيجية دمج دورة الحياة للتشغيل في عملية واحدة.
تقليل الكود النمطي (Boilerplate): تقييم تجريبي يظهر انخفاضاً كبيراً في الكود المواجه للإطار.
الإصدار مفتوح المصدر: إصدار HarnessAPI v0.1.4، المتاح عبر PyPI و GitHub.

4. نتائج التقييم

قيم المؤلفون HarnessAPI مقابل تنفيذ يدوي ثنائي المكدس (خوادم FastAPI و FastMCP منفصلة) باستخدام ست مهارات نموذجية: Echo، و Greet، و Summarize، و VectorNorm، و Classify، و Translate.

تقليل الكود النمطي: باستخدام أداة cloc لحساب الأسطر غير الفارغة وغير المعلقة (باستثناء منطق العمل)، تطلب HarnessAPI 44 سطراً فقط عبر جميع المهارات الست، مقارنة بـ 170 سطراً للتنفيذ اليدوي. يمثل هذا انخفاضاً بنسبة 74% في الكود النمطي.
سلوك التوسع: يظهر النهج اليدوي توسعاً من رتبة $O(n)$ ، حيث ينمو كود الإطار خطياً مع عدد المهارات (كل منها يتطلب زخارف وتسجيلات جديدة). أما HarnessAPI فيظهر توسعاً من رتبة $O(1)$ فيما يتعلق بكود الإطار، حيث تظل نقطة الدخول ثابتة بغض النظر عن عدد المهارات.
تطابق الميزات: يوفر HarnessAPI جميع ميزات FastAPI و FastMCP المستقلة بشكل مباشر، بما في ذلك بث SSE، وواجهة OpenAPI/Swagger UI، والمهلات الزمنية لكل مهارة، دون الحاجة إلى تكامل مكتبات إضافية.
التوافق: نجح الإطار في استيراد وتسجيل 12 مهارة موجودة من مستودع agentskills.io دون تعديل الكود المصدري، مما يدل على نشر خالٍ من الاحتكاك لمجموعات المهارات الحالية.

5. الأهمية والادعاءات

تدعي الورقة أن HarnessAPI يحل "الإجابة غير المريحة" المتمثلة في الصيانة المزدوجة لنشر أدوات LLM. تكمن أهميته في تحويل اتساق المخطط من انضباط المطور (المعرض للخطأ والتباعد) إلى ثابت هيكلي يفرضه الإطار.

يؤكد المؤلفون أن تقليل الكود النمطي بنسبة 74% هو نتيجة لهذا الثابت، ولكن النتيجة الأكثر ديمومة هي خاصية التوسع. مع نضوج أنظمة الوكلاء ونشر المطورين لعشرات أو مئات المهارات، تصبح عبء الصيانة المتراكم للتسجيل اليدوي ثنائي المكدس أمراً غير قابل للاستمرار. يقترح HarnessAPI أن الحل ليس في توفير أدوات أفضل لصيانة تسجيلين، بل في إلغاء التسجيل الثاني تماماً.

تظل الورقة متواضعة فيما يتعلق بنطاقها:

لا تدعي حل مشكلات زمن الوصول (latency) أو اختبارات التزامن من البداية إلى النهاية، بل تكتفي بالخصائص المعروفة لمجموعة FastAPI/Uvicorn الأساسية.
تقر بوجود قيود، مثل استخدام exec لتوليد غلاف MCP (كحل مؤقت لـ resolver الخاص بـ FastMCP حالياً) وعدم وجود مصادقة لكل أداة في طبقة MCP.
تحذر صراحة من استخدام نقطة نهاية التبديل السريع في عمليات النشر التي يمكن الوصول إليها عبر الشبكة، وحصرها في حلقات التطوير المحلي.

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