البنية المعمارية

تفكيك عميق مرجعي بالمصدر لمحرك كاظمه: عقل المُشرف، ومسار البيانات من نيّة المستخدم إلى تنفيذ الأداة، والأنظمة الفرعية التي تجعله دائمًا وآمنًا ومتعدد اللغات. الثوابت المُلزمة تعيش في AGENTS.md؛ هذه الصفحة تصف البنية. ولما تبنيه كاظمه بنفسها، كل جزء مع شيفرته واختباره، راجع الهندسة داخل كاظمه؛ ولرسالة واحدة متتبَّعة عبر الشيفرة، راجع كيف يجري الدور. التدقيق المُلزم: AUDIT_DEEP_2026-09-01_EXEC.md (الموجات 0–8 شُحنت).

1. الفلسفة: عقل واحد، أفواه كثيرة

تُنظَّم كاظمه حول فصل صارم بين الاستدلال (رسم LangGraph للمُشرف) والنقل (مُكيّفات المنصات). نسخة رسم واحدة — تُبنى مرة واحدة بـ build_supervisor_graph() — تخدم كل قناة. الرسم لا يرى أبدًا معرّفات خاصة بمنصة؛ المُكيّفات تملكها ولا تعيد ربطها إلا عند إصدار رد.

واجهة CLI‏ (kazma ask) وACP stdio‏ (kazma acp) فمان إضافيان: يبنيان المُشرف نفسه داخل العملية (بلا uvicorn). تُدفّق الرموز عبر register_delta_queue. يستخدم HITL منقّط MemorySaver مع interrupt() في الرسم — ‏y/N عبر TTY، أو session/request_permission عبر ACP.

ينتج عن هذا ثلاث خصائص يعتمد عليها بقية النظام:

حرية المزوّد — العقل يتحدث إلى أي نقطة نهاية متوافقة مع OpenAI عبر httpx. لا يُستورد SDK لأي بائع.
تكافؤ القنوات — وقفة HITL واستدعاء أداة ورمز متدفّق متطابقة سواء نشأت من Telegram أو واجهة الويب أو kazma ask.
حالة دائمة — لأن معرّفات المنصة تعيش خارج الرسم، حالة الرسم محادثية خالصة ويمكن حفظ نقاطها وإعادة تشغيلها واستئنافها عبر إعادة التشغيل.

2. طوبولوجيا الحزم

كاظمه monorepo من ست حزم في عجلة hatchling واحدة (معلنة في pyproject.toml [tool.hatch.build.targets.wheel]). لا توجد حزمة kazma-memory منفصلة — ذاكرة V2 تعيش في kazma_core.memory.

الحزمة	المسار	المسؤولية
`kazma-core`	`kazma-core/kazma_core/`	مشغّل الوكيل، مزوّد LLM، سجل النماذج، محرك السرب، ConfigStore، الأمان، ذاكرة V2، ذكاء المستندات (`documents/`)، المهارات، MCP، الـhub، الضغط، المجلس
`kazma-gateway`	`kazma-gateway/kazma_gateway/`	مُكيّفات Telegram/Discord/Slack، معالج الوكيل (جسر الرسم)، أوامر slash، مخزن الجلسات
`kazma-ui`	`kazma-ui/kazma_ui/`	مصنع تطبيق FastAPI، دردشة SSE، لوحة السرب، الإعدادات، لوحة التحكم، i18n، الأصول الثابتة
`kazma-tui`	`kazma-tui/kazma_tui/`	لوحة Textual TUI‏ (مستهلك غالبًا للقراءة لأحاديات النواة)
`kazma-skills`	`kazma-skills/kazma_skills/`	بيانات تعريف المهارات الأصلية
`kazma-cli`	`kazma-cli/kazma_cli/`	سطح أمر `kazma`

سكربتات الكونسول (pyproject.toml [project.scripts]):

kazma     = "kazma_cli.main:main"
kazma-tui = "kazma_tui.app:main"
kazma-web = "kazma_ui.app:main"

3. عقل المُشرف (LangGraph)

الرسم الأساسي حلقة ReAct. ‏graph_builder.py يسلك العقد؛ الأجسام تعيش في وحدات مقسّمة. لا تبحث عن HITL أو إعادة المحاولة داخل graph_builder.py — ستُفوّت البوابة.

العقدة	الوحدة	الدور
المُشرف	`graph_supervisor.py` (`supervisor_node`, `_call_llm_with_retry`)	استدعاء LLM + توجيه الأدوات. يعيد محاولة `LLMError` العابر فقط.
عامل الأدوات	`graph_tool_worker.py` (`tool_worker_node`, `_commitment_resolve_gate`)	الالتزام أولًا، ثم `interrupt()` لـ HITL، ثم التنفيذ.
الرد	`graph_respond.py` (`respond_node`)	الرد النهائي. يتخطى التوليف عندما تكون `turn_failed` مضبوطة.
السلك	`graph_builder.py` (`build_supervisor_graph`)	يجمّع الرسم؛ يمرر `hitl_config` إلى إغلاق عامل الأدوات.

