المكتبة المعرفية

المكتبة المعرفية

المكتبة المعرفية (Knowledge Library) هي مجموعة مُسمّاة ومُدارة من الوثائق المستوعَبة — مثل توثيق Meta WhatsApp Cloud API. تشير كاظمة إلى جذر التوثيق مرة واحدة؛ تزحف الشجرة كاملة، تُقسّمها بمراعاة التسلسل الهرمي، تُضمّنها وتفهرسها. بعدها يستدل الوكيل على المحتوى ويذكر المصادر عند الإجابة.

هذا RAG (توليد معزّز بالاسترجاع) على مجموعة مُنسّقة وقابلة للتحديث — وليس كشطًا حيًا للويب، ولا ضبطًا دقيقًا للنموذج. محتوى الوثائق يعيش في مساحة أسماء خاصة بكل مكتبة، معزولة تمامًا عن ذاكرة الدردشة.

الاسم العربي للمنتج: Kazma / كاظمه (أو كاظمة). لا تُستخدم كازما.

متى تستخدمها

الهدف	ما تفعله
أن يعرف الوكيل واجهة API / مجموعة وثائق بعمق	استيعاب مرة، ثم اسأل — يذكر رابط المصدر + القسم
إجابات موثوقة بمصادر	كل نتيجة knowledge_search تحمل source_url + section_header
تحديث عند تغيّر الوثائق	إعادة استيعاب (تحديث)؛ الصفحات المتغيّرة فقط تُفهرس من جديد (dedup عبر content_hash)
وصول متعدد المنصات	نفس المكتبة تعمل من الويب، Telegram، Discord، Slack، وTUI

إن أردت أن يبحث الوكيل في الويب الحي لكل سؤال، انظر البحث على الويب — ميزة مختلفة (نتائج مؤقتة، بلا فهرس ثابت).

كيف يعمل الاستيعاب

