مواصفة بيان المهارة

مواصفة بيان مهارة كاظمه

الإصدار: 1.0.0 | الحالة: نشطة | آخر تحديث: 2026-06-20

تُعرِّف هذه الوثيقة المواصفة الرسمية لبيانات مهارات كاظمه (skill_manifest.yaml). كل مهارة تُثبَّت في كاظمه يجب (MUST) أن تتضمّن ملف بيان صالحًا في دليلها الجذري.

جدول المحتويات

نظرة عامة
مخطط YAML
الحقول المطلوبة
الحقول الاختيارية
مرجع الحقول
نموذج الأذونات
إعداد خوادم MCP
قواعد الإصدارات
قواعد التحقق
درجات الأمان
أمثلة

نظرة عامة

بيان المهارة هو ملف YAML ‏(skill_manifest.yaml) يقع في جذر دليل المهارة. يصرّح بهوية المهارة وقدراتها وتبعياتها وأذوناتها وإعداد وقت التشغيل.

موضع البيان

my-skill/
├── skill_manifest.yaml    # This file
├── main.py                # Entry point (optional)
└── ...

يبحث المُتحقِّق عن skill_manifest.yaml تحديدًا (وليس manifest.yaml أو manifest.yml).

مخطط YAML

# ─── Required Fields ────────────────────────────────────────────────
name: string               # kebab-case identifier
version: string            # semver X.Y.Z
description: string        # human-readable description
author: string             # author name or organization
license: string            # SPDX license identifier

# ─── Optional Fields ────────────────────────────────────────────────
capabilities: [string]     # list of capability tags
dependencies:              # dependency constraints
  core: string             #   minimum core version (semver range)
  optional: [string]       #   optional Python package names
mcp_servers:               # MCP server configurations
  - name: string           #   server identifier
    type: string           #   transport type (stdio|sse|streamable-http)
    command: [string]      #   command to start server (for stdio)
    url: string            #   server URL (for sse/streamable-http)
    env: {string: string}  #   environment variables
permissions:               # permission declarations
  required: [string]       #   permissions needed for core functionality
  optional: [string]       #   permissions for enhanced features
entry_point: string        # dotted module path or file name (without .py)
config_schema: object      # JSON Schema for skill configuration
min_core_version: string   # minimum Kazma core version (semver)
tags: [string]             # searchable tags
homepage: string           # project homepage URL
repository: string         # source repository URL

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

يجب حضور الحقول الخمسة المطلوبة كلها. يفشل التحقق إن غاب أيٌّ منها.

`name`

النوع: string
النمط: ^[a-z][a-z0-9-]*$ (kebab-case)
الوصف: معرّف فريد للمهارة. يجب أن يبدأ بحرف صغير، وألّا يحوي إلا أحرفًا صغيرة وأرقامًا ووصلات.
أمثلة: drone-inspector, oil-pricing-v2, arabic-ocr

أخطاء التحقق:

حقل مفقود → "Missing required field: name"
صيغة غير صالحة → "Name must be kebab-case, got: 'MySkill'"

`version`

النوع: string
النمط: ^\d+\.\d+\.\d+$ (semver بسيط)
الوصف: الإصدار الدلالي للمهارة.
أمثلة: 1.0.0, 0.1.0, 2.3.1

أخطاء التحقق:

حقل مفقود → "Missing required field: version"
صيغة غير صالحة → "Version must be valid semver (X.Y.Z), got: 'v1.0.0'"

ملاحظة: لواحق ما قبل الإصدار (1.0.0-beta) وبيانات البناء (1.0.0+build) غير مدعومة. استخدم X.Y.Z البسيط فقط.

`description`

النوع: string
الوصف: وصف موجز ومقروء بشريًّا لغرض المهارة.
أمثلة: "Read files from the filesystem", "Arabic OCR with RTL layout support"

`author`

النوع: string
الوصف: اسم مؤلف المهارة أو المنظمة.
أمثلة: "ALMuhalab International Holding Group", "Jane Doe"

`license`

النوع: string
الوصف: معرّف ترخيص SPDX.
أمثلة: MIT, Apache-2.0, GPL-3.0-only

أخطاء التحقق:

فارغ أو مسافات فقط → "License must be a non-empty string"

الحقول الاختيارية

هذه الحقول غير مطلوبة لكنها تعزّز وظائف المهارة وقابليتها للاكتشاف.

`capabilities`

النوع: list[string]
الوصف: وسوم تصف ما تستطيع المهارة فعله. تُستخدم لكشف التعارض عند تشارك مهارتين القدرات نفسها.
أمثلة: ["drone_inspection", "trading_intelligence"], ["audio", "video"]

`dependencies`

