المهارات وMCP والأدوات

بيانات المهارات، التوقيع التشفيري، وسائل نقل MCP، تصنيف الأدوات، المركز (Hub)، وكيفية توسيع كاظمة بأدوات جديدة — جميعها مع مرجعية المصدر.

---

1. المفاهيم

المصطلح	المعنى
الأداة (Tool)	دالة يستطيع المُشرف استدعاءها (عمليات الملفات، الصدفة، الذاكرة، الويب، …). مُسجَّلة في ToolRegistry.
المهارة (Skill)	نقطة دخول Python مُغلَّفة وموقّعة اختياريًا + بيان يُسجِّل أداة واحدة أو أكثر. تعيش تحت kazma-skills/manifests/ أو في سجلّ المركز (Hub).
خادم MCP	خادم خارجي لبروتوكول سياق النموذج (MCP) (stdio أو SSE) تُكتشف أدواته أثناء التشغيل وتُمرَّر داخل الوكيل.
المركز (Hub)	سجلّ/سوق المهارات (kazma hub …) مع الشهادة والتوقيع.

---

2. سجلّ الأدوات (ToolRegistry)

kazma-core/kazma_core/agent/tool_registry.py هو السجلّ الذي يستشيره المُشرف في كل دورة. النقاط الرئيسية:

• execute(tool_name, arguments) (tool_registry.py:335) — مسار التنفيذ الوحيد. وهو يقوم بـ:
  1. إزالة _hitl_approved من الوسائط (السطر 349) — علامة البوابة المزدوجة.
  2. بالنسبة للأدوات الخطيرة، يستدعي await safety.check(...) ما لم تكن موافقًا عليها مسبقًا (الأسطر 384-417).
  3. الإغلاق عند الفشل (fail-closed): أي استثناء في فحص الأمان يُعيد is_error=True “blocked — SafetyMiddleware unavailable” (الأسطر 411-417).
• تشمل الأدوات المدمجة memory_search (السطر 591)، memory_store (السطر 607)، وأخرى تُسجَّل عند الإقلاع.
• تُحقن الذاكرة المتجهية عبر set_vector_memory(...) (tool_registry.py:95-98)، وتُخزَّن في متغيّر عام على مستوى الوحدة.

طالع الأمان والسلامة للاطّلاع على تصنيف الأدوات الخطيرة الذي يحكم التنفيذ.

---

3. المهارات (Skills)

3.1 موقع البيان (manifest) واكتشافه

• الإعداد: skills.path: kazma-skills/manifests/، skills.auto_discover: true (kazma.yaml:55-57).
• عند الإقلاع، يقوم المُحمِّل بمسح المسار وتحميل كل skill_manifest.yaml.

3.2 شكل البيان (manifest)

يصرّح بيان المهارة بنقطة الدخول والقدرات و(عندما يكون موقّعًا) حقول السلامة:

skill_manifest.yaml

name: my-skill
version: 1.0.0
description: "Example skill"
entry_point: my_skill.py        # Python file implementing the tool(s)
capabilities: [mcp, file_read]
author: your-org
# Added by `kazma hub sign`:
checksum: <sha256 of entry_point file>
signature: <HMAC-SHA256 of the checksum>

3.3 التوقيع التشفيري (HMAC-SHA256) — متحقَّق منه

توقيع المهارة حقيقي، ويُغلِق عند الفشل (fail-closed)، ويعيش في نظام المركز (Hub) الفرعي.

التوقيع — kazma hub sign <path> (kazma_core/hub/cli.py:703-770):

# Read the entry-point .py file
raw = py_file.read_bytes()
actual_hash = hashlib.sha256(raw).hexdigest()

# HMAC-SHA256 over the checksum, keyed by KAZMA_SECRET
signing_secret = secret or os.environ["KAZMA_SECRET"]
sig = hmac.new(
    signing_secret.encode(),
    actual_hash.encode(),
    hashlib.sha256,
).hexdigest()

# Write both into skill_manifest.yaml
manifest["checksum"] = actual_hash
manifest["signature"] = sig

يتطلّب KAZMA_SECRET (متغيّر بيئة أو --secret)؛ ويخرج إذا كان غير مُعيين (cli.py:728-733).

التحقّق عند التحميل (الإغلاق عند الفشل) — kazma_core/hub/loader.py:206-266 (SkillLoader._load_module_from_file):

الشرط	السلوك
وجود checksum، مع عدم تطابق	SkillLoadError — “may have been tampered with” (الأسطر 227-232).
وجود signature، دون KAZMA_SECRET	SkillLoadError (الأسطر 237-241).
وجود signature، مع عدم تطابق HMAC	SkillLoadError (الأسطر 242-250).
عدم وجود checksum إطلاقًا	تُسجَّل تحذيرًا؛ يُحمَّل غير موقّع (توافقًا مع الإصدارات السابقة، الأسطر 251-257).
أي خطأ في التحقق	قاتل — لا يُبتلع (الأسطر 259-266).

