التطوير

تخطيط المستودع، وإعداد البيئة، وأوامر الاختبار/الفحص النصّي/فحص الأنواع المستخدمة عبر المستودع الموحّد (monorepo) لكاظمة.

---

1. تخطيط المستودع

kazma/
├── kazma-core/          # Agent runner, LLM provider, swarm, ConfigStore, safety, memory, skills, MCP, hub
├── kazma-gateway/       # Telegram/Discord/Slack adapters, agent_handler package, slash commands
├── kazma-ui/            # FastAPI app, SSE chat, swarm panel, settings, i18n, static assets
├── kazma-tui/           # Textual TUI dashboard
├── kazma-memory/        # Arabic tokenizer + SQLite/FTS5 search backend
├── kazma-skills/        # Skill manifests (data)
├── kazma-cli/           # The `kazma` command surface
├── docs/                # Existing Docusaurus site (v3.4)
├── docs-v2/             # This rewrite
├── tests/               # Cross-cutting tests
├── examples/            # Example skills (e.g. almuhalab_custom_skills)
├── kubernetes/          # Hub API manifests (see Deployment §4)
├── kazma.yaml           # Main config
├── kazma-permissions.yaml
├── kazma-security.yaml
├── services.yaml
├── pyproject.toml       # Single hatchling build for all 7 packages
├── Dockerfile           # Main agent image
├── docker-compose.yml   # Main agent compose
├── setup.ps1            # Windows bootstrap
└── run.sh               # Minimal E2E reproduction

---

2. إعداد البيئة

2.1 التثبيت (قابل للتعديل، بكل الإضافات)

git clone <repo> kazma && cd kazma
python -m venv .venv
source .venv/bin/activate        # POSIX
# or: .venv\Scripts\activate      # Windows

pip install -e ".[rag,dev]"

الإضافات (pyproject.toml:37-71):

الإضافة	المحتويات
rag	chromadb>=0.5.0، sentence-transformers>=3.0.0
dev	pytest، pytest-asyncio، pytest-cov، pytest-mock، ruff، mypy، locust
test	رصة pytest + fakeredis
tracing	مُصدِّرات/أدوات قياس opentelemetry-*
tui	textual>=8.0.0، python-bidi

2.2 ويندوز

.\setup.ps1            # validates env, syncs venv, runs import check

2.3 uv (يُستخدَم في run.sh)

uv sync --extra dev --extra cli --extra tui --extra rag

---

3. أسلوب الكود والاتفاقيات

من AGENTS.md:

• Python: تلميحات الأنواع (type hints)، وسلاسل التوثيق (docstrings)، والسجل (logging).
• نمط logger = logging.getLogger(__name__).
• from __future__ import annotations لتلميحات الأنواع.
• مسألة واحدة لكل ملف؛ أبقِ الوحدات مركّزة.
• تحقّق من تجميع Python قبل الالتزام: python -c "import py_compile; py_compile.compile(r'<file>', doraise=True); print('OK')"
• تحقّق من صياغة JS قبل الالتزام: node --check "<file>"
• PowerShell: لا تستخدم &&/|| إطلاقًا؛ استخدم ; و$LASTEXITCODE.

---

4. الاختبار / الفحص النصّي / فحص الأنواع

# Python compile check (fast smoke)
.venv/Scripts/python.exe -c "import py_compile; py_compile.compile(r'kazma-core/kazma_core/llm_provider.py', doraise=True); print('OK')"

# JS syntax check
node --check "kazma-ui/kazma_ui/static/js/chat.js"

# Run tests
python -m pytest kazma-core/tests/ -v
python -m pytest tests/ -v                 # cross-cutting
python -m pytest -k majlis -v              # specific

# Lint
python -m ruff check kazma-core/kazma_core/
python -m ruff check kazma-tui/kazma_tui/  # (per services.yaml)

# Type check
python -m mypy kazma-tui/kazma_tui/        # (per services.yaml)

تُعلَن أوامر كل حزمة أيضًا في services.yaml:

commands:
  install: "pip install -e kazma-tui/ -e kazma-core/"
  test: "python -m pytest kazma-tui/tests/ -v"
  lint: "python -m ruff check kazma-tui/kazma_tui/"
  typecheck: "python -m mypy kazma-tui/kazma_tui/"

---

5. موقع وثائق Docusaurus (docs/)

موقع الوثائق الحالي هو Docusaurus 3.4 (docs/package.json):

kazma docs build        # npm install && npm run build
kazma docs serve        # npm run start (port 3000)

شجرة docs-v2/ هذه عبارة عن محتوى يُقصد دمجها في ذلك الموقع (انظر ملاحظة التكامل في ملخّص التدقيق). يقع ملفّا sidebars.js وdocusaurus.config.js الخاصّان بـ Docusaurus في docs/.

---

6. دورة حياة الخادم (التطوير)

أعد تشغيل خادم التطوير (PowerShell، من AGENTS.md):

Get-Process -Name python -ErrorAction SilentlyContinue |
  Where-Object { (Get-CimInstance Win32_Process -Filter ('ProcessId=' + $_.Id)).CommandLine -like '*uvicorn*kazma*' } |
  ForEach-Object { Stop-Process -Id $_.Id -Force }

cd 'G:\GitHubRepos\kazma'
& '.venv\Scripts\python.exe' -m uvicorn kazma_ui.app:create_app --factory --host 127.0.0.1 --port 8090

---

7. المساهمة

راجع CONTRIBUTING.md (في الجذر) للحصول على الدليل الكامل. قواعد سريعة:

• انشعب عن main لطلبات السحب (PR).
• أبقِ تواقيع الواجهة العامة (public API) مستقرّة (إعادة هيكلة السرب حفظتها؛ افعل المثل).
• تحقّق من التجميع/الصياغة قبل الالتزام.
• شغّل مجموعة الاختبارات ذات الصلة.
• وثّق التبعات الأمنية لأي أداة خطيرة جديدة أو عَلَم إعداد جديد.

---

ملاحظات تدقيق الوثائق

• يحتوي جذر المستودع على العديد من أدلّة .pytest_tmp_* الناتجة عن تشغيلات اختبار سابقة — فوضى مُتجاهَلة من قِبَل git، وآمنة التنظيف.
• نطاق services.yaml يقتصر على أوامر kazma-tui؛ تعامل معه كمثال، لا كالمُشغّل المهام القياسي لكل الحزم.
• run.sh هو إعادة إنتاج شامل من الطرف إلى الطرف (يُثبّت، ويُشغّل المجموعة الكاملة، ويُمارِس وكيلًا حيًّا، ويكتب EVAL.md) — مفيد للتحقّق شبيه الـ CI.