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

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

---

1. المفاهيم

المصطلح	المعنى
الأداة	دالة يستطيع المُشرف استدعاءها (عمليات ملفات، shell، ذاكرة، ويب، …). مُسجَّلة في ToolRegistry.
المهارة	نقطة دخول 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. مغلق عند الفشل: أي استثناء في فحص الأمان يعيد is_error=True “blocked — SafetyMiddleware unavailable” (الأسطر 411-417).
• الأدوات المدمجة تشمل memory_search وmemory_store وأدوات نظام الملفات/shell، وطقم بحث الويب (web_search وread_url وread_url_to_file وcrawl_site ومساعدات chunk/digest) المسجَّلة عند الإقلاع.
• أدوات الذاكرة تمر عبر المحرك الإدراكي V2: ‏memory_search → recall() (معتقدات ثنائية الزمن + PPR)؛ memory_store → mutate_belief() + mirror_episode(). الأحادية set_vector_memory(...) القديمة أُزيلت مع رصة V1.
• المهارات الأصلية (مثل advanced-web-crawler) تُحمَّل تلقائيًا عبر NativeSkillLoader — وهي مختلفة عن مهارات الوكيل القابلة للتثبيت.

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

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

---

3. المهارات

3.1 موقع بيان التعريف والاكتشاف

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

3.2 شكل بيان التعريف

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

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) — تم التحقق منه

توقيع المهارات حقيقي، ومغلق عند الفشل، ويعيش في نظام الـ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 (بزمن ثابت) لكل من المجموع الاختباري والتوقيع.

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 ويرفض التحميل عند عدم التطابق.

3.5 مهارات الوكيل (SKILL.md)

مهارات الوكيل تعليمات لا شيفرة: ملف SKILL.md بصيغة agentskills.io يقرؤه النموذج حين تطابق المهمة وصف المهارة. يقرؤها كاظمه من مجلده المضمَّن، ومن مجلدات المهارات في مجلدك الرئيسي (~/.agents/skills المشترك مع عملاء agentskills.io الآخرين، و.claude/skills و.cursor/skills و.kazma/agent-skills)، ومن مجلدات المشروع نفسه. وتثبيت المهارة يوقّعها بمفتاح هذا التثبيت (HMAC-SHA256 للملف بمفتاح KAZMA_SECRET، يُحفظ في .kazma-install.json بجوارها).

يفحص التفعيلُ ذلك التوقيع. وقائمة المهارات التي يراها النموذج، وأداة list_agent_skills، والأمر kazma agent-skills list، وصفحة المهارات، كلها تعرض النتيجة: موثّقة، أو غير موقّعة (تُحمَّل مع تحذير)، أو مرفوضة. ولا تُعرض المهارة المرفوضة على النموذج أبدًا. وإن كنت تثق بها فوقّعها من جديد بمفتاح هذا التثبيت: انظر مرجع سطر الأوامر ← kazma agent-skills.

---

4. الـHub (kazma hub)

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

4.1 الـHub

أُزيلت واجهة Hub REST API التي كانت في هذا المستودع (kazma_core/hub/api.py) في 2026-09-30: لم يكن يشغّلها شيء (تدقيق AUD-013). يتصل kazma hub بـHub بعيد على KAZMA_HUB_URL.

4.2 الشهادة

• kazma hub certified — يسرد المهارات المُصدَّق عليها.
• kazma hub badge <skill_ref> — يعرض شارة شهادة.
• kazma hub check-certification <path> — يفحص مهارة مقابل معايير الشهادة.

“مستويات الثقة” غير موجودة كميزة تشفيرية/أمنية. الإشارات الوحيدة إلى “الثقة” في قاعدة الكود هي (أ) راية الـHub الصريحة certified: bool و(ب) إعداد trust لخادم MCP: القيمة trusted تتخطى بطاقة الموافقة لأدوات ذلك الخادم (وتُرفض في الإنتاج ما لم يكن KAZMA_MCP_TRUSTED_IN_PROD=1)؛ وأي قيمة أخرى، ومنها الافتراضية approval_required، تُبقيها. هذا مُشار إليه صراحة لأن وثائق أقدم أوحت بنموذج ثقة متدرج.

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

التثبيت غير مُنفَّذ. يقول kazma hub install ومعالج تثبيت المهارات (kazma wizard) وصفحة المهارات لمعرّف kazma-hub:// ذلك، ولا يثبّت أيٌّ منها شيئًا: سجلّ المركز لا يستطيع جلب مهارة ولا إعطاء الوكيل أدواتها. ثبّت مهارة Agent Skill بدلًا من ذلك.

---

5. MCP (Model Context Protocol)

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

5.1 وسائل النقل

وسيلة النقل	الإعداد	المصادقة
stdio	command: [argv] — تشغيل عملية فرعية.	بلا. تحصل العملية الفرعية على الأساسيات المسموح بها مع env الخاص بها (تدقيق H-4)، ولا تحصل أبدًا على أسرار كاظمه.
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 تثق بها فقط، وفي بيئة معزولة.

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 على أنهما يتطلبان موافقة — أي أن المجهول يُعامل كخطر افتراضيًا (فشل آمن).

