كاظمه — البنية المعمارية وخريطة النظام

خريطة الوحدات الموصولة إنتاجيًا (الثوابت في AGENTS.md)
الإصدار: 0.10.x
التاريخ: 2026-09-02
التدقيق الصناعي المُلزِم: docs/audits/AUDIT_DEEP_2026-09-01_EXEC.md (الموجات 0–8 أُطلقت — لا تتبع الجزء 6 من الـ dump)
التدقيقات العميقة السابقة: docs/audits/AUDIT_DEEP_STRUCTURE_2026-08-19.md، docs/audits/AUDIT_INDUSTRY_STACK_2026-08-25.md
الوثائق المرافقة: docs/docs/ops/diagnosis-map.md، docs/docs/guide/architecture.md، AGENTS.md

ملاحظة صدق: تعطي هذه الخريطة الأولوية للمسارات الموصولة إنتاجيًا وتفهرس كل وحدات المصدر تحت الحزم الرئيسية. المخرجات المولَّدة (docs/node_modules، docs/build، __pycache__، .venv) مستثناة. الوحدات المكتبية-فقط موسومة [مكتبة فقط].

القسم 1: النظرة التنفيذية العامة وتدفق البيانات

الفلسفة

كاظمه إطار وكلاء ذاتي متعدد المنصات: عقل مُشرف واحد مبني على LangGraph، وأفواه كثيرة (Telegram/Discord/Slack/Web/TUI/kazma ask/kazma acp)، وطبقة تنفيذ واحدة للأدوات وIDE، وتنسيق سرب اختياري متعدد العمّال. معرّفات المنصة لا تدخل حالة LangGraph أبدًا. أدوات الخطر تتطلب HITL (ثلاثة مسارات تنفيذ: مقاطعة الرسم، ناقل السرب، نقطة تفتيش خط المعالجة) بالإضافة إلى سجل بوابات واحد (hitl_gates.db). توزيع FanOut في السرب ثلاثي الحالة، وليس «الأول يفوز». الإعدادات قابلة للتعديل وقت التشغيل عبر ConfigStore (SQLite أو Postgres). لا توجد حزمة kazma-memory.

متطلبات التشغيل

المتطلب	ملاحظات
Python	3.11–3.14
البيانات الافتراضية	`kazma-data/`‏ SQLite WAL
RAG اختياري	`[rag]` → ‏ChromaDB + sentence-transformers
تعدد النسخ اختياري	`[postgres]` + `KAZMA_DATABASE_URL`
الربط الافتراضي	يُفضَّل loopback؛ في Docker‏ `0.0.0.0` مع سر

حدود التشغيل

مضيف موثوق بمشغّل واحد افتراضيًا.
نمط الإنتاج: KAZMA_PRODUCTION=1 (تنفيذ code_exec داخل Docker، إيقاف YOLO، مفتاح الخزنة مطلوب، جذر مساحة العمل مطلوب).
أساس SaaS متعدد المستخدمين: ‏RBAC للمنصات + OIDC + جلسات معتمة + التحوّل إلى Postgres.
ليست: قواعد بيانات كتابة متعددة الرئيسيات متعددة المناطق دون منتج قواعد بيانات خارجي.

مخطط تدفق البيانات (ASCII)

┌──────────────────────────────────────────────────────────────────────────────┐
│ CLIENT INPUTS                                                                │
│  Web UI / SSE (graph) / WS (telemetry)   CLI   TUI   Gateway adapters        │
│  Telegram/Discord/Slack   GitHub OAuth/webhooks   MCP IDE bridge             │
└───────────────────────────────┬──────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ EDGE: FastAPI lifespan (app.py)                                              │
│  Auth middleware (secret / opaque session / API token / OIDC session)        │
│  Tenant middleware (prod: ignore spoofed X-Tenant-ID; JWT or default)        │
│  CORS · i18n · static · health/live · health/ready (DB ping)                 │
└───────────────────────────────┬──────────────────────────────────────────────┘
                                │
          ┌─────────────────────┼─────────────────────┐
          ▼                     ▼                     ▼
   SessionManager        Gateway SessionStore    Swarm Task APIs
   (chat threads)        (platform isolation)    (TaskStore)
          │                     │                     │
          └─────────────────────┼─────────────────────┘
                                ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ AGENT BRAIN                                                                  │
│  KazmaAgent / agent_runner  →  build_supervisor_graph (wires nodes)          │
│  graph_supervisor / graph_tool_worker / graph_respond                        │
│  Checkpointer: AsyncSqliteSaver | AsyncPostgresSaver                         │
│  Interrupt HITL + hitl_gates.db · turn_input · context integrity trim        │
│  SubAgentManager → build_child_graph (auto-deny danger)                      │
└───────────────────────────────┬──────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ TOOLS & SANDBOX                                                              │
│  LocalToolRegistry (SoT)  ·  UnifiedToolExecutor (local + MCP force_danger)  │
│  shell_exec (allowlist + env scrub)  ·  python_exec (Docker jail / blocklist)│
│  IdeService → same tools + HITL  ·  native skills (kazma-skills)             │
└───────────────────────────────┬──────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ SWARM ENGINE                                                                 │
│  dispatch / broadcast / pipeline / fanout / consult                          │
│  handoff_guards (depth 5, visits 2) · ReliabilityRegistry (breakers/retry)  │
│  FanOutBus tri-state HITL · NullBus fail-closed                              │
│  TaskStore (SQLite|Postgres) · SSE bridge · checkpoint_manager               │
└───────────────────────────────┬──────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ DATASTORES                                                                   │
│  ConfigStore (settings / vault / Soul) · SessionManager · checkpoints        │
│  hitl_gates.db · turn journal / agent_artifacts.db                           │
│  TaskStore · cron.db · memory_state.db + memory_ops.db (split, do not merge) │
│  WorkspaceStore · optional Postgres (KAZMA_PG_TABLES, not whole-DB)          │
└──────────────────────────────────────────────────────────────────────────────┘

القسم 2: مرجع المجلدات والوحدات

2.1 الشجرة العلوية (مركّزة على المصدر)