3.1 طوبولوجيا العقد

flowchart LR
    START([user message]) --> SUP[Supervisor]
    SUP -- "LLM calls tools" --> TW[Tool Worker]
    TW -- "tool results" --> SUP
    SUP -- "no tool calls" --> RESP[Respond]
    RESP --> END([reply / SSE / journal])
    TW -- "danger tool + HITL on" --> INT[LangGraph interrupt]
    INT -- "approve via registry" --> TW
    INT -- "deny / timeout" --> RESP

HITL نشط فقط عندما يُمرَّر hitl_config في مواقع البناء الثلاثة كلها: agent_runner.get_streaming_graph() وagent_runner._ensure_graph، وإعادة ترجمة إقلاع app.py إلى _graph_holder. الإعداد الحي هو get_hitl_config()؛ والمهلة الافتراضية في YAML هي 300s (safety.hitl.approval_timeout_seconds)، وليست 60.
القرار مقابل التنفيذ: ‏hitl_gates.db يملك ما إذا كانت البوابة قد أُجيبت؛ ونقطة حفظ LangGraph تملك ما إذا كان الرسم متوقفًا مؤقتًا. الويب يرسم من السجل (chat.js _serverGates). انظر AGENTS.md §7 + §30 + §31.
السياق: طبقتان، لا تسطّحهما. لا يزال ContextAuthority / TokenCounter.should_compact ينطلق عند 80% من نافذة النموذج. وبشكل مستقل، ينطلق تشذيب سلامة السياق عند 95% من النافذة (يحدد agent.trim.token_budget ميزانية أخرى) وتعمل شبكة التلخيص عند كل إسقاط لأدوار المستخدم/المساعد (AGENTS.md §29). اختفى النطاق الميت القديم “التلخيص عند 80% من النافذة”.
تسليم الدور: فقاعة SSE/WS هي إسقاط من يومية الدور. close_turn هو المغلق الوحيد. تفاضلات الرموز تُلحق؛ وturn_complete وحده يستبدل. لا تستعد رسّامًا ثانيًا.

3.2 التنفيذ الدائم

المنقّط: AsyncSqliteSaver على kazma-data/checkpoints.db، أو checkpoints* في Postgres عندما يُضبط KAZMA_DATABASE_URL (تلك الجداول في KAZMA_PG_TABLES).
هوية الخيط: thread_id من المُرسِل (مثل gw-telegram-12345) أو UUID — agent_handler/store.py. معرّفات المنصة لا تدخل حالة الرسم أبدًا.
التعافي من التعطل: تبقى توقفات HITL للرسم في مخزن نقاط الحفظ، وتوقفات السرب في CheckpointManager.restore_paused_tasks(). عند إقلاع المالك الحصري، يحتفظ boot_sweep() بالصفوف التي انقطع حجزها أو استئنافها كأخطاء تنفيذ مع حفظ القرار وصاحبه. ولا يمس الصفوف المعلّقة أبدًا؛ يجب أن تنجو البطاقة من إعادة التشغيل. تعيد إيصالات أدوات الرسم النتائج المكتملة وتحجز الآثار المجهولة للفحص.
الإيقاف: يجب أن يوقف _on_shutdown() الـcron أولًا، ثم يصفّي _task_handles للسرب / ‏stop_all()، ثم يغلق المخازن / تجمع HTTP / البوابة. القتل القاسي قد يفسد SQLite.
السفر في الزمن: ‏/replay و/fork (slash)؛ اللقطات في kazma-data/snapshots.db (‏LRU بقيمة 50 لكل خيط). يكتب /fork خيطًا جديدًا ويجب ألا يستبدل active_thread.{sender}.

4. مسار البيانات من طرف إلى طرف

sequenceDiagram
    participant U as User (Telegram/Web/...)
    participant A as Platform Adapter
    participant S as SessionStore
    participant H as AgentHandler (graph bridge)
    participant G as Supervisor Graph
    participant L as LLM Provider (httpx)
    participant T as ToolRegistry
    participant M as Bus (HITL)

    U->>A: text message
    A->>S: put(thread_id, {chat_id, user_id, ...})
    A->>H: IncomingMessage (no platform IDs in body)
    H->>G: graph.ainvoke({messages:[...]}, config={thread_id})
    loop ReAct
        G->>L: POST /chat/completions (tools=...)
        L-->>G: tool_calls or final text
        alt danger tool
            G->>M: interrupt(approval_input)
            Note over G,M: graph SUSPENDED
            M-->>U: approval request (inline button / SSE event)
            U->>M: approve
            M->>G: Command(resume={"approved":true})
        end
        G->>T: execute(tool, args)
        T-->>G: ToolResult
    end
    G-->>H: final state
    H->>S: get(thread_id)  // rehydrate platform IDs
    H->>A: OutboundMessage(target_id, text)
    A-->>U: reply

ثوابت رئيسية تُفرض على طول هذا المسار:

الثابت	يُفرض بواسطة	الموقع
معرّفات المنصة لا تدخل حالة الرسم أبدًا	`_PLATFORM_KEYS` + `_build_initial_state`	`agent_handler/store.py`
الرد يوجَّه عائدًا إلى الدردشة الصحيحة	`_build_target_id(platform, ctx)`	`agent_handler/store.py`
نموذج المزوّد الخاطئ لا يصل النقطة الخاطئة أبدًا	التصحيح التلقائي في `get_client()`	`model_registry.py`
الأدوات الخطرة تتوقف مؤقتًا، ولا تنفذ بصمت أبدًا	`interrupt()` في `graph_tool_worker.py` + صف السجل	`graph_tool_worker.py`، `hitl_gates.py`
تبديل المزوّد يبطل العملاء القدماء	`set_active_model` يمسح الذاكرة المؤقتة	`model_registry.py`
دور LLM الفاشل لا يُولَّف	`turn_failed` → `respond_node` يتخطى	`graph_supervisor.py`، `graph_respond.py`
العميل لا يؤلف حالة HITL	إسقاط `_serverGates` / TurnDocument	`chat.js`، `turn_runtime.close_turn`

5. طبقة مزوّد LLM

kazma-core/kazma_core/llm_provider.py عميل httpx رفيع وخالٍ من SDK. يتحدث صيغة التوصيل OpenAI Chat Completions إلى أي نقطة متوافقة. معظم المزوّدين (OpenAI وDeepSeek وGroq وMistral وTogether وCohere وFireworks وPerplexity وAI21 وxAI وOpenRouter وNVIDIA NIM وOllama وLM Studio) يعملون عبر LLMProvider العام هذا مع Authorization: Bearer.

أربعة مزوّدين لديهم أصناف أصلية مخصصة (مخطط مصادقتهم أو طلبهم يختلف عن صيغة توصيل OpenAI) ويُوزَّعون في model_registry.get_client() / get_model() / get_client_by_provider():

المزوّد	الصنف	لماذا أصلي
Google Gemini	`GeminiProvider` (`google_llm.py`)	Vertex AI، وADC، وعنوان أساسي محسوب
Anthropic	`AnthropicProvider` (`anthropic_llm.py`)	مخطط `/messages`، و`x-api-key` + `anthropic-version`
Azure OpenAI	`AzureProvider` (`azure_llm.py`)	ترويسة `api-key` + معامل استعلام `api-version`، وتوجيه النشر
AWS Bedrock	`BedrockProvider` (`bedrock_llm.py`)	توقيع SigV4 + ‏Converse API

انظر مزوّدو LLM للقائمة الكاملة والإعداد.

5.1 تحليل المزوّد

يعيد ModelRegistry.get_client(model=None) ‏LLMProvider مخزّنًا مؤقتًا للملف النشط. شبكة الأمان الحرجة:

# model_registry.py (paraphrased)
if effective_model:
    owner = self.find_provider_for_model(effective_model)
    if owner and owner["name"].lower() != provider_name.lower():
        # e.g. a DeepSeek model requested while OpenAI is active
        provider_name = owner["name"]      # auto-correct
        if model is None:
            self._active_provider = owner_name
            self._config_store.set("registry.active_provider", owner_name, ...)

لهذا السبب تعد “لا تغيّر النموذج أبدًا دون المزوّد” قاعدة صارمة — انظر استكشاف الأخطاء ← عدم تطابق المزوّد/النموذج وإعدادات المزوّد في التهيئة.

5.2 حل تراجع الأدوات في NVIDIA NIM

بعض المزوّدين (لا سيما NVIDIA NIM) يرفضون تعريفات الأدوات بخطأ 404 "Function not found". يكشف العميل ذلك ويعيد المحاولة مرة واحدة دون أدوات بحيث يحصل المستدعي مع ذلك على إجابة نصية:

nim_function_not_found = status_code == 404 and "function" in detail_lower
tool_schema_error = (
    status_code in (400, 422)
    and any(tok in detail_lower for tok in ("tool", "function"))
)
if tools and (nim_function_not_found or tool_schema_error):
    logger.warning("Provider rejected tool definitions; retrying without tools.")
    payload.pop("tools", None)
    payload.pop("tool_choice", None)
    resp = await client.post("/chat/completions", json=payload)

لا تُزل هذا الفرع. إزالته تكسر الوكلاء مستخدمي الأدوات على NVIDIA NIM وغيره من المزوّدين الصارمين.

5.3 البث

بث الرموز هو LLMProvider.chat_stream() يستهلكه invoke_llm_chat() (llm_stream.py)، الذي يحقن أحداث on_chat_model_stream اصطناعية لـ SSE/WS. مفتاح الإلغاء: KAZMA_LLM_STREAM=0 (‏chat() حظر). انظر ‏API ونقاط التوسعة.

5.4 التكلفة وإعادة المحاولة