5.3 تهيئة خادم MCP

mcp:
  servers:
    - name: filesystem
      transport: stdio
      trust: approval_required  # `trusted` skips the approval card for this server's tools
      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 يدويًا. لها وضعان:

الإضافة السريعة (إعداد جاهز) — قائمة منسدلة بخوادم MCP مجمّعة حسب الفئة، من kazma_skills/certified_servers.yaml: ‏13 خادمًا، كلٌّ منها حزمة ينشرها مشروع MCP أو مزوّد الخدمة التي يتصل بها (Filesystem وGit وTime وMemory وSequential Thinking وPlaywright وFirecrawl وBrave Search وContext7 وNotion وStripe وHeroku وAWS Documentation). اختر أحدها فيُملأ النموذج بالاسم ووسيلة النقل والأمر ومتغيرات البيئة التي يلزم ملؤها؛ تكتب أنت مفتاح API وتحتفظ به كاظمه في الخزنة. تُفحص حزمة كل إعداد جاهز على npm وPyPI (python scripts/verify_mcp_catalog.py، مسجّلًا في tests/fixtures/mcp_catalog_registry.json وتحرسه tests/test_mcp_catalog.py). حتى 2026-09-30 عرضت القائمة 81 خادمًا “معتمدًا”، منها 78 تسمّي حزمًا لم توجد قط. أُسقط عمدًا: جالب عناوين URL خام (سيتجاوز حارس الخروج الذي يفرضه read_url) وGitHub (لدى كاظمه أدوات GitHub الخاصة بها).

الأسرار تبقى في الخزنة. أي مفتاح يحتاجه خادم MCP (مدخل في env مسمّى كبيانات اعتماد، أو قيمة أو رمز في auth، أو ترويسة، أو علم --api-key=... في الأمر، أو كلمة مرور في عنوان URL) يُخزَّن في خزنة كاظمه؛ ويحتفظ kazma.yaml وقاعدة بيانات الإعدادات بمؤشر vault://، وتعرض صفحات MCP وواجهاتها البرمجية ****، ويتلقى الخادم القيمة الحقيقية عند بدئه. تنتقل المفاتيح المحفوظة قبل 2026-09-30 إلى الخزنة في المرة التالية التي تصل فيها كاظمه خوادم MCP الخاصة بها (kazma_core/mcp/secrets.py).

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

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. إذا فشل (خطأ تشغيل، 0 أدوات، مفتاح خاطئ)، يُعرض الخطأ + مخرجات stderr للعملية الفرعية داخل السطر ولا يُحفَظ الخادم. لا مزيد من “0 أدوات، ولا أدري لماذا”.

الخوادم التي تُضاف أو تُعدَّل أو تُزال عبر الصفحات تُحفَظ في إعدادات كاظمه وتبقى بعد إعادة التشغيل. ولا تكتبها كاظمه في kazma.yaml أبدًا: فهو ملف متتبَّع في مجلد التثبيت، وأي تغيير فيه يجعل أمر git pull اللاحق يرفض التحديث. والملف kazma.yaml هو القائمة الأولى والمكان الذي يُضاف فيه خادم يدويًا؛ وإزالة أحد خوادمه من صفحة تُبقيه خارج القائمة دون تعديل الملف (الإعداد mcp.removed_servers)، وإضافته من جديد تعيده. والاستثناء الوحيد: المفتاح المكتوب نصًا في kazma.yaml يُنقَل إلى الخزنة، ويحتفظ الملف بمؤشر vault:// مكانه. وحتى 2026-10-02 كان كل تغيير من صفحة يعيد كتابة kazma.yaml.

يعمل خادم نظام الملفات دائمًا على مساحة العمل النشطة: يمرّر كاظمه مجلد مساحة العمل حين يبدأ الخادم، ومرة أخرى بعد Switch Repo. ويُخزَّن بالعنصر النائب ${KAZMA_ACTIVE_WORKSPACE} وworkspace_bound: true، والنسخة القديمة المحفوظة بمسار ثابت لمجلد العزل تُقرأ وتُحفَظ من جديد بهذه الصيغة. وتعرض البطاقة المجلد الذي يعمل عليه الخادم.

في بطاقة كل خادم: تشغيل أو إيقاف، واختبار (يتصل مرة واحدة ويذكر عدد الأدوات التي وجدها)، وإظهار الأدوات، وإزالة. وتسأل «إزالة» أولًا، لأنها توقف الخادم أيضًا وتنسى إعداداته وأي مفاتيح محفوظة له. وحتى 2026-10-02 لم تكن «تشغيل» و«إيقاف» و«اختبار» وتسجيل الدخول عبر OAuth تفعل شيئًا عند النقر: كانت تستدعي أداة مساعدة في Alpine ($parent) لا يملكها Alpine 3.