kazma/
├── serve.py                 # Alternate WebUI entry (hardened secrets)
├── pyproject.toml           # Workspace package + extras [rag,postgres,…]
├── kazma.yaml               # Product defaults
├── kazma.local.yaml.example # Local overrides template
├── docker-compose.yml       # Single-node container
├── docker-compose.postgres.yml
├── docker-compose.ha.yml    # Multi-replica + optional nginx
├── Dockerfile               # [rag,postgres] image
├── deploy/nginx-ha.conf
├── scripts/                 # backup, restore, migrate, smoke, entrypoint
├── docs/                    # Docusaurus site + audits + ops + this map
├── tests/                   # Root regression suite
├── loadtests/               # k6/locust
├── examples/                # Sample skills + demos
├── kazma-core/              # Brain, swarm, tools, safety, db
├── kazma-ui/                # FastAPI web + static + SSE
├── kazma-gateway/           # Platform adapters + slash + routers
├── kazma-tui/               # Textual dashboard/IDE
├── kazma-cli/               # `kazma` CLI
├── kazma-skills/            # Native skill packages + YAML manifests
├── kazma-data/              # Runtime DBs (local; do not commit secrets)

2.2 الحزمة: `kazma-core/kazma_core/` (العقل)

الوحدة	الغرض
`__init__.py`	تصديرات الحزمة
`agent_runner.py`	دورة حياة KazmaAgent، ضمان جاهزية الرسم، مهلة الدور، حافظ نقاط التفتيش Postgres/SQLite
`audit_logger.py`	أحداث تدقيق أمنية/تشغيلية منظمة
`authority.py`	مساعدات سلطة السياق / عتبة الضغط
`authorization_flow.py`	[مكتبة فقط] تدفقات الموافقة عبر القطاعات
`compaction.py`	ضغط سجلّ الرسائل
`config_loader.py`	دمج YAML‏ (`kazma.yaml` + `kazma.local.yaml`)
`config_schema.py`	نماذج إعداد Pydantic
`config_store.py`	مصدر الحقيقة لإعدادات وقت التشغيل (SQLite أو Postgres)
`constants.py`	ثوابت مشتركة (قوائم أدوات الخطر — فضّل CANONICAL)
`cost_breaker.py`	قاطع دائرة ميزانية الجلسة
`cultural_context.py` / `cultural_context_enrichment.py`	إثراء ثقافي للأوامر
`dialect_detector.py`	كشف اللهجة العربية
`division_sandbox.py`	[مكتبة فقط] عزل مقيّد بالقطاع
`exceptions.py`	أنواع الاستثناءات المشتركة
`git_identity.py`	هوية مؤلف git للبوت في الالتزامات
`google_llm.py`	مسارات LLM لـ Google/Vertex
`http_pool.py`	تجمّع عملاء httpx مشترك
`kuwaiti_tokenizer.py` / `msa_tokenizer.py`	مساعدات الترميز العربي
`language_lock.py`	قفل لغة الردود
`llm_provider.py`	عميل LLM متوافق مع OpenAI، إعادة المحاولة، إغلاق aclose عند إعادة الإعداد
`logging_config.py`	إعداد السجلات
`majlis.py`	[مكتبة فقط] غلاف منسّق المجلس
`mcp_client.py`	مساعدات عميل MCP قديمة/بديلة
`metrics.py`	مساعدات المقاييس
`model_registry.py` / `model_registry_store.py`	حل المزوّد/النموذج + الاستمرارية
`pacing.py`	إيقاع الردود للبوابات
`paths.py`	حل مسارات البيانات
`permissions.py`	[مكتبة فقط] مدير صلاحيات YAML
`personalities.py`	أوامر الشخصيات
`providers.py`	مساعدات كتالوج المزوّدين
`rbac.py`	محرك RBAC للقطاعات (مؤسسي)
`retry.py`	أدوات إعادة محاولة عامة
`router.py` / `routing_engine.py`	مساعدات التوجيه / توجيه العمّال الموحّد
`service_container.py`	حاوية DI
`settings_manager.py` / `settings_mcp.py`	أوجه الإعدادات (facades)
`shutdown.py`	علم الإيقاف المتأنّي العالمي
`state.py`	أنواع حالة الوكيل
`summarizer.py`	أداة التلخيص
`telemetry.py`	جمع القياس عن بُعد (telemetry)
`tenant_context.py`	متغيّر سياق ContextVar لمعرّف المستأجر tenant_id
`time_travel.py`	مساعدات السفر عبر الزمن لنقاط التفتيش
`token_counter.py` / `tokenizer.py`	عدّ الرموز
`tone_adapter.py`	تكييف النبرة للمنصات
`tracing.py`	تكامل Langfuse/المتتبّع
`url_utils.py`	مساعدات URL
agent/
`agent/graph_builder.py`	يوصّل الرسم؛ لا يحتوي أجسام HITL/إعادة المحاولة
`agent/graph_supervisor.py`	عقدة المُشرف + `_call_llm_with_retry` (الأخطاء العابرة فقط)
`agent/graph_tool_worker.py`	بوابة الالتزام + `interrupt()` الخاص بـ HITL + التنفيذ
`agent/graph_respond.py`	عقدة الرد؛ تتخطى التوليف عند `turn_failed`
`agent/hitl_supersede.py`	إلغاء HITL المعلّق عند دور جديد
`agent/artifacts.py`	مقترحات/مسوّدة دائمة (ليست حالة الرسم)
`agent/nonstop.py`	مخطط NonStopConfig وطبقة إعداداته
`agent/pipeline_schema.py`	مخططات متعلقة بخط المعالجة
`agent/resilient_chat.py`	غلاف دردشة مرن مع إعادة محاولة وتجاوز وسجلّ
`agent/state.py`	حالة المُشرف / NodeName؛ مخفّض دمج المسوّدة
`agent/sub_agent.py`	إنشاء SubAgentManager + رفض تلقائي (auto_deny) لـ HITL
`agent/supervisor_watchdog.py`	غلاف تنفيذ مُشرَف عليه ومراقب توقّف
`agent/tool_registry.py`	مصدر حقيقة LocalToolRegistry + الأدوات المدمجة (`file_append`)
`agent/turn_input.py`	بناء الرسائل من حافظ نقاط التفتيش + دور المستخدم
agent_skills/	تثبيت/اكتشاف/تحليل Agent Skills
cron/	`scheduler.py` كرون SQLite + تزامن + إيقاف
db/	اختيار خلفية Postgres + تجمّع اتصالات + مساعدات
delegation/	[مكتبة فقط] تصميم متعدد الوكلاء متوازٍ
docs/	[مكتبة فقط] مولّد وثائق
hub/	API/CLI/سجلّ/مدقّق مركز المهارات
ide/	‏IdeService، env_context، workspace_scope
mcp/	‏AsyncMCPManager + UnifiedToolExecutor + classify_mcp_tool
memory/	محرك V2 المعرفي (`recall.py`، `memory_state.db` / `memory_ops.db`، `worker_bootstrap.py` — ثمانية مجدولات)
models/	اكتشاف المزوّدين (محصّن ضد SSRF)، موجّه النماذج
observability/	`ops_alerts`، الملخص اليومي، سجلّ الإطلاق (firing ledger)
safety/	‏hitl، `hitl_gates.py`، commitment/، yolo، prompt_fence
security/	‏ssrf، `ssrf_pin.py` (تثبيت IP)، الخزنة، web_sessions، platform_rbac، oidc
stores/	‏workspaces، bookmarks
swarm/	التنسيق الكامل (انظر §3.3)
system/	المثبّت، الصيانة، runtime_manager
tools/	تنفيذات أدوات مستقلة + سجلّ ShellTool الخاص بالسرب
voice/	‏STT/TTS/VAD
chaos/	خطافات اختبار الفوضى
cli/	مساعدات معالج الإعداد (wizard)

