تخطَّ إلى المحتوى
kazma.
البحث في كاظمه والتوثيق
EN

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

  • Python 3.11.5+ (يحتاجه soupsieve 4، الذي يسدّ ثلاث ثغرات أُعلنت في 2026)
  • 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
نافذة طرفيّة
# A lighter set, by hand (rag + tests + TUI); setup.sh / setup.ps1 install Express, Full or Custom.
# There is no [cli] extra — kazma-cli is in the wheel.
pip install -e ".[rag,dev,tui]"
# or: uv sync --inexact --extra rag --extra dev --extra tui --extra postgres

uv sync هنا لـتثبيت أول في بيئة جديدة. أما على كاظمه مثبّتة فحدّث بـ python -m kazma_cli update بدلًا منه: فإن uv sync المجرّد يزيل كل حزمة خارج الحزم الإضافية التي يسمّيها (تحديث كاظمه).

يأتي 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

تُصان حزم البناء للموقع بالأمر npm audit fix (دون --force أبدًا) وبالملف docs/package-lock.json. ويسمّي package.json الإصدار الرئيسي لـMermaid (overrides، وهو Mermaid 12 منذ 2026-11-13، مع KaTeX 0.18 الذي يُصلح ثغرة KaTeX في Mermaid 11): ويجب أن يُحلَّل به كل مخطط في الوثائق (tests/test_docs_mermaid_diagrams_parse.py، الذي يحتاج إلى npm install هنا وإلى Chromium الخاص بـPlaywright). ويُبقي أيضًا uuid على 11.x لأجل sockjs في خادم التطوير، الذي يطلب 8.x وورثت كل حزم Docusaurus ثغرته، ويُبقي tinypool على 2.x وserialize-javascript على 7.x (2026-11-11): فـDocusaurus 3.10.2 (الأحدث) يمنع كليهما إصدارًا رئيسيًا، ولا تُصلَح ثغراتهما الحرجة والعالية إلا هناك. ويُبنى الموقع بهما (npm run build)، وهذا يحتاج إلى Node 20، كما يحتاج Docusaurus. لا تشغّل npm audit fix دون أن تفحص npm ls @docusaurus/preset-classic بعده: ففي 2026-11-11 أعاد الحزمة إلى 3.7.0، أي Docusaurus ثانيًا أقدم بجانب 3.10.2. وما زال التدقيق يبلّغ عن أمر منخفض لا يوجد له إصدار مُصلَح بعد (deepmerge، في دمج إعدادات وقت البناء الخاص بإضافة SVG).