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

تحديث كاظمه

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

النسخة المختصرة

من مجلد التثبيت، وبـ Python الخاص بالتثبيت (.venv\Scripts\python.exe على ويندوز، و.venv/bin/python في غيره):

python -m kazma_cli update

هذا هو التحديث كله. ثم، حين ينطبق فقط:

متى	شغّل
سحبت بـ git pull بنفسك، أو أبلغ الخادم أن حزمه متأخرة (install.requirements_unmet)	python -m kazma_cli update --reinstall -y
تعمل المستندات في ملف الحاوية	python scripts/document_worker_image.py build (أدناه)

ثلاثة أشياء تعطّل التثبيت، ولا يفعل التحديث أيًا منها:

• ‏uv sync المجرّد. يجعل uv البيئة مطابقة تمامًا للحزم الإضافية المسمّاة على سطر أوامره ويزيل كل حزمة أخرى: فإن شُغّل بلا --extra أزال الحزم الإضافية الاختيارية (الذاكرة المتجهة، وواجهة الطرفية، وOCR، ومنصة المستندات…) وكل حزمة ثُبّتت من الإعدادات ← الحزم. يثبّت التحديث إضافيًا (uv pip install -e ".[your extras]") ويعود إلى uv sync --inexact بحزمك الإضافية، ولا يشغّل uv sync مجرّدًا أبدًا. وإن شغّلت uv بنفسك فافعل الشيء نفسه: uv sync --inexact --extra rag --extra tui. وإن كانت مزامنة قد أزالت حزمًا فعلًا، فإن python -m kazma_cli update --reinstall -y يعيد حزمك الإضافية (يتذكرها في system.installed_extras).
• ‏kazma update على ويندوز. يستبدل التحديث kazma.exe، ولا يسمح ويندوز باستبدال مشغّل يعمل؛ فإن بدأ منه رفض التحديث وسمّى python -m kazma_cli update.
• تثبيت كاظمه من PyPI بالاسم. أسماء كاظمه هناك محجوزة بلا شيفرة؛ تُثبَّت كاظمه من هذا المستودع وإصدارات GitHub الخاصة به فقط.

أي النسخ يثبّت

يثبّت التحديث ما يعلنه هذا البناء من كاظمه في pyproject.toml ويبقي أي نسخة مثبّتة تفي به بالفعل. ولا ينقل كل حزمة إلى أحدث إصداراتها. وحين يُصلَح تنبيه أمني يصبح الإصدار المُصلَح الحد الأدنى لكاظمه في pyproject.toml، فيثبّته التحديث التالي؛ وحتى ذلك الحين يقول الخادم عند الإقلاع أي الحزم المثبّتة دون ما يتطلبه البناء (انظر أدناه).

ما يفعله (تثبيت 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 كما في الأعلى.

المستندات بعد التحديث

تُحدَّث جداول المستندات عند الإقلاع التالي للخادم، على SQLite وعلى Postgres. وعلى Postgres يأخذ الإعداد قفلًا استشاريًا واحدًا تتشاركه كل عمليات إعداد مخطط كاظمه، ولا يرسل عبارةً إلا لجدول أو فهرس أو عمود يقول الفهرس (catalog) إنه مفقود (kazma_core/db/pg_schema.py)، فلا ينتظر الإقلاع خلف dump نسخة احتياطية جارية ولا يقع في جمود مع إقلاع آخر.

التحديث لا يعيد بناء صورة عامل المستندات. مع نمط الحاوية في تثبيت أصلي، شغّل python scripts/document_worker_image.py build مباشرة بعد التحديث؛ ويخدم وسيط الحارس الصورة الأقدم حتى ذلك الحين ثم يتحوّل من تلقاء نفسه، وتطلق كاظمه تنبيه تشغيل واحدًا يسمّي البناء. والتحديث يدويًا يتجنّب ذلك التنبيه: اسحب، ثم ابنِ، ثم أعد التحميل —

git pull
python scripts/document_worker_image.py build
python scripts/service/kazma_guard.py --reload --when-idle

— فيبدأ كاظمه على الصورة المطابقة لشيفرته (تُسمّى الصورة باسم الشيفرة التي بُنيت منها، لذا فإعادة التحميل قبل البناء لا تجد إلا الصورة القديمة). وتحت docker compose، أعد بناء الصورة من deploy/document-worker/Dockerfile وأعد تشغيل document-broker: فالوسيط يثبّت الصورة التي بدأ بها. وحتى ذلك الحين تبلّغ الجاهزية عن worker_isolation.image_code_matches: false وdocument_worker_image_outdated حين تتغير شيفرة المستندات (الفحص يغطي kazma_core/documents وحده، بينما تحوي الصورة kazma_core كاملًا). انظر معالجة المستندات ← عمال مستندات معزولون.

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

تحتفظ علامة التبويب التي فُتحت قبل التحديث بشيفرة الصفحة التي حمّلتها. وتعرض “Kazma was updated” مع زر Refresh خلال 5 دقائق، أو فور عودتك إليها؛ حدّث الصفحة لتحميل الإصدار الجديد.

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

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