الإعداد

المرجع الشامل. كل مفتاح في kazma.yaml، وكل متغير بيئة، ونموذج تجاوزات ConfigStore، وسجل المزوّدين/النماذج، وملفات إعداد الأمان — كلها قابلة للتتبع إلى المصدر.

---

1. مصادر الإعداد والأسبقية

تحلّ كاظمه الإعداد من ثلاث طبقات. بالنسبة إلى ConfigStore.get(key) العام، الترتيب هو:

flowchart LR
    C[In-process cache] -->|miss| DB[(SQLite or PostgreSQL settings)]
    DB -->|miss / child-merge| YAML["kazma.yaml + kazma.local.yaml"]
    YAML -->|fallback| DEFAULT[hardcoded default]

#	الطبقة	تفوز؟	ملاحظات
1	متغير البيئة	فقط في مساعدات محددة (get_kazma_secret، get_or_create_disclosure_key) — ليس في get() العام.	مثل KAZMA_SECRET
2	قاعدة ConfigStore (SQLite أو PostgreSQL)	نعم لقراءات زمن التشغيل عبر get().	الإعدادات المحفوظة تتجاوز YAML.
3	kazma.local.yaml	يتجاوز YAML المشحون.	ملف محلي اختياري؛ تملأ قيمه الإعدادات الناقصة عند أول إقلاع.
4	kazma.yaml	خط الأساس المشحون.	يُدمج مع YAML المحلي قبل ملء المفاتيح الناقصة بواسطة reconcile_from_yaml().
5	الافتراضي المشفّر في الكود	الملاذ الأخير.	مثل gpt-4o-mini، وDEFAULT_DANGER_TOOLS.

أسبقية التجاوز (مفصلة)

• ‏ConfigStore.get(key) (config_store.py:471-516): يفحص _cache داخل العملية أولًا (مع حارس _MISSING للمفاتيح المعروفة الغياب)، ثم صف قاعدة مطابقًا تمامًا، ثم إعادة دمج المفاتيح الابنة في القاعدة عبر _collect_prefixed (الصفوف التي يبدأ مفتاحها بـ key. تُفكّ نقاطها إلى قاموس متداخل)، ثم بحث عن مفتاح منقّط في YAML.
• يكتب ConfigStore.set(key, value) صفًا واحدًا ويمسح الخبيئة لذلك المفتاح (config_store.py:518-536).
• ‏ConfigStore.batch_set(items) هو الكتابة الذرية متعددة المفاتيح — BEGIN/COMMIT واحد، وتراجع عند أي فشل (config_store.py:538-568). فضّله دائمًا لتحديثات المفاتيح المتعددة.
• ‏ConfigStore.transaction() هو @contextmanager يسلّم الاتصال الخام لمعاملات متعددة العمليات يقودها المستدعي (config_store.py:572).
• يملأ reconcile_from_yaml() مفاتيح القاعدة الناقصة من YAML المشحون مدموجًا مع kazma.local.yaml، بالأسبقية نفسها لقراءات البديل. تبقى اختيارات المزوّد والنموذج المحلية محفوظة حين يوافق الإقلاع مساحة العمل النشطة. ويمكن لملف محلي وحده ملء الإعدادات دون YAML مشحون. تظل الإعدادات المحفوظة نافذة؛ ولا تستبدلها تعديلات YAML اللاحقة.
• تحدّث الهجرات المعلنة لمرة واحدة في config_defaults.RETIRED_DEFAULTS النسخ القائمة من الافتراضيات المتقاعدة قبل ملء المفاتيح الجديدة. تستخدم خط الأساس المشحون، لا التجاوزات المحلية. ويُحفظ الاختيار المحلي الجديد حتى إن ساوى افتراضيًا قديمًا. يؤجّل التقاعد حين لا تتوفر خريطة مشحونة صالحة.
• يجري export_yaml() / import_yaml() دورة ذهاب وعودة لكل صفوف القاعدة مدموجة في YAML؛ وبهذا ينقل kazma migrate الإعدادات (config_store.py:632, 650). أما النسخة الاحتياطية في صفحة الإعدادات فملف آخر، أدناه.
• يحذف reset_all() كل صفوف القاعدة → يعود إلى افتراضيات YAML (config_store.py:732). ولا تعرضه أي صفحة: كان سيحذف المفاتيح وتسجيل الدخول أيضًا.

قاعدة المفرد: استخدم دائمًا get_config_store()، ولا تنشئ ConfigStore() مباشرة للإعدادات المشتركة. إذا فشلت تهيئة SQLite أو PostgreSQL، يتوقف الإقلاع الإنتاجي؛ ولا يُستخدم بديل ذاكرة قابل للكتابة. انظر حفظ الإعدادات والتعافي من الانقطاع.

النسخ الاحتياطي للإعدادات واستعادتها

‏الإعدادات ← النظام ← تنزيل نسخة احتياطية من الإعدادات يحفظ ملف YAML يحمل اسمه تاريخ اليوم؛ والإعدادات ← الاستيراد/التصدير ← التصدير يعطي الملف نفسه بصيغة YAML أو JSON. يحمل الملف:

• كل إعداد يخزّنه هذا التثبيت، سطرًا لكل إعداد (agent.language: ar)، لا القيم الافتراضية في kazma.yaml، فلا تثبّت الاستعادة قيمة افتراضية قديمة أبدًا؛
• المفاتيح بأسمائها فقط، كإشارات إلى خزنة هذا التثبيت (vault://cfg:providers.list.deepseek.api_key)، لا المفاتيح نفسها. والمفتاح المحفوظ نصًا صريحًا (دون خزنة) وكلمة المرور داخل عنوان URL يُكتبان ****؛
• لا شيء من حالة Kazma الخاصة (أذونات الموافقة، وسجل المهمة الطويلة لمحادثة، وأختام الإقلاع) ولا أي بيانات اعتماد (سر تسجيل الدخول، وكلمة المرور، والمتصفحات المسجَّل دخولها، ومن يحق له استخدام التثبيت).

‏استعادة نسخة احتياطية من الإعدادات… (والاستيراد/التصدير ← الاستيراد، الذي يستطيع استعادة أقسام مختارة) يعرض أولًا ما سيتغير، ولا يكتب إلا بعد تأكيدك:

ما تحمله النسخة	ما تفعله الاستعادة
إعداد	تكتب قيمة النسخة، عبر الفحوص نفسها التي يجريها حفظ الإعدادات. والقيمة التي ترفضها الإعدادات تُذكر وتبقى كما هي.
مفتاح لديك الآن	تُبقي مفتاحك. لا يُستبدل أبدًا.
مفتاح لم يعد لديك	تعيده من خزنة هذا التثبيت ما دامت إشارة النسخة تفتح، فلا تدخل شيئًا. وإلا يُذكر لتدخله مجددًا من الإعدادات.
المزوّدون وخوادم MCP وحسابات البريد	تدمجها بالاسم. تبقى الإدخالات والحقول المضافة بعد النسخة، ويحتفظ كل منها بمفاتيحه. ولا يعود حساب بريد إلا ما دامت الخزنة تحفظ تسجيل دخوله.
حالة Kazma الخاصة، وبيانات الاعتماد	لا تُكتب أبدًا.
الروح التي تعلّمها Kazma	لا تُستعاد إلا حيث لا روح للتثبيت.
قيمة افتراضية غيّرها Kazma بعد النسخة	تبقى على قيمة اليوم (config_defaults.RETIRED_DEFAULTS).
إعداد لا تذكره النسخة	يبقى. الاستعادة لا تحذف شيئًا.

إذا تغيّرت إعداداتك بين المعاينة والتأكيد، لا يُكتب شيء وتُعرض المعاينة من جديد. والتراجع عن آخر استعادة يعيد ما غيّرته آخر استعادة، إلا إعدادًا تغيّر مجددًا بعدها ومفتاحًا أعادته. ثم يعرض Kazma إعادة التشغيل، لأن المزوّدين والنماذج وتطبيقات المحادثة تُقرأ عند البدء.

وتُستعاد الملفات الأقدم أيضًا: النسخة الاحتياطية السابقة (كل الصفوف، متداخلة)، والتصدير السابق من الاستيراد/التصدير (صفوف مجمّعة حسب الفئة). وتُستبعد منها بيانات الاعتماد وحالة Kazma الخاصة بالطريقة نفسها.

المصدر: kazma_core/settings_restore.py. يُصنَّف كل مفتاح هناك (KEY_RULES)؛ ويفشل tests/test_settings_restore_classes.py عند مفتاح يكتبه الكود ولا تسمّيه أي قاعدة. وفحوص القيم في kazma_core/settings_validation.py، مشتركة مع كل حفظ.

---

2. kazma.yaml — المرجع الكامل

الملف الافتراضي الكامل (kazma.yaml) بكل مفتاح ونوع وافتراضي، قسمًا قسمًا.

agent

المفتاح	النوع	الافتراضي	الوصف
agent.name	string	kazma	اسم عرض البوت.
agent.version	string	0.2.0	ملاحظة: يتباين عن pyproject.toml (0.3.0). لا يُزامَن تلقائيًا.
agent.language	string	ar	لغة الواجهة/الوكيل. ‏ar → RTL + عربية؛ en → إنجليزية.
agent.rtl	bool	true	مفتاح RTL الرئيس.

agent.topic_drift — كشف انزياح الموضوع بالتضمين

يُقرأ حيًّا عند كل فحص دور (لا حاجة لإعادة تشغيل للضبط). فشل مفتوح: إن كان المُضمِّن غير متاح أو أخطأ encode، لا يفرض انزياح التضمين انعطافًا أبدًا — مصنّفات regex/الصريحة والاستدلالية ما تزال تنطبق.

المفتاح	النوع	الافتراضي	الوصف
agent.topic_drift.enabled	bool	true	تشغيل/إطفاء كشف انزياح الموضوع بالتضمين. لا يؤثر في مصنّفات الانعطاف regex/الاستدلالية.
agent.topic_drift.threshold	float	0.55	المسافة الجيبية (1 − التشابه) التي عندها يُعلَّم الدور كانزياح موضوع. محصورة [0.05, 0.95]. الأعلى = لا تعدّ منعطفًا إلا الأدوار الأكثر اختلافًا.

اتجاه الضبط:

• انعطاف زائف (يتخلى الوكيل عن مهمة مشروعة متعددة الخطوات في منتصف التدفق) → ارفع العتبة.
• انعطاف مفقود (يستأنف الوكيل المهمة القديمة بعد انعطاف حقيقي) → اخفض العتبة.

يُقرأ المفتاحان معًا عبر topic_drift_config() من ConfigStore ويتراكبان فوق kazma.yaml.

agent.nonstop — محرك التنفيذ غير المتوقف وذاتي الشفاء

قابل للضبط عبر واجهة الإعدادات (الإعدادات → الوكيل → غير المتوقف وذاتي الشفاء)، أو ConfigStore (agent.nonstop.*)، أو kazma.yaml. يُقرأ حيًّا عند كل تنفيذ دور (get_nonstop_config()).

المفتاح	النوع	الافتراضي	الوصف
agent.nonstop.enabled	bool	false	المفتاح الرئيس للتنفيذ غير المتوقف والكلب الحارس.
agent.nonstop.watchdog.stall_threshold_seconds	int	60	عتبة كشف توقف الكلب الحارس بالثواني.
agent.nonstop.tool_timeout_seconds	int	120	مهلة تنفيذ كل أداة (asyncio.wait_for).
agent.nonstop.healing.max_recovery_attempts	int	3	أقصى محاولات الاستعادة والاستئناف قبل التصعيد.
agent.nonstop.healing.backoff_base_seconds	float	2.0	أساس التراجع الأسي لاستعادة الكلب الحارس.
agent.nonstop.healing.backoff_max_seconds	float	30.0	أقصى انتظار تراجع بين محاولات الاستعادة.
agent.nonstop.failover.enabled	bool	false	تفعيل سلسلة تجاوز فشل النموذج عند فشل LLM الأساسي.
agent.nonstop.failover.chain	list/str	[]	قائمة مرتبة أو سلسلة مفصولة بفواصل لمعرّفات نماذج التجاوز.
agent.nonstop.failover.cooldown_seconds	int	300	فترة التهدئة بالثواني قبل إعادة محاولة نموذج فاشل في السلسلة.
agent.nonstop.ledger.enabled	bool	true	تفعيل تسجيل دائم لكل استدعاء LLM (kazma-data/llm_calls.db).

models

المفتاح	النوع	الافتراضي	الوصف
models.default	string	gpt-4o-mini	معرّف النموذج الافتراضي.
models.router	string	kazma	تسمية موجّه كاظمه نفسه. ليس import litellm. وجّه base_url إلى وكيل LiteLLM إن كنت تشغّل واحدًا.
models.fallback	string	gpt-4o-mini	النموذج المستخدم عند إعادة المحاولة حين يفشل استدعاء HTTP الأساسي.

llm

المفتاح	النوع	الافتراضي	الوصف
llm.base_url	string	https://api.openai.com/v1	نقطة طرفية متوافقة مع OpenAI. تُلحق /v1 تلقائيًا إن غابت (باستثناء Ollama :11434 وLiteLLM :4000).
llm.api_key	string	''	اتركها فارغة للتحميل من البيئة (OPENAI_API_KEY → KAZMA_API_KEY → "not-needed" للمحلي).
llm.model	string	gpt-4o-mini	معرّف النموذج المرسل في الحمولة.
llm.max_tokens	int	4096	سقف رموز الإكمال.
llm.temperature	float	0.7	حرارة أخذ العينات.
llm.timeout	float	60.0	مهلة كل طلب (ثوانٍ).
llm.input_cost_per_1m	float	0.15	دولار لكل 1M رمز إدخال — تُستخدم لمحاسبة التكلفة.
llm.output_cost_per_1m	float	0.6	دولار لكل 1M رمز إخراج.
llm.gateway.url	string	''	وكيل LiteLLM اختياري للمزوّدين المتوافقين مع OpenAI. متغير البيئة KAZMA_LITELLM_URL يفوز. الفرع الأصلي الأربعة لا يستخدمه أبدًا.
llm.gateway.api_key	string	''	المفتاح الرئيس للوكيل (LITELLM_MASTER_KEY). مشفّر في الخزنة.
llm.gateway.include_local	bool	false	أرسل أيضًا Ollama/LM Studio عبر الوكيل (KAZMA_LITELLM_LOCAL=1).
llm.gateway.fallback_direct	bool	false	إن كان الوكيل متوقفًا، أعد محاولة URL الأصلي مرة (KAZMA_LITELLM_FALLBACK_DIRECT=1).

mcp

المفتاح	النوع	الافتراضي	الوصف
mcp.servers	list	انظر أدناه	تعريفات خوادم MCP.
mcp.servers[].name	string	—	معرّف الخادم.
mcp.servers[].transport	string	stdio	‏stdio أو sse أو streamable_http (كنية http). تدعم sse وstreamable_http حقل auth (bearer/ترويسة مخصصة)؛ ويتتبع streamable_http أيضًا Mcp-Session-Id لجلسات قابلة للاستئناف (مواصفة MCP 2025-03-26).
mcp.servers[].trust	string	trusted	سلسلة إعداد بسيطة — لا تستهلكها أي شفرة طبقات ثقة.
mcp.servers[].command	list	—	argv لإنشاء stdio.
mcp.ide_server.enabled	bool	true	تفعيل خادم MCP داخل العملية للـ IDE/الملفات.
mcp.ide_server.root	string	.	جذر مساحة العمل.
mcp.ide_server.max_file_size	int	1048576	سقف حجم الملف 1 MB.

الخادم الافتراضي المشحون:

mcp:
  servers:
    - name: filesystem
      transport: stdio
      workspace_bound: true
      trust: approval_required
      command: [npx, -y, '@modelcontextprotocol/server-filesystem', '${KAZMA_ACTIVE_WORKSPACE}']
  ide_server:
    enabled: true
    root: .
    max_file_size: 1048576

system_prompt

سلسلة متعددة الأسطر. الافتراضي واعٍ بالعربية: “You are Kazma (كاظمه), an autonomous AI agent framework…” ويُرشد النموذج إلى الرد بلغة المستخدم/لهجته.

storage

المفتاح	النوع	الافتراضي	الوصف
storage.engine	string	sqlite	محرك نقاط التفتيش.
storage.path	string	kazma-data/checkpoints.db	قاعدة نقاط تفتيش LangGraph.
storage.vector_dim	int	1024	بُعد المتجه المعلن (استئناسي — يجب أن يطابق memory.embedding.dim؛ افتراضي BGE-M3 هو 1024).

memory

المفتاح	النوع	الافتراضي	الوصف
memory.enabled	bool	true	المفتاح الرئيس (RAG لكل دور، الحفظ التلقائي، الموحِّد). يتراكب ConfigStore فوق yaml.
memory.per_turn_retrieval	bool	true	حقن أفضل k ذكريات عند كل دور مستخدم.
memory.auto_store	bool	true	كتابات الحفظ الدائم/الأدوار الاستدلالية بعد كل رد.
memory.auto_store_mode	str	both	durable | turns | both.
memory.max_context_tokens	int	1000000	نافذة السياق: ينطلق الضغط عند 80 %، وتشذيب السجل عند 95 %. أي نافذة تُطبَّق، والأولوية لأول تطابق: models.context_window.<model> (نافذة نموذج بعينه)، ثم الإعدادات ← الوكيل ← نافذة السياق (context.max_context_tokens)، ثم هذا المفتاح، ثم 1,000,000. ويحدد agent.trim.token_budget (مخزن الإعدادات) ميزانية التشذيب بدلًا من ذلك (تبقى بين 4,000 و95 % من النافذة). والدردشة التي تتجاوزها رغم ذلك تحتفظ بطلباتك السابقة وردود كاظمه النصية البحتة، الأحدث أولًا (حتى 16، كل منها مقتطع إلى 1,500 حرف)، فيبقى خيط المحادثة بعد التشذيب.
memory.retrieval_top_k	int	5	أفضل-K لـ RAG كل دور والضغط.
memory.provenance	bool	true	وسم الذكريات ببيانات المصدر الوصفية.
memory.consolidation.enabled	bool	true	أمين المكتبة بعد الدور (حقائق + ثلاثيات الرسم).
memory.consolidation.use_llm	bool	true	استخراج LLM؛ تراجع استدلالي عند الفشل/الإطفاء.
memory.consolidation.every_n_turns	int	1	ضبط التكلفة: تشغيل الموحِّد كل N دور.
memory.consolidation.skip_llm_in_demo	bool	true	لا LLM تحت KAZMA_DEMO_MODE.
memory.embedding.provider	str	local	local أو واجهة تضمين بعيدة متوافقة مع OpenAI.
memory.embedding.model	str	BAAI/bge-m3	معرّف نموذج التضمين (متعدد اللغات، بُعد 1024).
memory.embedding.dim	int	1024	يجب أن يطابق المُضمِّن.
memory.embedding.base_url	str	غير مضبوط	نقطة /embeddings للمزوّدين البعيدين.
memory.embedding.api_key_env	str	KAZMA_EMBED_API_KEY	متغير بيئة يحمل مفتاح API البعيد.

المُضمِّن قابل للضبط أيضًا من واجهة الويب: الإعدادات → المُضمِّن (الحفظ هناك يسري بعد إعادة تشغيل الخادم، ويتضمن إجراء “إعادة بناء التضمينات” الخلفي بنقرة واحدة + تركيبة الفضاء المتجهي لقاعدة ذاكرتك). تجاوز ConfigStore (embedding.*) يتقدم على kazma.yaml؛ ومتغيرات البيئة (KAZMA_EMBED_*) تفوز على كليهما. بعد تبديل نموذج، شغّل إعادة البناء كي يعيش كل صف في الفضاء المتجهي نفسه.

skills

المفتاح	النوع	الافتراضي	الوصف
skills.path	string	kazma-skills/manifests/	دليل بيانات المهارات.
skills.auto_discover	bool	true	تحميل البيانات تلقائيًا عند الإقلاع.

connectors

المفتاح	النوع	الافتراضي	متغير بيئة الرمز
connectors.telegram.enabled	bool	true	TELEGRAM_BOT_TOKEN
connectors.discord.enabled	bool	false	DISCORD_BOT_TOKEN
connectors.slack.enabled	bool	false	SLACK_BOT_TOKEN + SLACK_APP_TOKEN

gateway

المفتاح	النوع	الافتراضي	الوصف
gateway.rate_limits.telegram	int	30	عدد الرسائل التي يرسلها شخص واحد في الدقيقة على Telegram. وبعده يجيب كاظمه «تمهّل» (مرة كل 30 ثانية على الأكثر) ويترك الباقي بلا رد، ويُسجَّل كل منها ويظهر في اختبار المنصة. هو حارس من الإغراق، لا حدّ الإرسال الخاص بـTelegram.
gateway.rate_limits.discord	int	30	الأمر نفسه على Discord. وكانت قيمته المشحونة 5 حتى 2026-10-01؛ والتثبيت الذي ما زال يحمل 5 ينتقل إلى 30 عند تشغيله التالي.
gateway.rate_limits.slack	int	30	الأمر نفسه على Slack. وكانت قيمته المشحونة 1 حتى 2026-10-01، أي رسالة Slack واحدة في الدقيقة؛ والتثبيت الذي ما زال يحمل 1 ينتقل إلى 30 عند تشغيله التالي.
gateway.suggestions.enabled	bool	true	في Telegram وDiscord وSlack: بعد دور لم يستخدم فيه الوكيل أي أداة، ما يصل إلى تلميحين ”💡” حين تبدو رسالتك مهمة لأداة (رابط للقراءة، شيء للبحث عنه). القيمة false لا ترسل شيئًا. يُقرأ عند بدء التشغيل.
gateway.voice.enabled	bool	false	الصوت (STT وارد + TTS صادر) عبر كل المنصات (تيليجرام، ديسكورد، سلاك) + الويب. قابل للضبط أيضًا في زمن التشغيل عبر الإعدادات → الصوت.
gateway.voice.stt_provider	string	openai	اسم تحويل الكلام إلى نص: openai أو groq أو cohere أو nvidia أو faster-whisper. مفاتيح API تأتي من الإعدادات → المزوّدون، لا من هذه الكتلة. Whisper ليس نموذج دردشة.
gateway.voice.stt_language	string	auto	لغة STT (auto، ar، en، …). تستخدم الإعدادات form-select نفسه المستخدم لبقية حقول الصوت.
gateway.voice.stt_model	string	default	معرّف نموذج Whisper / transcribe لمزوّد STT المختار.
gateway.voice.tts_provider	string	edgetts	مزوّد تحويل النص إلى كلام: edgetts (مجاني، افتراضي)، openai، nvidia، kokoro (محلي)، coqui (محلي).

safety.hitl

المفتاح	النوع	الافتراضي	الوصف
safety.hitl.enabled	bool	true	مفتاح HITL الرئيس (مسار الرسم).
safety.hitl.require_approval_for	list	انظر أدناه	أدوات الخطر لمسار الرسم.
safety.hitl.approval_timeout_seconds	int	300	المدة التي تنتظر فيها بطاقة الموافقة إجابة. بعدها لا تُشغَّل الأداة، ويُبلَّغ النموذج والدردشة بأن الموافقة انتهت صلاحيتها. وهي أيضًا الموعد النهائي لطلبات ناقل السرب.
safety.hitl.auto_deny_on_timeout	bool	true	رفض المهام الموقوفة مؤقتًا تلقائيًا عند انتهاء المهلة.

افتراضي require_approval_for:

safety:
  hitl:
    enabled: true
    require_approval_for:
      - file_write
      - file_delete
      - shell_exec
      - code_exec
      - python_exec
      - spawn_agent
      - spawn_agents
      - schedule_task
      - cancel_scheduled
    approval_timeout_seconds: 300
    auto_deny_on_timeout: true

يستخدم ناقل السرب _EXTENDED_DANGER، وهي نسخة من القائمة المرجعية (CANONICAL_DANGER_TOOLS) بالمحتوى نفسه، لا قائمة أوسع. وتُضاف القائمة المرجعية دائمًا إلى القائمة أعلاه (ما لم يُضبط KAZMA_HITL_CANONICAL_FLOOR=0)، فلا يستطيع هذا الملف تضييقها. مسار MCP يصنّف ديناميكيًا بنمط الاسم. انظر الأمن والسلامة ← قوائم أدوات الخطر.

notifications.lifecycle

رسائل حالة الخادم — بطاقة واحدة في كل مرة يعود فيها كاظمه للعمل (كم توقف، وهل اتصل كل تطبيق محادثة، والإصدار والنموذج)، وبطاقة حين يفشل الإقلاع. تُرسل حيث تذهب التنبيهات. الإعدادات ← المزوّدون والموصلات ← موصلات المنصات ← المحوّلات والمسارات ← رسائل حالة الخادم. انظر النشر ← إشعارات دورة الحياة.

المفتاح	النوع	الافتراضي	الوصف
notifications.lifecycle.enabled	bool	true	المفتاح الرئيس.
notifications.lifecycle.events	list	[started, startup_failed]	الرسائل التي تُرسل: started (البطاقة حين يعود كاظمه للعمل)، وstartup_failed، وstarting، وshutting_down. القائمة الفارغة لا ترسل شيئاً. حتى 2026-09-29 كان الافتراضي الأربعة كلها — ثلاث رسائل لكل إعادة تشغيل — والتثبيت الذي ما زال يحتفظ بذلك الافتراضي المخزَّن يُنقل إلى الجديد مرة واحدة عند الإقلاع.
notifications.lifecycle.restart_window_seconds	int	60	إيقاف نظيف يتبعه بدء خلال هذه النافذة يُقرأ “Kazma restarted” بدل “Kazma started”. 0 يعطّل كشف إعادة التشغيل (ولا سطر لمدة التوقف أيضاً).

الافتراضي:

notifications:
  lifecycle:
    enabled: true
    events:
      - started
      - startup_failed
    restart_window_seconds: 60

تُوجَّه الإشعارات عبر SwarmMessageBus (لا مسار موازٍ). اضبط connectors.<platform>.swarm_chat_id على معرّف الدردشة التي يجب أن تهبط فيها الرسائل. بدونه يكون الناقل NullBusAdapter وتُهمل الرسائل بصمت.

ui

المفتاح	النوع	الافتراضي	الوصف
ui.host	string	127.0.0.1	مضيف الربط. يتحول إلى 0.0.0.0 تحت kazma serve فقط إن ضُبط KAZMA_SECRET.
ui.port	int	8000	منفذ الربط.
ui.rtl	bool	true	RTL الواجهة.
ui.title	string	Kazma Dashboard	عنوان الصفحة.

logging

المفتاح	النوع	الافتراضي	الوصف
logging.level	string	INFO	مستوى السجل.
logging.format	string	json	json أو عادي.
logging.langfuse.enabled	auto / bool	auto	auto = Langfuse عند وجود المفتاحين العام والسري. false / KAZMA_LANGFUSE=0 = مطفأ.
logging.langfuse.public_key	string	''
logging.langfuse.secret_key	string	''

time_travel

المفتاح	النوع	الافتراضي	الوصف
time_travel.enabled	bool	true	تفعيل /replay.
time_travel.max_snapshots	int	50	سقف اللقطات (لكل خيط). تجاوز ConfigStore ‏time_travel.max_snapshots (الإعدادات → المُضمِّن → السفر عبر الزمن) يتقدم على هذه القيمة؛ التحليل الفعلي هو store > yaml > default. يُطبَّق عند إقلاع الخادم.
time_travel.retention_days	int	30	تقليم اللقطات الأقدم من هذا العدد من الأيام (1–3650). تجاوز ConfigStore ‏time_travel.retention_days (الإعدادات → المُضمِّن → السفر عبر الزمن) تقرأه حلقة الصيانة اليومية حيًّا — لا حاجة لإعادة تشغيل.
time_travel.auto_maintain	bool	true	تفعيل حلقة التقليم اليومي للقطات + VACUUM. تجاوز ConfigStore ‏time_travel.auto_maintain يُقرأ حيًّا، مثل retention_days.
time_travel.db_path	string	kazma-data/snapshots.db	قاعدة اللقطات.

swarm

المفتاح	النوع	الافتراضي	الوصف
swarm.enabled	bool	true	مفتاح السرب الرئيس.
swarm.group_chat_id	int	0	القيمة الحقيقية تُقرأ من بيئة SWARM_CHAT_ID.
swarm.default_pattern	str	dispatch	نمط التراجع: dispatch | pipeline | consult | fan_out | broadcast.
swarm.auto_route	bool	true	تفعيل التوجيه الدلالي التلقائي (UnifiedRouter) لـ workers=["auto"].
swarm.max_concurrent_tasks	int	10 (1–100)	أقصى مهام سرب متزامنة.
swarm.max_concurrent	int	5	تزامن عمال fan-out / broadcast / consult.
swarm.orchestrator.name	string	Kazma Orchestrator	اسم عرض المنسّق.
swarm.orchestrator.profile	string	default	معرّف ملف المنسّق.
swarm.workers	list	[]	يُملأ في زمن التشغيل عبر واجهة الويب / POST /api/swarm/workers.
swarm.output_target	obj	none	\{bot_token, chat_id, platform, enabled\} — حين يُضبط، يجب أن يطابق الرمزُ رمزَ بوت تيليجرام النشط.

cron.* — التذكيرات والمهام المجدولة (ConfigStore)

يقرؤها المجدول حيًّا؛ والقيمة الخارجة عن النطاق تُرفض عند حفظها (PUT /api/settings/single). للمنطقة الزمنية عنصر تحكم خاص بها (الإعدادات، cron.timezone)؛ أما هذه المفاتيح فليس لها عنصر تحكم في أي صفحة بعد.

المفتاح	النوع	الافتراضي (النطاق)	الوصف
cron.timezone	string	فارغ (KAZMA_TZ، وإلا UTC)	المنطقة الزمنية التي يُقرأ بها الوقت الذي لا يذكر منطقة، ووقتُ الساعة (“يوميًا في 9 صباحًا”).
cron.catchup_minutes	int	60 (1–10080)	كم يجوز أن تتأخر مهمة وتبقى تنطلق بعد أن كان كاظمه متوقفًا. وما تأخر أكثر يُعدّ فائتًا، مع إشعار واحد. يُستخدم KAZMA_CRON_STALE_HOURS حين لا يكون هذا مضبوطًا.
cron.task_budget_seconds	int	300 (30–3600)	المدة التي يجوز أن يعملها دور مهمة الوكيل المُطلَقة.
cron.max_jobs_per_tenant	int	500 (1–10000)	المهام التي ما تزال تحمل عملًا لكل مستأجر؛ والحجز الذي يتجاوزه يُرفض.
cron.max_jobs_per_thread	int	50 (1–1000)	الشيء نفسه، لكل محادثة.
safety.cron_fire_without_hitl	bool	false	إطلاق مهام الوكيل والموافقات (HITL) مطفأة. مطفأ: لا تنطلق المهام حينئذ (والتذكيرات تنطلق). وهو تحت safety.، فلا يستطيع الوكيل ضبطه.

ما يجوز أن تفعله المهمة المُطلَقة: التذكيرات والمهام المجدولة.

pipelines

خطّان معرّفان مسبقًا (قوائم مراحل، لكل منها worker وdepends_on وsystem_prompt):

• standard — 4 مراحل: researcher (عامل core) → refiner (عامل bridge) → builder (عامل core) → validator (عامل bridge).
• quick — مرحلتان: researcher (عامل core) → builder (عامل core).

documents.* — الذكاء المستندي (ConfigStore / واجهة الإعدادات)

ليست كل المفاتيح في هيكل kazma.yaml المشحون؛ الافتراضيات النافذة تعيش على DocumentConfig (kazma_core/documents/config.py) وتُقرأ حيًّا عبر get_document_config(): تأخذ كل عملية لقطة واحدة من إعدادات documents وتحتفظ بها حتى النهاية. اضبط عبر:

• الإعدادات → المستندات (/settings?tab=documents): الكتابة الدائمة، ووضعا الظل والنافذ، وحجم الاستيعاب وعدد الملفات، ومهلة العامل وذاكرته، والحد الأدنى للمساحة الحرة في التخزين، ووضع مسح البرمجيات الخبيثة والإغلاق عند الفشل، وOCR، وقراءة الجداول المسطّرة في الصفحات الممسوحة ضوئيًا (documents.ocr.tables)، وGC والفهرسة؛ وتعرض أيضًا هل عُثر على ماسح برمجيات خبيثة
• GET/PUT /api/settings/documents (الحقول نفسها)
• PUT /api/settings/single بمفتاح متداخل، لكل مفتاح آخر
• بذرة kazma.yaml اختيارية تحت قسم documents:

القيمة المحفوظة التي لا يمكن قراءتها بنوعها لا تُستبدل بقيمة افتراضية: تجيب عمليات المستندات بـ 503 document_policy_unavailable حتى تُصحَّح، ومخزن الإعدادات الذي لا يمكن قراءته يرفض عمل المستندات أيضًا. ولا شيء يفحص القيمة حين تُحفظ عبر هذه المسارات.

بادئة المفتاح	الغرض
documents.enabled / shadow / default_authoritative	وضع الطرح (معطل / ظل / توافق / نافذ)
documents.storage_root	حيث تعيش المستندات، والرفوع الجارية، ومساحة العامل المؤقتة (يتطلب تغييره إعادة تشغيل)
documents.intake.*	أقصى بايتات/ملفات، وحدود الجلب البعيد، وlease_seconds (300: المدة التي يجوز أن يمضيها الرفع دون تجديد حجزه قبل أن يجوز لعملية أخرى الاستيلاء عليه)
documents.limits.*	صفحات، خلايا، أعضاء الأرشيف، الضغط، بكسلات، …
documents.security.*	وضع مسح البرمجيات الخبيثة (auto) والإغلاق عند الفشل (مطفأ، لكنه مفعّل افتراضيًا تحت KAZMA_PRODUCTION=1)، السياج، سياسة الموارد المشفرة/الخارجية، وremote_parse (الإنقاذ عبر طرف ثالث، مطفأ افتراضيًا)، وlocal_salvage (Docling داخل العامل، مفعّل افتراضيًا)
documents.render.embed_html_fonts	تضمين الخط المثبَّت داخل صادرات HTML (مفعّل افتراضيًا)
documents.ocr.*	تفعيل، لغات، DPI، ثقة، تزامن، مهلات، حد المخرجات؛ وtables (مفعّل افتراضيًا): تُقرأ الجداول المسطّرة في الصفحات الممسوحة ضوئيًا خلية خلية، بحد أقصى 600 خلية و120 ثانية للصفحة؛ والجدول الذي لا يُقرأ ضمن هذه الحدود يبقى على قراءة الصفحة نفسها
documents.workers.*	مهلة، ذاكرة، تزامن، حيازة، نبض، إعادة محاولة، حجم النتيجة
documents.indexing.*	رموز القطع، تراكب، حفظ الجداول/الصفحات
documents.retention.* / documents.gc.*	نوافذ الاحتفاظ + جدول GC / حدوده
documents.capacity.*	سقوف الطابور، نوافذ المعدل/البايت، أرضية التخزين الحرة، وmax_concurrent_uploads (4 رفوع تُستقبل في آن واحد لكل عملية)
documents.quotas.*	حصص بايت/صفحات يومية لكل مستأجر

سبعة مفاتيح مرتبطة بمخازن وعمّال تُبنى عند البدء، ويسري أثرها بعد إعادة التشغيل: documents.storage_root، وdocuments.quotas.tenant_bytes، وconcurrency وlease_seconds وheartbeat_seconds وretry_base_seconds وretry_max_seconds تحت documents.workers.. وحتى ذلك الحين تُبلغ الجاهزية عن policy.restart_required مع القيم المضبوطة والفعلية، وتقول صفحة المستندات إن بعض الإعدادات المحفوظة تحتاج إلى إعادة تشغيل.

security.execution.container_required (ملف التنفيذ الصارم، وليس مفتاحًا من documents.*) يرفض أيضًا ملف عامل المستندات المحلي process.

البيئة (اختيار الخلفية وعزل العامل):

المتغير	الافتراضي	الغرض
KAZMA_DOCUMENTS_JOBS_BACKEND	غير مضبوط	‏sqlite يفرض طابور مهام SQLite؛ وإلا Postgres حين تستخدم المنصة PG
KAZMA_DOCUMENTS_METADATA_BACKEND	غير مضبوط (auto)	sqlite / postgres / auto (الأخير يتبع المهام)
KAZMA_DOCUMENT_WORKER_ISOLATION	process	‏process (عملية فرعية محلية، بلا عزل لنظام الملفات أو الشبكة) أو container (وسيط عامل المستندات)؛ مع KAZMA_DOCUMENT_BROKER_URL وKAZMA_DOCUMENT_BROKER_TOKEN_FILE
KAZMA_DOCUMENT_SOAK_ITERATIONS	100	تكرارات اختبار التحليل الممتد في سكربت الشهادة (--soak)؛ وليس نقعًا متعدد الأيام

كل متغيرات المستندات: متغيرات البيئة.

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

---

3. متغيرات البيئة

3.1 موثَّقة في .env.example

المتغير	الغرض	الافتراضي
TELEGRAM_BOT_TOKEN	رمز محوّل تيليجرام.	placeholder
DISCORD_BOT_TOKEN	رمز محوّل ديسكورد.	فارغ
SLACK_BOT_TOKEN	رمز بوت سلاك.	فارغ
SLACK_APP_TOKEN	رمز تطبيق سلاك (وضع المقبس).	فارغ
OPENAI_API_KEY	مفتاح OpenAI (أيضًا تراجع LLM العام رقم 2).	فارغ
DEEPSEEK_API_KEY	معلن في .env.example لكن لا يقرؤه الكود — اضبط المفتاح عبر قائمة المزوّدين بدلًا منه.	فارغ
ANTHROPIC_API_KEY	معلن في .env.example لكن لا يقرؤه الكود.	فارغ
GOOGLE_CLOUD_PROJECT	مشروع GCP لـ Vertex AI (إن لم يكن في ADC افتراضي).	مُعلَّق بتعليق
SWARM_CHAT_ID	معرّف دردشة مجموعة السرب (يغذي swarm.group_chat_id).	فارغ
KAZMA_SECRET	السر المشترك لـ HITL؛ يربط serve بـ 0.0.0.0؛ تصدير كتابة المركز؛ kazma hub sign.	مُعلَّق بتعليق
KAZMA_VECTOR_PATH	دليل ذاكرة المتجهات.	~/.kazma/vector_memory
KAZMA_VECTOR_COLLECTION	اسم مجموعة ChromaDB.	agent_memory
KAZMA_VECTOR_MODEL	نموذج التضمين (كنية قديمة — فضّل KAZMA_EMBED_MODEL).	BAAI/bge-m3

3.2 تُقرأ في الكود، لا في .env.example

المتغير	الغرض	الموقع
KAZMA_AUTH_DISABLED	إن كان true/1/yes، يعيد get_kazma_secret() القيمة "" (المصادقة معطلة).	config_store.py:52
KAZMA_DISCLOSURE_KEY	مفتاح HMAC للإفصاح؛ يُولَّد تلقائيًا إن لم يُضبط.	config_store.py:95
KAZMA_API_KEY	تراجع مفتاح LLM رقم 3.	llm_provider.py:142
KAZMA_MAX_COST	سقف قاطع التكلفة (الافتراضي $0.50).	cost_breaker.py:42
KAZMA_HARD_MAX_COST	سقف التكلفة الصلب للقطع الفوري (الافتراضي 3x الأقصى الناعم، $15.0).	cost_breaker.py:46
KAZMA_SILENCE_WINDOW	نافذة صمت قاطع التكلفة (الافتراضي 300 ث).	cost_breaker.py:44
KAZMA_SEMANTIC_CACHE	متقاعد في 2026-09-30 (أُزيلت خبيئة الردود الدلالية، تدقيق AUD-001)؛ ضبطها لا يفعل إلا تسجيل تحذير.	kazma_ui/app.py
KAZMA_FETCH_MAX_BYTES	حد بايتات الرد المتدفق لـ read_url (الافتراضي 5242880 / 5 MB).	tools/read_url.py
KAZMA_CRAWL_RESPECT_ROBOTS	الافتراضي 1: فرض فحوص KazmaBot المحدودة لحفظ الزحف والمعرفة والبحث الآلي. يظهر 0 الصريح؛ ويمنع فشل الفحص الزحف. القيمتان 0/1 فقط صالحتان.	web_acquire/robots.py
KAZMA_BROWSER_CGROUP_ROOT	Linux فقط: جذر cgroup v2 مفوّض مطلق وقابل للكتابة؛ افتراضيًا مجموعة الخدمة الحالية. يحتاج ضوابط الذاكرة وpids وCPU وقتل المجموعة. يُرفض العرض عند غيابها؛ والتفويض مسؤولية المشغّل.	web_acquire/browser_cgroup.py
KAZMA_OTLP_ENDPOINT	نقطة جامع تتبعات OTLP HTTP JSON.	swarm/tracing.py
KAZMA_TOOL_TIMEOUT_SECONDS	مهلة تنفيذ كل أداة بالثواني (الافتراضي 120).	agent/graph_builder.py
KAZMA_HUB_DB	مسار سجل SQLite للمركز.	hub/cli.py:109
KAZMA_HUB_URL	أساس API المركز (الافتراضي https://hub.kazma.ai).	hub/cli.py:115
KAZMA_PORT	تجاوز منفذ الخادم (الافتراضي 8000).	gateway.py:36
HF_HUB_DISABLE_SYMLINKS_WARNING / HF_HUB_DISABLE_TELEMETRY	إسكات قياسات HuggingFace (يضبطها CLI).	main.py:9-10

لا تُقرأ متغيرات بيئة مخصصة لكل مزوّد لـ DeepSeek/Anthropic/xAI/Groq/Gemini في kazma_core. اضبط مفاتيح هؤلاء المزوّدين عبر قائمة مزوّدي ConfigStore أو kazma.yaml.

---

4. مفاتيح API

يحلّ LLMProvider._resolve_api_key() (llm_provider.py:136-146) بهذا الترتيب:

1. self.config.api_key (من LLMConfig)
2. os.getenv("OPENAI_API_KEY")
3. os.getenv("KAZMA_API_KEY")
4. "not-needed" (لمحلي LM Studio/Ollama)

مفاتيح وهمية خاصة بالمزوّدين للخوادم المحلية (url_utils.py:138-172):

الخادم	المفتاح الوهمي
LM Studio (:1234)	sk-lm-studio-dummy-key
Ollama (:11434)	ollama
وكيل LiteLLM (:4000)	sk-litellm-dummy-key
localhost آخر	not-needed

يستخدم Google Vertex AI بيانات اعتماد التطبيق الافتراضية فقط — لا مفتاح API. يعيد GeminiProvider._resolve_api_key() القيمة "adc-placeholder" ويُجلب رمز الحامل الحقيقي عند كل استدعاء عبر google.auth.default() + credentials.refresh() (google_llm.py:232-252). تحليل المشروع: project_id= الصريح > GOOGLE_CLOUD_PROJECT > google.auth.default() > quota_project_id في ADC > config_default في gcloud.

تُخزَّن المفاتيح لكل مزوّد في ConfigStore ‏providers.list (لكل مدخل api_key وbase_url وmodels و…). تُرفض العناصر النائبة المقنّعة (***) عند الـ upsert إلا إن كان مفتاح حقيقي موجودًا بالفعل (model_registry.py:646-652)؛ وتُقنَّع المفاتيح في كل قراءات الإعادة (_mask_profile).

---

5. سجل النماذج

‏ModelRegistry (model_registry.py:81) مفرد على مستوى العملية (عام وحدة _registry، آمن للخيوط عبر threading.RLock()). كنية التوافق الخلفي: UnifiedModelRegistry (السطر 950).

5.1 دورة الحياة

الدالة	الغرض
initialize_model_registry(config_store)	بناء + إزالة تسلسل + بذر الإعدادات المسبقة.
get_model_registry()	استرجاع المفرد (يرفع RuntimeError إن لم يُهيَّأ).
reset_model_registry()	الفكّ.

5.2 الإعدادات المسبقة للمزوّدين المدمجين

من kazma-core/kazma_core/providers.py. تتحدث أغلب الإعدادات المسبقة صيغة OpenAI Chat Completions السلكية وتعمل عبر LLMProvider العام (مصادقة Bearer). أربعة مزوّدين لها أصناف أصلية مخصصة (انظر مزوّدو LLM) لأن مصادقتها/مخططها يختلف: google → GeminiProvider، وanthropic → AnthropicProvider (‏API /messages الأصلي)، وazure → AzureProvider (ترويسة api-key + api-version)، وbedrock → BedrockProvider (‏AWS SigV4 + Converse API).

المفتاح	اسم العرض	base_url	auth_header	صنف أصلي؟
openai	OpenAI	https://api.openai.com/v1	Bearer	لا
anthropic	Anthropic	https://api.anthropic.com/v1	x-api-key	نعم — AnthropicProvider
deepseek	DeepSeek	https://api.deepseek.com/v1	Bearer	لا
google	Google Gemini	(يُحسب لكل مشروع/موقع)	Bearer	نعم — GeminiProvider
xai	xAI / Grok	https://api.x.ai/v1	Bearer	لا
openrouter	OpenRouter	https://openrouter.ai/api/v1	Bearer	لا
groq	Groq	https://api.groq.com/openai/v1	Bearer	لا
mistral	Mistral AI	https://api.mistral.ai/v1	Bearer	لا
together	Together AI	https://api.together.xyz/v1	Bearer	لا
cohere	Cohere	https://api.cohere.ai/v1	Bearer	لا
fireworks	Fireworks AI	https://api.fireworks.ai/inference/v1	Bearer	لا
perplexity	Perplexity	https://api.perplexity.ai	Bearer	لا
ai21	AI21 Labs	https://api.ai21.com/studio/v1	Bearer	لا
nvidia	NVIDIA NIM	https://integrate.api.nvidia.com/v1	Bearer	لا
azure	Azure OpenAI	(يُحسب من المورد + النشر)	api-key	نعم — AzureProvider
bedrock	AWS Bedrock	(يُحسب من المنطقة)	Bearer (SigV4)	نعم — BedrockProvider
ollama	Ollama (محلي)	http://127.0.0.1:11434/v1	(بلا)	لا
lm-studio	LM Studio (محلي)	http://localhost:1234/v1	(بلا)	لا
custom	نقطة طرفية مخصصة	(فارغ)	Bearer	لا

‏GEMINI_MODELS المثبت في الكود (ليس لـ Vertex AI نقطة /models ساكنة): gemini-2.5-flash، وgemini-2.5-pro، وgemini-2.0-flash، وgemini-2.0-flash-lite.

المزوّد المفعّل افتراضيًا: google وحده enabled=True خارج الصندوق (model_registry_store.py:117). كل غيره يجب ضبطه قبل الاستخدام. custom مستثنى من بذر الإعدادات المسبقة.

5.3 اكتشاف النماذج

يضرب discover_models(provider_name) (model_registry.py:427) العنوان \{base_url\}\{models_endpoint\} (الافتراضي /models)، ويحلّل شكل OpenAI ‏\{"data":[\{"id":...\}]\}، مع حارس SSRF (kazma_core.security.ssrf.validate_url). تُخبَّأ النتائج في _discovered_models.

5.4 مفاتيح ConfigStore (السجل)

المفتاح	الغرض
providers.list	مصفوفة المزوّدين المخزنة.
providers.health.*	صحة كل مزوّد.
models.saved.*	ملفات النماذج المحفوظة.
models.defaults.*	افتراضيات لكل مهمة (chat، code، research، fast، vision، general). تفوز على ModelRouter.classify بالكلمات المفتاحية (مثلًا لا يمكن لـ "code" في توجيه تجاوز models.defaults.code). ومتغير البيئة KAZMA_MODEL يفوز دائمًا.
llm.model، llm.base_url، llm.api_key	تراجعات قديمة.
registry.active_provider، registry.active_model، registry.discovered_models	الاختيار النشط + الخبيئة.

---

6. مفاتيح retry

تقرأ أدوات إعادة المحاولة والتراجع التجاوزات من ConfigStore (retry.py):

المفتاح	الافتراضي	الوصف
retry.max_attempts	3	أقصى محاولات إعادة المحاولة.
retry.min_wait	2 (ث)	أدنى تراجع.
retry.max_wait	10 (ث)	أقصى تراجع.

تنطلق إعادة المحاولة فقط على استثناءات الشبكة/المهلة (ConnectionError، TimeoutError، asyncio.TimeoutError، وhttpx ‏TimeoutException/ConnectError/RemoteProtocolError). أخطاء 4xx لا يُعاد محاولتها أبدًا (retry.py:107-109). لا تراجع 429.

---

7. ملفات إعداد الأمان

7.1 kazma-permissions.yaml — للمكتبة فقط (لا يُفرض في زمن التشغيل)

الحالة: يصف PermissionManager + هذا YAML تصميم RBAC تقسيميًا مؤسسيًا غير مُفرَض على مسار تنفيذ الأدوات الحي. تفويض زمن التشغيل هو HITL + قائمة سماح الصدفة + تصنيف MCP + RBAC منصات اختياري (KAZMA_MULTI_USER). انظر docs/audits/UNWIRED_INVENTORY.md.

شكل مثال (للتوصيل المستقبلي / وثائق سياسة دون اتصال فقط):

divisions:
  gas_oil:
    allowed_mcp_servers: [oil-pricing-api, contract-manager, supplier-directory]
    denied_mcp_servers:  [tourism-booking-api, general-inventory-api]
  tourism:
    allowed_mcp_servers: [booking-engine, hotel-api, flight-search]
    denied_mcp_servers:  [oil-pricing-api, contract-manager]
  general_trading:
    allowed_mcp_servers: [inventory-api, supplier-directory, procurement-api]
    denied_mcp_servers:  [oil-pricing-api, booking-engine]

cross_division_rules:
  require_explicit_approval: true
  max_approval_duration_hours: 24
  notify_admins: true
  audit_all_access: true

7.2 kazma-security.yaml

القسم	خيارات المفاتيح
scanning	enabled، interval: "24h"، sources: [osv, github_advisories, nvd]، auto_create_issues، severity_threshold: medium، ignore.
disclosure	enabled، response_window: "48h"، assessment_window: "7d"، security_txt_url (ملف اتصال RFC 9116، ليس مفتاح PGP)، encrypted_channels (بريد + إبلاغ GitHub الخاص).
bug_bounty	enabled: false — لا برنامج مدفوع. حقول الدفع محفوظة/مصفَّرة؛ لا تعلن عن المستويات كنشطة. انظر SECURITY.md في الجذر.
hardening	run_on_startup، fail_on_critical، auto_fix: false، checks (8: secrets_in_logs، input_validation، rbac_enforcement، tls_required، dependency_audit، least_privilege، audit_trail، config_integrity).

لا يقرأ أي كود kazma-security.yaml (فُحص في 2026-09-27): يعلن برنامج الأمان (جهات اتصال الإفصاح، لا مكافآت مدفوعة) للبشر. مفتاحا scanning وhardening فيه لا يجدولان شيئًا؛ وتقرير التحصين ومسح الاعتماديات يعملان عند الطلب عبر GET /api/security/hardening وGET /api/security/deps. انظر الأمن والسلامة.

7.3 مفاتيح proxy.* (إضافة مزوّد وكيل الكشط)

اختياري. يُضبط عبر الإعدادات → النظام → مزوّد الوكيل (القيم أدناه تعيش في ConfigStore تحت proxy.*؛ وproxy.password يُشفَّر تلقائيًا في الخزنة). يُعاد قراءة المزوّد النشط حيًّا عند كل جلب — لا حاجة لإعادة تشغيل.

المفتاح	الافتراضي	الغرض
proxy.provider	none	none (مباشر) | anyip
proxy.host	portal.anyip.io	مضيف نقطة الوكيل الطرفية
proxy.port	1080	منفذ نقطة الوكيل الطرفية
proxy.username	(فارغ)	اسم مستخدم anyip (مثل user_YOURID)
proxy.password	(فارغ، خزنة)	كلمة سر anyip
proxy.network	mixed	residential | mobile | mixed
proxy.country	(فارغ)	رمز بلد ISO اختياري (مثل US)
proxy.session_sticky	false	true = نفس IP عبر الطلبات (ولوجات)؛ false = تدوير لكل طلب

انظر بحث الويب ← الكشط المدرَّع.

---

حفظ الإعدادات والتعافي من الانقطاع

يجب حفظ الإعدادات في قاعدة SQLite أو PostgreSQL المُهيّأة. إذا فشلت التهيئة، تتوقف كاظمه قبل تشغيل العمال أو الأتمتة؛ ولا تستبدلها بمخزن ذاكرة قابل للكتابة. يبقى الحارس المُدار مسؤولًا عن إعادة تشغيل الخادم حين يصبح التخزين متاحًا.

يعيد فشل كتابة الإعدادات بسبب التخزين HTTP 503 مع code: config_store_unavailable وRetry-After: 5. تعرض عناصر الحفظ الخطأ وتحتفظ بالقيم المُدخلة، ولا تعيد إرسال الكتابة تلقائيًا. قد يُفقد إقرار الحفظ بعد تثبيت الكتابة، لذا لا يثبت الخطأ أن قاعدة البيانات ألغتها. أعد التخزين إلى الخدمة، وأعد تحميل الإعدادات، وراجع ما حُفظ، ثم أعد فقط التغييرات اللازمة.

في PostgreSQL، تُغلق محاولات المجمّع الفاشلة وتُحدّ محاولات الاتصال؛ ولا تضاعفها حلقة تهيئة الإعدادات. لكل من استعارة اتصال مخطط الإقلاع وعباراته مهلة خمس ثوانٍ. تحتفظ الاستعلامات العادية بسياسة مهلها الحالية. وتحاول تهيئة SQLite أربع مرات كحد أقصى.

انظر فشل حفظ الإعدادات وإجراءات التعافي والتقييم للمشغّل.

تنبيهات البحث والزحف

تضبط الإعدادات → النظام → جلب الويب → قراءة إعدادات التنبيهات مراقب التقدم والنتائج المحلي. المراقبة وتنبيهات الاكتمال مفعّلان افتراضيًا؛ وتحذير انقطاع التقدم بعد 180 ثانية، وعتبة الرصيد الحديث المنخفض 100. تُحفظ الإعدادات في قاعدة الإعدادات الحالية. يتبع التسليم الخارجي المحوّلات والمسارات؛ ويحتفظ الجرس المحلي بالملاحظات مستقلًا عن التسليم الخارجي. راجع تنبيهات التقدم والنتائج للنتائج والاحتفاظ وإيصالات التسليم ونطاق الجلب المحلي أولًا.

التحكم	الافتراضي	القيمة المسموحة
تفعيل المراقبة	true	قيمة منطقية
إشعارات الاكتمال	true	قيمة منطقية
عتبة غياب تقدم مرصود	180 ثانية	عدد صحيح، 30–3600
عتبة الرصيد الحديث المنخفض	100	عدد صحيح، 0–1000000000

واجهة المسؤول هي GET/PUT /api/settings/acquisition/monitor. احفظ كائن الإعدادات كاملًا؛ وتعيد الحقول أو الأنواع غير الصالحة 422. يقرأ المراقب الأدلة المحلية كل 15 ثانية ولا يحدّث رصيد المزوّدين. تُضبط سياسة الجلب منفصلة عبر متغيرات البيئة الموثقة؛ ولا تمنح ضوابط التنبيه إذن خدمة مستضافة.

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

• انزياح الإصدارات: ‏pyproject.toml هو 0.3.0؛ وagent.version في kazma.yaml هو 0.2.0؛ ونص --help في CLI يطبع v0.2.0. هذه مستقلة وغير متزامنة — عيب معروف.
• أعلام الذاكرة تُقرأ عبر kazma_core.memory.config (ConfigStore ← yaml). انظر الذاكرة وRAG وdocs/plans/MEMORY_REMAINING.md.
• يعدد .env.example المتغيرين DEEPSEEK_API_KEY / ANTHROPIC_API_KEY لكن لا يقرؤهما كود — عُلِّما لمنع ارتباك المستخدمين.
• mcp.servers[].trust سلسلة YAML بسيطة بلا مستهلك مُفرِض — ليست طبقة ثقة تشفيرية.