الأسئلة الشائعة
إجابات قصيرة على ما يسأله المشغّلون والمكاملون فعلًا.
هل كاظمه جاهزة للإنتاج؟
Section titled “هل كاظمه جاهزة للإنتاج؟”الوكيل الأساسي وتنسيق السرب وبوابات HITL والبوابات وذاكرة الدردشة (محرك V2 المعرفي — معتقدات ثنائية الزمن + استدعاء PPR لكل دور + auto-store) منفَّذة وموصولة. ثبّت pip install -e ".[rag]" للاسترجاع المتجهي الكامل. تعامَل مع طبقة الأمان بوصفها بمستوى الإنتاج؛ والذاكرة قابلة للاستخدام الإنتاجي على عقدة واحدة مع مراقبة الصحة (انظر الذاكرة وRAG).
ما لغة الواجهة افتراضيًا؟
Section titled “ما لغة الواجهة افتراضيًا؟”العربية، RTL (agent.language: ar، agent.rtl: true). عيّن en للإنجليزية. كوكي kazma-lang يبدّل لكل متصفح بلا إعادة تشغيل.
ماذا تعني «كاظمه»؟
Section titled “ماذا تعني «كاظمه»؟”Kazma باللاتينية؛ العلامة العربية كاظمه (مفضّلة) أو كاظمة. الإملاء كازما خطأ. بروتوكول المجلس (majlis.py) ينفّذ إيقاعات محادثة خليجية.
هل الصوت الحيّ على الويب مكالمة هاتفية (duplex)؟
Section titled “هل الصوت الحيّ على الويب مكالمة هاتفية (duplex)؟”زر Live يشغّل الصوت الحيّ على /ws/voice: نفس عقل LangGraph، ونفس خيط الدردشة/السجل كالرسائل المكتوبة، ويمكنك مقاطعته أثناء الكلام. ينطق الـ TTS الردَّ النهائي فقط، مقطعًا صوتيًا واحدًا لكل جملة. الدردشة المكتوبة على الويب لا تشغّل TTS تلقائيًا — اضغط 🔊 على الرسالة. مع ضبط LiveKit (LIVEKIT_URL + مفتاح/سر API) يحصل المتصفح أيضًا على إلغاء صدى WebRTC ويُنشر الـ TTS في الغرفة. تيليجرام/ديسكورد/سلاك تبقى ملاحظات صوتية (tts_reply بعد وارد صوتي فقط). انظر الصوت والوسائط. لا يُستخدم OpenAI Realtime / Gemini Live كعقل (ولا يُعتد بهما مرمّزات صوت). مفاتيح API تبقى في الإعدادات → المزوّدون؛ وWhisper يُختار في الإعدادات → الصوت، لا بوصفه نموذج الدردشة النشط.
هل "barcode" يختار نموذج البرمجة؟
Section titled “هل "barcode" يختار نموذج البرمجة؟”لا. التصنيف يستخدم حدود الكلمات. وmodels.defaults.code الصريح (الإعدادات → النماذج) يتقدم على التوجيه بالكلمات المفتاحية. وKAZMA_MODEL يتقدم على الاثنين.
هل يستطيع خادم MCP جعل كاظمه تنادي الـ LLM (sampling)؟
Section titled “هل يستطيع خادم MCP جعل كاظمه تنادي الـ LLM (sampling)؟”ليس تلقائيًا. مطفأ افتراضيًا (KAZMA_MCP_SAMPLING). عند التفعيل تحصل على بطاقة HITL لمرة واحدة؛ ونداء العيّنة بلا أدوات. قراءات الموارد مسيَّجة. انظر المهارات وMCP والأدوات.
هل يمكن تشغيل الوكيل دون خادم الويب؟
Section titled “هل يمكن تشغيل الوكيل دون خادم الويب؟”نعم. kazma ask "…" يشغّل مُشرف LangGraph داخل العملية (بلا uvicorn). وتيارات الـ tokens إلى stdout؛ وأسطر الأدوات إلى stderr. وعلى TTY تنبّه أدوات الخطر y/N. المدخلات المُمرَّرة عبر الأنبوب / kazma ask - تفشل مغلقًا ما لم تستخدم --yolo. تستضيف المحررات كاظمه عبر kazma acp (بروتوكول عميل الوكيل: session/update حيّ + session/request_permission). انظر البداية السريعة ومرجع CLI.
كيف أربط Gmail أو Microsoft؟
Section titled “كيف أربط Gmail أو Microsoft؟”انظر تكامل البريد. الـ sandbox يعمل بلا إعداد.
الإعدادات → البريد (/settings?tab=email) فيه مبدّل أوضاع لكل مزوّد: OAuth | IMAP | POP.
| المزوّد | المُوصى به | البدائل |
|---|---|---|
| Gmail | OAuth المتصفح (Gmail API) — عميل OAuth ويب من Google Cloud + مستخدم اختبار + نطاقات gmail.modify | IMAP/POP بكلمة مرور تطبيق Google (وليس كلمة مرورك المعتادة) |
| Microsoft 365 | OAuth المتصفح (Graph) أو الاحتياط برمز الجهاز (device-code) | IMAP/POP إلى outlook.office365.com إن كان المستأجر ما يزال يسمح بالمصادقة الأساسية |
أدوات التعديل (email_send وemail_delete وemail_categorize) تحتاج موافقة HITL. إن أعاد Gmail 403 insufficient scopes فأضف نطاقات Gmail على شاشة موافقة OAuth، وافصل الاتصال، ثم أعِده.
كيف تغرّد كاظمه على X؟
Section titled “كيف تغرّد كاظمه على X؟”عبر الـ API الرسمي لـ X فقط — ناشر X. أنشئ تطبيق Read + Write على developer.x.com، وضع مفاتيح OAuth 1.0a الأربعة في الإعدادات → X (لا في المحادثة). ألّف في استوديو X (/x): انشر الآن، جدوِل، أعد الجدولة، قفزات الخيط، احذف. نقرك في تلك الصفحة هو الموافقة. أدوات المحادثة (x_post، x_schedule_post، x_delete_post) ما تزال تحتاج بطاقة HITL (لا يمكن لـ YOLO تجاوزها). كل الجداول في الاستوديو يفتح /scheduled (cron + X معًا)؛ مخطِّط الاستوديو X فقط. مفتاح الإيقاف: KAZMA_X_POST=0.
الإشارات / الرد التلقائي منفصل: الرد التلقائي على X. ابدأ بوضع المسودة واضبط أهداف الموضوعات ومواقفها المحددة بالنطاق، ثم راجع المصادر والفحوص المصنفة في المحادثات. تُعلق التطابقات المتعددة أو المتعارضة والأدلة الناقصة؛ ولا يمنح وسم #Open الذي يكتبه غريب أي سلطة. تقيد الحقائق الموقف. يحتاج النشر دون إشراف إلى تقرير تأهيل ثنائي اللغة ساري المفعول ومراجع بشريًا؛ ويعطل KAZMA_X_REPLY=0 الردود.
كيف أجعل الوكيل يبحث في الويب؟
Section titled “كيف أجعل الوكيل يبحث في الويب؟”لا يوجد أمر /research. اسأل في الدردشة (مثل «Research X and cite sources») أو استخدم /swarm research … لتوزيع متعدد العمال. يستخدم الوكيل web_search، وread_url / read_url_to_file، وcrawl_site اختياريًا، وdigest_research_file. انظر البحث على الويب.
لماذا تُقتطع الصفحة الطويلة؟
Section titled “لماذا تُقتطع الصفحة الطويلة؟”read_url يعيد نافذة (افتراضي 16k، KAZMA_READ_URL_MAX_CHARS) مع offset / max_chars. للصفحة كاملة: read_url_to_file ثم digest_research_file أو read_research_chunk. تسمح نتائج الرسم لأدوات البحث بحد اقتطاع أعلى (KAZMA_TOOL_RESULT_RESEARCH_MAX_CHARS).
كيف أعالج ملفات PDF / مستندات Office بأمان؟
Section titled “كيف أعالج ملفات PDF / مستندات Office بأمان؟”استخدم ذكاء المستندات — لا مسار سكربت لمرة واحدة:
- الويب: افتح
/documents، وارفع، وانتظر الحالةready. - الوكيل:
document_import(مسار آمن ضمن مساحة العمل) →document_read/document_index. - بوابة الدردشة:
/documents list|read|…(الاسم البديل/docs).
يُستَنشق المحتوى، ويُحلَّل خارج العملية، ويُسيَّج تجاه الـ LLM، ويُخزَّن بعنوان محتوى. وتُرفض ملفات PDF التي فيها نصوص برمجية، أو إجراءات خارجية، أو مرفقات، أو روابط إلى ملفات ومشاركات شبكية. والعامل الافتراضي عملية فرعية لها حدود للذاكرة والمعالج لكن بلا حصر لنظام الملفات ولا للشبكة؛ فللمستندات التي لا تثق بها، شغّل ملف التعريف container (KAZMA_DOCUMENT_WORKER_ISOLATION=container: حاوية واحدة لكل مهمة، بلا شبكة، وبلا وحدات تخزين موصولة). انظر ذكاء المستندات وأمن المستندات.
ما الفرق بين generate_pdf وdocument_import؟
Section titled “ما الفرق بين generate_pdf وdocument_import؟”| المسار | المهارة / الـ API | التخزين |
|---|---|---|
| البسيط / القديم | أدوات document-generator (generate_pdf، …) | ملفات تحت kazma-data/documents/ — بلا مهام/ACL دائمة |
| المنصة | أدوات document-platform + /api/documents/* | معرّفات معتمة، ومهام، ومستأجرون، وخط أنابيب يصمد لإعادة التشغيل |
فضّل المنصة لأعمال المستندات متعددة المستخدمين أو الإنتاجية.
كيف أفهرس ملفًا مرفوعًا في مكتبة المعرفة؟
Section titled “كيف أفهرس ملفًا مرفوعًا في مكتبة المعرفة؟”بعد أن يصبح المستند ready: زر Index في الواجهة مع library_id، أو document_index / POST /api/documents/{id}/index. الفهرسة التلقائية معطّلة افتراضيًا. ابحث عبر document_search أو أدوات المكتبة. انظر مكتبة المعرفة — جسر المستندات.
لماذا يفشل التحويل / الحجب (redact)؟
Section titled “لماذا يفشل التحويل / الحجب (redact)؟”قد تنقص المحركات الاختيارية. ثبّت pip install -e ".[document-platform]" وتحقق من GET /api/documents/health (جهوزية العارضات/المعدِّلات). تعيد الـ API قيم 422/503 صادقة عند التدهور. وفي ملف تعريف العامل container تكون المحركات محركات صورة العامل لا المضيف: فحص الصحة يبلّغ عمّا في الصورة، والوسيط غير الجاهز يُجيب بالخطأ القابل لإعادة المحاولة worker_isolation_unavailable، ويُظهر GET /api/documents/ops/readiness القيمة document_worker_image_outdated حين تكون الصورة مبنية من شيفرة مستندات غير التي تشغّلها كاظمه (أعد بناءها وأعد تشغيل الوسيط).
كيف أفعّل فحص البرمجيات الخبيثة؟
Section titled “كيف أفعّل فحص البرمجيات الخبيثة؟”كاظمه لا تثبّت ClamAV عبر pip. تشغّل clamdscan عندما يكون ذلك البرنامج على PATH، وclamscan خلاف ذلك. الإعدادات → المستندات تضبط الوضع (auto أو on أو off) ومفتاح الفشل المغلق. تقرير الجهوزية يعرض malware.available.
مع KAZMA_PRODUCTION=1 يكون الفشل المغلق مفعّلًا. ماسحٌ مفقود، أو قاعدة بيانات فيروسات مفقودة، أو خطأ من الماسح — كلها ترفض الرفع. والمهمة المنتظرة في الطابور تُفحص مرة أخرى قبل تحليلها (بسياسة اليوم، لا بسياسة لحظة الرفع)؛ وحين يتعذّر تشغيل ذلك الفحص تُعلَّق المهمة وتُعاد محاولتها، ثم تذهب إلى الرسائل الميتة — ولا تُعلَّم أبدًا بأنها محتوى غير آمن.
Linux وDocker. الصورة تثبّت clamav وتشغّل freshclam. على مضيف مباشر، ثبّت حزمة ClamAV من التوزيعة وشغّل freshclam مرة واحدة ليحصل clamscan على التواقيع.
Windows.
winget install --id Cisco.ClamAV -e --accept-package-agreements --accept-source-agreementsيضع المثبّت clamscan.exe وclamdscan.exe في C:\Program Files\ClamAV ولا يضيف ذلك المجلد إلى PATH. لا تضف المجلد كاملًا إلى PATH إلا إذا كان clamd يعمل. تفضّل كاظمه clamdscan، وعميل البرنامج الخفي بلا برنامج خفي يعني فحصًا فاشلًا. الإنتاج عندها يرفض الرفع.
لاستخدام clamscan وحده:
- أنشئ مجلد
databaseيمكنك الكتابة فيه، وملفfreshclam.confبجانب نسخةclamscan.exeالتي ستضعها علىPATH. كتابة هذه تحتC:\Program Files\ClamAVتتطلب طرفية بصلاحيات مرتفعة؛ أما نسخة تحت%LOCALAPPDATA%\ClamAVفلا. - يجب ألا يحتوي
freshclam.confعلى سطرExampleالنموذجي. اضبطDatabaseMirror database.clamav.netوDatabaseDirectoryعلى مجلد قاعدة البيانات ذاك. - شغّل
freshclam.exe. ينزّلmain.cvdوdaily.cvdوbytecode.cvd. - ضع
clamscan.exeوملفات DLL من التثبيت علىPATH، مع قاعدة البيانات بجانب الملف التنفيذي (أو junction إليها). اتركclamdscan.exeخارجPATH.
يجب أن يطبع clamscan --no-summary على ملف نصي صغير كلمة OK. أعد تشغيل كاظمه من طرفية جديدة ليرث عملية الخادم PATH المحدّث. عندها تعرض الجهوزية malware.available بقيمة true وscanner بقيمة clamscan.
المزوّدون والنماذج
Section titled “المزوّدون والنماذج”أي مزوّدي LLM يعملون؟
Section titled “أي مزوّدي LLM يعملون؟”تُشحن عشرة إعدادات مسبقة: OpenAI، وAnthropic، وDeepSeek، وGoogle Gemini (ADC)، وxAI، وOpenRouter، وOllama، وLM Studio، وNVIDIA NIM، وCustom. وأي نقطة نهاية متوافقة مع OpenAI تعمل. انظر الإعدادات → الإعدادات المسبقة للمزوّدين.
هل أحتاج LiteLLM؟
Section titled “هل أحتاج LiteLLM؟”لا. كاظمه لا تنفّذ import litellm أبدًا. يكفي بروكسي اختياري: اضبط KAZMA_LITELLM_URL=http://127.0.0.1:4000 (أو llm.gateway.url). المزوّدون المتوافقون مع OpenAI فقط (OpenAI وDeepSeek وGroq وNIM و…) يمرّون عبره. أما Anthropic / Azure / Bedrock / Gemini فتبقى أصلية. والمحلي Ollama / LM Studio مباشر ما لم يُضبط KAZMA_LITELLM_LOCAL=1. مفتاح الإيقاف: KAZMA_LITELLM=0. ويمكنك كذلك توجيه base_url لمزوّد واحد نحو البروكسي.
لماذا لا يعمل DEEPSEEK_API_KEY / ANTHROPIC_API_KEY؟
Section titled “لماذا لا يعمل DEEPSEEK_API_KEY / ANTHROPIC_API_KEY؟”موجودة في .env.example لكن لا كود يقرأها. اضبط المفاتيح عبر ConfigStore أو kazma.yaml. فقط OPENAI_API_KEY وKAZMA_API_KEY احتياطات env عامة.
كيف أبدّل النماذج بأمان؟
Section titled “كيف أبدّل النماذج بأمان؟”استخدم set_active_model() (يبدّل المزوّد تلقائيًا) أو واجهة الويب / POST /api/provider/switch. لا تضبط نموذجًا بلا مزوّد أبدًا — يصحّح get_client() تلقائيًا، لكن الصريح أسلم.
كيف أستخدم نموذجًا محليًا؟
Section titled “كيف أستخدم نموذجًا محليًا؟”وجّه المزوّد إلى Ollama (http://127.0.0.1:11434/v1) أو LM Studio (http://localhost:1234/v1). لا حاجة إلى مفتاح API — تُحقن مفاتيح وهمية تلقائيًا.
الذاكرة وRAG
Section titled “الذاكرة وRAG”لماذا لا يتذكر وكيلي؟
Section titled “لماذا لا يتذكر وكيلي؟”افتراضيًا الذاكرة تلقائية:
- RAG لكل دور يحقن الحقائق السابقة ذات الصلة في كل رسالة مستخدم (
memory.per_turn_retrieval). - Auto-store يكتب حقائق المستخدم الدائمة (ولقطات الأدوار الاختيارية) بعد كل رد (
memory.auto_store). - يمكن لـ LLM أيضًا استدعاء أداتي
memory_store/memory_searchصراحة.
إن كان الاسترجاع فارغًا: ثبّت إضافة RAG (pip install -e ".[rag]")، وتأكد أن صحة الذاكرة في لوحة التحكم ACTIVE، وأن memory.enabled بقيمة true (إعدادات TUI أو kazma.yaml). انظر الذاكرة وRAG.
هل «الذاكرة بأربع طبقات» حقيقية؟
Section titled “هل «الذاكرة بأربع طبقات» حقيقية؟”كان ذلك مكدّس V1 (UnifiedMemoryAdapter: Chroma L1 + رسم L2 + FTS5 L3 + sqlite-vec L4، مدموج بـ RRF). أُزيلت V1 في التحوّل من V1 إلى V2. المكدّس الحالي والوحيد هو محرك V2 المعرفي — رسم معتقدات ثنائي الزمن + حلقات من 4 طبقات + استدعاء PPR بمخطط الأنانية المحلي (memory/recall.py:recall()). وهو افتراضي الدردشة للاستدعاء لكل دور، والأدوات، وauto-store، والضغط.
هل أحتاج ChromaDB؟
Section titled “هل أحتاج ChromaDB؟”استدعاء V2 على عقدة واحدة يعمل على sqlite-vec (مُضمَّن عبر الإضافة [rag])، وليس ChromaDB. وعند ضبط KAZMA_DATABASE_URL (أو state DSN للذاكرة) يختار البحث dense تلقائيًا pgvector (KAZMA_PGVECTOR=0 يبقي sqlite-vec). ثبّت pip install -e ".[rag]" للتضمين المحلي (sqlite-vec + sentence-transformers؛ لا يزال chromadb يُسحب لأنواع الـ embedder والـ semantic router). وبدون تضمينات تتدهوّر V2 إلى بحث حلقات FTS5 فقط؛ لوحة صحة الذاكرة تُظهر ما هو متاح.
لماذا يُذكر tiktoken دون اعتماد؟
Section titled “لماذا يُذكر tiktoken دون اعتماد؟”يستخدم TokenCounter مكتبة tiktoken إن كانت مثبتة، وإلا فتقدير chars/4. ثبّتها بنفسك (pip install tiktoken) للعدّ الدقيق.
الأمان وHITL
Section titled “الأمان وHITL”نُفِّذت أداة خطر بلا سؤال — لماذا؟
Section titled “نُفِّذت أداة خطر بلا سؤال — لماذا؟”ثلاثة أمور للتحقق (انظر استكشاف الأخطاء §3):
- هل مُرِّر
hitl_configإلى بناء رسمك؟ (البناءات المخصّصة عبرcreate_supervisor_graph()بدونه = بوابة نائمة.) - هل الأداة على قائمة الخطر الصحيحة؟ (ثلاث قوائم: yaml، و
_EXTENDED_DANGER، وclassify_mcp_tool.) - هل
allow_headless_danger=Trueمضبوط؟ (يجب أن يكونFalseفي الإنتاج.)
هل أحتاج KAZMA_SECRET؟
Section titled “هل أحتاج KAZMA_SECRET؟”نعم لأي نشر غير localhost. يحمي /api/approve. بدونه تكون نقاط نهاية الموافقة بلا مصادقة. ولا يربط kazma serve العنوان 0.0.0.0 إلا عند ضبطه.
هل المهارات موقّعة تشفيريًا؟
Section titled “هل المهارات موقّعة تشفيريًا؟”نعم. يكتب kazma hub sign توقيع HMAC-SHA256؛ ويتحقق منه المحمِّل بفشل مغلق عبر hmac.compare_digest. انظر المهارات وMCP والأدوات.
هل خوادم MCP مصادقة؟
Section titled “هل خوادم MCP مصادقة؟”SSE فقط (bearer/header). Stdio بلا مصادقة — اعزله.
كيف أشغّل مهمة متعددة العمال؟
Section titled “كيف أشغّل مهمة متعددة العمال؟”kazma swarm dispatch researcher "summarize X"kazma swarm fanout --workers a,b,c --aggregation vote "question"kazma swarm pipeline --workers researcher,builder "build Y"انظر مرجع CLI → السرب.
لماذا انكسرت حلقة التسليم؟
Section titled “لماذا انكسرت حلقة التسليم؟”التسليمات محدودة بعمق 5 وزيارتين لكل عامل (handoff_guards.py). التتابع A→B→A→B… محجوب قصدًا. أما تسليمات العودة المشروعة A→B→A فتعمل (زيارتان مسموحتان).
هل يوجد Prometheus؟
Section titled “هل يوجد Prometheus؟”لا. مقاييس في الذاكرة + SQLite. انظر خارطة الطريق.
Docker أم خادم عادي؟
Section titled “Docker أم خادم عادي؟”Docker Compose هو المسار الأساسي. kazma serve المجرّد يصلح للتطوير على مضيف واحد. انظر النشر.
هل أنشر على Cloudflare Pages / edge؟
Section titled “هل أنشر على Cloudflare Pages / edge؟”لا. كاظمه خدمة Python ذات حالة. لا تحاول التغليف بلا خادم.
هل يوجد بيان Kubernetes؟
Section titled “هل يوجد بيان Kubernetes؟”لا. ملفات kubernetes/ القديمة كانت تصف خدمة Hub منفصلة لم يبنِها هذا المستودع قط، وقد أُزيلت. النشر §4 يسرد ما يحتاجه بيان للوكيل الرئيسي.
لماذا الحاوية تربط 0.0.0.0؟
Section titled “لماذا الحاوية تربط 0.0.0.0؟”مطلوب داخل Docker كي يصل المنفذ المنشور إلى الخدمة. عزل شبكة Docker هو حدّ الأمان (كما تشرح تعليقات Dockerfile). على الخادم المباشر استخدم 127.0.0.1 + وكيلًا عكسيًا.
التزامن
Section titled “التزامن”«database is locked» — ماذا أفعل؟
Section titled “«database is locked» — ماذا أفعل؟”مفعّل في كل مكان WAL + busy_timeout=5000. غالبًا لديك معاملة كتابة طويلة أو اتصال ثانٍ. استخدم batch_set() لكتابات المفاتيح المتعددة، واستخدم get_config_store() دائمًا. انظر استكشاف الأخطاء §4.
هل أشغّل عدة عمليات كاظمه على نفس قاعدة البيانات؟
Section titled “هل أشغّل عدة عمليات كاظمه على نفس قاعدة البيانات؟”غير مُستحسن. WAL كاتب واحد. للتوسّع الأفقي: kazma-data/ لكل عملية أو تقسيم بالمستأجر.
ملاحظات تدقيق الوثائق
Section titled “ملاحظات تدقيق الوثائق”هذا FAQ يعكس السلوك المتحقَّق. إن تعارض مع README قديم، هذا FAQ هو الأدق اعتبارًا من v0.10.0+.