الاهتمام	الآلية	الموقع
تكلفة كل استدعاء	`(prompt_tokens * in_cost/1M) + (completion_tokens * out_cost/1M)`	`llm_provider.py`
سقف التكلفة	`CostCircuitBreaker` (الافتراضي $0.50، صمت 5 دقائق) — متغيرا البيئة `KAZMA_MAX_COST`، `KAZMA_SILENCE_WINDOW`	`cost_breaker.py`
إعادة المحاولة	المُشرف: `LLMError` العابر فقط (`graph_supervisor.py`). المزوّد: 429 + الشبكة. أخطاء 4xx الدائمة تفشل سريعًا.	`graph_supervisor.py`، `llm_provider.py`
معالجة تحديد المعدل (429)	‏Retry-After + تراجع أُسّي بثلاث محاولات؛ استنفاد 429 يعني `transient=True` + `kind=rate_limit_exhausted` (المُشرف يتخطى إعادة محاولة نفس المزوّد؛ التبديل لا يزال ينطلق)	`llm_provider.py`، `anthropic_llm.py`

قاطع التكلفة dataclass مستقلة؛ يجب على طبقة الوكيل قيادتها عبر record_cost / should_halt. هي ليست موصولة تلقائيًا في chat().

5.5 المخططات الصارمة والمخرجات المهيكلة

كائنات معاملات الأدوات المولّدة من تلميحات النوع (agent/tool_schema.py) هي JSON Schema مغلق: ‏additionalProperties: false على الجذر والكائنات المتداخلة التي لها properties. وrequired هي المعاملات بلا قيم افتراضية في Python (آمنة للمزوّدين). معاملات dict[K, V] حرة الشكل تبقى مفتوحة (additionalProperties هو مخطط القيمة) حتى يستمر عمل env={...}.

‏OpenAI Structured Outputs للأدوات اختياري: KAZMA_STRICT_TOOLS=1 يختم function.strict: true ويرفع كل خاصية إلى required، لاغلفًا الاختيارات السابقة كـ anyOf: [T, {type: null}]. الأدوات التي لا تستطيع تلبية ذلك العقد (القواميس المفتوحة) تبقى غير صارمة حتى لا ترجع Anthropic / Gemini / الخوادم المحلية خطأ 400.

الردود المهيكلة بـ JSON‏ (لا استدعاءات الأدوات) تستخدم LLMProvider.chat(..., response_format={"type": "json_schema", ...}) / json_object. المساعد: json_schema_response_format(). حلقة المُشرف لا ترفق هذا في كل دور. المزوّدون الذين يرفضون response_format تُعاد لهم المحاولة مرة واحدة بدونه. Anthropic/Bedrock الأصليان يقبلان الوسيطة لتكافؤ التوقيع ويتجاهلانها.

5.6 خطافات الأدوات (PreToolUse / PostToolUse)

استدعاءات راجعة قابلة للبرمجة حول LocalToolRegistry.execute والتنفيذ الموحد لـ MCP‏ (agent/tool_hooks.py). بأسلوب Claude Code:

الحدث	يستطيع	لا يستطيع
PreToolUse	رفض الاستدعاء، أو إعادة كتابة الوسائط	تخطي HITL، تخطي الالتزام، الموافقة التلقائية على الأدوات الخطرة
PostToolUse	إلحاق ملاحظة مراقبة قصيرة	التراجع عن أداة نفّذت بالفعل

داخل العملية: register_pre_tool_hook / register_post_tool_hook (‏glob للمطابقة أو a|b). أوامر المشغّل: ‏YAML/ConfigStore ‏agent.hooks.pre_tool / post_tool — ‏JSON في stdin، وJSON في stdout (أو الخروج بالرمز 2 = رفض). تُنشأ بـ asyncio.to_thread(subprocess.run) (‏SelectorEventLoop في Windows). القوائم الفارغة = لا عملية. مفتاح الإلغاء: KAZMA_TOOL_HOOKS=0. الخطاف المتعثر يفتح عند الفشل (الأداة لا تزال تعمل)؛ يبقى الأمان HITL + الالتزام.

5.7 وضع التخطيط

فحص-ثم-اقتراح من الدرجة الأولى (agent/plan_mode.py). بينما /plan مفعّل لخيط، يوحّد المُشرف read_only + no_writes في hard_constraints. تزيل filter_tools_for_constraints أدوات الكتابة/التنفيذ من مخطط LLM؛ وقائمة السماح لدى عامل الأدوات تحجبها إن ظل النموذج يسمّي واحدة. لا يستطيع YOLO توسيع قائمة السماح تلك.

‏/plan go أو رد قصير تابع / موافقة يخرج من وضع التخطيط، ويسقط تلك الوسوم، ويحقن ملاحظة نظام للتنفيذ بحيث ينفّذ تشغيل الرسم نفسه الخطة. لا تزال HITL تبوّب الأدوات الخطرة. مفتاح الإلغاء: KAZMA_PLAN_MODE=0.

6. تنسيق السرب (نظرة عامة)

عندما يحتاج المُشرف إلى أكثر من وكيل، ينتقل التحكم إلى SwarmEngine (kazma-core/kazma_core/swarm/engine.py). تُدعم ستة أنماط توزيع كـ TaskType enum‏ (swarm/task.py): ‏DISPATCH وBROADCAST وPIPELINE وFAN_OUT وCONSULT وCONDITIONAL.