وتعرض الإعدادات ← MCP الخوادم نفسها مع مفتاح تشغيل وإيقاف. يحدد المفتاح هل يبدأ الخادم مع كاظمه، ويُطبَّق فورًا: الإيقاف يوقف الخادم ويسحب أدواته من الوكيل، والتشغيل يبدؤه. وإن تعذّر بدء الخادم بقي المفتاح على التشغيل، وذكرت الرسالة السبب، وأُعيدت المحاولة عند البدء التالي. والنقطة بجانب الاسم هي حالة الخادم الآن (يعمل أو متوقف). وزر اختبار هو اختبار صفحة MCP نفسه. والأمر /config tools toggle <name> في تطبيقات المحادثة يفعل ما يفعله المفتاح. أما «تشغيل» و«إيقاف» في صفحة MCP فيبدآن الخادم أو يوقفانه للحظة الحالية فقط؛ والمفتاح هو ما يحدد البدء التالي. وحتى 2026-10-02 كان المفتاح يحفظ الإعداد فقط، ولا يستطيع أن يُظهر خادمًا متوقفًا، وكانت النقطة حمراء دائمًا.

الخادم الذي يفشل في البدء تُعاد محاولته. يتذكر كاظمه سبب فشل كل خادم حتى يتصل أو يوقفه أحد. ويعيد فحصٌ في الخلفية محاولة الخوادم الفاشلة بمهلة تطول تدريجيًا، وتعرض صفحة MCP سبب كل منها مع إخفاء أي مفتاح. وحتى 2026-10-02 لم يكن يُتذكَّر إلا فشل آخر خادم، فالخادم الذي فشل مبكرًا عند البدء لم تكن تُعاد محاولته أبدًا.

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

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

5.7 الموارد وprompts وsampling وroots

كاظمه عميل MCP (‏ACP يستضيف كاظمه بالفعل في المحررات). اعتبارًا من 2026-08-25 تعلن مصافحة initialize عن أكثر من الأدوات:

السطح	السلوك
Resources	mcp_list_resources / mcp_read_resource. جسم القراءة مغلّف بـ format_untrusted_block(source="mcp_resource:…") — بيانات، لا تعليمات.
Prompts	mcp_list_prompts / mcp_get_prompt. تُعاد كنص مرئي للمستخدم. ولا تُحقن كنظام.
Sampling	sampling/createMessage مطفأ ما لم يكن KAZMA_MCP_SAMPLING=1. عندها تنتظر بطاقة HITL حقيقية (kind=mcp_sampling) في مكانها (ولا تفك حزمة MCP stdio). وافق عبر زر “مرة واحدة” القائم (POST /api/approve/{thread_id}). استدعاء LLM بلا أدوات. المهلة KAZMA_MCP_SAMPLING_TIMEOUT (الافتراضي 60s).
Elicitation	الأمر نفسه: لا ملء تلقائي للنماذج التي يقودها الخادم.
Roots	roots/list يعيد مساحة العمل النشطة فقط (نفس سلّم الربط الخاص بأدوات الملفات).

نحن لا نشحن خادم MCP لكي تستضيفه IDEs أخرى وتقدم أدواتنا (D7).

---

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. التفويض (بين الوكلاء) — أُزيل

الحالة: لا توجد حزمة تفويض. كودها (بروتوكول Ed25519 + AES-GCM بين الوكلاء) لم يوصَل قط بالوكيل ولا بالسرب؛ بقي في archive/delegation/ حتى 2026-07-28 حين حُذف. تنسيق العمّال المتعددين هو SwarmEngine ‏(kazma_core/swarm/).

لا شيء يوقّع العمل المُسلَّم بين الوكلاء أو يشفّره؛ فلا تهيّئ نشرًا وكأنه يفعل. ما يحمي عمل السرب مذكور في الأمان والسلامة.

---

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 حقيقي ومغلق عند الفشل — وخلافًا لما قد يُفترض من خليط الأنظمة الفرعية، يرفض المُحمِّل فعلًا المهارات المعبوث بها/غير الموقعة حين يُشترط التوقيع.
• “مستويات الثقة” ليست ميزة في الكود. موثّقة صراحة لمواجهة أي إيحاء بنموذج ثقة متدرج. لا يوجد سوى راية الـHub المنطقية certified والإعداد trust: trusted لخادم MCP (الذي يتخطى بطاقة الموافقة لأدواته).
• وسيلة نقل MCP عبر stdio بلا مصادقة. تدعم SSE وStreamable HTTP مصادقة bearer/ترويسة مخصصة. يبدأ خادم stdio بالأساسيات المسموح بها (PATH ومجلدا المؤقت والمنزل والإعدادات المحلية وإعدادات الوكيل) مع env الخاص به، ولا يحصل أبدًا على أسرار كاظمه (تدقيق H-4؛ انضم إليها عميل زر الاختبار في 2026-09-30؛ وKAZMA_MCP_INHERIT_ENV=1 يمرّر البيئة كاملة).
• ‏classify_mcp_tool من unknown إلى danger هو الافتراضي الآمن وينبغي الحفاظ عليه.