إعداد بيئة التطوير

المتطلبات المسبقة

Python 3.11+
Node.js 18+ (للوثائق)
Git

الاستنساخ والتثبيت

git clone https://github.com/Mubder/kazma.git
cd kazma

# Create virtual environment
python -m venv .venv

فعِّل البيئة الافتراضية حسب منصتك:

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

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

:: Windows (CMD)
.venv\Scripts\activate.bat

# Same extras as setup.sh / setup.ps1 (rag + tests + TUI).
# There is no [cli] extra — kazma-cli is in the wheel.
pip install -e ".[rag,dev,tui]"
# or: uv sync --extra rag --extra dev --extra tui

تفعيل خطافات Git

يأتي pre-commit مع إضافة dev، لكن الخطافات لا تفعل شيئًا حتى تثبّتها في نسختك المستنسخة — افعل ذلك مرة واحدة لكل استنساخ:

pre-commit install

يشغِّل كل التزام بعدها بوابتين تعتمدان على AST فقط (~8 ثوانٍ، بلا إقلاع للتطبيق):

بوابات الاستيراد — كل وحدة من وحدات المنتج تظل قابلة للاستيراد، ولا يبقى مرجع استيراد kazma_* معلّقًا بعد نقل ملف أو حذفه.
البوابات الثابتة — لا استدعاء حاجب لقاعدة بيانات داخل async def، ولا asyncio.create_task من نوع «أطلق وانسَ» (fire-and-forget)، وكل أداة مسجّلة تحمل طبقة HITL، ومخرجات أدوات الويب تُسيَّج كنص غير موثوق.

شغّلها على الشجرة كاملة في أي وقت:

pre-commit run --all-files

يمر كلا الخطافين عبر scripts/run_gates.py الذي يعثر بنفسه على البيئة الافتراضية للمشروع. ينقّي pre-commit متغير PATH لخطافات system، لذا فإن python المجرّد في مدخل الخطاف سيُحلّ إلى مفسّر pre-commit نفسه (بلا pytest)، بينما يفشل المسار النسبي .venv/Scripts/python.exe على Windows — ولهذا لم تُشغَّل هذه الخطافات هناك بصمت قط قبل 2026-08-29. إذا كانت بيئتك الافتراضية في مكان غير معتاد، فوجّه الـ shim إليها:

export KAZMA_GATE_PYTHON=/path/to/python

بنية المشروع

kazma/
  kazma-core/          Agent, LLM providers, swarm, V2 memory, IDE
  kazma-gateway/       Telegram / Discord / Slack
  kazma-ui/            FastAPI dashboard + Settings
  kazma-tui/           Textual dashboard
  kazma-cli/           `kazma` CLI
  kazma-skills/        Native skills
  docs/                Docusaurus site
  tests/               Cross-cutting tests

تشغيل الاختبارات

pytest
pytest --cov=kazma_core
pytest tests/test_checkpoint.py

الفحص النصّي

ruff check .
ruff format .
mypy kazma-core/

الوثائق

cd docs
npm install
npm run start    # local dev server
npm run build    # production build