2.3 الحزمة: `kazma-ui/kazma_ui/`

الوحدة	الغرض
`app.py`	مصنع FastAPI، lifespan، إقلاع البوابة/الكرون/السرب، تركيب الموجّهات
`auth.py`	مصادقة بالسر/الجلسة/رمز API، وسيط المستأجر، بوابات مسار RBAC
`saas_api.py`	‏API إدارة المستخدمين والمستأجرين (متعدد المستخدمين)
`session_manager.py`	جلسات الدردشة (SQLite\|Postgres)
`sse_chat/`	بث دردشة SSE الأساسي + اعتراض YOLO + إطارات HITL (حزمة)
`turn_runtime.py` / `turn_document.py`	تسليم الدور V2 — ‏`close_turn` هو المُغلِّق الوحيد
`hitl_status.py` / `hitl_gate_bridge.py`	قارئات سجلّ البوابات للويب
`sse_utils.py`	مساعدات تأطير SSE
`chat.py`	صفحة الدردشة + مسار دردشة WebSocket
`ide_api.py`	ملفات/تشغيل/git/سرب في `/api/ide/*`
`workspace_api.py`	مسارات ويب مساحة العمل
`settings.py`	‏HTML/API للإعدادات (أسرار مقنّعة)
`dashboard.py`	لوحة التحكم + APIs قائمة الجلسات
`swarm_panel/*`	‏APIs واجهة السرب (مهام/عمّال/مقاييس)
`swarm_sse.py`	تدفقات أحداث مهام السرب
`agents.py` / `mcp_ui.py` / `skills_ui.py`	صفحات الميزات + APIs
`providers.py` / `models_route.py` / `models.py`	واجهة إدارة المزوّدين/النماذج
`health.py`	‏live/ready عامة؛ `/health/details` حسّاس (L-1)
`metrics.py`	مقاييس Prometheus
`routes_direct/`	تسجيل الدخول، الموافقة، النظام، ربط البوابة، OIDC، وAPIs كثيرة
`routes_voice.py` / `routes_voice_ws.py`	‏STT/TTS عبر REST + WS
`routes_chaos.py`	‏APIs واجهة الفوضى
`telemetry_route.py`	‏SSE/لقطة telemetry
`gateway_monitor.py`	بدء/إيقاف حالة البوابة
`hitl_approval.py`	مساعدات API لـ HITL
`i18n/`	ترجمات en/ar (وحدة فهرس لكل قسم من الواجهة)
`services.py`	مساعدات حالة الخدمات
`static/js/*`	وحدات Alpine/UI (الدردشة، IDE، السرب، الإعدادات، البث)
`templates/*`	صفحات Jinja (الدردشة، IDE، السرب، الإعدادات، تسجيل الدخول، …)

2.4 الحزمة: `kazma-gateway/kazma_gateway/`

الوحدة	الغرض
`gateway.py`	طابور تنسيق المُكيّفات
`adapters/telegram*.py`	بوت Telegram + الناقل + الاستدعاءات الراجعة + STT
`adapters/discord.py` / `slack.py`	مُكيّفات Discord/Slack + نواقل HITL
`agent_handler/graph.py`	الرسالة الواردة → رسم الوكيل
`agent_handler/hitl.py`	ملكية HITL للبوابة مغلقة عند الفشل (fail-closed)
`agent_handler/commands.py`	أوامر slash + `/ide`
`agent_handler/store.py`	عزل جلسات المنصة
`agent_handler/swarm_*.py`	إرسال السرب/مخرجاته من البوابة
`routers/github*.py`	‏GitHub OAuth، الاستنساخ، API
`routers/workspaces.py` / `workspace.py`	‏CRUD لمساحات العمل + حصر الجذر في الإنتاج
`routers/git.py` / `bookmarks.py` / `pipeline.py`	عمليات git، الإشارات المرجعية، خطوط المعالجة
`stores/checkpoint.py`	‏CheckpointManager + حافظ Postgres/SQLite
`stores/sqlite.py`	مخزن SQLite لجلسات البوابة
`mcp_server.py`	جسر خادم IDE MCP
`slash_commands.py` / `suggestions.py`	كتالوج الأوامر / تجربة الاستخدام
`swarm_notify.py`	إشعار Telegram اختياري (`maybe_notify_dispatch` عند ضبط `SWARM_BOT_TOKEN`)
`telegram_format.py` / `typing_keepalive.py` / `rate_feedback.py`	مساعدات UX للمنصات

