إعداد بيئة التطوير
إعداد بيئة التطوير
Section titled “إعداد بيئة التطوير”المتطلبات المسبقة
Section titled “المتطلبات المسبقة”- Python 3.11.5+ (يحتاجه soupsieve 4، الذي يسدّ ثلاث ثغرات أُعلنت في 2026)
- Node.js 18+ (للوثائق)
- Git
الاستنساخ والتثبيت
Section titled “الاستنساخ والتثبيت”git clone https://github.com/Mubder/kazma.gitcd kazma
# Create virtual environmentpython -m venv .venvفعِّل البيئة الافتراضية حسب منصتك:
# Linux / macOS / WSLsource .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 postgresuv sync هنا لـتثبيت أول في بيئة جديدة. أما على كاظمه مثبّتة فحدّث بـ
python -m kazma_cli update بدلًا منه: فإن uv sync المجرّد يزيل كل حزمة
خارج الحزم الإضافية التي يسمّيها
(تحديث كاظمه).
تفعيل خطافات Git
Section titled “تفعيل خطافات 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بنية المشروع
Section titled “بنية المشروع”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تشغيل الاختبارات
Section titled “تشغيل الاختبارات”pytestpytest --cov=kazma_corepytest tests/test_checkpoint.pyالفحص النصّي
Section titled “الفحص النصّي”ruff check .ruff format .mypy kazma-core/الوثائق
Section titled “الوثائق”cd docsnpm installnpm run start # local dev servernpm 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).