flowchart TB
    subgraph SwarmEngine
        DI[dispatch_inner]
        DI -->|single| DSP[dispatch]
        DI -->|all| BCAST[broadcast]
        DI -->|ordered| PIPE[pipeline + blackboard]
        DI -->|parallel| FAN[fan-out + aggregate]
        DI -->|opinions| CONS[consult + synthesize]
        DI -->|router| COND[conditional routes]
    end
    DSP & BCAST & PIPE & FAN & CONS & COND --> W[Worker / InProcessWorker]
    W --> REL[ReliabilityRegistry]
    REL --> CB[CircuitBreaker]
    REL --> RT[RetryPolicy]
    REL --> TO[TimeoutGuard]
    REL --> OV[OutputValidator]
    REL --> BC[BoundedConcurrency]
    PIPE -.->|hitl_checkpoints| CK[CheckpointManager]

التسليمات بين العمال محمية من العودية اللانهائية: ‏MAX_HANDOFF_DEPTH = 5 وMAX_VISITS = 2 (عدد زيارات لكل عامل، لا مجموعة منطقية) يعيشان في swarm/handoff_guards.py. ‏HITL الخاص بـ Swarm FanOut ثلاثي الحالات (True يحسم؛ False صوت حتى expected_voters أو الموعد النهائي) — ليس أول-منطقية-تفوز. انظر تنسيق السرب لكتالوج الأنماط الكامل.

يكشف المحرك أيضًا get_autoscaler() (كسول) — عندما لا تكون لمهمة عامل مسجل مطابق، ينشئ واحدًا تلقائيًا من swarm_templates.json ويختار أفضل نموذج متاح لنوع المهمة. انظر تنسيق السرب §14.

7. أنظمة الذاكرة الفرعية (نظرة عامة)

ذاكرة الدردشة لدى كاظمه هي المحرك الإدراكي V2 (رسم معتقدات ثنائي الزمن، استرجاع PPR). أُزيلت رصة RRF ذات الأربع طبقات في V1 في الانتقال V1→V2؛ وV2 هي الرصة الوحيدة. القطع المساندة:

النظام الفرعي	الدعم	يستخدمه	الحالة
المحرك الإدراكي V2	رسم معتقدات ثنائي الزمن + حلقات من 4 مستويات + sqlite-vec (`memory_state.db`)؛ pgvector عندما يكون Postgres مفعلًا	الدردشة (استرجاع لكل دور، أدوات، تخزين تلقائي، ضغط) + السرب + التحسين الذاتي	✅ افتراضي الدردشة — مسار قراءة/كتابة واحد (`recall()` من `memory/recall.py`)
PPR لرسم الأنا المحلي	PageRank شخصي فوق رسم المعتقدات/الحلقات (قفزتان، N≤200)	تعزيز استرجاع V2	✅ `memory/ppr.py`
المُدمج	استخراج المعتقدات + الحلقات بـ LLM/استدلالي، محاط بسور التوجيه	مسار الكتابة بعد الدور	✅ `memory/consolidator.py`
طابور الدمج الدائم	طابور عمال مدعوم بـ SQLite‏ (`memory_ops.db`)	استخراج معتقدات غير متزامن، نوم كلي، نسخ احتياطي/تصدير	✅ `memory/task_queue.py`
مكتبة المعرفة	‏Chroma‏ `kazma_kb_*` لكل مكتبة + كتل SQLite	‏RAG للوثائق (أدوات `knowledge_*`)	✅ معزولة عن ذاكرة الدردشة

مسار الكتابة: mutate_belief هو خنق INSERT الأوحد. معتقدات كائن الحمولة تحصل أيضًا على حافة related_to مركزية (memory/ego_anchor.py) حتى لا تعرض اللوحة مفاهيم منفصلة. مرآة حالة Postgres الاختيارية تتلقى شواهد القبور عند الإبطال/الاستبدال/المسح؛ والكتابة المزدوجة الاختيارية في Neo4j تحذف تلك الحواف أيضًا.

المجدولات (كلها تنطلق من start_memory_worker() — أضف جديدًا هناك وإلا فلن يعمل أبدًا): ‏macro_sleep كل 6h؛ نسخ احتياطي/تصدير كل 6h + native_pg_backup (وليس 24h)؛ إعادة دمج كل 24h؛ جمع التزامات كل 15m (يركب أيضًا TTL بوابة HITL)؛ إضافة إلى تنظيف الجلسات، وملخص يومي، ودفتر إطلاق أسبوعي، وتمرين استرداد.

الإعداد: رايات memory.* تستخدم ConfigStore ← kazma.yaml (kazma_core.memory.config)؛ وV2 مفعّل عند memory.v2.use_new_stack: true. التفاصيل الكاملة في الذاكرة وRAG. التدقيق: AUDIT_MEMORY_SYSTEM_2026-08-24.md.

8. الطبقة العربية والثقافية

كاظمه عربية الأصل افتراضيًا (agent.language: ar، agent.rtl: true). ثلاثة مكوّنات تنفذ هذا:

المرمِّز العربي (kazma_core/msa_tokenizer.py) — تطبيع الفصحى (أشكال الألف، التشكيل). حزمة kazma-memory القديمة أُحيلت إلى التقاعد.
i18n + واجهة RTL (kazma-ui/kazma_ui/i18n/ بوحدة فهرس لكل قسم، static/css/kazma.css) — قاموس TRANSLATIONS مدمج (EN/AR)، وdir/lang لكل طلب، وIBM Plex Sans / IBM Plex Sans Arabic، وجذر مشترك 14px، وأرضية قراءة للفئات الصغيرة.
بروتوكول المجلس (kazma-core/kazma_core/majlis.py) — تدفق محادثة ثقافي خليجي من 4 مراحل (‏GREETING → SOCIAL → TRANSACTION → FAREWELL) مع افتراضات اللهجة الكويتية ومعدّلات ثقافية (رمضان، العيد، اليوم الوطني).

انظر الميزات العربية والثقافية.

9. الرصد (الحالة الحالية)

الإشارة	المصدر	الحالة
السجلات المهيكلة	`logging` (خيار صيغة JSON في `kazma.yaml`)	✅ نشط
مقاييس السرب	`MetricsCollector` (في الذاكرة + SQLite) — `tasks_completed`، `tasks_failed`، `avg_latency`، `total_tokens`، `total_cost`	✅ نشط
فترات التتبع	`TraceStore` منزلي الصنع (ذاكرة حلقية + WebSocket إلى لوحة التحكم) + `TracingEmitter` (السرب، بمكتبة قياسية فقط)	✅ نشط
أدوات بحث الويب	`read_url` / `web_search` / `crawl_site` / حفظ+هضم البحث (`tools/read_url.py`، `web_research.py`)	✅ نشط — بحث الويب
قياسات SSE عن بُعد	أحداث `/api/chat/stream`؛ موجّه القياس عن بُعد	✅ نشط
Langfuse	`KazmaTracer` مع `backend="langfuse"`؛ يفعّل `logging.langfuse.enabled: auto` عند وجود المفاتيح	✅ موصول (مفتاح إلغاء `KAZMA_LANGFUSE=0`)
OpenTelemetry	فترات GenAI لكل استدعاء LLM وتنفيذ أداة (`observability/genai_otel.py`)	✅ اختياري — ثبّت `opentelemetry-sdk` + مصدّر OTLP واضبط `OTEL_EXPORTER_OTLP_ENDPOINT` (دليل العمليات)
Prometheus	`/metrics` + `/api/metrics` (`kazma_ui/metrics.py`)	✅ نشط

OpenTelemetry — فترات GenAI‏ (اختياري)، بعد إزالة الخلفية القديمة

منذ 2026-09-14 تُصدر كاظمه فترات OpenTelemetry GenAI بالاصطلاحات الدلالية لكل استدعاء LLM وتنفيذ أداة عندما يكون SDK مثبتًا ونقطة OTLP مضبوطة؛ لا شيء منها تبعية لكاظمه (دليل العمليات). ما يلي هو سجل الخلفية الأسبق، التي أُزيلت.

كانت خلفية OpenTelemetry القديمة معلنة كتبعية بكود حقيقي، لكنها لم تكن قابلة للوصول أبدًا في وقت التشغيل — لا مسار إعداد يختار backend="opentelemetry". كانت الإضافة [tracing] (6 حزم) حملًا ميتًا خالصًا (لم تُستورد أبدًا).

أُزيلت في تنظيف يوليو 2026:

طريقة _init_opentelemetry() + الطرق الأربع _trace_*_otel() كلها من KazmaTracer
قيمة OPENTELEMETRY من enum‏ TracingBackend
opentelemetry-api + opentelemetry-sdk من تبعيات النواة
الإضافة الاختيارية [tracing] بأكملها (6 حزم) من pyproject.toml
حقل otlp_endpoint + "opentelemetry" من الخلفيات الصالحة في TracingConfig

للتتبع الآن خلفيتان: Langfuse (الأولية، تفعل تلقائيًا عند وجود المفاتيح) وConsole (الاحتياطية). يبقى TraceStore المنزلي (ذاكرة حلقية + لوحة WebSocket) وTracingEmitter الخاص بالسرب (بمكتبة قياسية فقط، بصيغة فترات متوافقة مع OTel وبلا حزمة OTel) دون تغيير.

10. مخازن البيانات المتقاطعة

تتشارك جميع مخازن SQLite في كاظمه نمط التزامن نفسه، الممركز في config_store.py apply_sqlite_pragmas():

PRAGMA journal_mode=WAL;       -- concurrent readers, single writer
PRAGMA busy_timeout=5000;      -- 5 s wait on lock
PRAGMA synchronous=NORMAL;     -- WAL-safe, faster than FULL

