ard.json

‫"استكشاف الموارد المستندة إلى الذكاء الاصطناعي الوكيل" (ARD) هو مواصفات لفهرسة الموارد المستندة إلى الذكاء الاصطناعي الوكيل. يصف ملف بيان ard.json الموارد المستندة إلى الوكلاء في نطاق معيّن، مثل خوادم MCP ووكلاء A2A ومهارات الوكلاء، لكي يتمكّن وكلاء الذكاء الاصطناعي والسجلات من العثور عليها.

آلية عمل تدقيق Lighthouse

عملية الاكتشاف: تبحث عملية التدقيق عن ملف البيان استنادًا إلى آليات الاكتشاف في مواصفات ARD (الفقرة 5.1):

  • جارٍ التحقّق من توجيه Agentmap: داخل robots.txt.
  • جارٍ فحص ملف HTML بحثًا عن علامات <link rel="ard" href="...">.
  • يتم فحص استجابة عنوان HTTP Link: <...>; rel="ard".
  • جارٍ الجلب من نقطة النهاية المعروفة /.well-known/ard.json.

إذا تعذّر الاكتشاف الأساسي، تتحقّق Lighthouse من المسارات القديمة (مثل rel="ai-catalog" أو /.well-known/ai-catalog.json). ومع أنّه يتم التحقّق من صحة المحتوى الذي يتم العثور عليه هنا، يتم إصدار تحذير لأنّ برامج ARD العادية غير مُلزَمة بإتاحة المسارات المتوقفة نهائيًا.

قواعد التحقّق: يتم إجراء عملية التحقّق باستخدام منفذ JavaScript من حزمة اختبار المطابقة ARD v0.91، ويتم الاختبار وفقًا للمعايير التالية:

أخطاء المطابقة والتحقّق:

  • بنية الجملة والمخطط: ملف البيان هو ملف JSON صالح ويتطابق مع مخطط بيان ARD، وكل إدخال يتطابق مع مخطط إدخال ARD. لا تجلب Lighthouse أو تتحقّق من صحة العنصر الذي يشير إليه الإدخال (على سبيل المثال، بطاقة خادم MCP على url).
  • الحقول المطلوبة: يحتوي ملف البيان على مصفوفة entries، ويتضمّن كل إدخال identifier وdisplayName وtype.
  • أسماء الموارد الموحّدة (URN) المرتبطة بالنطاق: يتّبع كل identifier التنسيق urn:air:<publisher>:<namespace>:<name>.
  • تعريف الموقع الجغرافي: يحدّد كل إدخال السمة url أو السمة data المضمّنة، ولا يمكن أن يحدّد كليهما أو لا يحدّد أيًا منهما.
  • بنية بيان الثقة: عند تضمين trustManifest، يكون عبارة عن عنصر يتضمّن السمة identity.

تحذيرات بشأن أفضل الممارسات:

  • طلبات البحث التمثيلية: يحتوي كل إدخال على مصفوفة representativeQueries تتضمّن من طلبَي بحث إلى 5 طلبات بحث نموذجية. تنشئ السجلات فهرس البحث الخاص بها من هذه، لذا لن يظهر الإدخال بدونها في نتائج البحث. (إذا كان موجودًا، يجب أن يكون مصفوفة من السلاسل، وأي شيء آخر هو خطأ).
  • نوع الوسائط: يجب أن يكون type نوع وسائط منسَّقًا بشكل صحيح. تحذّر أداة Lighthouse من الأنواع المتوقفة نهائيًا (مثل application/mcp-server+json إلى application/mcp-server-card+json)، والأنواع العادية التي تتضمّن معلمات مفقودة أو إضافية، والأنواع غير المعروفة خارج application/*. يُسمح باستخدام أنواع application/* المخصّصة.
  • Collections: تشير إلى حقل collections في المستوى الأعلى. لم يعُد جزءًا من ARD ويتم تجاهله، ويمكنك استخدام التسلسلات الهرمية للنماذج داخل entries بدلاً من ذلك.
  • نقاط النهاية القديمة: يتم وضع علامة على ملفات البيان التي يتم العثور عليها فقط من خلال مواقع ai-catalog القديمة.
  • المواقع الجغرافية المُعلَن عنها المعطّلة: يتم وضع علامة على أي موقع جغرافي مُعلَن عنه (رابط Agentmap: أو rel="ard" أو rel="ai-catalog" أو عنوان Link) تعذّر تحميله عندما تم العثور على البيان في مكان آخر.

غير مطلوبة:

  • لا يؤثر specVersion والحقول الإضافية الأخرى ذات المستوى الأعلى في النتيجة.
  • capabilities اختيارية ولا يتم تسجيلها. إذا كان المورد يعرض أدوات أو مهارات مُسمّاة، ننصحك بإدراجها (على سبيل المثال، ["WeatherTool", "ForecastTool"]) حتى تتمكّن السجلّات من فلترتها بدون جلب العنصر الكامل. في حال تضمينها، يجب أن تكون مصفوفة من السلاسل.

قراءة جدول النتائج

يعرض عمود "العنصر" القيمة Root للمشاكل المتعلّقة بملف البيان ككل. بالنسبة إلى المشاكل المتعلّقة بإدخال معيّن، يعرض هذا العمود displayName للإدخال، أو identifier، أو Entry #n إذا لم يكن أي منهما متاحًا. قد تظهر مشكلة واحدة في المخطط مرتين، مرة ضمن Root ومرة ضمن الإدخال، بما يتطابق مع نتائج اختبار المطابقة الرسمي.

فهم نتيجتك

تظهر نتائج التدقيق بالطرق التالية:

  • ناجح (1): تم العثور على ملف البيان ولا يحتوي على أي أخطاء أو تحذيرات.
  • رصيد جزئي (0.9): البيان صالح ولكنّه يتضمّن تحذيرًا واحدًا على الأقل بشأن أفضل الممارسات.
  • فشل (0): أي خطأ في المطابقة، مثل تنسيق JSON غير صالح أو انتهاك المخطط أو اسم مورد موحّد (URN) غير صالح أو كليهما أو أي من url/data. يفشل التدقيق أيضًا إذا تم الإعلان عن بيان (من خلال robots.txt أو رابط rel="ard" أو rel="ai-catalog" أو عنوان Link) ولكن تعذّر تحميله.
  • لا ينطبق: لم يتم العثور على أي بيان بأي طريقة. لا يؤثر ذلك في نتيجة Lighthouse.

كيفية حلّ المشكلة

لاجتياز التدقيق، اتّبِع الخطوات التالية:

  1. يُرجى عرض ملف البيان على /.well-known/ard.json أو ربطه بـ rel=ard. إذا كنت تستخدم ai-catalog.json أو rel=ai-catalog، انتقِل إلى الأسماء الجديدة.
  2. أصلِح أي أخطاء مُدرَجة في جدول التدقيق ليتطابق ملف البيان مع مخطّط ARD.
  3. أضِف معرّف urn:air:... إلى كل إدخال، وأضِف أيضًا إما url أو data.
  4. استخدِم نوع وسائط ARD عاديًا في type حيثما ينطبق ذلك.
  5. أضِف من 2 إلى 5 representativeQueries إلى كل إدخال للحصول على نتيجة مثالية.