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

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

---

1. المفاهيم

المصطلح	المعنى
الأداة (Tool)	دالة يستطيع المُشرف استدعاءها (عمليات الملفات، الصدفة، الذاكرة، الويب، …). مُسجَّلة في ToolRegistry.
المهارة (Skill)	نقطة دخول Python مُغلَّفة وموقّعة اختياريًا + بيان يُسجِّل أداة واحدة أو أكثر. تعيش تحت kazma-skills/manifests/ أو في سجلّ المركز (Hub).
خادم MCP	خادم خارجي لبروتوكول سياق النموذج (Model Context Protocol) (stdio أو SSE أو Streamable HTTP) تُكتشف أدواته أثناء التشغيل وتُمرَّر داخل الوكيل.
المركز (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، memory_store، أدوات نظام الملفات/الصدفة، ومجموعة بحث الويب (web_search، read_url، read_url_to_file، crawl_site، ومساعدات التجزئة/الهضم) المُسجَّلة عند الإقلاع.
• تُحقن الذاكرة المتجهية عبر set_vector_memory(...) (tool_registry.py)، وتُخزَّن في متغيّر عام على مستوى الوحدة.
• المهارات الأصلية (مثل advanced-web-crawler) تُحمَّل تلقائيًا عبر NativeSkillLoader — وهي متميّزة عن Agent Skills القابلة للتثبيت.

كتيّبات بحث الويب: بحث الويب. القائمة الكاملة: كتالوج الأدوات.

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

---

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) — متحقَّق منه {#cryptographic-signing}

توقيع المهارة حقيقي، ويُغلِق عند الفشل (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 إعداد auth من الدرجة الأولى يحقن Authorization: Bearer <token> أو ترويسة مخصّصة.
streamable_http (مستعار http)	url + حقل auth اختياري. مواصفات MCP 2025-03-26 — نقطة نهاية POST واحدة مع بثّ استجابة SSE + استئناف عبر Mcp-Session-Id.	نعم — نفس حقل auth مثل SSE.

لا توجد مصادقة داخل 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
    - name: remote-mcp
      transport: streamable_http   # MCP 2025-03-26 spec
      url: https://mcp.example.com/mcp
      trust: approval_required
  ide_server:
    enabled: true
    root: .
    max_file_size: 1048576

5.4 إضافة خوادم MCP عبر واجهة الويب

توفّر صفحة /mcp نافذة إضافة خادم مرئية تستبدل تحرير YAML اليدوي. لها وضعان:

الإضافة السريعة (إعداد مسبق) — قائمة منسدلة لأكثر من 85 خادم MCP معروف مُجمَّعة حسب الفئة (Filesystem، Web، Database، Code، AI، Communication، إلخ). اختر واحدًا فيُملأ النموذج تلقائيًا بالاسم ووسيلة النقل والأمر ومفاتيح متغيّرات البيئة. ما عليك سوى ملء قيمة مفتاح API. تُحمَّل الإعدادات المسبقة من certified_servers.yaml (81 خادمًا) بالإضافة إلى 5 خوادم عالية القيمة (firecrawl، playwright، sequential-thinking، memory، time).

مخصّص — نفس نموذج الأمر الخام، مع ثلاث شبكات أمان:

1. تحليل بأسلوب shlex — الوسائط المقتبسة التي تحتوي مسافات تبقى (npx -y foo "path/with spaces").
2. إعادة كتابة تلقائية — تُكتشف أخطاء أوامر التثبيت الشائعة وتُصلَح:
   • npm install -g firecrawl-mcp → npx -y firecrawl-mcp
   • pip install mcp-server → python -m mcp_server
   • pipx install some-mcp → pipx run some-mcp تشرح ملاحظة زرقاء إعادة الكتابة حتى تعرف ما تغيّر.
3. التحقق قبل الحفظ — قبل الاستمرار، يُختبر اتصال الخادم عبر /api/mcp/test-config. إذا فشل (خطأ spawn، 0 أدوات، مفتاح سيئ)، يُعرض الخطأ + stderr للعملية الفرعية مضمّنًا ولا يُحفظ الخادم. لا مزيد من “0 أدوات، بلا فكرة لماذا.”

الخوادم المضافة عبر الواجهة تُحفظ في kazma.yaml (كتابة ذرّية) وتبقى بعد إعادة التشغيل.

5.5 تسمية مساحات أسماء الأدوات

تُعطى أسماء أدوات MCP مساحات أسماء بصيغة mcp__<server>__<tool> قبل إرسالها إلى LLM. يمنع هذا التصادمات بين خوادم MCP والأدوات المدمجة (مثل browser_click في Playwright MCP مقابل browser_click في مهارة browser_automation). بدون مساحات الأسماء، المزوّدون الذين يتطلّبون أسماء أدوات فريدة (DeepSeek، OpenAI) يرفضون الطلب بالكامل بـ 400 Tool names must be unique، مما يجعل كاظمة تزيل كل الأدوات للدورة — السبب الجذري لخطأ “توقّف الوكيل عن الكلام”.

تُزال بادئة مساحة الاسم بشفافية عند توجيه استدعاء الأداة إلى خادم MCP الأصلي (execute_mcp_tool يتعامل مع الصيغتين ذات المساحة والخام).

5.6 خادم IDE

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

---

6. خزنة الأسرار (تخزين بيانات اعتماد مشفّر)

خزنة الأسرار مهارة أصلية توفّر تخزينًا مشفّرًا في حالة السكون لمفاتيح API والرموز وكلمات المرور وغيرها من الأسرار. تستخدم تشفير AES-256-GCM مع مفتاح مشتق عبر PBKDF2.

6.1 البنية

المكوّن	الملف	الدور
محرّك الخزنة	kazma-core/kazma_core/security/vault.py	تشفير/فك AES-256-GCM، اشتقاق مفتاح PBKDF2، تخزين SQLite
بيان المهارة	kazma-skills/kazma_skills/native/secret_vault/skill_manifest.yaml	تصريح المهارة الأصلية
أدوات LLM	kazma-skills/kazma_skills/native/secret_vault/tools.py	vault_store، vault_retrieve، vault_list، vault_delete

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

الجانب	التنفيذ
المفتاح الرئيسي	متغيّر البيئة KAZMA_VAULT_KEY. إن لم يُعيَّن، تُعطَّل الخزنة (كل الأدوات تُعيد خطأً لطيفًا).
اشتقاق المفتاح	PBKDF2-HMAC-SHA256، 600,000 تكرار، ملح عشوائي 32 بايت لكل تثبيت.
التشفير	AES-256-GCM مع nonce عشوائي 12 بايت لكل سجل. وسم المصادقة مدمج في GCM.
التخزين	قاعدة SQLite مشفّرة منفصلة عند kazma-data/vault.db (وليست settings.db بالنص الصريح).
عزل المستأجرين	يستخدم get_current_tenant_id() ContextVar. أسرار خاصة بالمستأجر + احتياطي عام.
بوابة HITL	vault_retrieve وvault_delete يتطلّبان موافقة بشرية قبل التنفيذ.

6.3 الأدوات

الأداة	HITL؟	الوصف
vault_store(name, value, category, metadata)	لا	تخزين (أو تحديث) سر. يُشفَّر قبل الاستمرار.
vault_retrieve(name)	نعم	استرجاع وفك تشفير سر. يُعيد [SECRET — handle with care]\n<value>.
vault_list()	لا	سرد جميع أسماء الأسرار + الفئات (القيم لا تُعرض).
vault_delete(name)	نعم	حذف سر نهائيًا.

6.4 تفعيل الخزنة

.env

KAZMA_VAULT_KEY=your-vault-passphrase

أي سلسلة تعمل — إنها عبارة مرور، وليست مفتاحًا مشتقًا مسبقًا. يحوّلها اشتقاق PBKDF2 إلى مفتاح AES بطول 256 بت.

6.5 ملاحظة أمان حول الاسترجاع

عندما يُسترجع سر (بعد موافقة HITL)، تدخل القيمة المفكوكة سياق المحادثة كنتيجة أداة. هذا يعني أنها ستظهر في:

• تاريخ المحادثة (تيار الرسائل)
• نقطة تحقق LangGraph (checkpoints.db) إذا كان التحقق نشطًا
• أي تتبّع مُفعَّل (Langfuse)

هذا بالتصميم — يحتاج LLM القيمة لإجراء استدعاءات API مصادقة. تضمن بوابة HITL موافقة بشر على كل استرجاع. استرجع الأسرار فقط عند الحاجة الفعلية.

---

7. التفويض (وكيل إلى وكيل) — مكتبة فقط (ليست وقت تشغيل)

الحالة (2026-07): حزمة التفويض متعددة الوكلاء مؤرشفة / مكتبة فقط. تنسيق العمّال المتعددين في الإنتاج هو SwarmEngine (kazma_core/swarm/*). راجع docs/audits/UNWIRED_INVENTORY.md.

قد لا يزال الكود التاريخي (بروتوكول Ed25519 + AES-GCM) موجودًا تحت archive/delegation/ أو كوحدات مكتبة محتفظ بها لقرارات المنتج المستقبلية — وهو غير موصول في مسار تنفيذ الوكيل / السرب الافتراضي. لا تُهيّئ أنظمة الإنتاج كما لو كان التفويض التشفيري الحي بين الوكلاء نشطًا.

---

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

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

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 و Streamable HTTP يدعمان مصادقة الحامل (Bearer)/الترويسة المخصّصة؛ أمّا stdio فيرث بيئة العملية. وهذا حدّ أمني ذو دلالة لتخطيط الإنتاج.
• classify_mcp_tool حيث unknown ← danger هو الافتراضي الآمن ويجب الحفاظ عليه.