النوع: object
الوصف: تبعيات حزم Python.
الحقول الفرعية:
- core (سلسلة نصية): الحد الأدنى المطلوب من إصدار نواة كاظمه (مثل ">=0.1.0")
- optional (قائمة سلاسل نصية): حزم Python اختيارية تستخدمها المهارة

dependencies:
  core: ">=0.1.0"
  optional:
    - numpy
    - paho-mqtt
    - opencv-python

`mcp_servers`

النوع: list[object]
الوصف: خوادم MCP ‏(Model Context Protocol) التي تتطلبها هذه المهارة.
يجب أن يحوي كل مدخل: name (سلسلة نصية) وtype (سلسلة نصية)
انظر: إعداد خوادم MCP

`permissions`

النوع: object أو list[string]
الوصف: الأذونات التي تتطلبها المهارة. يمكن أن تكون قائمة بسيطة أو منظمة بقائمتي فرعيتين required/optional.
انظر: نموذج الأذونات

# Simple form
permissions:
  - file_read
  - network_outbound

# Structured form
permissions:
  required:
    - file_read
  optional:
    - camera_access

`entry_point`

النوع: string
الوصف: مسار وحدة Python أو اسم الملف (من دون الامتداد .py) الذي يشكّل نقطة دخول المهارة.
أمثلة: "main", "my_skill.main:run", "src.plugin"

تحذيرات:

المسارات النسبية (المحتوية على / أو البادئة بـ .) تولّد تحذيرًا: استخدم مسارات وحدات منقّطة بدلًا منها.

`config_schema`

النوع: object
الوصف: مخطط JSON يُعرِّف خيارات إعداد المهارة. تستخدمه الواجهة لتوليد نماذج الإعداد.

config_schema:
  type: object
  properties:
    api_key:
      type: string
      description: "API key for external service"
    max_retries:
      type: integer
      default: 3
  required:
    - api_key

`min_core_version`

النوع: string
النمط: ^\d+\.\d+\.\d+$ (semver)
الوصف: الحد الأدنى لإصدار نواة كاظمه اللازم لتشغيل هذه المهارة. إن كان إصدار النواة المثبَّت أدنى من ذلك، فلن تُحمَّل المهارة.
أمثلة: "0.5.0", "1.0.0"

`tags`

النوع: list[string]
الوصف: وسوم قابلة للبحث لاكتشاف المهارة في الـ hub.
أمثلة: ["testing", "example"], ["data", "oil-gas"]

`homepage`

النوع: string (رابط URL)
الوصف: رابط الصفحة الرئيسية للمشروع.
مثال: "https://example.com/my-skill"

`repository`

النوع: string (رابط URL)
الوصف: رابط مستودع الكود المصدري.
مثال: "https://github.com/example/my-skill"

مرجع الحقول

الحقل	مطلوب	النوع	الافتراضي	الوصف
`name`	نعم	string (kebab)	—	معرّف فريد للمهارة
`version`	نعم	string (semver)	—	إصدار دلالي
`description`	نعم	string	—	وصف مقروء بشريًّا
`author`	نعم	string	—	المؤلف أو المنظمة
`license`	نعم	string (SPDX)	—	معرّف الترخيص
`capabilities`	لا	list[string]	`[]`	وسوم القدرات
`dependencies`	لا	object	`{}`	تبعيات حزم Python
`mcp_servers`	لا	list[object]	`[]`	إعدادات خوادم MCP
`permissions`	لا	object/list	`[]`	تصريحات الأذونات
`entry_point`	لا	string	None	نقطة دخول الوحدة
`config_schema`	لا	object	None	مخطط JSON للإعداد
`min_core_version`	لا	string (semver)	None	الحد الأدنى لإصدار النواة
`tags`	لا	list[string]	`[]`	وسوم قابلة للبحث
`homepage`	لا	string (URL)	None	الصفحة الرئيسية للمشروع
`repository`	لا	string (URL)	None	مستودع الكود المصدري

نموذج الأذونات

تُصرِّح الأذونات بموارد النظام التي تحتاج المهارة إلى الوصول إليها. تتحقق كاظمه من الأذونات مقابل قائمة سماح، وتحتسب الأذونات غير المعروفة في درجة الأمان.

قيم الأذونات المسموح بها

الإذن	الوصف
`file_read`	قراءة ملفات من نظام الملفات
`file_write`	كتابة/إنشاء ملفات على نظام الملفات
`network_outbound`	إجراء طلبات شبكة صادرة
`network_inbound`	قبول اتصالات شبكة واردة
`camera_access`	الوصول إلى كاميرا الجهاز
`mqtt_broker`	الاتصال بوسطاء MQTT
`database_read`	القراءة من قواعد البيانات
`database_write`	الكتابة إلى قواعد البيانات

صيغ التصريح عن الأذونات

قائمة بسيطة (كلها مطلوبة):

