تحديث كاظمه (ترقية المشغّل)

تحديث كاظمه

kazma update هو مسار الترقية المدعوم للمشغّل لتثبيتات git / المستودع الأحادي. فضّله على git pull اليدوي حتى تُعالَج التعديلات المحلية والإضافات الاختيارية وصحة CLI بطريقة متسقة.

ما يفعله (تثبيت git)

1. فحص مسبق — git متاح، لا يوجد .git/index.lock، الفرع هو main/master (أو --sync-main)، ولا التزامات محلية متقدمة على origin/main ما لم تقبل صراحةً التخلص منها.
2. كنس باسم — الملفات المحلية المتتبعة وغير المتتبعة (git stash push -u برسالة kazma-update-… فريدة). الملفات المتجاهَلة (.env، الأسرار) تبقى مكانها.
3. جلب + إعادة ضبط صارمة إلى origin/main (بلا مطالبات التزام دمج).
4. استعادة الكنس بالاسم (التعارضات تُبقي الكنس لاستعادة يدوية).
5. إعادة تثبيت الحزمة القابلة للتحرير مع الحفاظ على الإضافات (عملية Python جديدة). ويُوقَف الخادم العامل لهذه الخطوة وحدها، عبر حارسه (انظر أدناه)، ثم يُشغَّل من جديد بعدها.
6. فحص لاحق — HEAD يطابق origin/main وkazma_cli / kazma_core تستورد بنجاح. يُبلَّغ عن الفشل؛ لن يدّعي CLI «اكتمال» وهو معطوب.

الحالة أثناء التشغيل: kazma-data/update-state.json (تُمسح عند النجاح).

الأوامر

kazma update              # check + confirm + sync main + reinstall
kazma update -y           # non-interactive
kazma update --check      # dry-run only
kazma update --reinstall -y   # packages only (repair wiped venv)
kazma update --sync-main  # checkout main first (from a feature branch)
kazma update --accept-discard-local-commits
                          # allow hard-reset when you have local commits on main

قواعد الأمان

الحالة	السلوك
على main، متأخر عن البعيد، عمل غير متتبع غير نظيف	كنس ← إعادة ضبط ← استعادة ← إعادة تثبيت
على فرع ميزة	يرفض إعادة الضبط الصارمة؛ استخدم --sync-main أو بدّل بنفسك
التزامات محلية متقدمة على origin/main	يرفض ما لم يُمرَّر --accept-discard-local-commits
HEAD منفصل / index.lock	يرفض مع تلميحات استعادة
تركت إعادة التثبيت CLI معطوبًا	التحديث يفشل مع أوامر الإصلاح

يوقف التحديث الخادم ويعيد تشغيله بنفسه

لا يمكن استبدال حزم كاظمه والخادم يحمّلها: على ويندوز تفشل إعادة التثبيت في منتصفها، وتترك بعض الحزم جديدة وبعضها قديمة. وفي تثبيت يشرف عليه الحارس (مهمة KazmaAgent) يتولى kazma update أمر الخادم بنفسه:

1. ينتظر حتى لا تبقى أي دورة محادثة جارية. وإن بقيت دورة جارية بعد 15 دقيقة، لا يوقف شيئًا ولا يثبّت شيئًا، ويقول ذلك.
2. يوقف الحارس مؤقتًا، فيوقف الحارس الخادم بلطف ويُبقيه متوقفًا. ولا يثبّت التحديث شيئًا حتى يؤكد الحارس أنه يُبقي الخادم متوقفًا.
3. يثبّت الحزم.
4. يرفع الإيقاف المؤقت وينتظر حتى يجيب كاظمه من جديد، على الحزم الجديدة.

يذكر سؤال التأكيد ذلك قبل أن يحدث أي شيء؛ والخيار -y يتخطى السؤال. والإيقاف المؤقت هو نفسه الذي يأخذه kazma_guard.py --pause، باسم التحديث نفسه. ويرسل الحارس رسالتي «supervision paused» و«resumed» كما يفعل مع أي إيقاف مؤقت. ولا يرفع التحديث أبدًا إيقافًا مؤقتًا أخذته أنت بنفسك.

حين يفشل التثبيت، يبقى كاظمه متوقفًا. فقد تكون حزمه مستبدَلة إلى نصفها، والحارس سيظل يعيد تشغيل خادم قد لا يقلع. يقول التحديث ذلك، والإصلاح هو الأمر نفسه: يتسلّم الإيقاف المؤقت ويشغّل كاظمه حين ينجح. ولتشغيل كاظمه كما هو بدلًا من ذلك، شغّل python scripts/service/kazma_guard.py --resume. وفي الحالتين يُرفع الإيقاف المؤقت تلقائيًا بعد ساعتين، ثم يشغّل الحارس كاظمه.

