خريطة التشخيص (الأنظمة متعددة المسارات)

خريطة التشخيص — الأنظمة متعددة المسارات

الغرض: حين “يلمس” خطأٌ “ملفات كثيرة”، تجيب هذه الوثيقة عن: ما العنصر نفسه، وكم مسارًا يخدمه، وأين تنظر أولًا.

الجمهور: المشغّلون، والمساهمون، ووكلاء البرمجة.
الرفيق: السرد في البنية · فهرس الوحدات الكامل docs/ARCHITECTURE_AND_SYSTEM_MAP.md · قواعد الوكلاء AGENTS.md.

كيفية الاستخدام: اعثر على العَرَض في §1 → افتح العنصر في §2–10 → طبّق الثابت وخطوة التحقق.
إن غيّرت عنصرًا متعدد المسارات، فحدّث هذه الصفحة في نفس طلب الدمج.

0. النموذج الذهني (دماغ واحد، أفواه كثيرة)

إشارات مراجعة جودة الأجوبة

تقرأ لوحة جودة الأجوبة في Dashboard نقطة GET /api/dashboard/answer-quality الخاصة بالمشرفين. يُكتب سجل بياناتها الوصفية خارج حلقة الأحداث عند عقدة الرد النهائي المشتركة (agent/graph_respond.py → observability/answer_quality.py) لأدوار الويب والبوابة. يحفظ العلامات وهوية الدور والمحادثة دون نص الموجّه أو الجواب أو وسائط الأدوات، لمدة 30 يومًا وبحد أقصى 10,000 دور. تربط الإشارات الحديثة بالمحادثات القائمة.

قد تكون للمسودات الفارغة وإعادة فحص وسائط الأدوات وكتل التخطيط نتائج صحيحة أو مُصلحة: افحص الدور المرتبط بدل اعتبار العداد درجة دقة. تغطي فحوص الفقرة طلبات النثر الإنجليزي والعربي الصريحة بفقرة واحدة فقط؛ وتُستثنى الشيفرة والقوائم وJSON والتنسيقات المقتبسة. تقع التوقفات والإلغاءات وأوامر الاستخدام خارج هذا السجل النهائي. تظهر أخطاء التخزين كعدم توفر ولا تمنع تسليم الرد. ولا ترسل هذه اللوحة إشعارات خارجية.

User surfaces          Identity                 Brain                    Execution              Safety
─────────────          ────────                 ─────                    ─────────              ──────
Web SSE                session_id               build_supervisor_graph   UnifiedToolExecutor    HITL A graph interrupt
Web WS    ──►          ≠ thread_id   ──►        (LangGraph)       ──►    LocalToolRegistry ──►  HITL B swarm bus
Telegram/Discord/Slack gw-{platform}-…          checkpointer             IdeService._call_tool  HITL C pipeline
TUI / CLI              active_thread.*          agent_runner             MCP + native skills    YOLO / grants

القواعد الذهبية

معرّفات المنصات لا تدخل حالة LangGraph أبدًا (البوابة تعيدها عند الرد).
النموذج والمزوّد يتبدلان معًا (model_registry).
أدوات الخطر تمر عبر واحد من ثلاثة مسارات تنفيذ HITL؛ حقيقة القرار هي hitl_gates.db. ‏FanOut في السرب ثلاثي الحالة، لا أول-صوت-يفوز.
لجذر مساحة العمل حلّال واحد: workspace.binding.resolve_active_root() (وأيضًا file_write._get_workspace).
مصدر حقيقة إعدادات التشغيل هو ConfigStore (get_config_store())، لا ملفات مرتجلة.
تسليم الدور: close_turn هو المُغلِق الوحيد؛ العميل يعرض. لا رسّاخ ثانٍ.
عرض HITL: اضمم النص + السجل قبل الرسم. resolve_gate_views هو الجواب الوحيد عن “في أي حالة هذه البوابة”. يرسم JS ‏part.view / status.gate_views. والمعلّق هو الحالة التفاعلية الوحيدة.

1. العَرَض → أول مكان تنظر إليه