permissions:
  - file_read
  - network_outbound

منظمة (مطلوبة + اختيارية):

permissions:
  required:
    - file_read
    - network_outbound
  optional:
    - camera_access
    - mqtt_broker

التحقق

يُفحص كل إذن مقابل قائمة السماح
تولّد الأذونات غير المعروفة تحذيرًا وتخصم -5 من درجة الأمان
الأذونات لا تسبب فشل التحقق (إنها استشارية)

إعداد خوادم MCP

توفر خوادم MCP قدرات أدوات خارجية للمهارات. يتطلب كل مدخل خادم name وtype.

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

الحقل	النوع	الوصف
`name`	string	معرّف الخادم (فريد)
`type`	string	نوع النقل (انظر أدناه)

أنواع النقل

النوع	الوصف	حقول إضافية
`stdio`	عملية محلية عبر stdin/stdout	`command`, `env`
`sse`	نقطة نهاية HTTP بـ Server-Sent Events	`url`
`streamable-http`	نقطة نهاية HTTP قابلة للبث	`url`

مثال: خادم stdio

mcp_servers:
  - name: oil-pricing-api
    type: stdio
    command: ["python", "-m", "oil_pricing_server"]
    env:
      API_KEY: "${OIL_API_KEY}"

مثال: خادم SSE

mcp_servers:
  - name: remote-analytics
    type: sse
    url: "https://analytics.example.com/mcp"

التحقق

غياب name → خطأ
غياب type → خطأ
type غير صالح → خطأ (يجب أن يكون stdio أو sse أو streamable-http)
mcp_servers ليست قائمة → خطأ

قواعد الإصدارات

تستخدم كاظمه semver صارمًا (X.Y.Z) لكل حقول الإصدارات.

الصيغة

MAJOR.MINOR.PATCH

MAJOR (X): تغييرات كاسرة
MINOR (Y): ميزات جديدة، متوافقة مع الإصدارات السابقة
PATCH (Z): إصلاحات أخطاء، متوافقة مع الإصدارات السابقة

القواعد

يجب حضور الأجزاء الثلاثة كلها: 1.0 غير صالح، و1.0.0 صالح
يجب أن تكون الأجزاء أعدادًا صحيحة غير سالبة: 1.0.0 صالح، و-1.0.0 ليس صالحًا
لا لواحق ما قبل الإصدار: 1.0.0-beta غير صالح
لا بيانات بناء: 1.0.0+build123 غير صالح
لا بادئة v: v1.0.0 غير صالح

فحص التوافق

يستخدم حقل min_core_version مقارنة semver:

# Pseudo-code
skill_version >= min_core_version

مثال: مهارة ذات min_core_version: "0.5.0" تتطلب إصدار نواة 0.5.0 أو أعلى.

كشف التعارض

عند تثبيت مهارة جديدة:

الاسم نفسه: استبدال (مع تحذير)
القدرات نفسها: تحذير (تعارض محتمل)
عبر الإصدارات: فحص توافق عبر min_core_version

قواعد التحقق

يجري التحقق عبر SkillValidator (في kazma-core/kazma_core/hub/validator.py) الذي يشغّل خمسة فحوص:

الفحص 1: البيان موجود وهو YAML صالح

يجب أن يوجد skill_manifest.yaml في جذر المهارة
يجب أن يكون مخطط YAML صالحًا (لا قائمة ولا قيمة مفردة)
الخصم: -30 نقطة إن غاب أو كان غير صالح

الفحص 2: التحقق من نقطة الدخول

إذا صُرِّح بـ entry_point، فيجب أن يوجد ملف .py المقابل
مثال: entry_point: main يتطلب main.py
الخصم: -10 نقاط إن غاب

الفحص 3: التحقق من الأذونات

يُفحص كل إذن مقابل قائمة السماح
الأذونات غير المعروفة تولّد تحذيرات
الخصم: -5 نقاط لكل إذن غير معروف

الفحص 4: التحقق من خوادم MCP

يجب أن يحوي كل خادم name وtype
يجب أن يكون type واحدًا من: stdio, sse, streamable-http
الخصم: فشل تحقق (قائمة الأخطاء)

الفحص 5: المسح الأمني

تُفحص كل ملفات .py في دليل المهارة بحثًا عن أنماط خطرة:

النمط	الكشف	الخصم
`eval()`	`eval\s*\(`	-20
`exec()`	`exec\s*\(`	-20
`__import__`	`\b__import__\b`	-15
`os.system()`	`os\.system\s*\(`	-25
أسرار مكتوبة في الكود	أنماط متنوعة	-10 لكل ملف

أنماط الأسرار المكتشفة:

api_key = "..." أو api_secret = "..."
password = "..." أو passwd = "..."
secret = "..." أو secret_key = "..."
token = "..." أو access_token = "..."