ومن دون حارس، يرفض التحديث خادمًا يعمل قبل أن يتغير أي شيء: أوقف الخادم، وشغّل التحديث، ثم شغّل الخادم من جديد.

يوقف تحديث git الخادم من أجل إعادة التثبيت وحدها. فالسحب يجري وكاظمه يخدم، كما يجري سحب النشر. وإن كان كاظمه لا يزال مشغولًا حين يحين وقت إعادة التثبيت، تُعاد النسخة المحلية إلى ما كانت عليه ولا يُثبَّت شيء.

حين يقول الخادم إن حزمه متأخرة

git pull يجلب شيفرة جديدة ولا يثبّت شيئًا. وحين يرفع إيداعٌ الحدَّ الأدنى لإصدار في pyproject.toml (حدًّا أمنيًّا، أو إصدارًا تحتاجه ميزة جديدة)، يفحص الخادم ذلك عند الإقلاع ويسجّل تحذيرًا (WARNING) يسمّي كل حزمة والإصدار الذي يتطلبه هذا الإصدار من كاظمه. ويطلق كذلك تنبيه التشغيل install.requirements_unmet، ويعرض فحص التبعيات في تقرير الأمان الحزم نفسها. والإصلاح أمر واحد، من مجلد التثبيت:

python -m kazma_cli update --reinstall -y

python هنا هو مفسّر التثبيت نفسه: .venv\Scripts\python.exe على ويندوز، و.venv/bin/python في غيره. فقد يكون python وحده مفسّرًا آخر، أو لا يكون موجودًا أصلًا؛ والتنبيه يطبع الأمر بالمفسّر الصحيح. ويُشغَّل التحديث بالصيغة python -m kazma_cli update لا kazma update: فعلى ويندوز يجب أن تستبدل إعادة التثبيت kazma.exe، وويندوز لا يسمح باستبدال مشغّل (ولا حتى بإعادة تسميته) ما دام يعمل. وإذا بدأ التحديث من kazma.exe (أو كانت الواجهة النصية TUI تعمل)، يرفض قبل أن يثبّت أي شيء ويسمّي الأمر الذي يجب استخدامه.

الخيار --reinstall هو مسار الحزم وحدها: يحافظ على إضافاتك الاختيارية ولا يمسّ حالة git. وفي تثبيت يشرف عليه الحارس، يوقف كاظمه ويشغّله كما ورد أعلاه.

الإصلاح بعد إعادة تثبيت معطوبة

قد تترك إعادة تثبيت فشلت في منتصفها حزمة كاظمه نفسها نصف مُزالة: مجلدات ~azma* في site-packages، ويفشل import kazma_cli، فلا يستطيع الخادم أن يبدأ. وحتى 2026-10-02 كانت كل إعادة تثبيت تُشغَّل من kazma.exe على ويندوز تنتهي هكذا (“failed to remove file … kazma.exe”): فالتحديث مضطر إلى استبدال المشغّل الذي يعمل منه، وويندوز يقفل المشغّل الجاري. صار التحديث الآن يرفض العمل من مشغّل يجب أن يستبدله، قبل أن يثبّت أي شيء، ويسمّي أمر python -m kazma_cli update الذي يُستخدم بدلًا منه.

للإصلاح، والخادم متوقف، في مجلد التثبيت:

# PowerShell (Windows)
Remove-Item -Recurse -Force .\.venv\Lib\site-packages\~azma* -ErrorAction SilentlyContinue
uv pip install --python .\.venv\Scripts\python.exe -e ".[rag,tui,document-platform]"
.\.venv\Scripts\python.exe -c "import kazma_cli; print('ok')"

ضع بين القوسين إضافات تثبيتك أنت: تلك التي يطبعها kazma update تحت “Preserving optional extras”. ثم شغّل الخادم من جديد: في تثبيت يشرف عليه الحارس python scripts/service/kazma_guard.py --resume، وإلا فـkazma serve.

أو: python -m kazma_cli update --reinstall -y متى أصبح CLI قابلًا للاستيراد بما يكفي لتشغيله، أو بعد إصلاح venv بـ uv pip install كما في الأعلى.

نسخ المطوّرين

استخدم git العادي على فروع الميزات. لا تعتمد على تحديث إعادة الضبط الصارمة وأنت في منتصف ميزة. عندما تريد main الإنتاجي: git checkout main ثم kazma update، أو kazma update --sync-main.