التطوير

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

---

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

kazma/
├── kazma-core/          # Agent runner, LLM provider, swarm, ConfigStore, safety, V2 memory, skills, MCP
├── kazma-gateway/       # Telegram/Discord/Slack adapters, agent_handler, slash commands
├── kazma-ui/            # FastAPI app, SSE chat, swarm panel, settings, i18n, static assets
├── kazma-tui/           # Textual TUI dashboard
├── kazma-skills/        # Native skills + manifests
├── kazma-cli/           # The `kazma` command surface
├── docs/                # Docusaurus site — single SoT (content under docs/docs/)
├── tests/               # Cross-cutting tests
├── examples/            # Example skills
├── scripts/             # Ops: migrate, smoke, guard, tools-catalog regen, …
├── kazma.yaml           # Main config
├── kazma-permissions.yaml
├── kazma-security.yaml
├── pyproject.toml       # Single hatchling build (6 packages in the wheel)
├── Dockerfile           # Main agent image
├── docker-compose.yml   # Host 9090 → container 8000
├── setup.ps1            # Windows bootstrap (uv sync rag+dev+tui)
├── setup.sh             # Linux / macOS / WSL bootstrap
└── run.sh               # Minimal E2E reproduction

---

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

2.1 التثبيت (قابل للتحرير، كل الحزم الإضافية)

git clone <repo> kazma && cd kazma
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:
pip install -e ".[rag,dev,tui]"
# or: uv sync --extra rag --extra dev --extra tui

لا توجد حزمة إضافية [cli] ولا حزمة إضافية [tracing]. جدول الحزم الإضافية الكامل: البدء السريع §2.

2.2 Windows

.\setup.ps1            # Python 3.11+, uv, uv sync rag+dev+tui, import check

2.3 uv (يستخدمه setup.sh / run.sh)

uv sync --extra rag --extra dev --extra tui
# Full optional set (heavy):
# uv sync --all-extras

---

3. نمط الشيفرة والأعراف

من AGENTS.md:

• Python: تلميحات أنواع، وسلاسل توثيق، وتسجيل.
• نمط 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 — prefer the crash-tolerant chunked runner (full suite ~10 min;
# one chunk per CPU, at most 8)
python scripts/fast_test.py
python -m pytest tests/test_system_install_allowlist.py -v   # one file

# Lint
python -m ruff check kazma-core/kazma_core/
python -m ruff check kazma-tui/kazma_tui/

# Type check
python -m mypy kazma-tui/kazma_tui/

---

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

شجرة توثيق واحدة: docs/docs/ ‏(Docusaurus 3.x). الإعداد: docs/sidebars.js، وdocs/docusaurus.config.js.

cd docs
npm install
npm start               # http://localhost:3000/kazma/
npm run build

# or via CLI:
kazma docs build
kazma docs serve

أعد توليد كتالوج الأدوات بعد إضافة أدوات:

python scripts/generate_tools_catalog.py

سياسة التخطيط والأرشفة: docs/plans/done/DOCS_CONSOLIDATION_PLAN.md (مكتملة؛ تعيش الأشجار المتقاعدة تحت docs/audits/archive/).

---

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

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

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 9090 --ws-ping-interval 20 --ws-ping-timeout 20

---

7. المساهمة

انظر CONTRIBUTING.md (الجذر) للدليل الكامل. قواعد سريعة:

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

---

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

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