حساب الدرجة

الدرجة الأساسية: 100
يعيد كل فحص فرقًا (صفرًا أو سالبًا)
الدرجة النهائية: max(0, min(100, 100 + sum(deltas)))
ينجح التحقق فقط إذا كانت الأخطاء صفرًا
التحذيرات استشارية (لا تحجب التثبيت)

درجات الأمان

تعكس درجة الأمان (0-100) الملف الأمني للمهارة:

نطاق الدرجة	التقييم	المعنى
90-100	ممتاز	لا مشكلات، آمنة للتثبيت
70-89	جيد	تحذيرات طفيفة، آمنة عمومًا
50-69	حذر	عدة مشكلات، راجِع قبل التثبيت
0-49	محفوفة بالمخاطر	مخاوف أمنية جوهرية

شارة معتمد من كاظمه

تنال المهارة شارة معتمد من كاظمه (Kazma-Certified) عندما:

ينجح التحقق (صفر أخطاء)
درجة الأمان >= 90
كل الحقول المطلوبة حاضرة
تستخدم خوادم MCP أنواعًا صالحة
عدم اكتشاف أسرار مكتوبة في الكود

أمثلة

بيان أدنى

name: hello-world
version: 1.0.0
description: "A simple hello world skill"
author: "Example Author"
license: MIT

بيان كامل الميزات

name: drone-inspection
version: 2.1.0
description: "AI-powered drone inspection with YOLO detection and telemetry"
author: "ALMuhalab International Holding Group"
license: Apache-2.0

capabilities:
  - drone_inspection
  - computer_vision
  - telemetry_analysis

dependencies:
  core: ">=0.5.0"
  optional:
    - numpy
    - opencv-python
    - paho-mqtt

mcp_servers:
  - name: oil-pricing-api
    type: stdio
    command: ["python", "-m", "oil_pricing_server"]
  - name: mqtt-broker
    type: sse
    url: "mqtt://broker.local:1883"

permissions:
  required:
    - file_read
    - file_write
    - network_outbound
    - mqtt_broker
  optional:
    - camera_access

entry_point: main
config_schema:
  type: object
  properties:
    broker_url:
      type: string
      default: "mqtt://localhost:1883"
    yolo_model:
      type: string
      default: "yolov11"
  required:
    - broker_url

min_core_version: "0.5.0"
tags:
  - drone
  - inspection
  - oil-gas
  - computer-vision

homepage: "https://example.com/drone-inspection"
repository: "https://github.com/example/drone-inspection"

مهارة مؤسسية بأذونات الأقسام

name: trading-intelligence
version: 1.0.0
description: "Market data analysis and trading intelligence for general trading division"
author: "ALMuhalab International Holding Group"
license: MIT

capabilities:
  - trading_intelligence
  - market_analysis

dependencies:
  core: ">=0.1.0"
  optional:
    - pandas
    - requests

mcp_servers:
  - name: market-data-api
    type: stdio
    command: ["python", "-m", "market_data_server"]
  - name: news-aggregator
    type: sse
    url: "https://news-api.example.com/mcp"

permissions:
  required:
    - network_outbound
    - database_read

entry_point: intelligence_loop

min_core_version: "0.1.0"
tags:
  - trading
  - finance
  - market-data

مهارة واعية بالعربية

name: arabic-doc-processor
version: 1.0.0
description: "Process Arabic documents with RTL layout and diacritics support"
author: "Kazma Community"
license: MIT

capabilities:
  - arabic_nlp
  - document_processing

mcp_servers:
  - name: arabic-ocr
    type: stdio
    command: ["npx", "-y", "@anthropic-ai/arabic-ocr-mcp"]

permissions:
  required:
    - file_read
    - file_write

entry_point: processor
min_core_version: "0.1.0"
tags:
  - arabic
  - nlp
  - rtl
  - ocr

ملحق: صيغة ملف البيان

يجب أن يُسمّى ملف البيان skill_manifest.yaml حرفيًّا (وليس manifest.yaml أو manifest.yml أو أي صيغة أخرى).

بنية الملف

# Lines starting with # are comments (YAML standard)
# Top-level keys are case-sensitive
# Use double quotes for strings containing special characters

name: my-skill
version: 1.0.0
description: "Description here"
author: "Author Name"
license: MIT

# ... optional fields ...

الترميز

يجب أن يكون الملف UTF-8 صالحًا
يجب أن يُفسَّر YAML بلا أخطاء
المحارف يونيكود مسموح بها (مثل النص العربي في الأوصاف)

حدود الحجم

الحد الأقصى لحجم الملف: 64 كيلوبايت
الحد الأقصى لعدد خوادم MCP: 20
الحد الأقصى لعدد القدرات: 50
الحد الأقصى لعدد الوسوم: 20