يستخدم التحقق hmac.compare_digest (بزمن ثابت) لكلٍّ من البصمة (checksum) والتوقيع.

3.4 إضافة مهارة مخصّصة (مثال مصغّر)

1. أنشئ kazma-skills/manifests/my-skill/skill_manifest.yaml + my_skill.py.
2. نفّذ دالة/دوال الأداة التي تتيحها مهارتك.
3. (موصى به) وقّعها:

export KAZMA_SECRET="$(openssl rand -hex 32)"
kazma hub sign kazma-skills/manifests/my-skill
kazma hub validate kazma-skills/manifests/my-skill

4. أعِد تشغيل الخادم (أو اعتمد على skills.auto_discover). يتحقق المُحمِّل من التوقيع باستخدام KAZMA_SECRET ويرفض التحميل عند عدم التطابق.

---

4. المركز (Hub) (kazma hub)

المركز عبارة عن واجهة سطر أوامر مبنية على Click لسجلّ/سوق المهارات (kazma_core/hub/cli.py:104). طالع مرجع CLI ← المركز (Hub) للحصول على القائمة الكاملة للأوامر الفرعية.

4.1 مصادقة واجهة برمجة تطبيقات المركز (Hub)

نقاط النهاية للكتابة (kazma_core/hub/api.py:26-47، _require_auth) تتطلّب ترويسة X-Kazma-Secret تُطابَق عبر hmac.compare_digest. الإغلاق عند الفشل (fail-closed): إذا كان KAZMA_SECRET غير مُعيين، تُرفض جميع عمليات الكتابة.

4.2 الشهادة (Certification)

• kazma hub certified — سرد المهارات الموثَّقة.
• kazma hub badge <skill_ref> — عرض شارة شهادة.
• kazma hub check-certification <path> — فحص مهارة مقابل معايير الشهادة.
• يحمل البيان علمًا منطقيًا بسيطًا certified: true (manifest.py:87-90 is_certified).

“مستويات الثقة” (trust tiers) لا توجد كميزة تشفيرية/أمنية. المراجع الوحيدة لكلمة “الثقة” في قاعدة الشيفرة هي (أ) العلم البسيط certified: bool و(ب) السلسلة النصية trust: trusted في إعداد MCP ضمن kazma.yaml، والتي لا يقرأها أي كود. وقد تم التنويه عن ذلك صراحةً لأن الوثائق الأقدم أوحت بوجود نموذج ثقة متدرّج.

4.3 البحث عن المهارات وتثبيتها (سير عمل المُستهلك)

البحث في السجلّ حسب النص أو القدرة أو الوسم أو المُؤلِّف (cli.py:171-234):

kazma hub search "weather"
kazma hub search --capabilities "image_analysis,data_processing"
kazma hub search --tags "utility,beginner-friendly"
kazma hub search --author "kazma-team"

التصفّح للمهارات المثبَّتة وفحص واحدة بالتفصيل (cli.py:208-303):

kazma hub list
kazma hub info author/skill-name

التثبيت لإصدار محدد أو الأحدث (cli.py:234-266):

kazma hub install author/skill-name@1.0.0
kazma hub install author/skill-name

أو استخدم معالج تثبيت المهارات التفاعلي (kazma_core/cli/wizard.py، main.py:117-123):

kazma wizard

⚠ hub install/hub update مُعطَّلة حاليًا كأكواد مبتورة (stubs) — registry.py:269 يحدّث صفًا في قاعدة البيانات فقط ولا يجلب أي شيء فعليًا. تحقّق من مصدر المهارة عبر قناة خارجية حتى يُربَط المُثبِّت بالكامل.

---

5. بروتوكول سياق النموذج (MCP)

kazma-core/kazma_core/mcp/manager.py يكتشف خوادم MCP الخارجية ويُمرِّرها.

5.1 وسائل النقل (Transports)

وسيلة النقل	الإعداد	المصادقة
stdio	command: [argv] — إنشاء عملية فرعية (subprocess).	لا توجد. ترث العملية الفرعية بيئة العملية.
sse	url + حقل auth اختياري.	نعم — يدعم AsyncMCPManager._connect_sse (manager.py:452-505) إعداد auth من الدرجة الأولى يحقن Authorization: Bearer <token> أو ترويسة مخصّصة (الأسطر 461-466).

