البداية السريعة

شغّل كاظمة وأجب على الرسائل في أقل من 10 دقائق. يغطي الدليل ثلاث مسارات تثبيت وأقصر طريق لدردشة تعمل.

---

1. المتطلبات

المتطلب	التفصيل
Python	>=3.11, <3.14 (في pyproject.toml)
Git	للاستنساخ / kazma update
مفتاح مزوّد LLM	OpenAI أو Anthropic أو DeepSeek أو Gemini أو xAI أو OpenRouter أو NIM أو محلي (Ollama / LM Studio) — وAzure/Bedrock مدعومان أصليًا
Node.js (اختياري)	فقط لبناء موقع وثائق Docusaurus

ملاحظة extras: pip install -e . يكفي للوكيل والويب وTUI والبوابات والسرب. extra rag مطلوب فقط للذاكرة المتجهة / RAG — انظر الذاكرة وRAG.

---

2. التثبيت

اختر مسارًا. الثلاثة تنتج: kazma، kazma-tui، kazma-web.

المسار أ — تثبيت قابل للتحرير (موصى للتطوير)

git clone <your-repo-url> kazma
cd kazma
python -m venv .venv

# Linux / macOS / WSL
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

pip install -e ".[rag,dev]"
# أو كل شيء:
pip install -e ".[all]"

Extra	يفعّل
[rag]	ذاكرة V2 / RAG (استدعاء sqlite-vec + تضمينات)
[dev]	اختبارات + lint
[tui]	لوحة الطرفية
[observability]	نقطة /metrics
[web]	مهارة أتمتة المتصفح (playwright install chromium)
[document]	توليد PDF/DOCX/XLSX
[database]	Postgres/MySQL/Mongo في مهارة قاعدة البيانات
[postgres]	حالة مشتركة SaaS متعددة النسخ
[all]	كل ما سبق

المهارات الأصلية تُحمَّل دائمًا — استدعاء أداة بلا خلفية يعيد تلميح تثبيت.

المسار ب — Docker Compose للإنتاج

cp .env.example .env
docker compose up -d --build

انظر النشر.

المسار ج — Windows أصلي (setup.ps1)

.\setup.ps1

لا تسلسل أوامر PowerShell بـ && — استخدم ; و$LASTEXITCODE.

---

3. الإعداد

ثلاث طبقات (أسبقية متزايدة لقراءات وقت التشغيل):

1. kazma.yaml — افتراضيات تصريحية
2. ConfigStore (SQLite) — kazma-data/settings.db
3. متغيرات البيئة — تربح في مواضع محددة

.env أدنى

OPENAI_API_KEY=sk-...
# TELEGRAM_BOT_TOKEN=...
# KAZMA_SECRET=generate-a-long-random-string

مهم: فقط OPENAI_API_KEY وKAZMA_API_KEY احتياطات env عامة. مزوّدون آخرون عبر ConfigStore / kazma.yaml.

تحقق من kazma.yaml

agent:
  name: kazma
  language: ar
  rtl: true

models:
  default: gpt-4o-mini
  router: litellm
  fallback: gpt-4o-mini

llm:
  base_url: https://api.openai.com/v1
  model: gpt-4o-mini
  max_tokens: 4096
  temperature: 0.7
  timeout: 60.0

ui:
  host: 127.0.0.1
  port: 9090

المرجع الكامل: الإعدادات.

---

4. التشغيل

واجهة الويب (الأشيع)

kazma serve              # 127.0.0.1:9090
kazma serve 9091         # إن كان 9090 مشغولاً

افتح http://127.0.0.1:9090 — http وليس https. انتقل إلى المحادثة.

curl http://127.0.0.1:9091/health

أمن الربط: المضيف الافتراضي 127.0.0.1. غير الحلقي يتطلّب KAZMA_SECRET قويًا.
Windows ERR_CONNECTION_RESET على :9090: غالبًا portproxy قديم لـ WSL/Docker — جرّب kazma serve 9091.

TUI

kazma-tui

تحقق CLI

kazma status

---

5. أول رسالة

خلف الكواليس:

1. نصك يُرسل POST إلى /api/chat/stream (SSE).
2. المُشرف يستدعي LLM بالأدوات المسجّلة.
3. إن استُدعيت أداة خطر يتوقف التنفيذ ويُصدَر approval_required.
4. وافق من الواجهة → يستأنف الرسم بـ Command(resume={"approved": true}).

مع extras [rag] تُحقَن الذاكرة تلقائيًا لكل دور وتُخزَّن الحقائق بعد الرد. انظر الذاكرة وRAG.

---

6. قناة ثانية (Telegram، اختياري)

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

connectors:
  telegram:
    enabled: true

أعد التشغيل. جرّب /help، /status، /model.

عزل المنصة: chat_id وuser_id لا يدخلان حالة LangGraph أبدًا.

---

7. الخطوات التالية

إن أردت…	اقرأ
فهم المحرك	البنية المعمارية
ضبط كل إعداد	الإعدادات
أداة / مهارة مخصّصة	المهارات وMCP
سرب متعدد العمال	تنسيق السرب
نشر إنتاج	الأمان + النشر
العربية أولًا	الميزات العربية
المكتبة المعرفية	المكتبة المعرفية

---

ملاحظات تدقيق

• أُزيل «خط أنابيب الذاكرة بأربع طبقات» (V1) في التحوّل من V1 إلى V2. V2 (معتقدات ثنائية الزمن + استدعاء PPR) هي مكدّس الذاكرة الوحيد — انظر الذاكرة وRAG. الذاكرة تلقائية (استدعاء لكل دور + auto-store) بمجرّد تثبيت إضافة [rag]؛ ويمكن للنموذج أيضًا استدعاء memory_search صراحةً.
• tiktoken ليس اعتمادًا معلنًا؛ العدّ chars/4 بدونه.