العَرَض	افحص أولًا	ثم	العنصر ذو الصلة
واجهة الويب عالقة على إيقاف / Enter ميت	آلة أدوار `chat.js` + حالة `idle`/`stream_end` في `agentStore`	تفضيل مسار WS مقابل SSE؛ حدث نهاية مفقود	§2 ناقلات الدردشة
YOLO “مفعّل” لكنه ما يزال يطلب الموافقة	`thread_id` في ContextVar مقابل session_id	استئناف WS يستخدم `ainvoke` + `enable_yolo(thread)`	§2، §4 HITL أ
أدوات الخطر تعمل بلا توجيه	أي رسم هو الحي (هل أُعيد تجميع `_graph_holder`؟)	`hitl_config` محذوف في موقع بناء	§3 بناء الرسم
زر الموافقة لا يفعل شيئًا	هل يطابق thread_id الاستئنافُ المقاطعةَ؛ مطالبة السجل 409؟	وجود Checkpointer؛ `Command(resume=…)`؛ حالة صف `hitl_gates.db`	§4 HITL أ، سجل البوابات
بطاقة شبح / مختومة مسبقًا بـموافق / سؤال ثانٍ على لوحة التحكم فقط	`resolve_gate_views` + `gate_views`؛ `pending` هي الحالة التفاعلية الوحيدة	اضمم `/messages` + `/status` قبل الرسم؛ لا تستنتج أبدًا “موافق” من صف مفقود	§4 عرض HITL، سجل البوابات
موافقة مزدوجة / تعليق بعد الموافقة	`_graph_hitl_gate_ctx` / `_hitl_approved_ctx`	على الناقل التخطي حين يكون الرسم موافقًا بالفعل؛ H-8 لا بوابة ثانية من `execute()`	§4 البوابة المزدوجة
كتابة IDE مرفوضة بواسطة HITL	يستخدم IDE الناقل (HITL ب)، لا مقاطعة الرسم	NullBus يفشل مغلقًا بلا ناقل منصة	§4 ب، §7 الأدوات
الدردشات تتجمد 15–70 ث؛ الحارس يعيد التشغيل بـ `unhealthy (probe error: timed out)`	`.kazma/stall-*.txt` — إطار كاظمه الأعلى في خيط حلقة الأحداث يسمّي مساعدًا متزامنًا يقوم بـ I/O من كود غير متزامن	أضفه إلى `_LOOP_STALL_HELPERS` (`tests/test_static_gates.py`)؛ غلّف كل موقع استدعاء غير متزامن في `asyncio.to_thread`	AGENTS §35؛ التقرير الأسبوعي “توقف حلقة الأحداث”
مجسات الصحة تفشل بـ `WinError 10048` / `10055`	الآلة نفدت منافذها، لا كاظمه: `guard.log` ‏`health.probe_unrunnable` + `health.port_exhaustion` (مالكو المقابس)	سجل Windows للنظام، Tcpip 4231 / 4227 / 4266؛ وسّع النطاق (`netsh int ipv4 set dynamicport tcp start=10000 num=55535`)	الحارس — هذه المجسات لا تُحتسب أبدًا نحو إعادة تشغيل
تقرير المرونة الأسبوعي يقول إن آلية “صامتة”	هل سجّل الكود سطر نجاح؟ هل تطابقه التوقيعات (`test_every_ledger_signature_matches_a_line_the_code_emits`)؟	يقرأ التقرير السجلات المتدوّرة؛ ابحث أنت عن السطر في `kazma.log.*`	AGENTS §27C
التقرير الأسبوعي: “Needs a look”	عَرَض ظهر (إعادات تشغيل بأسبابها، تجمدات حلقة الأحداث) أو مهمة مجدولة دون جدولها (“daily digest (2 of 7 scheduled)”)	عبارة “The event loop was blocked in: …” تسمّي الدالة؛ وهي المُدخل التالي في `_LOOP_STALL_HELPERS`	AGENTS §27C، §35
تنبيه الحارس “Kazma is up, but not ready”	التبعية التي يسمّيها التنبيه — عادةً قاعدة البيانات: `docker logs kazma-db-win` (“was interrupted”، “not properly shut down”)، وتحديثات Docker Desktop	يتجاوزه الحارس ولا يعيد التشغيل إلا بعد `KAZMA_GUARD_DEPENDENCY_OUTAGE_S` (10 دقائق)	AGENTS §44
تنبيه الحارس “Kazma stopped: process exited (code N)”	أسطرها الأخيرة في التنبيه؛ وكاملها في `.kazma/server.stderr.log`	الانهيار الأصلي يكتب هناك مكدّس كل خيط (`faulthandler`)	AGENTS §39
الوكيل “نسي” محادثة قديمة	`episodes.tier = 'archived'` — لا يبقى إلا بذرة `summary_text`	تحتاج الأرشفة إنشاءً وعدم استدعاء يتجاوز `episodic_ttl_days`؛ استعد النص من نسخة احتياطية أُخذت قبل تاريخ الأرشفة	§9 الذاكرة؛ “دورة حياة الحلقات” في `memory-and-rag`
مستودع النسخ الاحتياطية ينمو باستمرار	تجميع `restic forget` — يجب أن يكون `--group-by host,tags`	هل `[restic] maintenance ok` في السجل؟	الاحتفاظ في `ops/disaster-recovery`
مفتاح تبديل في الإعدادات بلا أثر	أسماء المفاتيح: YAML متداخل مقابل ConfigStore مسطّح	دالة المستهلك تقرأ المفتاح فعلًا	§6 طبقات الإعداد
نموذج خاطئ / 401 بعد التبديل	نقاط الدخول الثلاث في `model_registry` كلها	فرع صنف المزوّد (لا Bearer العام)	§5 المزوّدون
أدوات الملفات “خارج مساحة العمل”	أسبقية `_get_workspace()` فقط	لا تعد التنفيذ في IdeService	§8 مساحة العمل
الذاكرة تنسى / البحث ≠ استدعاء الدردشة	`recall()` فارغ / انزياح FTS / المُضمِّن متوقف	صحة V2 في لوحة التحكم؛ `fts_health`؛ ليست محوّل V1	§9 الذاكرة
`web_search` فارغ	عنوان SearXNG + صيغة JSON	ملاحظات سلسلة الخلفيات في مخرجات الأداة	§10 البحث
`read_url` ضعيف أو حاجز روبوتات	HTTP ثم Chromium محلي ثم استرداد مستضاف مسموح صراحة	وضع الجلب وقائمة السماح؛ المفتاح وحده لا يمنح إذنًا؛ وتثبيت IP عند المسار المباشر	§10 البحث
نتائج معرفة قديمة بعد تقلص الوثائق	تتخطى الفهرسة الذكية الصفحات غير المتغيرة وتستبدل المحتوى المتغير؛ ويُحفظ المحتوى عند غياب الاكتشاف وحده	`KnowledgeIndex.index` / `purge_source`؛ افحص أخطاء الاكتشاف والتغطية	§10 المعرفة
حقن KB فارغ / مستأجر خاطئ	`list_auto_inject_libraries` + ‏RRF الفيدرالي بـ `kb_mode=inject`	`KAZMA_KB_AUTO_INJECT`، والبحث الذكي، وراية الأرشفة	§10 المعرفة
مهمة سرب عالقة “متوقفة مؤقتًا”	مدير نقاط تفتيش HITL ج	ليست أ ولا ب	§4 ج
الوكيل يستأنف مهمة قديمة بعد تغيّر الموضوع	`shift_explicit` مقابل `shift_inferred`؛ هل `task_status` استُبدل؟	الانعطاف الصريح وحده يوقف الاستدعاء؛ والمستنتَج يعيد الترتيب	§9 تركيز الدور، AGENTS.md §29
الوكيل يتخلى عن مهمة مشروعة متعددة الخطوات في منتصف التدفق	`shift_inferred` على استفسار تفقدٍ استفهامي	التفقدات (EN + AR شنو/وش/…) يجب ألا تُصنَّف انحرافًا أبدًا	§9 تركيز الدور
`/replay` فارغ على قناة واحدة	`snapshot_recorder` في كل مواقع بناء الرسم	الالتقاط في عقدة المشرف	§3 السفر عبر الزمن
الجلسة في الشريط الجانبي بعد F5 فقط	على WS تحديث/إدراج الجلسات صعودًا مثل SSE	هل SessionManager مشترك؟	§2 الجلسات
تيليجرام: الموافقة منتهية بعد الجواب النهائي	استدعاء راجع `approve_task` مكرر/متأخر بعد الاستئناف	رسالة ناعمة / إزالة ارتداد في `hitl.py` — العمل غالبًا يكون قد جرى بالفعل	§4 HITL أ
حلقة أدوات / حد تكرار (بطاقة توقف ثنائية اللغة)	`recursion_limit` مقابل `agent.max_iterations` غير متحاذيين	`/long on` أو إعدادات المهمة الطويلة؛ `resolve_turn_budgets()`	§11 المهمة الطويلة
المتابعة تعيد العمل نفسه بعد بلوغ الميزانية	سياق المتابعة غير مخزّن/مستهلك	`long_task.continue.{thread}` + حقن في الدور التالي	§11 المهمة الطويلة
تدقيق طويل يموت مع تفعيل YOLO	YOLO يتخطى HITL فقط؛ ما يزال يحتاج سعة	فعّل كلا `/long on` و`/yolo`	§4، §11
البوت يُقرّ بـ“حُفظ. جاهز…” بدل تنفيذ الأوامر	مهمة متقادمة بعد Partial: سياق متابعة محقون قبل أمر جديد + المهمة تُركت نشطة	منذ 2026-08-19: الحقن مقيد بـ `is_continuation_reply`، وPartial يوقف المهمة الطويلة مؤقتًا. البُنى الأقدم: `/long off` يمسحه	§11 المهمة الطويلة
تذكير / بطاقة HITL لا تُسلَّم أبدًا بعد ~5 دقائق	TTL لـ SessionStore هو 300s — لا تبحث عن `chat_id` وقت الإطلاق	يستخدم Cron ‏`delivery_target` الملتقط عند الجدولة. المساعد: `kazma_core.sessions.ttl.refuse_session_lookup_for_durable_job`	§2 الجلسات، AGENTS.md §16
توجيه يحوي “barcode” يوجَّه إلى نموذج البرمجة	كان `ModelRouter.classify` يطابق `code` كسلسلة جزئية	تصنيف بحدود الكلمات؛ `models.defaults.<kind>` يتغلب على كلمات YAML المفتاحية	§5 المزوّدون
نص مورد MCP يُتَّبع كتعليمات	يجب تسوير جسم المورد	`mcp_read_resource` → `format_untrusted_block(source=mcp_resource:…)`	§12 الحقن
خادم MCP طلب من كاظمه أخذ عيّنة (استدعاء LLM الخاص بنا)	يجب ألا يعمل `sampling/createMessage` تلقائيًا	مرفوض بلا HITL؛ `KAZMA_MCP_SAMPLING` مطفأ افتراضيًا	§4 HITL
خطة مرسومة، لا ردّ (حفظ الذاكرة / الأدوات)	`plan_fence.py` فصل/تسوية؛ متابعة المشرف بالخطة فقط	`done.content` في SSE/WS مصدر الحقيقة؛ strip في chat.js + applyFinal دائمًا	§2 ناقلات الدردشة
أفكار مرئية حيّة، تختفي بعد الدور	كانت بطاقة المهمة الحية سلسلة تفكير ثانية تُفكّ؛ وسرق `_answerFromDoc` التفكير كجواب	طيّة عمل واحدة في الفقاعة؛ بطاقة المهمة شريط؛ الأفكار أجزاء `reasoning`	`docs/plans/COT_AND_THOUGHTS.md`