المخزن	المسار	الغرض
ConfigStore	`kazma-data/settings.db`	إعدادات وقت التشغيل (تتخطى `kazma.yaml`). تفاضلات الروح: المفتاح `self_improvement.agent_evolution`
منقّط LangGraph	`kazma-data/checkpoints.db` أو `checkpoints*` في Postgres	حالة المحادثة، وقفات التنفيذ لـ HITL
سجل بوابات HITL	`kazma-data/hitl_gates.db`	حقيقة القرار لـ HITL‏ (‏CAS). أحادي العملية؛ ليس في `KAZMA_PG_TABLES`
يومية الأدوار / القطع الأثرية	`kazma-data/` (يومية الأدوار + `agent_artifacts.db`)	مصدر الحقيقة لتسليم الأدوار؛ مقترحات دائمة
مخزن المهام	`kazma-data/swarm_tasks.db`	مهام السرب + مقاييس العمال
لقطات السفر في الزمن	`kazma-data/snapshots.db`	تاريخ `/replay` / `/fork`
ذاكرة V2 (الساخنة)	`kazma-data/memory_state.db`	المعتقدات، الحلقات، الكيانات، PPR
ذاكرة V2 (العمليات)	`kazma-data/memory_ops.db`	طابور دائم، تدقيق — لا تدمج مع الساخنة
Cron	`kazma-data/cron.db`	التذكيرات؛ يُلتقط `delivery_target` عند الجدولة
سجل الـHub	`~/.kazma/hub/registry.db`	المهارات المثبتة
المتجهات / مكتبة المعرفة	`kazma-data/vector_memory`، `kazma_kb_*`	معزولة عن ذاكرة الدردشة
مخزن الجلسات (البوابة)	قابل للتهيئة	ربط معرّف المنصة ↔ thread_id‏ (‏TTL بقيمة 300s — ليس للتذكيرات)
مخزن المستندات	`{documents.storage_root}/documents.db` + شجرة CAS (الجذر الافتراضي `kazma-data/document-store/`)	الفهرس، والمهام، وحجوزات الاستقبال، والتدقيق + الكتل والبيانات التعريفية (manifests). في تثبيت Postgres تكون المهام و(افتراضيًا، حين يكون `KAZMA_DOCUMENTS_METADATA_BACKEND` غير مضبوط أو `auto`) الفهرس جداولَ Postgres؛ وتبقى الملفات على القرص

ذكاء المستندات (نظام فرعي)