عند إعطاء كاظمة رابط بذرة (مثل https://developers.facebook.com/docs/whatsapp/cloud-api):

1. الاكتشاف (sitemap أولًا). تقرأ robots.txt بحثًا عن Sitemap:، ثم تجرّب /sitemap.xml و/sitemap_index.xml و/docs/sitemap.xml. تُفلتر الروابط حسب بادئة مسار البذرة (/docs/whatsapp/overview → /docs/whatsapp/) فتبقى الزحف داخل شجرة التوثيق. الاحتياطي: سير BFS للروابط عبر HTML من Playwright (لالتقاط روابط SPA).
2. الجلب (متدرّج + واعٍ بالتبويبات). كل صفحة تُجلب عبر المستخرج المتدرّج (Jina → Firecrawl → httpx+trafilatura → Playwright). صفحات JS/التبويبات تحصل على مرور Playwright كامل يستخرج نص كل العناصر بما فيها المخفية.
3. التقسيم (واعٍ بالتسلسل). يُقسَّم Markdown عند عناوين #/##/###/#### مع مسار قسم ("Messages > Send Text Message"). كتل الكود المسيّجة ذرّية — لا تُقسَّم حتى لو كانت كبيرة.
4. التضمين والفهرسة. كل مقطع يُضمَّن (محليًا all-MiniLM-L6-v2 افتراضيًا، أو أي /embeddings متوافق مع OpenAI) ويُخزَّن في مجموعة ChromaDB لكل مكتبة + جدول FTS5 + SQLite (مصدر الحقيقة). إعادة الاستيعاب تُزيل التكرار عبر content_hash.

حدود الاكتشاف/الجلب: KAZMA_KB_MAX_PAGES (افتراضي 200، سقف 1000)، KAZMA_KB_MAX_DEPTH (10)، KAZMA_KB_DELAY_MS (300)، KAZMA_KB_SCOPE_MODE (tree | prefix | domain | exact، الافتراضي tree).

نظافة إعادة الاستيعاب: فهرسة رابط تمسح المقاطع السابقة لذلك الرابط أولًا (SQLite + FTS + Chroma) حتى لا تبقى أقسام يتيمة عند تقلّص الصفحة. مهام التحديث دائمة (نفس مخزن مهام ConfigStore الخاص بالزحف). أداة الوكيل knowledge_ingest_site محدودة (~15 صفحة) مقارنة بزحف الواجهة — استخدم /knowledge أو /kb crawl للأشجار الكبيرة.

الحقن التلقائي يشمل فقط المكتبات غير المؤرشفة للمستأجر الحالي (عند تفعيل فلتر المستأجر في الإنتاج).

البحث الذكي (اختياري): عيّن KAZMA_KB_SMART_SEARCH=1 (أو ConfigStore knowledge.smart_search=true) لاسترجاع المكتبات النشطة ذات المقاطع أيضًا عندما تبدو رسالة المستخدم تقنية (API/توثيق/كيفية)، حتى لو كان الحقن التلقائي لكل مكتبة متوقفًا. مفتاح الإيقاف KAZMA_KB_AUTO_INJECT=0 يعطّل كل الحقن.

الاستخدام

من واجهة الويب

افتح /knowledge → «إضافة مكتبة» → معرّف (مثل shipx_whatsapp_api) واسم ورابط البذرة → اختر:

• استيعاب صفحة واحدة — فوري، رابط واحد.
• 🕷️ زحف شجرة التوثيق كاملة — مهمة خلفية؛ راقب التقدّم (اكتشاف / جلب / استيعاب / فشل).

لكل مكتبة: 🔍 اختبار بحث، ↻ تحديث، 📋 استعراض المقاطع، 🗑 حذف.

من المحادثة (Telegram / Discord / Slack)

الأمر	الوظيفة
/kb	قائمة المكتبات + مساعدة
/kb add <id> <url>	إنشاء/استخدام مكتبة، استيعاب صفحة واحدة (متزامن)
/kb crawl <id> <url> [N]	استيعاب شجرة التوثيق كاملة (خلفية)
/kb refresh <id>	إعادة زحف من رابط البذرة
/kb search <id> <query>	بحث مباشر (مفيد بلا LLM أيضًا)
/kb status <id>	تقدّم حي لزحف/تحديث جارٍ
/kb delete <id>	حذف المكتبة وجميع مقاطعها

مثال:

/kb crawl shipx_whatsapp_api https://developers.facebook.com/docs/whatsapp/cloud-api
/kb status shipx_whatsapp_api

ثم اسأل بشكل طبيعي. يقرّر الوكيل متى يستشير المكتبة عبر أداة knowledge_search.

الحقن التلقائي (سلوك «يعرف مباشرة»)

افتراضيًا يستدعي الوكيل knowledge_search عندما يرى أن السؤال يحتاج سياق المكتبة. إن فضّلت طيّ المقاطع ذات الصلة في كل موجّه تلقائيًا، فعّل الحقن التلقائي على المكتبة (مربع في الواجهة، أو PATCH /api/kb/libraries/{id}).

عند التفعيل تُسترجع أعلى k مقاطع لآخر رسالة مستخدم وتُضاف إلى موجّه النظام — مسيّجة كبيانات غير موثوقة (<kazma:data source="knowledge" untrusted="true">) حتى لا تهرّب صفحة خبيثة تعليمات. ثلاث نقاط حقن (مماثلة لـ Soul في التحسين الذاتي، انظر الأمان والسلامة):

• agent_runner.py — تهيئة الوكيل (لا عملية؛ الحقن لكل دور)
• sse_chat.py — دردشة Web SSE، لكل دور
• gateway graph.py — Telegram/Discord/Slack، لكل دور

مفتاح الإيقاف: KAZMA_KB_AUTO_INJECT=0 يعطّل النظام وقت التشغيل (يُفحص حيًا لكل دور). الاشتراك لكل مكتبة ما زال مطلوبًا.

قابل للضبط: KAZMA_KB_AUTO_INJECT_TOP_K (افتراضي 3، أقصى 10).

تذييل الاقتباس

كل إجابة مبنية على بيانات المكتبة المعرفية تحمل تذييلًا ظاهرًا:

📚 This data is from Knowledge “shipx_whatsapp_api”.

ينطبق على مسار knowledge_search الصريح ومسار الحقن التلقائي. التذييل يسمّي المكتبة (أو المكتبات). توجيه لين على مستوى الموجّه — يُطلب من النموذج إلحاقه حرفيًا.

الأرشفة

يمكن أرشفة المكتبات — تُخفى من القائمة النشطة دون حذف المقاطع. مفيد للزحف الفاشل أو المتروك.

• زر 📦 أرشفة (عرض النشط).
• زر ♻️ استعادة (عرض المؤرشف).
• تبويبا نشط / مؤرشف.
• المكتبات المؤرشفة تبقى قابلة للبحث.
• الحذف منفصل ودائم؛ الأرشفة قابلة للعكس.

ملاحظات معمارية (للمساهمين)

الطبقة	الملف	الغرض
المخزن	kazma-core/kazma_core/stores/knowledge.py	SQLite knowledge_libraries + knowledge_chunks + FTS5
المقطّع	kazma-core/kazma_core/stores/knowledge_chunker.py	مقسّم عناوين+كود؛ بلا اعتماد LangChain
الفهرس	kazma-core/kazma_core/stores/knowledge_index.py	ChromaDB لكل مكتبة + FTS5 + RRF (k=60)
الاستيعاب	kazma-core/kazma_core/stores/knowledge_ingest.py	اكتشاف sitemap، جلب متدرّج، Playwright للتبويبات
الأداة	tool_registry.py → knowledge_search	قابلة لاستدعاء الوكيل؛ library فارغ → RRF عبر المكتبات
البوابة	commands.py → _try_kb_command	أوامر /kb على كل المنصات
Web API	kazma_ui/kb_api.py	/api/kb/*
صفحة الويب	knowledge_base.html + kb.js	/knowledge

لماذا مساحة أسماء منفصلة (وليس رسم معتقدات V2؟) ذاكرة الدردشة V2 (memory_state.db معتقدات/حلقات) تستخدم نموذج معتقدات ثنائي الزمن، لذا سيتسرب محتوى KB إلى استدعاء الدردشة ولا يطابق مخطط sha256(text)[:16] + الفلترة حسب metadata لكل مكتبة نموذج معتقدات V2. يعيد KB استخدام صنف VectorStore المشترك (memory/vector_store_global.py) وsingleton الـ get_embedder()، لكن في مجموعات ChromaDB مخصّصة لكل مكتبة (kazma_kb_<library_id>) — معزولة تمامًا عن ذاكرة الدردشة V2.

اعتماديات اختيارية

الاسترجاع المفهرس يحتاج extra rag (pip install kazma[rag])؛ جلب JS/التبويبات يحتاج web (pip install kazma[web] ثم playwright install chromium). بدونها: بحث FTS5 فقط، بلا تصيير صفحات JS.

حدود وتحفظات صادقة

• المواقع المحمية ضد الروبوتات تحتاج خلفية جلب. عيّن واحدًا من: KAZMA_FIRECRAWL_API_KEY، Jina Reader، أو Playwright. قائمة errors في تقدّم المهمة تسمّي الخلفية الناقصة.
• ثنائي Chromium منفصل عن حزمة Python: بعد pip install kazma[web] شغّل playwright install chromium.
• جزء صغير من مواقع SPA المُعمّاة قد يقاوم كل الطبقات؛ الصفحات الفاشلة تُبلَّغ في السجل.
• التضمينات المحلية مجانية وأبطأ على CPU؛ البعيدة أسرع/أفضل بتكلفة. انظر memory.embedding: في kazma.yaml.
• الزحف محدود بـ KAZMA_KB_MAX_PAGES (سقف 1000).
• معرّفات المكتبات تُحوَّل تلقائيًا إلى slug آمن لـ ChromaDB.
• سجلات المهام لكل عملية: زحف من الواجهة يُرى عبر /api/kb/jobs/{id} وليس بالضرورة عبر /kb status والعكس. رؤية عبر العمليات تحسين مستقبلي.