خريطة النظام

الخريطة المعمارية الكاملة للمستودع الأحادي (مخطط تدفق البيانات، كتالوجات الحزم، الغوص العميق في الأنظمة الفرعية، جدول مطابقة المعالجات) تُصان في:

docs/ARCHITECTURE_AND_SYSTEM_MAP.md

ذلك الملف هو مصدر الحقيقة الهندسي الوحيد لـكيف تُوصَّل الحزم معًا. موقع التوثيق هذا يركّز على أدلة المشغّل والمطوّر.

خريطة الحزم السريعة

الحزمة	الدور
`kazma-core`	عقل الوكيل، السرب، الأدوات، سجل النماذج، الخزنة، خدمة IDE، ConfigStore، ذكاء المستندات (`documents/`، بما فيها وسيط عامل المستندات `documents/worker_broker.py` المعتمد على المكتبة القياسية وحدها، والذي يعمل خارج كاظمه وصوره تحت `deploy/`)
`kazma-gateway`	مكيّفات Telegram / Discord / Slack + معالج الوكيل (أمر slash ‏`/documents`، قراءات عابرة للمرفقات)
`kazma-ui`	واجهة الويب FastAPI، دردشة SSE، الإعدادات، IDE، لوحة السرب، `/documents` + API المستندات
`kazma-tui`	لوحة Textual / محرّر / تبويب المستندات (يقرأ API المستندات من الخادم العامل)
`kazma-cli`	نقاط دخول `kazma` CLI (بما فيها migrate مع مخزن المستندات)
`kazma-skills`	بيانات المهارات + المهارات الأصلية (`document-platform`، `document-generator`, …)

الوحدات المفكَّكة

أربع وحدات تجاوزت 2,700 سطر صارت الآن حزمًا خلف واجهات عامة غير متغيّرة (تدقيق O5، 2026-08-29). مسارات الاستيراد لم تتغير؛ وقد جرى التحقق من أن جدول المسارات وسجل الأدوات متطابقان بايتًا ببايت قبل التغيير وبعده.

الحزمة	الواجهة	الوحدات الفرعية
`kazma_ui/routes_direct/`	`register_direct_routes`	`memory` `system` `settings` `auth` `backup` `misc` `_shared`
`kazma_ui/sse_chat/`	`create_sse_chat_router`	`_helpers` `_persistence` `_streaming`
`kazma_ui/i18n/`	`TRANSLATIONS`, `t`, `make_translator`	`catalog/` — وحدة واحدة لكل قسم من أقسام الواجهة
`kazma_core/agent/tool_builtins/`	`register_builtin_tools`	`filesystem` `memory` `system` `knowledge` `research` `mcp` `external`

تترتّب على ذلك قاعدتان:

ترتيب التسجيل محفوظ داخل كل واجهة. external يعمل أخيرًا في tool_builtins حتى يظل الاسم المسجَّل مرتين يُحلَّ بالطريقة نفسها.
رقِّع الدرز حيث يُعرَّف، لا على الواجهة. _module_graph يعيش في sse_chat/_helpers؛ والرقعة المطبَّقة على kazma_ui.sse_chat لن تصل إلى ربط from … import في _streaming.

قواعد التشغيل الحرجة

النموذج والمزوّد يتبدّلان معًا دائمًا (model_registry.py).
معرّفات المنصة لا تدخل حالة LangGraph أبدًا.
ثلاث بوابات HITL: مقاطعة الرسم، ناقل السرب، نقاط تفتيش الخط.
تعديلات IDE تمر عبر LocalToolRegistry (HITL مشترك).
ConfigStore عبر get_config_store() فقط.
المسار الدائم للمستندات يستخدم DocumentIngestionService فقط — لا استيرادات gateway/UI لبواطن المحلل (AGENTS.md §19). والبايتات غير الموثوقة لا تُحلَّل ولا تُعدَّل ولا تُعرَض إلا في العامل المحدود (عملية فرعية محلية، أو حاوية يشغّلها وسيط مع KAZMA_DOCUMENT_WORKER_ISOLATION=container)، ولا يُفتح أي ملف PDF آتٍ من خارج كاظمه خارجه (tests/test_pdf_openers_stay_in_workers.py). وكل قراءة لمهمة تسمّي الفاعل (tests/test_document_job_read_matrix.py).
كل أداة مسجَّلة تحتاج مدخل TOOL_TIERS. ما لا تستطيع HITL تصنيفه ترفضه افتراضيًا، فالأداة غير المصنفة تستوجب سؤالًا في كل استدعاء. بوابة CI: test_every_registered_tool_has_a_tier.
لا استدعاء قاعدة بيانات حاجب داخل async def، ولا asyncio.create_task عارٍ. كلاهما يعطّل العمل أو يُسقطه بصمت على الحلقة التي تخدم كل دفق SSE/WebSocket. استخدم asyncio.to_thread (أو معالجًا متزامنًا) وkazma_core.background.spawn_background. مقيَّد ببوابة CI.
عنوان النظير ليس اعتمادًا خلف وكيل. يجب ضبط KAZMA_TRUSTED_PROXIES أينما وقف أي شيء أمام كاظمه — انظر التحصين.

التشخيص متعدد المسارات

عندما يُخدَم عنصر واجهة واحد من عدة مسارات شيفرة (SSE مقابل WS، ثلاث بوابات HITL، سجلان مزدوجان)، استخدم الموجَّه للمشغّل:

خريطة التشخيص — جداول الأعراض، و«X مرتبط بـ Y»، والثوابت، واختبارات الانحراف.

انظر أيضًا البنية المعمارية وAGENTS.md في جذر المستودع.