2. ناقلات الدردشة (SSE ↔ WebSocket)

الشأن	متصل بـ
دردشة المتصفح	رسم SSE (حزمة `sse_chat/` + عارض `static/js/chat.js`) + قياسات WS البعدية (`routes/ws_chat.py`)
الناقل المفضل	SSE للأدوار وHITL. ‏WS لاستئناف المؤشر / الإطارات الحية.
التحكم في الأدوار عبر WS	لا شيء: تُرفض `send_prompt` / `approve_tool` / `stop` / `steer` / `abort` مع ذكر مسار HTTP (`ws_chat._HTTP_ROUTE_FOR`). أُزيل منفذ الخروج `KAZMA_WS_GRAPH` في 2026-09-30 (AUD-026).
مخزن الجلسات	واحد `SessionManager` / `chat_sessions.db` لكليهما
خيط LangGraph	`ChatSession.thread_id` (قد ≠ `session_id` لمعرّفات UUID الويب العادية)
جلسات الويب المرتبطة بالمنصات	`session_id == thread_id` حين تكون `gw-*`

يجب أن يبقيا متزامنين

الشأن	SSE (الرسم مصدر الحقيقة)	WebSocket (القياسات)
النقطة الطرفية	`POST /api/chat/stream`	`/ws/chat/{session_id}`
مصدر الرسم	`_graph_holder` (بعد إعادة التجميع)	الحامل نفسه؛ للقراءة فقط (بطاقة HITL عند الاتصال)
`recursion_limit`	ميزانيات المهام الطويلة	المساعد نفسه (مسح HITL عند الاتصال)
نهاية الدور	SSE ‏`event: done`	`idle` + `stream_end` (مسجَّل)
إصدار HITL	إطار `hitl` في SSE يحمل `view`	`hitl_approval` القياسي (مسح)
استئناف HITL	`POST /api/approve/{thread_id}` (‏200/409 يحملان `view` + `gate_id`)	لا شيء — يُرفض `approve_tool`
YOLO	أمر `/yolo` في التدفق	لا شيء (لا أدوار)
سياق البيئة	`build_env_context()` لكل دور	لا شيء (لا أدوار)
حقن الروح	كتلة تحسين ذاتي مسيَّجة	(انظر البوابة لمسار تيليجرام)
سياج الخطة / النص النهائي	`plan_fence.pick_user_facing_text` على `done.content` + حفظ الجلسة	لا شيء (المقبس لا يحفظ شيئًا)

الثوابت

