مرجع البيان

كل برنامج مصغر أو إضافة أو plugin يتطلب ملف manifest.json يصف بيانات الامتداد الوصفية والأذونات ونقاط الدخول. يتبع البيان مخطط البيان v2.

مثال بسيط

أبسط بيان صالح لبرنامج مصغر:

{
  "name": "my-app",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "entry": "index.html",
  "base_url": "https://cdn.example.com/my-app/"
}

مثال كامل

بيان كامل بجميع الحقول الشائعة:

{
  "name": "word-counter",
  "version": "1.2.0",
  "abi": 1,
  "type": "mini-program",
  "title": "عداد الكلمات",
  "description": "عد الكلمات في سجل محادثاتك حسب الدور وتصور الاتجاهات",
  "icon": "https://cdn.example.com/word-counter/icon.png",
  "author": {
    "name": "Jane Developer",
    "url": "https://janedev.com"
  },
  "entry": "index.html",
  "base_url": "https://cdn.example.com/word-counter/",
  "permissions": ["storage", "chat:read", "ui:toast"],
  "keywords": ["إحصائيات", "أداة مساعدة", "عدد-الكلمات"],
  "license": "MIT",
  "repository": "https://github.com/janedev/word-counter",
  "min_platform_version": "1.0.0"
}

مرجع الحقول

الحقول المطلوبة

`name`

اسم الحزمة الفريد. يُستخدم كمعرف داخلي لعزل التخزين وفحوصات التثبيت وبحوث السجل.

الخاصية	القيمة
النوع	`string`
النمط	`^[a-z0-9-]+$` (أحرف صغيرة، أرقام، واصلات فقط)
الحد الأقصى للطول	64 حرفاً
مطلوب	نعم

"name": "word-counter"

حذر

يجب أن يكون الاسم فريداً عالمياً داخل السجل. اختر اسماً وصفياً. لا يمكنك تغييره بعد النشر دون إنشاء إدخال حزمة جديد.

`version`

سلسلة الإصدار الدلالي. يجب أن تتبع تنسيق semver.

الخاصية	القيمة
النوع	`string`
النمط	`^\d+\.\d+\.\d+` (رئيسي.ثانوي.تصحيح، إصدار أولي اختياري)
مطلوب	نعم

"version": "1.0.0"

عند تحديث تطبيقك في السجل، قم بزيادة الإصدار في كل من البيان وإدخال registry/packages.json.

الحقول الموصى بها بشدة

`abi`

إصدار ABI (واجهة البناء الثنائية) الذي يستهدفه هذا البيان. يجب أن يكون 1 للمنصة الحالية.

الخاصية	القيمة
النوع	`integer`
ثابت	`1`
مطلوب	تقنياً اختياري، لكن موصى به بشدة

"abi": 1

ترفض المنصة البيانات بقيم abi غير 1. إذا حُذف، تفترض المنصة ABI 1 لكن الإعلان الصريح مُفضل للتوافق المستقبلي.

`type`

نوع الامتداد. يحدد بيئة التشغيل والقدرات المتاحة.

الخاصية	القيمة
النوع	`string`
قيم مقبولة	`"plugin"`، `"addon"`، `"mini-program"`
الافتراضي	`"plugin"`

"type": "mini-program"

النوع	وقت التشغيل	سطح واجهة المستخدم	المتطلبات
`plugin`	WASM (فتحات kernel 4-7)	لا شيء (خطافات فقط)	`wasm` + `wasm_sha256`
`addon`	WASM أو JS	فتحات واجهة مستخدم مُسمّاة	`wasm` أو `entry`
`mini-program`	iframe معزل (أصل null)	لوحة كاملة (يستبدل المحادثة)	`entry` + `base_url`

`entry`

المسار إلى ملف HTML للمدخل، نسبي لـ base_url.

الخاصية	القيمة
النوع	`string`
مطلوب	نعم للبرامج المصغرة وإضافات HTML

"entry": "index.html"

تجلب المنصة {base_url}{entry} وقت التثبيت وتخزن HTML مؤقتاً للاستخدام دون اتصال.

`base_url`

URL الأساسي لحل ملف المدخل ومسارات الأصول النسبية (الصور، السكربتات، أوراق الأنماط).

الخاصية	القيمة
النوع	`string` (URI)
مطلوب	نعم للبرامج المصغرة

"base_url": "https://cdn.example.com/word-counter/"

يتم حقن علامة <base href="{base_url}"> في iframe بحيث تحل المسارات النسبية في HTML الخاص بك بشكل صحيح.

معلومات

للحزم .ais المثبتة من رفع الملف، يُضبط base_url على local:// تلقائياً حيث يتم تضمين جميع الأصول.

حقول البيانات الوصفية الاختيارية

