hkuds--deeptutor/assets/README/README_AR.md

 

DeepTutor: تدريس شخصي مدى الحياة

   

                   

الميزات · البدء · الاستكشاف · واجهة CLI · النظام البيئي · المجتمع

---

🤝 نرحب بجميع أنواع المساهمات! صوّت على عناصر خارطة الطريق أو اقترح عناصر جديدة في خارطة الطريق، وراجع دليل المساهمة لمعرفة استراتيجية الفروع ومعايير البرمجة وكيفية البدء.

📰 الأخبار

• 2026-05-22 🌐 موقع الوثائق الرسمي متاح على deeptutor.info — الأدلة والمراجع وجولات القدرات كلها في مكان واحد.
• 2026-04-19 🎉 20 ألف نجمة في 111 يومًا! شكراً على الدعم نحو تدريس شخصي وذكي حقيقي.
• 2026-04-10 📄 ورقتنا البحثية متاحة على arXiv — اقرأ النسخة الأولية للتعرف على التصميم والأفكار وراء DeepTutor.
• 2026-02-06 🚀 10 آلاف نجمة في 39 يومًا فقط! شكر جزيل لمجتمعنا الرائع.
• 2026-01-01 🎊 كل عام وأنتم بخير! انضم إلى Discord أو WeChat أو النقاشات — لنشكّل معاً مستقبل DeepTutor.
• 2025-12-29 🎓 تم إطلاق DeepTutor رسميًا!

✨ الميزات الرئيسية

DeepTutor هو بيئة تعلم أصيلة للوكلاء تربط التدريس وحل المشكلات وتوليد الاختبارات والبحث والتصور وممارسة الإتقان في نظام واحد قابل للتوسيع.

• بيئة تشغيل واحدة لجميع الأوضاع — Chat وQuiz وResearch وVisualize وSolve وMastery Path تعمل على نفس حلقة الوكيل، لذا تغيّر الهدف لا المحرك، والسياق يتبع المتعلم.
• سياق تعلم متصل — قواعد المعرفة والكتب ومسودات Co-Writer ودفاتر الملاحظات وبنوك الأسئلة والشخصيات والذاكرة متاحة في جميع سير العمل بدلاً من العيش في أدوات معزولة.
• الوكلاء الفرعيون والشركاء — استشارة Claude Code أو Codex أو Partner مباشرةً من أي دور (أو استيراد محادثاتهم السابقة)، وتشغيل رفاق IM دائمين على نفس الدماغ.
• معرفة متعددة المحركات — مكتبات RAG مُصدَّرة عبر LlamaIndex وPageIndex وGraphRAG وLightRAG أو مخزن Obsidian مرتبط، مع تحليل مستندات قابل للتوصيل.
• أدوات ومهارات قابلة للتوسيع — أدوات مدمجة وخوادم MCP ونماذج توليد الصور/الفيديو/الصوت ومهارات مجتمع قابلة للتثبيت من EduHub.
• ذاكرة قابلة للتدقيق — آثار L1 وملخصات سطحية L2 وتركيب L3 تجعل التخصيص مرئياً وقابلاً للتحرير، مع Memory Graph يتتبع كل ادعاء إلى دليله.

---

🚀 البدء

يأتي DeepTutor بأربعة مسارات تثبيت. وكلها تشترك في تخطيط مساحة عمل واحد: تعيش الإعدادات في data/user/settings/ تحت الدليل الذي تُطلق منه التطبيق (أو تحت DEEPTUTOR_HOME / deeptutor start --home إذا حددت واحداً صراحةً). للتطبيق الكامل، التدفق الموصى به هو اختر دليل مساحة عمل → تثبيت → deeptutor init → deeptutor start.

الخيار 1 — التثبيت من PyPI · تطبيق ويب محلي كامل + CLI، لا يلزم الاستنساخ

تطبيق ويب محلي كامل + CLI، لا يلزم الاستنساخ. يحتاج Python 3.11+ وبيئة تشغيل Node.js 20+ في PATH (يُشغَّل خادم Next.js المستقل المُحزَّم بواسطة deeptutor start).

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # يطلب المنافذ + مزود LLM + تضمين اختياري
deeptutor start    # يشغّل الخلفية + الواجهة الأمامية؛ ابقِ الطرفية مفتوحة

يطلب deeptutor init منفذ الخلفية (افتراضي 8001)، ومنفذ الواجهة الأمامية (افتراضي 3782)، ومزود LLM / عنوان URL الأساسي / مفتاح API / النموذج، ومزود تضمين اختياري لقاعدة المعرفة / RAG.

بعد deeptutor start، افتح عنوان URL للواجهة الأمامية المطبوع في الطرفية — افتراضياً http://127.0.0.1:3782. اضغط Ctrl+C في تلك الطرفية لإيقاف الخلفية والواجهة الأمامية معاً. تخطي deeptutor init لا بأس به للتجربة السريعة؛ يُقلع التطبيق بالمنافذ الافتراضية وإعدادات نموذج فارغة، قم بتهيئتها لاحقاً في الإعدادات ← النماذج.

الخيار 2 — التثبيت من المصدر · للتطوير مقابل نسخة مسحوبة

للتطوير مقابل نسخة مسحوبة. استخدم Python 3.11+ وNode.js 22 LTS لمطابقة CI وDocker.

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# إنشاء venv (macOS/Linux). Windows PowerShell:
#   py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1
python3 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip

# تثبيت تبعيات الخلفية والواجهة الأمامية
python -m pip install -e .
( cd web && npm ci --legacy-peer-deps )

deeptutor init
deeptutor start

تشغّل تثبيتات المصدر Next.js في وضع التطوير مقابل دليل web/ المحلي؛ كل شيء آخر (تخطيط التهيئة، المنافذ، الإيقاف بـ Ctrl+C) يطابق الخيار 1.

بيئة Conda (بديلاً عن venv)

conda create -n deeptutor python=3.11
conda activate deeptutor
python -m pip install --upgrade pip

إضافات التثبيت الاختيارية — dev / partners / matrix / math-animator

pip install -e ".[dev]"             # أدوات الاختبار/الفحص
pip install -e ".[partners]"        # SDK قنوات شركاء IM + عميل MCP
pip install -e ".[matrix]"          # قناة Matrix بدون E2EE/libolm
pip install -e ".[matrix-e2e]"      # Matrix E2EE؛ يتطلب libolm
pip install -e ".[math-animator]"   # إضافة Manim؛ تتطلب LaTeX/ffmpeg/مكتبات النظام

تعديلات تبعيات الواجهة الأمامية وحل مشاكل خادم التطوير

تغيير تبعيات الواجهة الأمامية: شغّل npm install --legacy-peer-deps لتحديث web/package-lock.json، ثم ارفع كلاً من web/package.json وweb/package-lock.json.

خادم تطوير متوقف: إذا أبلغ deeptutor start عن واجهة أمامية موجودة لا تستجيب، أوقف الـ PID الذي يطبعه. إذا لم يكن هناك أي عملية Next.js تعمل فعلياً، فملفات القفل قديمة — احذفها وأعد المحاولة:

rm -f web/.next/dev/lock web/.next/lock
deeptutor start

الخيار 3 — Docker · حاوية واحدة مكتفية بذاتها

حاوية واحدة لتطبيق الويب الكامل. الصور على GitHub Container Registry:

• ghcr.io/hkuds/deeptutor:latest — إصدار مستقر
• ghcr.io/hkuds/deeptutor:pre — إصدار تجريبي، عند توفره

راجع CONTAINERIZATION.md لعمليات نشر podman/rootless/read-only-rootfs والدليل الكامل لكل تثبيت.

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