لا توجد مصادقة داخل mcp/manager.py لوسيلة نقل stdio. شغّل خوادم MCP عبر stdio التي تثق بها، وفي بيئة معزولة (sandbox).

5.2 تصنيف الأدوات (classify_mcp_tool)

تُكتشف أدوات MCP أثناء التشغيل، لذا لا يمكن وضعها في قائمة خطر ثابتة. تقوم classify_mcp_tool() (manager.py:71-88) بالتصنيف عبر مطابقة جزء من نمط الاسم:

الفئة	الكلمات المُطابَقة
danger	write, delete, remove, exec, run, shell, bash, command, kill, terminate, install, deploy, upload, download, fetch, request, post, put, patch
safe	read, list, search, get, info, status, check, describe, query, count, exists, help
unknown	(لا تطابق أياً من المجموعتين)

تعامل البوابة في UnifiedToolExecutor.execute() (manager.py:725-727) كلًّا من danger وunknown على أنهما يتطلبان موافقة — أي أن unknown يُعامَل افتراضيًا كخطر (أمان زائد، fail-safe).

5.3 إعداد خادم MCP

mcp:
  servers:
    - name: filesystem
      transport: stdio
      trust: trusted          # informational only — not enforced
      command:
        - npx
        - '-y'
        - '@modelcontextprotocol/server-filesystem'
        - kazma-data/workspace
    - name: secured-api
      transport: sse
      url: https://mcp.example.com/sse
      auth:
        type: bearer
        token: ${MCP_API_TOKEN}   # supply via env
  ide_server:
    enabled: true
    root: .
    max_file_size: 1048576

5.4 خادم IDE

خادم IDE/الملفات الداخلي (mcp.ide_server) يتيح قراءة/كتابة الملفات عبر جذر مساحة العمل بحدّ أقصى 1 ميغابايت لكل ملف (max_file_size). وفقًا لتقارير التدقيق، من المتوقع أن يتطلّب _secret يطابق KAZMA_SECRET عبر hmac.compare_digest؛ تحقّق مقابل mcp_server.py قبل الاعتماد عليه.

---

6. التفويض (بين الوكلاء) — نظام تشفيري منفصل

بمعزل عن المهارات وMCP، يتيح نظام التفويض (delegation) الفرعي (kazma_core/delegation/) للوكلاء تمرير المهام إلى وكلاء آخرين بسلامة تشفيرية:

البدائي (Primitive)	الخوارزمية	الموقع
التوقيع	Ed25519 (وليس HMAC)	delegation/security.py:81-119
التشفير	X25519 + AES-256-GCM	delegation/security.py:121-161
التوصيل	الطلبات موقّعة عند الإرسال، مُتحقَّق منها عند الاستلام	delegation/protocol.py:153 (التوقيع)، :179-208 (التحقق، الإغلاق عند الفشل)

هذا هو مسار التفويض بين الوكلاء — وهو غير مرتبط بـ MCP أو توقيع المهارات.

---

7. إضافة أداة جديدة (نقطة التوسعة)

أبسط توسعة هي دالة أداة مُسجَّلة. النمط المصغّر:

my_tools.py

from kazma_core.agent.tool_registry import register_tool

@register_tool(
    name="weather_lookup",
    description="Look up current weather for a city.",
    danger=False,            # set True if it should trigger HITL
)
async def weather_lookup(city: str) -> str:
    # ... your implementation ...
    return f"Weather in {city}: sunny, 25C"

سجّلها أثناء الإقلاع (أو عبر نقطة دخول مهارة). سيعرّضها المُشرف أمام النموذج اللغوي الكبير (LLM) كأداة قابلة للاستدعاء. إذا كان danger=True، فإن التنفيذ يمرّ عبر بوابة HITL (طالع الأمان والسلامة).

---

ملاحظات تدقيق الوثائق

• توقيع المهارات بـ HMAC حقيقي ويُغلِق عند الفشل — على عكس ما قد يُفترض من خليط الأنظمة الفرعية، فإن المُحمِّل يرفض فعلًا المهارات المُعبَّث بها أو غير الموقّعة عند وجوب توقيعها.
• “مستويات الثقة” ليست ميزة في الكود. موثَّقة صراحةً لمواجهة أي إيحاء بوجود نموذج ثقة متدرّج. لا يوجد سوى علم certified المنطقي وسلسلة trust: trusted غير المستخدمة.
• وسيلة نقل MCP عبر stdio بلا مصادقة. فقط SSE يدعم مصادقة الحامل (Bearer)/الترويسة المخصّصة. وهذا حدّ أمني ذو دلالة لتخطيط الإنتاج.
• classify_mcp_tool حيث unknown ← danger هو الافتراضي الآمن ويجب الحفاظ عليه.