إضافة حدث قياسي جديد على SSE وحدها أو WS وحدها يكسر الواجهة من جديد.
أدوار الرسم مكانها SSE. لا تضف عميل رسم ثالثًا.
session_id للواجهة/التخزين؛ thread_id لـ LangGraph + YOLO + HITL.
نص المساعد المواجه للمستخدم ليس أبدًا غالق plan ملصوقًا (` Saved.). ‏plan_fence.py` هو مصدر الحقيقة.
استئناف HITL للنماذج المخصصة: استخدم ainvoke(Command)، لا astream_events المعلِّق.

الملفات الأساسية

kazma-ui/kazma_ui/sse_chat/ (الحزمة)
kazma-ui/kazma_ui/turn_runtime.py (close_turn)
kazma-ui/kazma_ui/routes/ws_chat.py
kazma-ui/kazma_ui/static/js/chat.js (renderTurn، _serverGateViews، TurnView)
kazma-ui/kazma_ui/static/js/modules/turn_document.js
kazma-ui/kazma_ui/static/js/stores/agentStore.js
kazma-ui/kazma_ui/session_manager.py
kazma-ui/kazma_ui/app.py (يركّب كلا الموجِّهين + _graph_holder)

3. مواقع بناء الرسم (فشل صامت إن حُذف شيء)

يُستدعى build_supervisor_graph(...) من مواقع متعددة. حذف الوسائط المفتاحية يُفشل ذلك المسار وحده.

الموقع	hitl_config	checkpointer	snapshot_recorder	يُستخدم بواسطة
`agent_runner.get_streaming_graph`	نعم + `auto_deny`	لا (متزامن، بلا checkpointer)	نعم	الصوت / نافذة الإقلاع فقط — لا يمكنه استئناف `interrupt()`
`agent_runner._ensure_graph`	نعم	نعم	نعم	CLI / ‏`run()` الوكيل
إعادة تجميع إقلاع `app.py`	نعم (أو None إن كان معطلًا)	نعم (`checkpoints.db`)	يعيد استخدام ملك الوكيل	ويب SSE/WS الحي
`build_child_graph` / وكيل فرعي	رفض-تلقائي للخطر	لا	نعم	الوكلاء الأبناء
معالج البوابة	رسم معدّ مسبقًا محقون	عبر الرسم	مسجّل الأوامر	TG/Discord/Slack

الثوابت

بعد الإقلاع، يجب أن يستخدم مرور الويب الرسم المعاد تجميعه في _graph_holder.
السفر عبر الزمن فارغ ⇒ مسجّل مفقود في موقع بناء أو المشرف لا يستدعي capture.
ما قبل الإقلاع / فشل إعادة التجميع ⇒ قد لا تُحفظ حالة HITL/الحالة.

ذو صلة

kazma-core/kazma_core/agent/graph_builder.py (التوصيلات)
kazma-core/kazma_core/agent/graph_supervisor.py / graph_tool_worker.py / graph_respond.py
kazma-core/kazma_core/agent_runner.py
kazma-ui/kazma_ui/app.py
kazma-core/kazma_core/time_travel.py

4. HITL — ثلاثة مسارات تنفيذ + سجل واحد (لا تخلط بينها)

الآلية	متى	موقع البوابة	الاستئناف
أ. مقاطعة الرسم	أدوات الخطر في دردشة الوكيل المفرد	`graph_tool_worker.tool_worker_node`	موافقة HTTP / أمر البوابة (ليس عبر WebSocket أبدًا)
ب. ناقل السرب	أدوات السرب + IDE ‏`LocalToolRegistry.execute`	`tool_registry.execute` → `SafetyMiddleware`	أزرار المنصة / استدعاءات راجعة للناقل
ج. نقطة تفتيش الخط	مهام PIPELINE في السرب	`checkpoint_manager` (+ `_gate_register_pipeline`)	`approve_checkpoint` + `settle_gate`
السجل	كل ما سبق	`hitl_gates.db` ‏CAS	حقيقة القرار؛ نقطة التفتيش حقيقة التنفيذ

البوابة المزدوجة (أ ثم ب)

بعد موافقة الرسم، تمنع ContextVars توجيه ناقل ثانٍ. كسر هذا = تعليق أو واجهة مزدوجة.

مصدر حقيقة قائمة الخطر

المصدر	الدور
`CANONICAL_DANGER_TOOLS`	مصدر الحقيقة في الكود
`kazma.yaml` `safety.hitl.require_approval_for`	افتراضات الملف (مختبَرة للتطابق)
ConfigStore `safety.require_approval_for`	تجاوز واجهة الإعدادات → `get_hitl_config()`
`_EXTENDED_DANGER`	كنية لـ CANONICAL (ليست قائمة أطول)
MCP `classify_mcp_tool`	استدلالات الأسماء → UnifiedToolExecutor

طوبولوجيا الناقل

0 منصات → NullBusAdapter (الخطر يفشل مغلقًا إلا بلا واجهة).
منصة واحدة → ذلك المحوّل.
منصتان أو أكثر → FanOutBusAdapter (ثلاثي الحالة: True يحسم؛ False صوت حتى expected_voters أو الموعد النهائي — ليس أول-قيمة-منطقية-تفوز؛ وليس claim_gate الخاص بالويب).

العرض — اضمم قبل الرسم، حلّال واحد، إرسال واحد

يشغّل kazma_ui/gate_view.py ‏resolve_gate_views(parts, live_rows, *, authoritative) عند السلك (يختم GET /messages القيمةَ part.view، ويعيد GET …/status القيمة gate_views، وتحمل إطارات hitl في اليوم القيمة view، وتحمل الموافقة 200/409 القيمتين view + gate_id). يبحث JS عن live_gate_views[id] ?? part.view ويحذف الهيكل حين لا وجود له. لا يعيد الاشتقاق.

ينفّذ loadSession ‏Promise.all لـ /messages?stats=1 و/status ويستوعب العروض قبل مرور TurnView الأول. الهوية هي gate_id (زائد الكنية)، لا thread_id.

الفم	كيف يرى المعلّق	كيف يُرسل
فقاعة الويب	`gate_views` / `part.view` → TurnView	`POST /api/approve/{thread_id}`
لوحة التحكم	`/api/pending-approvals`، إزالة تكرار بـ `gate_id` / الكنية	نفس POST
TUI	القائمة نفسها؛ مجموعة العرض مفتاحها معرّف البوابة	نفس POST
تيليجرام / ديسكورد / سلاك	لوحة مفاتيح أصلية	`hitl approve {thread_id}` (للرسم مقاطعة مفتوحة واحدة)
FanOut السرب	أحداث في الذاكرة	ثلاثي الحالة — لا تعيد توجيه `claim_gate` الخاص بالويب
نقاط تفتيش الخط	لوحة السرب	`approve_checkpoint` + `settle_gate`

لا تسطّح أفواهًا صادقة أصلًا. الموافقة التسلسلية بالخيط في البوابة صحيحة. كان “أول-يفوز” في FanOut حادثًا مسمّى (H-12).

الملفات ذات الصلة

safety/hitl.py، safety/yolo.py، safety/hitl_grants.py
agent/tool_registry.py، agent/graph_tool_worker.py
swarm/safety.py، swarm/bus.py، swarm/checkpoint_manager.py
safety/hitl_gates.py، kazma_ui/gate_view.py، kazma_ui/turn_runtime.py، _serverGateViews في chat.js
محوّلات *_bus.py في البوابة
tests/test_gate_view.py (المدوّنة) · tests/e2e/test_hitl_view_model.py (‏Playwright 2 و3 — بوابة CI)

5. تحليل المزوّد / النموذج

الشأن	متصل بـ
النموذج النشط	يجب تحديث المزوّد عبر `find_provider_for_model` / `set_active_model`
الإرسال	أربعة أصناف خاصة: Google وAnthropic وAzure وBedrock
المسار العام	`LLMProvider` → Bearer ‏`/chat/completions` فقط
نقاط الدخول	`get_client`، `get_model`، `get_client_by_provider` — الثلاثة كلها تحتاج الفروع نفسها

عَرَض عدم التزامن: اسم النموذج يشير إلى API متوافق مع OpenAI لكن المزوّد Anthropic (أو العكس).

الملف: kazma-core/kazma_core/model_registry.py (+ وحدات المزوّدين).

6. طبقات الإعداد (YAML مقابل ConfigStore مقابل البيئة)

الطبقة	أمثلة	يُحمَّل بواسطة
YAML المنتج	`kazma.yaml` / `kazma.local.yaml`	`config_loader` عند الإقلاع
ConfigStore	مفاتيح مسطّحة في `settings.db` (`safety.hitl_enabled`)	واجهة زمن التشغيل + `get_config_store()`
البيئة	`KAZMA_*`	بيئة العملية (غالبًا تجاوزات / ميزات)

فخاخ تسمية المفاتيح

المفهوم	YAML	ConfigStore / الإعدادات
تشغيل/إطفاء HITL	`safety.hitl.enabled`	`safety.hitl_enabled`
قائمة الموافقة	`safety.hitl.require_approval_for`	`safety.require_approval_for`
المهلة	`safety.hitl.approval_timeout_seconds` (الافتراضي 300)	`safety.approval_timeout`
SearXNG	(البيئة `KAZMA_SEARXNG_URL`)	`search.searxng_url`

المستهلك: يدمج get_hitl_config() ‏YAML ثم ConfigStore (ويمكن لـ YOLO الإجبار على الإطفاء).

لا تُنشئ قط ConfigStore() في كود التطبيق — فقط get_config_store().

7. مكدّس تنفيذ الأدوات

المسار	المنفّذ	MCP؟	HITL
الدردشة / الرسم	`UnifiedToolExecutor` (agent.tools)	نعم	أ (مقاطعة) + بوابة مزدوجة
عمليات IDE المغيِّرة	`get_tool_registry()` → `LocalToolRegistry`	لا	ب (ناقل)
مساعدو عامل السرب	غالبًا LocalToolRegistry	يعتمد	ب
المهارات الأصلية	مسجَّلة على LocalToolRegistry	لا ينطبق	كأدوات
زمن تشغيل `python_exec`	E2B (إن وُجد مفتاح) → سجن Docker → قائمة حظر محلية	لا ينطبق	أ أو ب قبل التشغيل
بحث قاعدة الكود	رموز `code_index` في SQLite + `rg` الحي (تراجع grep في Python)	لا ينطبق	قراءة

الثوابت

يجب ألا يستدعي IDE قط دوال file_write / file_apply_patch / الصدفة الخام — دائمًا _call_tool → السجل.
“الأداة موجودة في الدردشة لا في IDE” غالبًا لأنها خاصة بـ MCP فقط على UnifiedToolExecutor.
ملف registry.py في حزمة السرب هو سجل العمّال — لا تخلطه مع tool_registry.py الخاص بالوكيل.

8. تحليل مساحة العمل (سُلّم واحد)

دالة واحدة: kazma_core.workspace.binding.resolve_active_root()
(يعاد تصديرها أيضًا كـ file_write._get_workspace / configure_workspace).

الأسبقية (من الأعلى إلى الأدنى):

workspace_scope لكل مهمة في ContextVar (SwarmTask.workspace_id)
صف WorkspaceStore النشط (تبديل المستودع / الاستنساخ — نية المستخدم)
تثبيت العملية في configure_workspace()
متغير البيئة KAZMA_WORKSPACE
الافتراضي {data_dir}/workspace (صندوق رمل المشروع، لا cwd للمستودع الموحد)

ناقل الربط: WorkspaceStore.set_active_workspace → notify_root_changed
→ تثبيت العملية + إعادة ربط MCP لخوادم workspace_bound
(يستخدم @modelcontextprotocol/server-filesystem المتغير ${KAZMA_ACTIVE_WORKSPACE}).

الوحدة ذات الصلة	يجب
`IdeService._resolve_workspace_root`	فوّض القواعد نفسها
`workspace_api`	فوّض `resolve_active_root` (لا سُلّم ثانٍ)
`env_context.build_env_context`	الإدراك نفسه للجذر
`worker_dispatch`	غلّف بـ `workspace_scope` حين تكون للمهمة معرّف
كل أدوات `file_*`	استخدم `_get_workspace` / `resolve_active_root` فقط
نظام ملفات MCP	`workspace_bound: true` + إعادة ربط عند التبديل

9. الذاكرة / RAG

V2 هي مكدّس الذاكرة الوحيد للدردشة (recall() في memory/recall.py). محوّل RRF رباعي الطبقات في V1 (UnifiedMemoryAdapter / VectorMemory) أُزيل.

الطبقة	الدور
الاستدعاء	مرشّحو FTS5 بكلمات المحتوى + كثيف (sqlite-vec، أو pgvector عند ضبط Postgres DSN)، مرتّبون على الدليل (`recall._rank_by_evidence`: لا يُحقن شيء تحت الأرضية؛ و`scripts/memory_bench.py` يقيسه) + انحياز الجلسة
الكتابة	`mutate_belief` (خنقة INSERT واحدة) + مرآة PG اختيارية + كتابة مزدوجة Neo4j
لكل دور	حقن المشرف عند `memory.per_turn_retrieval` (ConfigStore ← yaml)
بعد الدور	`turn_runtime.close_turn` → `consolidator.remember_turn` → المستخرِج → `mutate_belief` + مرساة الإيغو؛ الأدوار الفائتة: `turn_reconcile`
الصحة	`build_memory_health()` / `build_v2_health()` على لوحة التحكم
واجهة الرسم	`GET /api/memory/v2/graph` · `/memory` · `memory_console.js`
إعادة تسمية الكيان / المركز	`POST …/entities/{id}/rename` · `memory/self_hub.py` (قواقع User → المركز `user`)
تحرير المعتقد	`PATCH /api/memory/v2/beliefs/{id}`

مفهوم مفصول على اللوحة (موضوع بمفعول حرفي، بلا حافة مركز): معتقدات كائن-الحمولة كانت تسكّ ورقة بلا user → related_to → subject. مرساة الإيغو عند الكتابة + التعبئة الراجعة كل 6 ساعات تصلانهما (memory/ego_anchor.py). أعد التشغيل بعد تدقيق 2026-08-24 إن كنت لا تزال ترى أيتامًا من قبل التعبئة.

عقدة مكررة يتيمة (التسمية نفسها مرتين): نص مفعول المعتقد ساوى معرّف كيان → كيان مزدوج + عقدة افتراضية. أُصلح بإزالة التكرار في الخادم؛ المعرّفات الفريدة مطلوبة.

المركز ما يزال يقول “أنت” بعد إعادة تسمية الشخص User: يجب أن تزامن إعادة التسمية entities.user (‏self_hub)؛ وgraph_id في القائمة يركّز المركز.

لافتة الاقتطاع تعرض حواف مفقودة: يحتفظ الرسّاخ بأعلى N عقدة ثم يُسقط الوصلات التي اقتُطعت أطرافها. تُبلغ اللافتة عن اتصالات مخفية بالتقطيع — رشّح أو ارفع limit، ليست هذه بيانات مفقودة.

استدعاء الدردشة يفوته حقيقة موجودة في SQLite: جداول FTS ‏content= لا تكشف عدم تزامن جزئي عبر COUNT(*) على الجدول الافتراضي. يقارن مسح الـ 6 ساعات *_docsize بالأساس ويعيد البناء (fts_health.fts_drift_check).

مرآة Postgres ستبعث حقائق ميتة عند role=primary: الإبطال / الاستبدال / الأرشفة / مسح الرسم تضع الآن شواهد قبور على المرآة، ومزامنة المرآة كل 15 دقيقة تدفع ما يختلف (صحة الذاكرة: mirror). مصالحة كاملة لمرة واحدة: python scripts/reconcile_memory_mirror.py.

“تعذّر تسليم رسالتك بعد عدة محاولات” (الويب، مؤشر V2): ليست علة ذاكرة — استيراد get_active_turn محليٌّ داخل دالة حجب ربط الوحدة على مقابس ?last_seq= (ws_chat.py، التدقيق M-01). أُصلحت؛ أعد التشغيل.

إن كان استدعاء الدردشة فارغًا: ثبّت .[rag]، وافحص صحة لوحة التحكم (المُضمِّن / V2)، وتأكد من memory.enabled.
إن كانت الدردشة ≠ نتائج الأدوات: كلاهما يجب أن يبلغ recall()؛ ابحث عن مخزن فارغ يفشل مغلقًا أو وضع DEMO.
التدقيق: AUDIT_MEMORY_SYSTEM_2026-08-24.md.

10. البحث المعمّق / الجلب / البحث

العنصر	السلسلة / الترتيب	الإعداد
`web_search`	SearXNG → DDG → Bing → Wikipedia	`KAZMA_SEARXNG_URL`، ConfigStore ‏`search.searxng_url`، ملف compose باسم `search` على :8088
`read_url` / استيعاب المعرفة	تحقق SSRF ثم httpx محلي (تثبيت IP) ثم Chromium محلي ثم بديل مستضاف مسموح	`KAZMA_ACQUISITION_MODE` و`KAZMA_ACQUISITION_REMOTE_PROVIDERS`؛ الاعتماد منفصل؛ لا تثبّت عبر `proxy=` مسموح

يستخدم استيعاب KB والبحث المعمّق kazma_core.web_acquire (ملفات fetch_text / search / crawl) فوق سُلّم الاستعادة المشترك في read_url — مكدّس I/O واحد، ومصارف المنتج تبقى منفصلة.

مكتبة المعرفة (الاستدعاء / الحقن — مكدّس هجين واحد)

المسار	الدور
`KnowledgeIndex.search_all_sync`	استرجاع مصدر الحقيقة — دلالي Chroma + FTS5 BM25 → RRF
`federated_search(..., kb_mode=inject\|all_active)`	دمج الدردشة + الأدوات؛ يوسم `store=knowledge` (لا دمج مخطط مع V2)
`build_knowledge_inject`	RRF نفسه عبر `kb_mode=inject`؛ يسيّجه المشرف ويحقنه مرة واحدة في كل دور (`graph_supervisor`)
إعادة الفهرسة	صفحة غير متغيرة → تخطٍّ؛ صفحة متغيرة → تُستبدل في معاملة واحدة؛ وعنوان URL غائب عن الاكتشاف يُحتفظ به
العزل	ملف `knowledge.db` خاص؛ Chroma لكل مكتبة `kazma_kb_*`؛ أرشفة عند العرض/الحقن؛ لتثبيتات المشغّل الواحد فقط

اختبار دخاني حيّ: scripts/smoke_research_stack.py.

11. الهوية وقواعد البيانات

المعرّف / القاعدة	الغرض	ذو صلة
`session_id`	مفتاح جلسة دردشة واجهة الويب	SessionManager
`thread_id`	نقطة تفتيش LangGraph + YOLO + HITL	يجب أن يطابق الاستئناف
`gw-{platform}-{sender}`	سكّ البوابة؛ غالبًا `session_id == thread_id` على مرايا الويب	SessionStore
`chat_sessions.db`	رسائل/جلسات الويب	SSE + WS
`sessions.db`	جلسات منصات البوابة	المحوّلات
`checkpoints.db`	حالة LangGraph الدائمة	إيقاف/استئناف HITL
`snapshots.db`	السفر عبر الزمن	المسجّل
`settings.db`	ConfigStore	واجهة الإعدادات
`swarm_tasks.db`	مخزن مهام السرب	المحرك

حذف “جلسة” قد يحتاج كلاً من SessionManager وتنظيف خيط نقاط التفتيش.

12. مواقع الحقن (حافظ على التزامن)

المحتوى المحقون	المواقع	السياج / الحارس
كتلة البيئة / مساحة العمل	تهيئة الوكيل، وSSE/WS لكل دور، وعامل السرب، وإرسال سرب IDE	صدقٌ عن المضيف
الروح / التحسين الذاتي	agent_runner، وsse_chat، ورسم البوابة	`format_untrusted_block` + `is_override_delta`؛ مفتاح إيقاف `KAZMA_SELF_IMPROVEMENT=0`
سياق المعرفة	البوابة (+ مسارات دردشة أخرى عند إضافتها)	سياج غير موثوق

إضافة موقع رابع بلا السياج تراجعٌ أمني.

13. الحزم بنظرة

الحزمة	تملك	لا تملك
`kazma-core`	الرسم، والأدوات، والسرب، وConfigStore، وخدمة IDE، والسلامة	واجهة HTTP، وواجهات منصات API
`kazma-ui`	دردشة FastAPI وSSE/WS، والإعدادات، وصفحة IDE، وJS الساكن	محوّلات المنصات
`kazma-gateway`	محوّلات TG/Discord/Slack، والأوامر، وعزل الجلسات	SessionManager للويب
`kazma-tui`	واجهة Textual فوق API النواة	دماغ وكيل منفصل
`kazma-cli`	أوامر `kazma`	بوابة طويلة التشغيل
`kazma-skills`	حزم المهارات الأصلية	سياسة HITL في زمن التشغيل
ذاكرة `kazma-core`	معتقدات V2 / FTS / `MSATokenizer`	سياسة RAG الكاملة

14. اختبارات التحقق / الانحراف

الشأن	كيفية التحقق
تطابق قائمة الخطر	`tests/test_agent_skills.py` / `scripts/check_docs_sync.py`
توصيل HITL في مواقع البناء	`kazma_core_tests/test_hitl_gates_wired.py`
مكدّس البحث	`python scripts/smoke_research_stack.py`
وحدة SearXNG / الاستعادة	`tests/test_searxng_discovery.py`، `tests/test_hard_page_recovery.py`
الإعدادات → قائمة HITL	ConfigStore ‏`safety.require_approval_for` → `get_hitl_config`
عرض HITL (الضم / الرسم / الإرسال)	`tests/test_gate_view.py`؛ وPlaywright 2+3 في `tests/e2e/test_hitl_view_model.py` (بوابة CI)
التجميع	`py_compile` على الوحدات الملموسة

حين تدمج مسارين في واحد، أضف اختبارًا كان سيفشل تحت علة المسار المزدوج القديمة.

15. سجل تغييرات دمج المسارات المتعددة (حيّ)

التاريخ	الدمج / الإصلاح	ما لا يُعاد تقسيمه
2026-07	SessionManager مشترك بين SSE+WS	لا تضف قواميس جلسات لكل ناقل
2026-07	ناقل FanOut متعدد المنصات	يجب ألا تدّعي الوثائق حصرية TG>Discord>Slack فقط
2026-07	مصدر حقيقة مساحة العمل + النطاق	لا تشعّب أسبقية IdeService
2026-07	WS ‏recursion_limit=100	أبقه متحاذيًا مع SSE/البوابة
2026-07	الإعدادات `require_approval_for` → `get_hitl_config`	لا تُمِت مستوى تحكم الإعدادات من جديد
2026-07	استعادة الصفحات الصعبة مشتركة مع KB	أبقِ الجلب في `read_url._fetch_full_text`
2026-09	سجل بوابات HITL	القرار = `hitl_gates.db`؛ التنفيذ = نقطة التفتيش. لا “موافق” مستنتَج
2026-09	FanOut ثلاثي الحالة	لا تعد أول-قيمة-منطقية-تفوز؛ `claim_gate` للويب يبقى 200/409
2026-09	تسليم الدور V2	`close_turn` المُغلِق الوحيد؛ لا رسّاخ ثانٍ في `chat.js`
2026-09	نموذج عرض HITL	اضمم قبل الرسم؛ `resolve_gate_views` فقط؛ الإرسال عبر `POST /api/approve/{thread_id}` (أمر البوابة يبقى بمعرّف الخيط)

11. وضع المهمة الطويلة وميزانيات الرسم

الشأن	مصدر الحقيقة
الميزانية لكل دردشة	ConfigStore ‏`long_task.{thread_id}` عبر `/long on` (بحث ناعم ~40 — قد يصدر PARTIAL)
المهمة لكل دردشة	`/long mission` أو `/mission on` — جدار صلب افتراضي 500 جولة / ~2500 خطوة
جولات الأدوات الأساسية	`agent.max_iterations` (الإعدادات → الوكيل)
سقف خطوات LangGraph	مشتق `resolve_turn_budgets()` → `recursion_limit` (المهمة تستخدم `mission_recursion_limit()`)
مقابض بيئة المهمة	`KAZMA_MISSION_MAX_ROUNDS`، `KAZMA_MISSION_RECURSION`
المتابعة بعد الميزانية	`long_task.continue.{thread_id}` يُخزَّن عند النفاد؛ يُحقن في الدور التالي فقط للردود ذات شكل الاستمرار (متابعة/استمر/نعم بـ ≤8 كلمات/… — الأمر الجديد لا يحصل على التوجيه أبدًا؛ والسياق المخزَّن يُمسح في الحالتين)
سلوك Partial	‏Partial التكرار يوقف المهمة الطويلة مؤقتًا (`pause_long_task`): ميزانيات أساسية، بلا تأطير مهمة، ولا تُستهلك أدوار المتابعة؛ السجل يبقى لـ `/long status` حتى TTL
المقاييس	Prometheus ‏`kazma_long_task_events_total{kind=…}`
HITL مقابل السعة	`/yolo` = تجاوز الخطر؛ `/long` = ميزانيات فقط؛ المهمة ≠ لانهائية

ثابت: رفع جولات الأدوات القصوى دون اشتقاق recursion_limit يعيد إدخال GraphRecursionError في المهام بعمق البحث. اذهب دائمًا عبر kazma_core.agent.long_task. وضع الميزانية ليس “بلا حدود”؛ استخدم المهمة للتشغيل-حتى-الإنجاز مع جدار أمان.

تحقق: حالة /long؛ يعرض /long mission جدارًا صلبًا ≥100؛ رد وكيل الإعدادات يتضمن recursion_limit؛ وسجّل أحداث long_task + budget_recursion / mission_*.

16. فهرس سريع “X يرتبط بـ Y”

إن لمست…	افحص أيضًا…
`sse_chat/`	`ws_chat.py`، عارض chat.js، `turn_runtime.close_turn`
`long_task.py` / التكرار	البوابة، وSSE، وWS، ومواقع `recursion_limit` في agent_runner
رسالة موافقة HITL متقادمة	إزالة الارتداد + النسخة الناعمة في `hitl.py`؛ ليست “لم ينفَّذ شيء” بعد نجاح
`ws_chat.py`	نفسه + ربط خيط ContextVar لـ YOLO
HITL في `graph_tool_worker.py`	كل مواقع البناء، وContextVars البوابة المزدوجة، و`hitl_gates.py`
`tool_registry.execute`	خدمة IDE، وسلامة السرب، ومنفّذ MCP
طريقة واحدة في `model_registry`	الطريقتان الأخريان + أصناف المزوّدين
`file_write._get_workspace`	IdeService، وenv_context، وworkspace_scope
`CANONICAL_DANGER_TOOLS`	kazma.yaml، وافتراضي الإعدادات، وكنية السرب، وأنماط MCP
مفاتيح السلامة في `ConfigStore`	`get_hitl_config`، والمفاتيح المسطّحة في SettingsManager
`build_env_context`	agent_runner، وSSE، وWS، وإرسال العامل
الروح / self_improvement	كل مواقع الحقن + prompt_fence
محوّل ناقل السرب	ثلاثية حالة FanOut مقابل Null، وتجربة IDE الفاشلة المغلقة
استعادة `read_url`	knowledge_ingest، وcrawl، وweb_research
مسار المستندات الدائم	واجهة الويب API، والأدوات، و`/documents` في البوابة، وTUI — كلها → `DocumentIngestionService` فقط
تنفيذ تحليل المستندات	`DocumentService` (العاملون + المرفقات العابرة في الدردشة) — لا تستورد قط `documents.parsers` من البوابة/الواجهة
عزل عامل المستندات	ملف التعريف `process`: عملية فرعية من `sandbox.py`؛ ملف التعريف `container`: موقعا استدعاء العامل كلاهما → `worker_container.run_container_worker` → `worker_broker.py`، الحائز الوحيد لمقبس Docker — ولا رجوع من أحدهما إلى الآخر
مهام المستندات مقابل البيانات الوصفية	`jobs_pg` متعدد النسخ؛ `repository_pg` حين تكون البيانات الوصفية على Postgres (`auto` يتبع خلفية المهام)؛ وقبول الاستلام يعيش مع المهام (`admission.py`)؛ وGC محايد للخلفية (`repository.gc_mark`)
النسخ الاحتياطي للمستندات	`backup.py` (بيانات SQLite الوصفية + المهام) أو `backup_pg.py` ‏(Postgres) — يُختار بحسب مكان مخازن الخدمة المثبَّتة؛ ويُعاد نشر فهرس المعرفة عند بدء العامل (`reconcile_index`)
تنقيح المستندات شبه الخطرة	`kazmaConfirm` في الواجهة فقط؛ ACL ‏API/الأدوات ما يزال ينطبق

أعراض الذكاء المستندي

العَرَض	المسارات ذات الصلة	الثابت
رفض الرفع 429/503/507/413	`documents_api.py` (`precheck_upload` قبل جسم الطلب)، و`capacity.py`، و`admission.py`، ومستندات الإعدادات	حالة صادقة؛ وحالات الرفض لأسباب السعة تحمل Retry-After
الرفع 409 `intake_in_progress` / `intake_taken_over`	حجوزات `admission.py` وعقدها الإيجاري	المفتاح نفسه ما زال محجوزًا؛ أو أن عقدًا إيجاريًا منقضيًا أُخذ وسُيِّج — أعد المحاولة
الجاهزية `document_intake_reservations_stranded`	`admission.py`، و`admission.stranded` في `ops/capacity`	حجز قديم أو منقضٍ لا تستطيع أي عملية إثبات موت صاحبه؛ لا ينتهي بالعمر وحده أبدًا
الجاهزية `document_worker_isolation_unavailable` / `document_worker_image_outdated`	`worker_container.isolation_report`، وسجل الوسيط	الوسيط غير موثَّق أو يتعذّر الوصول إليه؛ أو الصورة مبنية من شيفرة أخرى — أعد بناءها، وأعد تشغيل الوسيط
مهمة عالقة	مجموعة العاملين، والحيازات، و`recover_expired_leases`	استعادة إعادة التشغيل + نبض
مهمة أُعيدت محاولتها ثم ذهبت إلى الرسائل الميتة (`malware_scanner_unavailable`، `storage_full`، `metadata_unavailable`، `worker_isolation_*`)	`errors.py`، و`_classify_failure` في `worker.py`	الأعطال تُعاد محاولتها ضمن الميزانية المحدودة؛ ولا يُرفض إلا المحتوى
مهمة “غير موجودة” وهي موجودة	فحص الفاعل في `ingestion.job_status`	المهمة غير المقروءة تُقرأ تمامًا كالمهمة غير المعروفة (لا كاشف للوجود)
وصول عابر للمستأجرين	ACL المستودع	مستأجر + فاعل عند كل قراءة
التحويل/التنقيح غير متاح	المحوّلات/المغيّرات في `GET /api/documents/health` (تقرير صورة العامل في ملف تعريف الحاوية)	422/503، لا نجاح زائف صامت
عدم اتساق النسخ المتعددة	جهوزية خلفيات البيانات الوصفية/المهام + وحدة blob المشتركة	افحص `ops/readiness` قبل التوسع
استيراد المحلّل من البوابة	اختبارات مطابقة البنية	قائمة الوحدات المحظورة

الدليل: الذكاء المستندي · التشغيل: معالجة المستندات.

أبقِ هذه الوثيقة أقصر من تفريغ وحدات كامل — أشر إلى الملفات، واذكر الثوابت والعلاقات. الفهارس الكاملة تبقى في ARCHITECTURE_AND_SYSTEM_MAP.md.

تاريخ تذكير خاطئ / استبدال ذاكرة

العَرَض: يجدول الوكيل تذكيرًا بتاريخ خاطئ، أو يستبدل معتقد ذاكرة أكّده المستخدم بتاريخ مختلَق.

السبب الجذري: عامل النموذج عبارةً نسبية (“بعد يومين”) كتاريخ حدث مطلق بدل تثبيتها بحدث في الذاكرة؛ وكتب مستخرِج ما بعد الدور التاريخ المختلَق كمعتقد مستنتَج.

طبقات الإصلاح (كلها في مكانها):

بوابة الالتزام (safety/commitment/authorize.py): تثبّت resolve_remind العبارات النسبية بأحداث الذاكرة وتعيد كتابة وسائط الأداة إلى fire_at الصحيح قبل التنفيذ.
بوابة الثقة بالمصدر (memory/belief_mutation.py:_mutate_functional): المعتقد الوظيفي user_explicit لا يمكن أن يستبدله مصدر أوثقية أدنى (llm_inferred).
الحفظ التلقائي المحافظ (memory/belief_extractor._apply_beliefs_to_v2): المعتقدات المستنتَجة منخفضة الثقة تُهمل بعد الدور.

مفتاح الإيقاف: يعطّل KAZMA_COMMITMENT_ENABLED=0 البوابة. افحص تدقيق الالتزامات: SELECT * FROM commitments WHERE act='remind' ORDER BY created_at DESC LIMIT 10.

محرّك النية

العنصر: kazma_core/agent/intent/ — classify_turn → execute/constrain/loop

الأعراض:

إطلاق خط معالجة خاطئ (مثل “ابنِ محلّل PDF” → تنفيذ مستندي)
تخطي بطاقة HITL عند توليد مستند
تشويه موضوع البحث أو توجيهه إلى مسار خاطئ
النموذج يتجاهل إرشاد الأدوات في توجيه النظام

التشخيص:

افحص سجل المشرف عن [Supervisor] Intent Engine: focus=X route=Y acts=Z reason=W
تحقق من مفاتيح الإيقاف: KAZMA_INTENT_ENGINE، KAZMA_INTENT_EXECUTE، KAZMA_INTENT_TIER2 ليست 0
اختبر التصنيف: python -c "from kazma_core.agent.intent.classify import classify_turn_sync; d = classify_turn_sync('reproduce this PDF'); print(d.route, [a.kind for a in d.acts], d.reason)"
إن كان المسار غير متوقع → افحص أنماط regex في heuristics.py
إن نُفِّذ بلا نتيجة → افحص تسجيل المعالجات في registry.py

الملفات الأساسية:

agent/intent/heuristics.py — كشف الأفعال (متعدد التسميات)
agent/intent/policy.py — قرار المسار (قائمة السماح للتنفيذ)
agent/intent/entities.py — تحليل الملفات
agent/intent/classify.py — نقطة الدخول الوحيدة
agent/intent/handlers/ — معالجات التنفيذ (المستندات، البحث، المؤلِّف)

سجل بوابات HITL (2026-09-01)

العَرَض → أول مكان تنظر إليه. بطاقات موافقة أشباح/مكررة، أو بطاقة مختومة مسبقًا “موافق — يعمل” بلا نقرة، أو سؤال خطر ثانٍ لا يُرى إلا على لوحة التحكم، أو “الموافقة لم تفعل شيئًا”، أو دور مُعلن اكتماله وسؤال معلّق → kazma_core/safety/hitl_gates.py (مصدر الحقيقة الوحيد لدورة الحياة، kazma-data/hitl_gates.db).

pending هي الحالة الوحيدة التي تعرض أزرارًا حية؛ القرّاء يستخدمون السجل (hitl_thread_status، close_turn، /api/pending-approvals، status.gate_views). ترسم الدردشة part.view / gate_views؛ ولا تعيد الاشتقاق. تستطلع لوحة التحكم وTUI قائمة المعلّق مفتاحها gate_id، لا thread_id.
صف معلّق + نقطة تفتيش موقفة مؤقتًا ⇒ يبقى الدور مفتوحًا (قاعدة الصمت). موقفة مؤقتًا + لا صف يغطي ⇒ تعبئة من اللقطة والبقاء مفتوحًا. صف معلّق + غير موقف ⇒ يتيم، يُحسم في close_turn.
سباقات المطالبة: CAS — فائز واحد، و409 يحمل الحالة/القرار الفعليين؛ القرار نفسه مرتين هو 200.
راقب kazma_hitl_gate_reconciled_total. مفتاح الإيقاف KAZMA_GATE_REGISTRY=0 تراجع تنفيذ رفيع (مقاطعة حية ⇒ بطاقة معلّقة)، لا مُقرِّر ثانٍ.
المواصفة الكاملة: docs/plans/HITL_GATE_REGISTRY_PLAN.md + AGENTS.md §30.