يكفي نشر 3782 فقط. يتحدث المتصفح حصرياً إلى أصل الواجهة الأمامية؛ يقوم وسيط Next.js (web/proxy.ts) بإعادة توجيه /api/* و/ws/* إلى خلفية FastAPI داخل الحاوية. نشر 8001 (-p 127.0.0.1:8001:8001) اختياري — مفيد فقط لاستدعاء واجهة برمجة التطبيقات مباشرةً باستخدام curl أو نصوص.

افتح http://127.0.0.1:3782. تُنشئ الحاوية /app/data/user/settings/*.json عند الإقلاع الأول؛ قم بتهيئة مزودي النماذج من صفحة إعدادات الويب. تبقى التهيئة ومفاتيح API والسجلات وملفات مساحة العمل والذاكرة وقواعد المعرفة في وحدة تخزين deeptutor-data.

• منافذ مضيف مختلفة: غيّر الجانب الأيسر من كل تعيين -p host:container (مثلاً -p 127.0.0.1:8088:3782). إذا غيّرت المنافذ على جانب الحاوية في /app/data/user/settings/system.json، أعد التشغيل وحدّث الجانب الأيمن من كل تعيين ليطابق ذلك.
• وضع المنفصل: أضف -d، ثم docker logs -f deeptutor للمتابعة، وdocker stop deeptutor للإيقاف، وdocker rm deeptutor قبل إعادة استخدام الاسم. تحتفظ وحدة تخزين deeptutor-data بإعداداتك ومساحة عملك عبر إعادات التشغيل.

Docker عن بُعد / وكيل عكسي: يتحدث المتصفح فقط إلى أصل الواجهة الأمامية (:3782)؛ يقوم وسيط Next.js داخل الحاوية بإعادة توجيه /api/* و/ws/* إلى خادم الخلفية من جانب الخادم. في حالة الحاوية الواحدة الشائعة لا تهيّئ قاعدة API على الإطلاق — فقط وجّه وكيلك العكسي / منهي TLS إلى :3782. تحتاج قاعدة API فقط لـ النشر المنفصل (الخلفية في حاوية/مضيف منفصل): اضبط next_public_api_base في data/user/settings/system.json على عنوان الشبكة الداخلية الذي يستخدمه خادم الواجهة الأمامية للوصول إلى الخلفية (يُقرأ من جانب الخادم، ولا يُرسَل أبداً إلى المتصفح).

{
  "next_public_api_base": "http://backend:8001"
}

يُقبَل next_public_api_base_external (واسمه المستعار public_api_base) كبدائل ذات أولوية أقل. يستخدم CORS منشآت الواجهة الأمامية، وليس عناوين URL لواجهة برمجة التطبيقات. مع تعطيل المصادقة، يسمح DeepTutor بمنشآت متصفح HTTP/HTTPS العادية افتراضياً. مع تفعيل المصادقة، أضف منشآت الواجهة الأمامية الدقيقة:

{
  "cors_origins": ["https://deeptutor.example.com"]
}

الاتصال بـ Ollama / LM Studio / llama.cpp / vLLM / Lemonade على المضيف

داخل Docker، يشير localhost إلى الحاوية نفسها، وليس جهازك المضيف. للوصول إلى خدمة نموذج تعمل على المضيف، استخدم بوابة المضيف (موصى بها):

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 -p 127.0.0.1:8001:8001 \
  --add-host=host.docker.internal:host-gateway \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

ثم في الإعدادات ← النماذج، وجّه عنوان URL الأساسي للمزود إلى host.docker.internal:

• Ollama LLM: http://host.docker.internal:11434/v1
• Ollama embedding: http://host.docker.internal:11434/api/embed
• LM Studio: http://host.docker.internal:1234/v1
• llama.cpp: http://host.docker.internal:8080/v1
• Lemonade: http://host.docker.internal:13305/api/v1

عادةً ما يحل Docker Desktop (macOS/Windows) host.docker.internal بدون --add-host. على Linux، يُعدّ هذا العلم الطريقة المحمولة لإنشاء هذا الاسم المضيف على Docker Engine الحديث.

بديل Linux — شبكة المضيف: أضف --network=host وأزل علامات -p. تشارك الحاوية شبكة المضيف مباشرةً، لذا افتح http://127.0.0.1:3782 (أو frontend_port في system.json)، ويمكن الوصول إلى خدمات المضيف بعناوين URL العادية لـ localhost مثل http://127.0.0.1:11434/v1. لاحظ أن شبكة المضيف تكشف منافذ الحاوية مباشرةً على المضيف وقد تتعارض مع الخدمات الموجودة — للإبقاء عليها على loopback، اضبط BACKEND_HOST=127.0.0.1 وFRONTEND_HOST=127.0.0.1 (راجع CONTAINERIZATION.md).

الخيار 4 — واجهة سطر الأوامر فقط · بدون واجهة ويب، من نسخة مسحوبة

عندما لا تحتاج إلى واجهة مستخدم الويب. يُثبَّت حزمة CLI فقط من نسخة مسحوبة من المصدر، وليس من PyPI.

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# إنشاء venv (macOS/Linux). Windows PowerShell:
#   py -3.11 -m venv .venv-cli ; .\.venv-cli\Scripts\Activate.ps1
python3 -m venv .venv-cli && source .venv-cli/bin/activate
python -m pip install --upgrade pip

python -m pip install -e ./packaging/deeptutor-cli
deeptutor init --cli
deeptutor chat

يشارك deeptutor init --cli نفس تخطيط data/user/settings/ مع التطبيق الكامل لكنه يتخطى موجهات منفذ الخلفية/الواجهة الأمامية ويضبط التضمينات افتراضياً على إيقاف (اختر نعم إذا كنت تخطط لاستخدام deeptutor kb … أو أدوات RAG). لا يزال يكتب تخطيط وقت تشغيل كامل (system.json، auth.json، integrations.json، model_catalog.json، main.yaml، agents.yaml) ولا يزال يطلب مزود LLM النشط والنموذج.

الأوامر الشائعة

deeptutor chat                                          # REPL تفاعلي
deeptutor chat --capability deep_solve --tool rag --kb my-kb
deeptutor run chat "Explain Fourier transform"
deeptutor run deep_solve "Solve x^2 = 4" --tool rag --kb my-kb
deeptutor kb create my-kb --doc textbook.pdf
deeptutor memory show
deeptutor config show

لا يشحن تثبيت deeptutor-cli المحلي بأصول الويب أو تبعيات الخادم. احتفظ بالنسخة المسحوبة من المصدر — يشير التثبيت القابل للتحرير إليها. لإضافة تطبيق الويب لاحقاً، ثبّت حزمة PyPI (الخيار 1) وشغّل deeptutor init + deeptutor start من نفس مساحة العمل.

صندوق أمان تنفيذ الرمز (مهارات المكتب) · تشغيل الرمز المُولَّد بالنموذج لـ docx / pdf / pptx / xlsx

مهارات المكتب المدمجة — docx / pdf / pptx / xlsx — تعمل عن طريق جعل النموذج يكتب برنامج Python قصير (python-docx، reportlab، openpyxl، ...)، وتشغيله عبر أدوات exec / code_execution، وإرجاع عنوان URL للتنزيل. تُثبَّت هذه الأدوات عندما تكون خلفية صندوق الأمان نشطة، وهي كذلك افتراضياً في كل شكل نشر:

• محلي (الخيار 1 / 2) وDocker (الخيار 3، حاوية واحدة): يُشغَّل صندوق أمان عمليات فرعية مقيّدة لرمز النموذج (على المضيف محلياً، أو داخل الحاوية تحت Docker — والحاوية هي حدود عزلها الخاصة).
• docker-compose: يُوجَّه بدلاً من ذلك إلى مرافق runner محصَّن وأقل امتيازاً (Dockerfile.runner) عبر DEEPTUTOR_SANDBOX_RUNNER_URL — أقوى وضع، ويُفضَّل تلقائياً عند توفره.

يتحكم إعداد sandbox_allow_subprocess في data/user/settings/system.json (افتراضي true) في صندوق أمان العمليات الفرعية. تشغيل الرمز المُولَّد بواسطة النموذج على مضيفك هو قرار ثقة حقيقي — اضبطه على false (أو صدّر DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0) لتعطيل التنفيذ على جانب المضيف، على حساب عدم قدرة مهارات المكتب على إنتاج الملفات بعد الآن.

مرجع التهيئة — ملفات التهيئة تحت data/user/settings/ (JSON/YAML)

كل شيء تحت data/user/settings/ هو JSON/YAML عادي. صفحة الإعدادات في المتصفح هي المحرر الموصى به.

الملف	الغرض
model_catalog.json	ملفات تعريف مزودي النماذج اللغوية الكبيرة والتضمين والبحث؛ مفاتيح API؛ النماذج النشطة
system.json	منافذ الخلفية/الواجهة الأمامية، وقاعدة API العامة، وCORS، والتحقق من SSL، ودليل المرفقات
auth.json	تبديل مصادقة اختياري، واسم مستخدم، وتجزئة كلمة مرور، وإعدادات الرمز/الكوكي
integrations.json	إعدادات تكامل PocketBase والمرافق الاختيارية
interface.json	تفضيلات لغة واجهة المستخدم / الثيمة / الشريط الجانبي
main.yaml	افتراضيات سلوك وقت التشغيل وحقن المسار
agents.yaml	إعدادات درجة حرارة القدرة/الأداة والرمز

ملف .env في جذر المشروع لا يُقرأ كملف تهيئة للتطبيق. للإعداد الأدنى للنموذج، افتح الإعدادات ← النماذج، أضف ملف تعريف LLM (عنوان URL الأساسي / مفتاح API / اسم النموذج)، واحفظ. أضف ملف تعريف التضمين فقط إذا كنت تخطط لاستخدام ميزات قاعدة المعرفة / RAG.

📖 استكشاف DeepTutor

ابدأ بالأسطح الرئيسية التي ستستخدمها يومياً: Chat وPartners وMy Agents وCo-Writer وBook ومركز المعرفة وفضاء التعلم والذاكرة والإعدادات. ثم تغطي الجولة عمليات النشر متعددة المستخدمين لمساحات العمل المشتركة المعزولة.

🏗️ معمارية النظام

💬 Chat — حلقة الوكيل التي تستخدمها فعلاً

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

الحلقة بسيطة عمداً: يفكر النموذج في جولات، ويستدعي الأدوات عند الحاجة، ويلاحظ النتائج، وينتهي برسالة خالية من الأدوات. ask_user خاص — بدلاً من التخمين، يمكن للوكيل إيقاف الدور مؤقتاً، وطرح سؤال توضيحي منظَّم، والاستئناف بمجرد إجابتك.

الأدوات القابلة للتبديل من قِبَل المستخدم هي brainstorm وweb_search وpaper_search وreason وgeogebra_analysis — بالإضافة إلى imagegen وvideogen بمجرد تهيئة نموذج التوليد المطابق. الأدوات السياقية مثل rag وread_source وread_memory وwrite_memory وread_skill وload_tools وexec وweb_fetch وask_user وlist_notebook وwrite_note وgithub وconsult_subagent تُثبَّت تلقائياً عندما يكون للدور السياق الصحيح.

يأتي السياق في نوعين: السياق اللاصق للجلسة (الوكيل الفرعي وقواعد المعرفة والشخصية والنموذج والصوت) يعيش على شريط أدوات المؤلف ويستمر عبر الأدوار؛ المراجع لمرة واحدة (الملفات وتاريخ المحادثة والكتب ودفاتر الملاحظات وبنك الأسئلة والوكلاء المستوردون) تأتي من قائمة + لدور واحد.

Chat هي أيضاً نقطة انطلاق للقدرات الأعمق: Quiz لتوليد الأسئلة، وResearch للتقارير المستشهَد بها، وVisualize للمخططات / الرسوم البيانية / الرسوم المتحركة، وتحت المزيد من القدرات — Solve للتفكير المعمق وMastery Path لتدفقات خطط التعلم.

🤝 Partner — رفاق دائمون على نفس الدماغ

الشركاء هم رفاق دائمون بروحهم الخاصة وسياسة النموذج ومكتبتهم وذاكرتهم وقنواتهم. إنهم ليسوا محرك بوت منفصلاً: كل رسالة ويب أو IM واردة تصبح دوراً عادياً لـ ChatOrchestrator داخل مساحة عمل محدودة بنطاق الشريك. الشريك هو "محادثة لها شخصية ورقم هاتف".

لكل شريك SOUL.md واختيار نموذج وقنوات وسياسة أدوات ومكتبة مخصصة. تُنسخ قواعد المعرفة والمهارات ودفاتر الملاحظات إلى data/partners/<id>/workspace/، لذا تعمل نفس أدوات RAG والمهارة ودفتر الملاحظات والذاكرة بدون حالات خاصة. يقرأ الشريك ذاكرة مالكه لكنه يكتب فقط في ذاكرته الخاصة.

طبقة القناة مدفوعة بالمخطط ويمكنها الاتصال بمنصات IM مثل Feishu وTelegram وSlack وDiscord وDingTalk وQQ/NapCat وWeCom وWhatsApp وZulip وMattermost وMatrix وMochat وMicrosoft Teams بناءً على الإضافات المثبتة والبيانات الاعتمادية المهيأة. يمكن أيضاً توصيل الشريك كوكيل فرعي واستشارته من دور محادثة عادي — راجع My Agents أدناه.

🧑‍🚀 My Agents — استشارة واستيراد الوكلاء الآخرين

يحوّل My Agents الوكلاء الآخرين إلى سياق لـ DeepTutor، ويقوم بشيئين متمايزين. توصيل وكيل مباشر — Claude Code أو Codex CLI على جهازك، أو أحد شركائك — واستشارته من داخل دور محادثة: DeepTutor يشغّل الوكيل الآخر فعلاً ويبث عمله إلى لوحة Activity عبر أداة consult_subagent. اختره بشريحة الوكيل (أو اكتب @)، وحدد عدد الجولات التي يمكن للاستشارة أن تأخذها.

استيراد المحادثات السابقة — أحضر تاريخ Claude Code وCodex الموجود لديك كوكلاء مسماة قابلة للبحث والاستئناف. اختر الأيام التي تريد استيرادها؛ التحديث يعيد مزامنتها. استشر محادثة مستوردة من أي دور محادثة عبر + ← My Agents، وسيقرأها DeepTutor كنصوص محادثة لطرف ثالث — تبقى محادثتهم، وليس صوت DeepTutor الخاص.

✍️ Co-Writer — صياغة Markdown واعية بالتحديد

Co-Writer هو مساحة عمل Markdown ذات عرض مقسَّم للتقارير والدروس التعليمية والملاحظات والقطع التعليمية الطويلة. تحفظ المستندات تلقائياً وتُظهر معاينة مباشرة (رياضيات KaTeX وأسوار الرسم البياني)، ويمكن حفظها مرة أخرى في دفاتر الملاحظات عندما تصبح المسودة سياقاً قابلاً لإعادة الاستخدام.

الفكرة المحورية هي التحرير الجراحي: حدد نطاقاً واطلب من DeepTutor إعادة كتابته أو توسيعه أو تقصيره. يمكن لوكيل التحرير ترسيخ التغيير في قاعدة معرفة أو دليل ويب، ويحتفظ بآثار استدعاءات أدواته، ويعرض كل تغيير كـ diff قبول/رفض — لذا لا شيء يُقبَل حتى توافق عليه.

📖 Book — كتب حية من موادك

يحوّل Book المصادر المحددة إلى كتاب حي تفاعلي — ليس PDF ثابتاً، بل بيئة قراءة مبنية من كتل مكتوبة. يمكن أن يبدأ الكتاب من قواعد المعرفة أو دفاتر الملاحظات أو بنوك الأسئلة أو تاريخ المحادثة؛ يقترح تدفق الإنشاء هيكل فصل قبل توليد المحتوى، لذا تراجع الشكل بدلاً من قبول مخرجات عشوائية.

   

يُجمِّع كل فصل إلى كتل مكتوبة — نصوص وأقسام وتنبيهات واختبارات وبطاقات فلاش وجداول زمنية ورمز وأشكال وHTML تفاعلية ورسوم متحركة وأشكال مفاهيم وغوص عميق وملاحظات مستخدم — وكل صفحة لها Page Chat الخاصة بها. الكتل قابلة للتحرير: أدرج أو حرّك أو أعد التوليد أو غيّر نوع الكتلة بدون إعادة كتابة الفصل. أوامر الصيانة مثل deeptutor book health وdeeptutor book refresh-fingerprints تساعد في الكشف عن انجراف معرفة المصدر من الصفحات المُجمَّعة.

📚 مركز المعرفة — مكتبات RAG متعددة المحركات

قواعد المعرفة هي مجموعات المستندات وراء RAG — إنها ترسّخ أدوار Chat وتحرير Co-Writer وتوليد Book ومحادثات Partner. ما يميزها هو اختيار محرك الاسترجاع: LlamaIndex (الافتراضي، ناقل محلي + BM25)، PageIndex (مستضاف، استرجاع تفكيري مع استشهادات على مستوى الصفحة)، GraphRAG وLightRAG (استرجاع قائم على الرسم البياني المعرفي)، LightRAG Server (استرجاع مُحال إلى نسخة LightRAG خارجية تتصل بها عبر HTTP)، أو مخزن Obsidian مرتبط يقرأ المدرس ويكتب فيه في مكانه. كل قاعدة معرفة مرتبطة بمحرك واحد.

عند إنشاء قاعدة معرفة، إما أن تنشئ جديدة (تحميل مستندات وبناء فهرس جديد) أو تربط موجودة (إعادة استخدام فهرس مبني في مكان آخر، قراءة في مكانه بدون إعادة فهرسة). تكتب إعادة الفهرسة دليل version-N مسطحاً جديداً وتحتفظ بالسابقة، لذا لا يُدمَّر فهرس عامل أبداً أثناء إعادة البناء. يمكن إزالة مستند واحد حتى من قاعدة في حالة خطأ — إسقاط ملف فشل تحليله بدون حذف وإعادة بناء كاملين. تحليل المستندات — نص فقط أو MinerU أو Docling أو markitdown أو PyMuPDF4LLM — يُختار في الإعدادات ← قاعدة المعرفة، مع إيقاف تنزيلات النماذج المحلية افتراضياً. تعكس واجهة CLI دورة الحياة مع deeptutor kb list وinfo وcreate وadd وsearch وset-default وdelete.

🌐 فضاء التعلم — المهارات والشخصيات والسياق القابل لإعادة الاستخدام

فضاء التعلم هو طبقة المكتبة والتخصيص — حيث تعيش الأشياء التي تستمر. المحادثات والمواد تحتفظ بتاريخ المحادثة ودفاتر الملاحظات وبنك الأسئلة (كل سؤال محفوظ يحتفظ بإجابتك والإجابة المرجعية وشرحاً). التخصيص يحتفظ بمسارات الإتقان والشخصيات (إعدادات السلوك المسبقة مثل زميل ومساعد بحثي ومعلم) والمهارات (دليل SKILL.md يقرأه النموذج عند الطلب). كل شيء هنا يمكن إعادة استخدامه من Chat وPartners وCo-Writer وBook.

لا يجب عليك كتابة كل مهارة بنفسك — الاستيراد من EduHub يتصفح الكتالوج المجتمعي ويُنزّل المهارة مباشرةً إلى مكتبتك من خلال بوابة أمان (راجع النظام البيئي).

🧠 Memory — تخصيص قابل للتدقيق

الذاكرة نظام ثلاثي الطبقات مدعوم بالملفات يمكنك قراءته وتنظيمه ومراجعته — وهو عمداً ليس مخزناً ناقلاً مخفياً. L1 هو مرآة مساحة العمل بالإضافة إلى آثار أحداث تراكمية فقط (trace/<surface>/<date>.jsonl)؛ L2 هو حقائق منظَّمة لكل سطح (L2/<surface>.md)؛ L3 هو تركيب عبر الأسطح (L3/<profile|recent|scope|preferences>.md). لأن L2 يستشهد بـ L1 وL3 يستشهد بـ L2، لا شيء في ملفك الشخصي غير مسؤول.

يُظهر Memory Graph الهرم بأكمله — تركيب L3 في المركز وL2 في الحلقة الوسطى وآثار L1 في الخارج — لذا يمكنك تتبع أي ادعاء مُوليَّف إلى الحدث الخام الدقيق خلفه. يُتتبع الذاكرة عبر أسطح chat وnotebook وquiz وkb وbook والشريك وcowriter؛ ميزانيات تحديث الموحّد / تدقيقه / إلغاء تكراره تُضبط في الإعدادات ← الذاكرة.

⚙️ الإعدادات — لوحة تحكم واحدة

الإعدادات هي لوحة التحكم التشغيلية، مع شريط حالة مباشر (الخلفية وLLM والتضمين والبحث) وبطاقة واحدة لكل منطقة: المظهر (الثيمة + لغة واجهة المستخدم)، الشبكة (قاعدة API والمنافذ وCORS)، النماذج (LLM والتضمين والبحث وتحويل النص إلى كلام وتحويل الكلام إلى نص وتوليد الصور وتوليد الفيديو)، قاعدة المعرفة (محرك تحليل المستندات)، Chat (الأدوات وخوادم MCP والمعاملات لكل قدرة)، الشركاء والوكلاء (الوكلاء الفرعيون الذين يمكنك استشارتهم من دور)، والذاكرة (ميزانيات الموحّد).

تستخدم معظم الأقسام تدفق صياغة-وتطبيق، لذا يمكنك اختبار مزود قبل الالتزام به. تشحن أربع ثيمات في الصندوق — Default وCream وDark وGlass. ملفات .env في جذر المشروع تُتجاهل عمداً؛ يعيش تهيئة وقت التشغيل تحت data/user/settings/*.json إلا إذا وجّه DEEPTUTOR_HOME أو deeptutor start --home التطبيق في مكان آخر.

👥 متعدد المستخدمين — النشر المشترك · مصادقة اختيارية، مساحات عمل معزولة لكل مستخدم

المصادقة معطلة افتراضياً — يعمل DeepTutor لمستخدم واحد. فعّلها وشجرة data/ واحدة تستضيف مساحة عمل المشرف ومساحات عمل معزولة لكل مستخدم ومساحات عمل الشريك جنباً إلى جنب:

data/
├── user/                    # مساحة عمل المشرف + الإعدادات العامة
├── users/<uid>/             # نطاق المستخدم: تاريخ المحادثة والذاكرة ودفاتر الملاحظات وقواعد المعرفة
├── partners/<id>/workspace/ # نطاق المستخدم الاصطناعي (الشريك)
└── system/                  # auth/users.json · grants/<uid>.json · audit/usage.jsonl

أول مستخدم مسجَّل يصبح مشرفاً ويمتلك كتالوجات النماذج وبيانات اعتماد المزود وقواعد المعرفة المشتركة والمهارات والمنح لكل مستخدم. يحصل الجميع الآخرون على مساحة عمل معزولة وصفحة إعدادات منقوصة — تظهر النماذج وقواعد المعرفة والمهارات المعيّنة من المشرف كخيارات محدودة النطاق وللقراءة فقط، وليس كمفاتيح API خام.

تفعيله: فعّل المصادقة في data/user/settings/auth.json، وأعد تشغيل deeptutor start، وسجّل أول مشرف على /register، ثم أضف المستخدمين من /admin/users وعيّن النماذج وقواعد المعرفة والمهارات والـ Partners وسياسة الأداة/MCP ووصول تنفيذ الرمز من خلال المنح.

يبقى PocketBase تكاملاً لمستخدم واحد — أبقِ integrations.pocketbase_url فارغاً لعمليات النشر متعددة المستخدمين إلا إذا وصلت مخزن مستخدم خارجي.

⌨️ واجهة سطر أوامر DeepTutor — الواجهة الأصيلة للوكلاء

ثنائي deeptutor واحد، طريقتان للدخول: REPL تفاعلي للأشخاص الذين يعيشون في الطرفية، وJSON منظَّم للوكلاء الأخرى التي تقود DeepTutor كأداة. نفس القدرات والأدوات وقواعد المعرفة في كلتا الحالتين.

قدّها بنفسك

deeptutor chat يفتح REPL تفاعلياً؛ deeptutor run <capability> "<message>" يُشغّل دوراً واحداً ويخرج. يتحدث كلاهما بنفس علامات --capability و--tool و--kb و--config.

deeptutor chat                                              # REPL تفاعلي
deeptutor chat --capability deep_solve --kb my-kb --tool rag
deeptutor run chat "Explain the Fourier transform" --tool rag --kb textbook
deeptutor run deep_research "Survey 2026 papers on RAG" \
  --config mode=report --config depth=standard

كل ما يفعله تطبيق الويب موجود هنا أيضاً — قواعد المعرفة (kb)، والجلسات (session)، والشركاء (partner)، والمهارات (skill)، ودفاتر الملاحظات، والذاكرة، والتهيئة. القائمة الكاملة أدناه.

دع وكيلاً يقودها

DeepTutor مبنية لتكون مُشغَّلة بواسطة وكيل آخر. أضف --format json إلى أي run وكل دور يبث NDJSON — حدث واحد في كل سطر (content وtool_call وtool_result وdone و...)، وكل سطر مُعنوَن بـ session_id الخاص به. التشغيلات آمنة بدون TTY: توقف ask_user بدون TTY يحل تلقائياً برد فارغ بدلاً من التعليق.

# لقطة واحدة، قابلة للقراءة آلياً
deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json

# سلسل الأدوار في جلسة واحدة ذات حالة — التقط المعرّف، أعد استخدامه
SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \
  --config mode=report --config depth=standard --format json \
  | jq -r 'select(.type=="done").session_id')
deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json

يشحن المستودع بملف SKILL.md في الجذر — وثيقة تسليم بنحو 150 سطراً تعلّم أي LLM يستخدم الأدوات السطح بأكمله في قراءة واحدة. سلّمها إلى Claude Code أو Codex أو OpenCode (يلتقطون SKILL.md تلقائياً)، أو لفّ deeptutor run كأداة في حلقة LangChain / AutoGen. الوصفات الكاملة: Agent Handoff.

مرجع الأوامر

الأمر	الوصف
deeptutor init	إنشاء أو تحديث data/user/settings لمساحة العمل الحالية
deeptutor start [--home PATH]	تشغيل الخلفية + الواجهة الأمامية معاً
deeptutor serve [--port PORT]	تشغيل خلفية FastAPI فقط
deeptutor run <capability> <message>	تشغيل دور قدرة واحدة (chat وdeep_solve وdeep_question وdeep_research وvisualize وmath_animator وmastery_path)؛ أضف --format json لإخراج NDJSON
deeptutor chat	REPL تفاعلي مع تحكمات القدرة والأداة وقاعدة المعرفة ودفتر الملاحظات والتاريخ
deeptutor partner list/create/start/stop	إدارة الشركاء المتصلين بـ IM
deeptutor kb list/info/create/add/search/set-default/delete	إدارة قواعد المعرفة LlamaIndex
deeptutor skill search/install/list/remove/login/logout/publish/update	إدارة المهارات، التثبيت من المراكز، ونشر مهاراتك الخاصة (eduhub:<slug> افتراضياً، راجع النظام البيئي)
deeptutor memory show/clear	فحص مستندات الذاكرة L2/L3 أو مسح ذاكرة L1/الكل
deeptutor session list/show/open/rename/delete	إدارة الجلسات المشتركة
deeptutor notebook list/create/show/add-md/replace-md/remove-record	إدارة دفاتر الملاحظات من ملفات Markdown
deeptutor book list/health/refresh-fingerprints	فحص الكتب وتحديث بصمات المصادر
deeptutor plugin list/info	فحص الأدوات والقدرات المسجلة
deeptutor config show	طباعة ملخص التهيئة
deeptutor provider login <provider>	مصادقة المزود (openai-codex OAuth login؛ github-copilot يتحقق من جلسة مصادقة Copilot موجودة)

توزيع CLI فقط

حزمة CLI فقط تعيش في packaging/deeptutor-cli. في هذه النسخة، ثبّتها من المصدر:

python -m pip install -e ./packaging/deeptutor-cli

لم تُنشر على PyPI بعد، لذا يحتفظ قسم البدء الرئيسي بمسار التثبيت من المصدر.

🧩 النظام البيئي — EduHub ومجتمع المهارات

تستخدم مهارات DeepTutor تنسيق Agent-Skills المفتوح — مجلد يحتوي دليل SKILL.md (YAML frontmatter + Markdown) وملفات مرجعية اختيارية. لا شيء في ذلك خاص بـ DeepTutor، لذا أي سجل يتحدث التنسيق يصبح مصدراً لمكتبتك. يشحن DeepTutor مع EduHub — سجل المهارات المركّز على التعليم الخاص بنا — مُوصَّلاً كمركز افتراضي.

EduHub — النظام البيئي للمهارات في DeepTutor

EduHub هو المركز المجتمعي الذي أطلقه DeepTutor لمشاركة مهارات الوكيل الموجهة نحو التعليم — موجهو سقراط وبناة بطاقات الفلاش وتغذية راجعة للمقالات وخطط الامتحانات وشارحو المفاهيم وغيرها. مُدمَج في DeepTutor، لذا لا شيء يجب تهيئته: slug مجرد أو بادئة eduhub: تحل إليه.

البحث والتثبيت — في المتصفح، افتح فضاء التعلم ← المهارات ← الاستيراد من EduHub لتصفح الكتالوج وتنزيل مهارة مباشرةً إلى مكتبتك. من الطرفية:

deeptutor skill search "socratic tutor"               # البحث في EduHub (المركز الافتراضي)
deeptutor skill install socratic-tutor                # جلب → التحقق → التسجيل
deeptutor skill install eduhub:socratic-tutor@1.2.0   # تثبيت مركز وإصدار محددين
deeptutor skill list                                  # المهارات المحلية مع مصدرها من المركز

انشر مهارتك الخاصة — حزّم SKILL.md وشاركها مع المجتمع:

deeptutor skill login                                 # تسجيل دخول المتصفح إلى EduHub
deeptutor skill publish ./my-skill                    # تفاعلي: اختر track + tags، ثم رفع
deeptutor skill update                                # تراجع أو أصدر إصداراً جديداً

EduHub هو أيضاً سجل مستقل متوافق مع ClawHub، لذا الوكلاء الذين ليسوا DeepTutor (Claude Code وCodex و...) يمكنهم استخدامه مباشرةً من خلال واجهة eduhub — npx eduhub install socratic-tutor.

بوابة أمان الاستيراد

مهما كان المصدر، كل استيراد يمر من نفس بوابة الأمان قبل أن يلمس أي شيء مساحة عملك:

• يُفحَص حكم الأمان للسجل أولاً — الحزم الموسومة ترفض إلا إذا مررت --allow-unverified؛
• تُستخرَج الأرشيفات بشكل دفاعي (حراس zip-slip / zip-bomb) خلف قائمة بيضاء للاحقات نص/نص، لذا الثنائيات لا تصل أبداً إلى مساحة العمل؛
• تُعيَّر الـ frontmatter إلى مخطط DeepTutor وalways: تُزال، لذا مهارة محملة لا يمكنها أبداً إجبار نفسها في كل مطالبة نظام؛
• المصدر — المركز والإصدار والحكم ووقت التثبيت — يُكتب إلى .hub-lock.json للمراجعات والتحديثات.

في عمليات النشر متعددة المستخدمين، التثبيت للمشرفين فقط: تهبط مهارة جديدة في كتالوج المشرف وتظل غير مرئية للمستخدمين الآخرين حتى تعيّنها منحة، لذا يمكن للمشرف فحصها قبل طرحها.

متوافق أيضاً مع ClawHub

لأن DeepTutor يتحدث تنسيق Agent-Skills المفتوح، ClawHub يعمل كمصدر من الدرجة الأولى أيضاً — مُدمَج جنباً إلى جنب مع EduHub. اختره ببادئة المركز:

deeptutor skill search "git release notes" --hub clawhub
deeptutor skill install clawhub:git-release-notes@1.0.1

أضف المزيد من السجلات في settings/skill_hubs.json: إدخال type: "clawhub" يشير إلى أي HTTP API متوافق (EduHub وClawHub يتحدثانه كلاهما)، type: "command" يلفّ أي CLI جلب يشحنه السجل، و"default" يختار المركز المستخدم للـ slugs المجردة. كلها تُغذّي نفس بوابة الاستيراد.

🌐 المجتمع

📮 التواصل

DeepTutor هو مشروع مفتوح المصدر تقوده Bingxi Zhao ضمن مجموعة HKUDS، ويتطور بشكل مفتوح المصدر بالكامل، مبني مع المجتمع. حتى الآن، لا يوجد لدينا أي منتجات مدفوعة عبر الإنترنت من أي شكل. تفضّل بالتواصل على bingxizhao39@gmail.com للنقاشات والأفكار والتعاون.

🙏 التقدير

خالص الشكر لـ Chao Huang، مدير مختبر ذكاء البيانات @ HKU، ولزملائنا في HKUDS على دعمهم الحار — وخاصةً Jiahao Zhang، وZirui Guo، وXubin Ren. ونحن ممتنون عميقاً أيضاً لـ مجتمع المصادر المفتوحة: نجومكم وإصداراتكم وطلبات السحب والنقاشات تشكّل DeepTutor كل يوم.

يقف DeepTutor أيضاً على أكتاف مشاريع مفتوحة المصدر متميزة أعطتنا أدوات وإلهاماً:

المشروع	الدور / الإلهام
LlamaIndex	العمود الفقري لخط أنابيب RAG وفهرسة المستندات
nanobot	محرك وكيل خفيف الوزن للغاية مكّن TutorBot الأصلي (HKUDS)
LightRAG	RAG بسيط وسريع (HKUDS)
AutoAgent	إطار وكيل بدون رمز (HKUDS)
AI-Researcher	خط أنابيب بحث آلي (HKUDS)
OpenClaw	بوابة وكيل مفتوحة ونظام مهارات وراء ClawHub
Codex	واجهة برمجة أصيلة للوكلاء ألهمت سير عمل CLI لدينا
Claude Code	واجهة برمجة للوكلاء ألهمت حلقة وكيل DeepTutor
ManimCat	توليد رسوم متحركة رياضية مدفوع بالذكاء الاصطناعي لـ Math Animator

🗺️ خارطة الطريق والمساهمة

نريد لـ DeepTutor أن يستمر في التطور والتحسين — وفي نهاية المطاف أن يصبح هدية نقدمها للمجتمع مفتوح المصدر. يُحدَّث خارطة طريقنا باستمرار؛ صوّت على العناصر هناك أو اقترح عناصر جديدة. إذا كنت ترغب في المساهمة، راجع دليل المساهمة لمعرفة استراتيجية الفروع ومعايير البرمجة وكيفية البدء.

نأمل أن يصبح DeepTutor هدية للمجتمع. 🎁

مرخّص بموجب رخصة Apache 2.0.