2.5 الحزم: CLI وTUI والمهارات

kazma-cli: ‏main (serve/wizard/status)، gateway، swarm، update، project، completions، banner، migrate.

kazma-tui: تطبيق Textual، شاشات دردشة/لوحة/محرّر/ملفات/سرب، ودجات (نافذة HITL، لوحة أوامر، تنبيهات toast).

kazma-skills/native/*: مهارات معبّأة (git، cron، crawler، الخزنة، health، code-review، …) + بيانات YAML.

لا حزمة kazma-memory. المُرمِّز العربي هو kazma_core/msa_tokenizer.py؛ ذاكرة V2 هي kazma_core.memory.

2.6 سكربتات ونشر

المسار	الغرض
`scripts/backup_kazma.py` / `restore_kazma.py`	نسخ احتياطي/استعادة DR مضغوطة (zip)
`scripts/migrate_sqlite_to_postgres.py`	ترحيل كامل للمخازن
`scripts/smoke_production.py`	حزمة فحص الدخان للإنتاج
`scripts/docker-entrypoint.sh`	ترحيل تلقائي اختياري ثم uvicorn
`deploy/nginx-ha.conf`	نموذج وكيل عكسي متعدد النسخ

القسم 3: الغوص في الأنظمة الفرعية

3.1 مُشرف الوكيل والرسم

الاهتمام	الموقع	السلوك
بناء الرسم	يوصّل `graph_builder.py`؛ الأجسام في `graph_supervisor` / `graph_tool_worker` / `graph_respond`	حلقة ReAct؛ حد أقصى لتكرارات الأدوات
مقاطعة HITL	`graph_tool_worker.tool_worker_node` + `hitl_config`	أدوات الخطر `interrupt()`؛ صفّ في سجلّ `hitl_gates.db`
الاستئناف	`POST /api/approve/{thread_id}`، ‏`/hitl` للبوابة	استرجاع من سجلّ البوابات + `Command(resume=…)`
منع البوابة المزدوجة	`_hitl_approved_ctx` ‏ContextVar	يجب ألا يُصكّ `execute()` بوابة ويب ثانية (H-8)
تجميع الدور	`turn_input.py`	سجلّ حافظ نقاط التفتيش + رسالة المستخدم
الوكلاء الفرعيون	`sub_agent.py` + `build_child_graph`	رفض تلقائي للخطر، مهلة، مرشّح أدوات
الاستمرارية	`agent_runner` / `stores/checkpoint.py`	‏SQLite أو AsyncPostgresSaver
إبطال HITL	`hitl_supersede.py`	رسالة مستخدم جديدة تلغي المقاطعة المتقادمة

3.2 الأدوات والعزل (Sandboxing)

المسار	الوحدة	ملاحظات
أدوات الوكيل	`LocalToolRegistry`	‏file_، shell_exec، python_exec، memory_، config_*، spawn_agent(s)، context_info
MCP	`mcp/manager.py`	`force_danger=True`؛ ‏HITL في الإنتاج لغير المدرَج في قائمة السماح
code_exec	`tools/code_exec.py`	يُفضَّل Docker‏ network=none؛ محليًا قائمة حجب استيراد
shell_exec	tool_registry	‏shlex + `asyncio.to_thread(subprocess…)` (‏SelectorEventLoop على Windows — أبدًا `create_subprocess_exec` عاريًا)؛ `_EXEC_CAPABLE_ARGS`؛ تنظيف متغيرات البيئة؛ HITL
IDE	`ide/service.py`	كل التعديلات عبر execute الخاص بالسجلّ

مصدر حقيقة الخطر: safety/hitl.CANONICAL_DANGER_TOOLS → ‏_EXTENDED_DANGER الخاص بالسرب.

3.3 محرك السرب والمهام غير المتزامنة

المكوّن	الوحدة
المنسّق	`swarm/engine.py`
الأنماط	`patterns.py`، `broadcast.py`، `consultation.py`
حدود التسليم	`handoff_guards.py` (عمق 5، زيارات 2)
الموثوقية	`reliability.py`، `reliability_registry.py`
الإرسال	`worker_dispatch.py`، `dispatch_inner.py`
الاستمرارية	`task_store.py` (SQLite\|Postgres)
دورة الحياة	`task_lifecycle.py`، `task_control.py`
HITL خط المعالجة	`checkpoint.py`، `checkpoint_manager.py`
الناقل	`bus.py` + مُكيّفات المنصات؛ ‏HITL لـ FanOut ثلاثي الحالة
الموسِّع التلقائي	`autoscaler.py` (`maybe_scale` فقط عند `NoCapableWorkersError`)
سجلّ البوابات	`checkpoint_manager._gate_register_pipeline` / `_gate_settle_pipeline`
الذاكرة	‏`recall.search` في V2 عبر دفتر الهاتف (مسيَّج)؛ وليس محوّلًا رباعي الطبقات

3.4 ناقل الأحداث والخدمات الخلفية

الخدمة	الوحدة	الدورة
ناقل رسائل السرب	`swarm/bus.py`	ينشر الموافقة/التقارير/التنبيهات؛ ‏FanOut ثلاثي الحالة
مجدول الكرون	`cron/scheduler.py`	يجب تمرير `graph_builder=`؛ ‏`delivery_target` وقت الجدولة
عامل الذاكرة	`memory/worker_bootstrap.py`	ثمانية مجدولات (نسخ احتياطي كل 6 ساعات، نوم كل 6 ساعات، إعادة توحيد كل 24 ساعة، GC كل 15 دقيقة، ملخص، سجلّ، تدريب طوارئ، تنظيف جلسات)
SSE telemetry	`telemetry_route.py`	بث حتى `is_shutting_down`
دردشة SSE	حزمة `sse_chat/`	بث لكل دور؛ إسقاط السجلّ (journal projection)
SSE السرب	`swarm_sse.py` / اللوحة	أحداث المهام
طابور البوابة	`gateway.py`	وارد المُكيّف ← المعالج
تنبيهات ops	`observability/ops_alerts.py`	‏FanOut داخل التطبيق + Telegram مباشر؛ الحارس عملية منفصلة
إشارة الإيقاف	`shutdown.py`	علم عالمي للحلقات

3.5 الذاكرة والاستمرارية

المخزن	الخلفية	ملاحظات
ConfigStore	‏SQLite WAL / ‏Postgres `kazma_settings`	مراجع الخزنة؛ مفتاح Soul‏ `self_improvement.agent_evolution`
SessionManager	‏SQLite / `kazma_chat_sessions`	ذاكرة ساخنة LRU + قفل
TaskStore	جداول SQLite / Postgres	‏WAL + مرشّح عمّال json_each
نقاط التفتيش	aiosqlite / AsyncPostgresSaver	حقيقة التنفيذ لـ HITL
بوابات HITL	`hitl_gates.db` (SQLite WAL)	حقيقة القرار لـ HITL؛ أحادية العملية
الأصناف الفنية (Artifacts)	`agent_artifacts.db`	مقترحات دائمة؛ الرسم يقرأ عبرها (read-through)
ذاكرة V2 الساخنة	`memory_state.db`	معتقدات، حلقات، كيانات — لا تُدمج مع ops
ذاكرة V2 العمليات	`memory_ops.db`	طابور دائم + تدقيق
الكرون	`cron.db`	تذكيرات؛ ليست SessionStore وقت الإطلاق
FTS5	‏SQLite + قفل	ذاكرة الكلمات المفتاحية (V2)
المتجهات / المكتبة	sqlite-vec / pgvector / Chroma اختياري	معزولة عن استدعاء الدردشة
WorkspaceStore	‏SQLite	أعمدة هوية المستودع

3.6 بوابة الويب وIDE والواجهة

السطح	التقنية
مصنع التطبيق	‏FastAPI + تصريف إيقاف lifespan
المصادقة	سر / جلسة معتمة / رمز API / ‏OIDC
الدردشة	‏SSE هو ناقل الأدوار الوحيد (`/api/chat/stream`)؛ WS للقياس عن بعد / المؤشر فقط؛ العميل يُسقِط TurnDocument
IDE	صفحة `/ide` + `/api/ide/*` + ‏CodeMirror `ide.js`
لوحة السرب	`/swarm` + `/api/swarm/*`
الإعدادات	‏Alpine + `mask_deep` + `kazmaConfirm`/`kazmaPrompt`
الصحة	`/health/live` + `/health/ready` عامة؛ `/health/details` مصادقة (L-1)؛ `/health/deep` عصفورة كنارية

القسم 4: مصفوفات API والمسارات والأدوات

4.1 مصفوفة API والمسارات (الأسطح الرئيسية)

نطاق المصادقة: مفتوح = مفتوح دائمًا؛ سري = ‏KAZMA_SECRET / جلسة / رمز عند ضبط السر؛ مشرف = دور مشرف المنصة (متعدد المستخدمين).

الطريقة	مسار نقطة النهاية	نطاق المصادقة	HITL / الخطر	الوصف والوحدة
GET	`/health`	مفتوح	—	صحة أساسية (`routes_direct`)
GET	`/health/live`	مفتوح	—	حيوية LB‏ (`health.py`)
GET	`/health/ready`	مفتوح	—	الجهوزية + فحص قاعدة البيانات (`health.py`)
GET	`/health/details`	سري	—	تفاصيل التصحيح — ليست عامة (الموجة 8 ‏L-1؛ تسرّب النموذج/MCP) (`health.py`)
GET	`/health/deep`	مفتوح	—	عصفورة كنارية بذهاب-وإياب حقيقي، ‏TTL ‏30 ثانية (`health.py`)
GET	`/api/status`	مفتوح	—	حالة التطبيق
GET	`/api/telemetry`	مفتوح	—	قياس عن بُعد خفيف
GET	`/login`	مفتوح	—	صفحة تسجيل دخول متعددة الأنماط
GET/POST	`/api/auth/*`	مفتوح (login/status/oidc)	—	تهيئة المصادقة (`routes_direct`)
GET	`/api/auth/me`	سري	—	الهوية الأصلية (principal)
POST	`/api/chat/stream`	سري	HITL الرسم	دردشة وكيل SSE‏ (`sse_chat`)
WS	`/ws/chat` (إن رُكِّب)	سري	HITL الرسم	دردشة WS‏ (`chat.py`)
POST	`/api/approve/{thread_id}`	سري	استئناف المقاطعة	موافقة/رفض HITL ونطاق YOLO
GET/POST	`/api/ide/*`	سري	HITL الناقل عند التعديل	خلفية IDE‏ (`ide_api`)
GET/POST	`/api/swarm/*`	سري	HITL خط المعالجة	لوحة تحكم السرب
GET	`/api/swarm/tasks/{id}/stream`	سري	—	SSE المهام
CRUD	`/api/settings/*`	سري/مشرف	—	الإعدادات (`settings.py`)
CRUD	`/api/saas/*`	مشرف	—	المستخدمون/المستأجرون (`saas_api`)
GET/POST	`/api/mcp/*`	سري/مشرف	force_danger لـ MCP	إدارة خوادم MCP
GET/POST	`/api/skills/*`	سري	—	واجهة المهارات
GET/POST	`/api/agents/*`	سري	—	حالة/آثار الوكلاء
GET/POST	`/api/models/`، `/api/providers/`	سري	SSRF عند الاكتشاف	النماذج/المزوّدون
GET/POST	`/api/workspace`، `/api/workspaces`	سري	حصر المسار	مساحات العمل
GET/POST	`/api/github/*`	مختلط (ردّ OAuth مفتوح)	—	‏GitHub OAuth/API
GET/POST	`/api/git/*`	سري	HITL للأوامر	عمليات git
POST	`/api/voice/*`	سري	—	‏STT/TTS
GET	`/api/gateway/*`	سري	—	مراقب البوابة
GET	`/metrics`	سري	—	‏Prometheus
POST	`/api/webhooks/telegram`	سر الويبهوك	أدوات الوكيل	ويبهوك Telegram
GET	`/`، `/chat`، `/ide`، `/swarm`، …	صفحات: الهياكل مفتوحة؛ البيانات عبر API	—	صفحات شبيهة بـ SPA
GET	`/settings`، `/dashboard`	سري (HTML مسوَّر)	—	صفحات المشرف

/health/details موجود في SENSITIVE_PREFIXES. تبقى /health/live و/health/ready عامتين.

4.2 مصفوفة الأدوات وCLI

اسم الأداة / الأمر	النوع	الخطر الافتراضي	العزل	الوحدة
`file_read` / `file_list` / `file_search` / `codebase_search`	محلي	آمنة	نطاق مساحة العمل	`tool_registry` + `code_index`
`file_write` / `file_delete`	محلي	خطر	مساحة العمل + HITL	`tool_registry`
`shell_exec`	محلي	خطر	قائمة سماح + تنظيف بيئة + HITL	`tool_registry`
`python_exec` / `code_exec`	محلي	خطر	سجن Docker / قائمة حجب + HITL	`code_exec`
`memory_search` / `memory_store`	محلي	آمنة / كتابة	متجهات/FTS	`tool_registry`
`config_read` / `config_save`	محلي	أسرار مقنّعة / حجب الحسّاس	ConfigStore	`tool_registry`
`spawn_agent` / `spawn_agents`	محلي	خطر (امتداد السرب)	SubAgentManager	`tool_registry` / `sub_agent`
`current_datetime` / `context_info`	محلي	آمنة	—	`tool_registry`
`read_url` / `web_search`	حزمة أدوات محلية	SSRF + تثبيت IP	`validate_url` + `PinHostAsyncTransport` (بلا وكيل)؛ `assert_peer_public`	`tools/read_url`، `security/ssrf_pin.py`
أدوات MCP (ديناميكية)	MCP	خطر/مجهول يفرض HITL؛ غير قائمة السماح يأخذ HITL في الإنتاج	عملية خادم MCP	`mcp/manager`
`kazma serve`	CLI	—	مصادقة مطلوبة لغير loopback	`kazma_cli/main`
`kazma gateway *`	CLI	—	‏HTTP إلى الواجهة	`gateway.py`
`kazma swarm *`	CLI	الإرسال قد يستدعي HITL	‏HTTP API	`swarm.py`
`kazma update` / `project` / `docs`	CLI	—	محلي	وحدات CLI
`/ide *` slash	أمر بوابة	خطر عبر الأدوات	IdeService	`commands.py`
`/yolo`	دردشة/SSE	تجاوز HITL إن سُمح	yolo.py	`sse_chat` / البوابة
`/hitl approve\|deny`	البوابة	استئناف	hitl.py	agent_handler

القسم 5: المرجع الرئيسي للإعدادات والبيئة

اسم المتغير	الافتراضي	مطلوب في الإنتاج	الغرض ونطاق الأمان
`KAZMA_SECRET`	مولَّد (loopback)	نعم (غير loopback)	سر المشرف المشترك / مصادقة API
`KAZMA_HOST`	`127.0.0.1` (CLI/serve)	يُضبط صراحةً	عنوان الربط
`KAZMA_PORT`	‏9090 لـ CLI / ‏8000 لـ Docker	لا	منفذ الاستماع
`KAZMA_TRUST_LAN`	`0`	أبقِه `0`	كوكي تلقائي للشبكة المحلية
`KAZMA_PRODUCTION`	غير مضبوط	نعم (`1`)	فرض code_exec في Docker، إيقاف YOLO، الخزنة مطلوبة، جذر مساحة العمل
`KAZMA_VAULT_KEY`	تطوير تلقائي فقط	نعم	تشفير الأسرار في السكون
`KAZMA_ALLOW_YOLO`	غير مضبوط	لا (معطّل)	اشتراك YOLO تحت الإنتاج
`KAZMA_YOLO_TTL_SECONDS`	1h	لا	انتهاء صلاحية YOLO
`KAZMA_CODE_EXEC_DOCKER`	تلقائي	`force`	سياسة سجن code_exec
`KAZMA_CODE_EXEC_IMAGE`	python:3.12-slim	لا	صورة السجن
`KAZMA_WORKSPACE`	data/workspace	لا	تثبيت مساحة العمل الافتراضية
`KAZMA_WORKSPACE_ROOT`	غير مضبوط	نعم في الإنتاج	حصر مسارات مساحة العمل
`KAZMA_CLONE_DIR`	~/kazma-repos	لا	جذر الاستنساخ
`KAZMA_DATABASE_URL`	غير مضبوط	تعدد النسخ	حالة Postgres مشتركة
`KAZMA_DB_BACKEND`	تلقائي	فرض اختياري	`postgres` / `sqlite`
`KAZMA_PG_POOL_MIN/MAX`	1 / 10	لا	حجم التجمّع
`KAZMA_PG_POOL_TIMEOUT`	5	لا	ثوانٍ الانتظار لاتصال حرّ من التجمّع
`KAZMA_PUBLIC_URL`	غير مضبوط	OAuth/OIDC	عنوان عام أساسي ثابت
`KAZMA_JWT_SECRET`	غير مضبوط	JWT متعدد المستأجرين	مطالبات مستأجر مُتحقَّقة
`KAZMA_CORS_ORIGINS`	قائمة localhost	الإنتاج: أصلك	قائمة سماح CORS
`KAZMA_OPAQUE_SESSIONS`	`1`	أبقِه مفعّلًا	جلسات متصفح معتمة
`KAZMA_SESSION_TTL_SECONDS`	14 يومًا	لا	‏TTL لكوكي الجلسة
`KAZMA_TURN_TIMEOUT_SECONDS`	600	لا	مهلة جدارية للرسم
`KAZMA_MCP_SAFE_ALLOWLIST`	فارغة	اختياري	أدوات MCP تتخطى HITL‏ (الإنتاج)
`KAZMA_ALLOW_PRIVATE_LLM`	غير مضبوط	لا	اشتراك اكتشاف عناوين URL الخاصة
`KAZMA_MULTI_USER`	غير مضبوط	SaaS	فرض النمط متعدد المستخدمين
`KAZMA_OIDC_*`	غير مضبوط	‏SSO لـ SaaS	مُصدر/عميل/سر/إعادة توجيه/مطالبة دور OIDC‏ (يُتحقَّق من id_token؛ بلا احتياطي غير مُتحقَّق)
`KAZMA_PGVECTOR`	تلقائي مع DSN ‏Postgres	لا	`0` يُبقي sqlite-vec؛ غير المضبوط يختار pgvector تلقائيًا للاستدعاء الكثيف
`KAZMA_E2B_API_KEY` / `E2B_API_KEY`	غير مضبوط	كود غير موثوق	`python_exec` عبر Firecracker؛ مفتاح الإيقاف `KAZMA_E2B=0`
`KAZMA_TEMPORAL_HOST`	غير مضبوط	سرب متعدد الساعات	تغليف Temporal لإرسال السرب؛ مفتاح الإيقاف `KAZMA_TEMPORAL=0`
`KAZMA_CODE_INDEX`	مفعّل	لا	`0` يعطّل فهرس الرموز / `codebase_search`
`KAZMA_PROVIDER` / `KAZMA_MODEL`	غير مضبوط	لا	مزوّد/نموذج الإقلاع
`KAZMA_API_KEY` / `OPENAI_API_KEY`	غير مضبوط	المزوّد	مفاتيح LLM‏ (فضّل ConfigStore/الخزنة)
`TELEGRAM_BOT_TOKEN`	غير مضبوط	Telegram	المُكيّف
`TELEGRAM_WEBHOOK_SECRET`	مولَّد إن فُرغ	ويبهوك	أصالة الوارد
`DISCORD_BOT_TOKEN` / `SLACK_*`	غير مضبوط	المنصة	المُكيّفات
`GITHUB_TOKEN` / `GITHUB_OAUTH_*`	غير مضبوط	ميزات GitHub	‏PAT / تطبيق OAuth
`KAZMA_VECTOR_*`	مسار/مجموعة/نموذج	RAG	ذاكرة المتجهات
`KAZMA_EMBED_API_KEY`	غير مضبوط	تضمين بعيد	التضمينات (embeddings)
`KAZMA_BOT_NAME` / `EMAIL`	افتراضيات	لا	هوية git
`KAZMA_DEMO_MODE`	غير مضبوط	لا	اختصارات العرض التجريبي
`KAZMA_CHAOS_ENABLED`	غير مضبوط	لا	مسارات الفوضى
`KAZMA_ENV`	غير مضبوط	`production` لحجب تفاصيل الأخطاء	سياسة تفاصيل الأخطاء
`KAZMA_AUTO_MIGRATE`	`0`	لا	ترحيل entrypoint لـ Docker
`KAZMA_SMOKE_BASE`	localhost:9090	لا	عنوان الأساس لسكربت فحص الدخان
`SWARM_BOT_TOKEN` / `SWARM_CHAT_ID`	غير مضبوط	اختياري	بوت إشعارات السرب

القسم 6: التحقق من جهوزية الإنتاج (مواءمة المعالجة)

إحالة متقاطعة: docs/audits/REMEDIATION_PLAN_2026-07-21.md (كل WP ‏0.x–4.x موسومة مكتملة في الشيفرة).

المرحلة 0 → الأهداف الحية

WP	الملفات المستهدفة	الحالة
0.1 سر serve	`serve.py`	معالَج — لا إسناد لسرّ معروف؛ يرفض السيّئ؛ توليد/loopback
0.2 ربط CLI	`kazma-cli/kazma_cli/main.py`	معالَج — الافتراضي `127.0.0.1`؛ غير loopback يتطلب سرًا
0.3 compose	`docker-compose.yml`، `Dockerfile`	معالَج — `/health`، مسار المتجهات، بيئة الإنتاج

المرحلة 1 → الأهداف الحية

WP	الملفات المستهدفة	الحالة
1.1 الإيقاف	`kazma_ui/app.py` ‏`_on_shutdown`	معالَج
1.2 رفض المهام النشطة	`swarm/engine.py` ‏`reject_checkpoint`	معالَج
1.3 إلغاء الإنهاء	`task_control.py`، `engine._finalize_task`	معالَج
1.4 فحص القاطع	`reliability.py`، `worker_dispatch.py`	معالَج
1.5 إغلاق LLM	`llm_provider.py` ‏`reconfigure`	معالَج
1.6 NullBus	`swarm/bus.py`	معالَج (`False`)
1.7 YOLO في الإنتاج	`safety/yolo.py`، ‏SSE/المسارات	معالَج (+ `KAZMA_ALLOW_YOLO`)

المرحلة 2 → الأهداف الحية

WP	الملفات المستهدفة	الحالة
2.1 اكتشاف SSRF	`models/discovery.py`	معالَج
2.2 code_exec	`tools/code_exec.py`	مُصلَّب
2.3 سياسة shell	`agent/tool_registry.py`	مُصلَّب
2.4 مصادقة رفض-افتراضي	`auth.py`	معالَج
2.5 الكرون	`cron/scheduler.py`	معالَج
2.6 ملكية HITL	`agent_handler/hitl.py`، `routes_direct`	معالَج
2.7 جذر مساحة العمل	`routers/workspaces.py`	معالَج

المراحل 3–4 + صقل التشغيل → الأهداف الحية

المجال	الأهداف	الحالة
جلسات معتمة / RBAC / OIDC	`web_sessions.py`، `platform_rbac.py`، `oidc.py`، `saas_api.py`	مُطلَق
التحوّل إلى Postgres	`config_store.py`، `session_manager.py`، `task_store.py`، `checkpoint.py`، `agent_runner.py`	مُطلَق
‏DR / HA / فحص الدخان	`scripts/`، `docker-compose.ha.yml`، `docs/ops/`	مُطلَق

المخاطر المتبقية المفتوحة (ليست عوائق غير مُصلَحة — متبقية بحسب التصميم)

الخطر	الشدة	ملاحظات
shell/الكود بعد HITL لا يزالان قويين	متبقٍ عالٍ	مقصود بعد موافقة الإنسان؛ YOLO يضخّم
‏MCP غير موثوق بـ `trust: trusted`	متوسط	فخّ تشغيلي للمشغّل
نمط السرّ الفارغ المفتوح على loopback	منخفض–متوسط	‏تجربة مطوّر موثَّقة
شجرتا وثائق / مكتبات غير موصولة	قابلية صيانة منخفضة	خطة تنظيف
قاعدة بيانات متعددة الرئيسيات متعددة المناطق	لا ينطبق	منتج بنية تحتية، لا تطبيق

أوامر التحقق

# Security-critical automated sample
& .venv\Scripts\python.exe -m pytest tests/test_auth_middleware.py tests/test_hitl_wiring.py tests/test_mcp_hitl.py tests/test_pg_store_dual_backend.py -q

# Live smoke (server running)
& .venv\Scripts\python.exe scripts\smoke_production.py --base http://127.0.0.1:9090 --secret $env:KAZMA_SECRET

القسم 7: أبرز جرد الميزات (شاملة الحديثة)

مجال الميزة	الوحدات / الأسطح
مركز القيادة / السرب الحيّ	`swarm.html`، `swarm.js`، `swarm_panel/*`، `swarm_sse.py`
محرّر IDE ‏CodeMirror	`ide.html`، `ide.js`، `ide_api.py`، `ide/service.py`، `tools/file_apply_patch.py`
دردشة SSE متدفّقة	حزمة `sse_chat/`، مُسقِط `chat.js`، `turn_runtime.close_turn`
سجلّ بوابات HITL	`safety/hitl_gates.py`، `hitl_status.py`، `_serverGates` في `chat.js`
الصوت عبر WebSocket	`routes_voice_ws.py`، `voice.js`
ذكاء المستندات	`documents/*`، `documents_api.py`، `documents.html`/`js`، ‏`/documents` للبوابة، مهارة `document_platform`، ‏`DocumentsPanel` في TUI، `scripts/certify_documents.py`
صحة الحارس	`health.py`، الكرون، قواطع الدائرة، cost_breaker
ثقافي/عربي	اللهجات، المُرمِّزات، i18n ar، النبرة/الإيقاع، مكتبة المجلس
تعدد الوكلاء	‏SwarmEngine حيّ؛ `delegation/*` مكتبة فقط
‏SaaS متعدد المستخدمين	تسجيل دخول متعدد الأنماط، `/api/saas`، هوية principal في رأس الطلب
Postgres متعدد النسخ	`db/*`، مخازن مزدوجة، ‏HA compose؛ مهام المستندات + الكتالوج على `KAZMA_PG_TABLES` عند استخدام تلك الخلفية

وثائق ذات صلة

الوثيقة	الدور
`AGENTS.md`	عقد البناء (الثوابت §1–§33)
`docs/docs/guide/architecture.md`	البنية المعمارية السردية
`docs/docs/guide/swarm-orchestration.md`	أنماط السرب + ناقل HITL
`docs/audits/AUDIT_DEEP_2026-09-01_EXEC.md`	التدقيق الصناعي المُلزِم (الموجات 0–8)
`docs/audits/AUDIT_DEEP_STRUCTURE_2026-08-19.md`	تدقيق البنية العميقة
`docs/audits/AUDIT_PRODUCTION_READINESS_2026-07-21.md`	تدقيق جهوزية الإنتاج التاريخي
`docs/audits/AUDIT_DOCUMENT_CERTIFICATION.md`	تقرير اعتماد ذكاء المستندات
`docs/docs/guide/document-intelligence.md`	دليل منتج المستندات
`docs/audits/UNWIRED_INVENTORY.md`	الحزم المكتبية-فقط
`docs/docs/ops/diagnosis-map.md`	التشخيص متعدد المسارات
`docs/plans/GUARD_OPS_ALERTING_CAUSE_QUALITY.md`	تنبيهات الحارس/التشغيل المؤجَّلة

آخر تحديث 2026-09-02. الثوابت في AGENTS.md؛ هذا الملف هو خريطة الوحدات. لا تُدرِج حزمة kazma-memory.

كاظمه — البنية المعمارية وخريطة النظام

كاظمه — البنية المعمارية وخريطة النظام

القسم 1: النظرة التنفيذية العامة وتدفق البيانات

الفلسفة

متطلبات التشغيل

حدود التشغيل

مخطط تدفق البيانات (ASCII)

القسم 2: مرجع المجلدات والوحدات

2.1 الشجرة العلوية (مركّزة على المصدر)

2.2 الحزمة: kazma-core/kazma_core/ (العقل)

2.3 الحزمة: kazma-ui/kazma_ui/

2.4 الحزمة: kazma-gateway/kazma_gateway/

2.5 الحزم: CLI وTUI والمهارات

2.6 سكربتات ونشر

القسم 3: الغوص في الأنظمة الفرعية

3.1 مُشرف الوكيل والرسم

3.2 الأدوات والعزل (Sandboxing)

3.3 محرك السرب والمهام غير المتزامنة

3.4 ناقل الأحداث والخدمات الخلفية

3.5 الذاكرة والاستمرارية

3.6 بوابة الويب وIDE والواجهة

القسم 4: مصفوفات API والمسارات والأدوات

4.1 مصفوفة API والمسارات (الأسطح الرئيسية)

4.2 مصفوفة الأدوات وCLI

القسم 5: المرجع الرئيسي للإعدادات والبيئة

القسم 6: التحقق من جهوزية الإنتاج (مواءمة المعالجة)

المرحلة 0 → الأهداف الحية

المرحلة 1 → الأهداف الحية

المرحلة 2 → الأهداف الحية

المراحل 3–4 + صقل التشغيل → الأهداف الحية

المخاطر المتبقية المفتوحة (ليست عوائق غير مُصلَحة — متبقية بحسب التصميم)

أوامر التحقق

القسم 7: أبرز جرد الميزات (شاملة الحديثة)

وثائق ذات صلة

2.2 الحزمة: `kazma-core/kazma_core/` (العقل)

2.3 الحزمة: `kazma-ui/kazma_ui/`

2.4 الحزمة: `kazma-gateway/kazma_gateway/`