`title`

اسم العرض البشري المقروء الظاهر في متجر التطبيقات ومربع حوار الأذونات. إذا حُذف، يُستخدم name.

الخاصية	القيمة
النوع	`string`

"title": "عداد الكلمات"

`description`

وصف قصير لقائمة المتجر ومربع حوار الأذونات.

الخاصية	القيمة
النوع	`string`
الحد الأقصى للطول	256 حرفاً

"description": "عد الكلمات في سجل محادثاتك حسب الدور وتصور الاتجاهات"

`icon`

URL لصورة أيقونة مربعة. الحجم الموصى به: 128x128 PNG. تُعرض في شبكة التطبيقات وقائمة المتجر.

الخاصية	القيمة
النوع	`string` (URI)

"icon": "https://cdn.example.com/word-counter/icon.png"

تلميح

استخدم PNG مربع بحجم 128x128 بكسل بخلفية شفافة أو داكنة لتتناسب مع المظهر الداكن للمنصة. SVG مقبول أيضاً.

`author`

معلومات المؤلف.

الخاصية	القيمة
النوع	`object`
الخصائص	`name` (نص، حد أقصى 100)، `url` (نص، URI)

"author": {
  "name": "Jane Developer",
  "url": "https://janedev.com"
}

`license`

معرف ترخيص SPDX.

الخاصية	القيمة
النوع	`string`

"license": "MIT"

`repository`

URL مستودع المصدر.

الخاصية	القيمة
النوع	`string` (URI)

"repository": "https://github.com/janedev/word-counter"

`keywords`

كلمات مفتاحية للبحث للاكتشاف في متجر التطبيقات.

الخاصية	القيمة
النوع	`string[]`
الحد الأقصى للعناصر	10
الحد الأقصى لكل كلمة مفتاحية	32 حرفاً

"keywords": ["إحصائيات", "أداة مساعدة", "عدد-الكلمات"]

`min_platform_version`

الحد الأدنى لإصدار منصة AISCouncil المطلوب لتشغيل هذا الامتداد.

الخاصية	القيمة
النوع	`string` (semver)

"min_platform_version": "1.0.0"

الأذونات

`permissions`

مصفوفة سلاسل الأذونات التي يطلبها الامتداد. يجب على المستخدم الموافقة عليها وقت التثبيت.

الخاصية	القيمة
النوع	`string[]`
عناصر فريدة	نعم

"permissions": ["storage", "chat:read", "ui:toast"]

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

الإذن	الوصف	ممنوح تلقائياً؟
`storage`	تخزين قيم-مفتاح معزل لكل تطبيق	نعم (مسموح دائماً)
`chat:read`	قراءة سجل المحادثة والاشتراك في الرسائل الجديدة	لا
`chat:write`	إرسال رسائل كمستخدم (يحفز استجابات الذكاء الاصطناعي)	لا
`config:read`	قراءة إعدادات البوت النشط (الموفر، النموذج، موجه النظام)	لا
`config:write`	تعديل إعدادات البوت النشط	لا
`auth:read`	قراءة معلومات المستخدم (الاسم، البريد، صورة الملف الشخصي) ومستوى الاشتراك	لا
`ui:toast`	إظهار إشعارات toast في واجهة المستخدم للمنصة	لا
`ui:modal`	إظهار مربعات حوار التأكيد	لا
`hooks:action`	تسجيل وإطلاق أحداث الخطافات	لا
`hooks:filter`	تسجيل خطافات التصفية	لا
`network:fetch`	إجراء طلبات شبكية موسطة عبر المنصة (مستقبلاً)	لا
`secrets:sync`	قراءة وكتابة مفاتيح API للنقل بين الأجهزة	لا
`pages:publish`	نشر صفحات ويب إلى bcz.co	لا

تحذير

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

حقول Plugin الخاصة

تُستخدم هذه الحقول بواسطة plugins وإضافات WASM، وليس البرامج المصغرة.

`wasm`

URL للثنائي WASM.

الخاصية	القيمة
النوع	`string` (URI)
مطلوب	لـ plugins

"wasm": "https://cdn.example.com/my-plugin/plugin.wasm"

`wasm_sha256`

ملخص SHA-256 سداسي عشري للثنائي WASM للتحقق من السلامة.

الخاصية	القيمة
النوع	`string`
النمط	`^[0-9a-f]{64}$`
مطلوب	لـ plugins

"wasm_sha256": "a1b2c3d4e5f6..."

`segment_size`

حجم قطعة ذاكرة وحدة WASM بالبايت.

الخاصية	القيمة
النوع	`integer`
الحد الأدنى	0

"segment_size": 4194304

الحقول المتقدمة

`pages`

مسارات صفحات إضافية للبرامج المصغرة متعددة الصفحات.