يعيش الاستيعاب/التحليل/OCR/الفهرسة/التوليد الدائم للمستندات تحت kazma_core/documents/. الحد الدائم العام: ‏DocumentIngestionService (الويب /api/documents/*، الأدوات، البوابة /documents (الاسم البديل /docs)، و‏TUI عبر واجهة الويب API). حد التنفيذ: ‏DocumentService، الذي يحلّل ويجري OCR ويعدّل ويولّد في عامل معزول. نمطا عامل (KAZMA_DOCUMENT_WORKER_ISOLATION): process (الافتراضي) عملية فرعية ببيئة منظّفة وحدود للذاكرة والمعالج، لكن بلا حصر لنظام الملفات أو الشبكة، فتبلّغ الجاهزية عنه بأنه غير مؤهل للمستندات العدائية؛ وcontainer يرسل كل تشغيل إلى وسيط مستندات يشغّله في حاوية جديدة موثَّقة بلا شبكة ولا تركيبات، دون أي رجوع إلى process. سياسة واحدة للمحتوى النشط في PDF ترفض النصوص البرمجية والإجراءات الخارجية والمرفقات والروابط غير الويبية عند الاستقبال، وعند كل تعديل، وفي كل PDF مولَّد، داخل العامل. التحليل البعيد (LlamaParse/Reducto) معطّل ما لم يُضبط documents.security.remote_parse، ويعمل في عملية كاظمه مع صف تدقيق قبل كل رفع.

تُقبل عمليات الرفع قبل قراءة جسمها: حجز دائم لكل رفع يمسك ميزانيات الطابور والمستأجر والمعدل. ويُتراجَع عن رفعٍ قطعه انهيار؛ ورفعٌ توقّف مالكه عن تجديد عقد إيجاره (مضيف آخر، أو عملية متوقفة مؤقتًا) يُستولى عليه ويُسيَّج، فلا يستطيع المالك نشره لاحقًا. يمكن أن يستخدم انتزاع المهام Postgres‏ (jobs_pg.py). البيانات الوصفية للمستندات تتبع خلفية المهام ما لم يقل KAZMA_DOCUMENTS_METADATA_BACKEND غير ذلك، وتنتقل إلى repository_pg.py حين تكون تلك Postgres والتجمع يعمل. يجب أن يبلّغ الجاهزية بعقدة واحدة كلما كانت خلفية البيانات الوصفية النشطة SQLite — لا تدّعي توفرًا عاليًا أبدًا من مسار غير مستخدم. تلك الجداول، ومعها حجوزات الاستقبال، في KAZMA_PG_TABLES (‏H-13)؛ ويُنسخ مخزن مستندات Postgres احتياطيًا مع ملفاته نقطةً زمنية واحدة (backup_pg.py). الدليل الكامل: ذكاء المستندات · خريطة المراحل · الأمان.

الأمان والمرونة (متقاطعان)

يعمل عبر المُشرف والأدوات نظامان فرعيان متقاطعان:

محرك عدم التوقف والشفاء الذاتي. يغلف supervised_invoke() تنفيذ الرسم بنبضات العقد وكشف التعثر؛ عند التعثر يتراجع إلى آخر نقطة حفظ دائمة، ويحقن تأمل [KAZMA RECOVERY]، ويستأنف حتى N محاولة. النماذج الأولية المستنفدة تفشل نازلة عبر agent.nonstop.failover.chain مع فترات تبريد لكل نموذج (دون تغيير الملف النشط). يسجل دفتر استدعاءات LLM الدائم (kazma-data/llm_calls.db) كل استدعاء؛ وتُعاد مهام السرب التائهة إلى الطابور عند الإقلاع؛ وكلب مراقبة يرفض تلقائيًا موافقات HITL القديمة بعد safety.hitl.approval_timeout_seconds. التفاصيل: الميزات الأخيرة → Non-Stop.
طبقة الالتزام (الحل-قبل-الفعل). بوابة سياسات بين LLM والطفرات الدائمة. قبل الجدولة/الإرسال/التنفيذ/تغيير الإعداد، يحل authorize_effect النية مقابل الذاكرة والسياسة؛ الأفعال الملتبسة ترفع بطاقة مقاطعة توضيح/تأكيد دلالية على كل منصة. يعمل في graph_tool_worker.tool_worker_node قبل انقسام HITL حتى يستطيع إعادة كتابة وسائط الأداة أولًا. دليل مخصص: طبقة الالتزام.
سجل بوابات HITL. صف واحد لكل طلب في hitl_gates.db (pending → claimed → resuming → settled). الأسطح تعرض فقط؛ وهي لا تسكّها أبدًا. Swarm FanOut ثلاثي الحالات؛ وclaim_gate في الويب أول مطالبة 200 / ثانية 409.
بطاقات الموافقة. دردشة الويب بلا حد معدل للبطاقات — كل بوابة تظهر فورًا. المنشورات المدعومة بالمقترحات المتمايزة (x_post/x_schedule_post مع proposal_id) تظهر بطاقتها دائمًا على كل مسار؛ وحد الانفجار لدى البوابة 3-بطاقات-لكل-4-دقائق ينطبق فقط على عواصف حلقات إعادة محاولة التنفيذ على مُكيّفات المنصات ويعفي بطاقات X/المقترحات عمدًا. البطاقات المتروكة تنتهي صلاحيتها عند safety.hitl.approval_timeout_seconds (الافتراضي 300): لا تُشغَّل الأداة، ويُبلَّغ النموذج بأن الموافقة انتهت صلاحيتها (لا بأنك رفضتها)، وتُغلق البطاقة؛ وفي Telegram وDiscord وSlack تتلقى الدردشة إشعارًا وبقية الدور. ويُختم الموعد النهائي كـ approval_deadline على حمولة SSE وبوابات حالة الجلسة وعناصر الموافقة المعلقة، وبطاقة الدردشة تعد تنازليًا إليه. “السماح بالأداة (جلسة)” تمنح أداة واحدة لنحو 30 دقيقة في الخيط. أما الأداة التي تطلب الموافقة دائمًا (عمليات الكتابة في X) فلا تعرض إلا موافقة لمرة واحدة والرفض: لا “السماح بالأداة”، ولا YOLO.
تسليم الأدوار V2. اليومية + close_turn هما مصدر الحقيقة؛ وSSE/WS/chat.js تسقط. صف سجل معلق يبقي الدور مفتوحًا. لا رسّام ثانٍ.
إنذارات العمليات. ثلاثة مسارات فقط: Guard مباشر عبر Telegram (الابن متوقف)، وops_alerts FanOut (فشل داخل التطبيق)، وlifecycle_notifier (إقلاع/إيقاف). جودة السبب لهياكل 503 لدى Guard مؤجلة: GUARD_OPS_ALERTING_CAUSE_QUALITY.md.
SSRF. الكشط المباشر يثبت الـIP المُتحقق منه (PinHostAsyncTransport)؛ أجهض إذا كان النظير خاصًا. لا تثبت عبر proxy=.

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

الذاكرة (انتقال 2026-07): ‏V2 (معتقدات ثنائية الزمن + استرجاع PPR) هي رصة الذاكرة الوحيدة. أُزيل محول RRF ذو الأربع طبقات في V1؛ الملاحظات التي تشير إلى UnifiedMemoryAdapter / VectorMemory كمسار الدردشة متقادمة.
لا تثبّت أرقام الأسطر في هذا الدليل. الوحدات تتحرك (graph_tool_worker.py، حزمة sse_chat/، حزمة agent_handler/). سمِّ الوحدة؛ AGENTS.md هي قائمة الثوابت.
agent_handler حزمة وليست ملفًا (store.py، graph.py، commands.py، …).
UnifiedModelRegistry اسم بديل لـ ModelRegistry.
حزمة kazma-memory غير موجودة. المرمِّز العربي هو kazma_core/msa_tokenizer.py.
التدقيق المُلزم: AUDIT_DEEP_2026-09-01_EXEC.md. لا تتبع الجزء 6 من الـdump.