الخاصية	القيمة
النوع	`string[]`

"pages": ["settings.html", "about.html"]

`hooks`

تسجيلات الخطافات لـ plugins والإضافات. كل خطاف له اسم وأولوية اختيارية.

الخاصية	القيمة
النوع	`object[]`

"hooks": [
  { "name": "chat:before-send", "priority": 50 },
  { "name": "message:filter", "priority": 100 }
]

يجب أن تتطابق أسماء الخطافات مع ^[a-z][a-z0-9_.:-]*$ وأن تكون بحد أقصى 128 حرفاً. تتراوح الأولوية من 0 (الأقدم) إلى 999 (الأحدث)، الافتراضي 100.

`settings`

إعدادات قابلة للتكوين من قبل المستخدم تظهر في واجهة إعدادات المنصة.

الخاصية	القيمة
النوع	`object` (المفاتيح هي أسماء الإعدادات، القيم هي تعريفات الإعدادات)

"settings": {
  "theme": {
    "type": "select",
    "label": "مظهر الألوان",
    "default": "dark",
    "options": [
      { "value": "dark", "label": "داكن" },
      { "value": "light", "label": "فاتح" }
    ]
  },
  "maxMessages": {
    "type": "number",
    "label": "الحد الأقصى للرسائل للتحليل",
    "default": 500,
    "description": "تحديد عدد رسائل المحادثة المحملة"
  },
  "autoRefresh": {
    "type": "boolean",
    "label": "تحديث تلقائي عند الفتح",
    "default": true
  }
}

أنواع الإعدادات: string، number، boolean، select.

`mcp_tools`

إعلانات أدوات MCP (بروتوكول سياق النموذج) التي يوفرها هذا الامتداد.

الخاصية	القيمة
النوع	`object[]`

"mcp_tools": [
  {
    "name": "count-words",
    "description": "عد الكلمات في النص المحدد",
    "inputSchema": {
      "type": "object",
      "properties": {
        "text": { "type": "string" }
      },
      "required": ["text"]
    }
  }
]

متطلبات خاصة بالنوع

الحقل	Plugin	إضافة	برنامج مصغر
`name`	مطلوب	مطلوب	مطلوب
`version`	مطلوب	مطلوب	مطلوب
`type`	`"plugin"`	`"addon"`	`"mini-program"`
`wasm`	مطلوب	مطلوب إذا لم يكن هناك `entry`	غير مستخدم
`wasm_sha256`	مطلوب	مطلوب عند استخدام `wasm`	غير مستخدم
`entry`	غير مستخدم	مطلوب إذا لم يكن هناك `wasm`	مطلوب
`base_url`	غير مستخدم	اختياري	مطلوب

التحقق

استخدم سكربت التحقق المدمج للتحقق من بيانك قبل النشر:

# التحقق من ملف بيان واحد
python3 registry/validate.py manifest path/to/manifest.json

يتحقق المدقق من:

الحقول المطلوبة موجودة
name يطابق النمط ^[a-z0-9-]+$ وبحد أقصى 64 حرفاً
version هو semver صالح
abi هو 1 (إذا كان موجوداً)
type هو واحد من plugin، addon، mini-program
الأذونات من المجموعة المسموحة
الحقول المطلوبة الخاصة بالنوع موجودة (مثلاً، entry للبرامج المصغرة)
لا حقول غير معروفة (المخطط صارم مع additionalProperties: false)

تلميح

مخطط JSON منشور في registry/manifest-schema.json. يمكنك استخدامه مع أي مدقق JSON Schema للتكامل مع IDE أو خطوط CI.

مرجع المخطط

مخطط البيان مُعرّف كـ JSON Schema (Draft 2020-12) ومتاح في:

https://aiscouncil.net/schema/manifest/v2

ارجع إليه في بيانك للإكمال التلقائي في المحرر:

{
  "$schema": "https://aiscouncil.net/schema/manifest/v2",
  "name": "my-app",
  "version": "1.0.0"
}

معظم المحررات (VS Code، JetBrains، إلخ) ستوفر الإكمال التلقائي والتحقق عند وجود الحقل $schema.

مثال بسيط​

مثال كامل​

مرجع الحقول​

الحقول المطلوبة​

name​

version​

الحقول الموصى بها بشدة​

abi​

type​

entry​

base_url​

حقول البيانات الوصفية الاختيارية​

title​

description​

icon​

author​

license​

repository​

keywords​

min_platform_version​

الأذونات​

permissions​

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

حقول Plugin الخاصة​

wasm​

wasm_sha256​

segment_size​

الحقول المتقدمة​

pages​

hooks​

settings​

mcp_tools​

متطلبات خاصة بالنوع​

التحقق​

مرجع المخطط​