تحديث كاظمه (ترقية المشغّل)
تحديث كاظمه
Section titled “تحديث كاظمه”kazma update هو مسار الترقية المدعوم للمشغّل لتثبيتات git /
المستودع الأحادي. فضّله على git pull اليدوي حتى تُعالَج التعديلات
المحلية والإضافات الاختيارية وصحة CLI بطريقة متسقة.
النسخة المختصرة
Section titled “النسخة المختصرة”من مجلد التثبيت، وبـ 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أبدًا. وإن شغّلت uv بنفسك فاستعملuv sync --inexact --extra rag --extra tui. وإن كانت مزامنة قد أزالت حزمًا فعلًا، فإنpython -m kazma_cli update --reinstall -yيعيد حزمك الإضافية (يتذكرها فيsystem.installed_extras). - تثبيت يفشل في منتصفه. على ويندوز قد يوقف ملفٌّ يُبقيه برنامج آخر مفتوحًا
تثبيتًا بعد أن أزال حزمًا. فيعيد التحديث حينئذ كتابة كل حزمة
(
uv pip install --reinstall)، مرتين على الأكثر مع توقف قصير، ولا يعدّ التحديث منجزًا إلا حين تُستورد كاظمه في Python جديد. والمخرجات الكاملة لكل خطوة في.kazma/update.log. وإن ظل يفشل، تبقى كاظمه متوقفة ويسمّي التحديث الخطأ. - حزم جديدة تحتاج إلى شيء خارج Python. بعد الحزم، ينزّل التحديث نسخة Chromium التي يشغّلها Playwright المثبَّت (فقط حيث أُعدّت أدوات المتصفح)، ويضع كل حاوية أنشأها الإعداد من ملفات compose في هذا التثبيت (SearXNG، Neo4j) على الصورة التي يثبّتها الملف الآن. أما حاويتك التي تحمل اسمًا آخر فتُترك كما هي.
-
kazma updateعلى ويندوز. يستبدل التحديثkazma.exe، ولا يسمح ويندوز باستبدال مشغّل يعمل؛ فإن بدأ منه رفض التحديث وسمّىpython -m kazma_cli update. - تثبيت كاظمه من PyPI بالاسم. أسماء كاظمه هناك محجوزة بلا شيفرة؛ تُثبَّت كاظمه من هذا المستودع وإصدارات GitHub الخاصة به فقط.
أي النسخ يثبّت
Section titled “أي النسخ يثبّت”يثبّت التحديث النسخ التي جرت بها اختبارات كاظمه: النسخ التي يسمّيها uv.lock
(منذ 2026-11-14).
- تثبيت git يثبّت مستعملًا ملف
uv.lockالخاص به قيودًا (uv export --locked، أي تثبيتات كل حزمة إضافية؛ ولا يأخذ التثبيت إلا الحزم التي يحتاجها). والحزمة المثبّتة بنسخة أخرى تُنقل إلى النسخة المقفلة. وإن لم يعد القفل مطابقًا لـpyproject.toml(نسخة مستنسخة معدَّلة)، قال التحديث ذلك وثبّت أحدث النسخ التي يسمح بهاpyproject.toml. - تثبيت wheel يقرأ النسخ المقفلة من داخل حزمة wheel الخاصة بالإصدار
(
kazma_cli/locked_versions.txt، الذي يكتبه سير عمل الإصدار قبل البناء، فيشمله توقيع الحزمة) ويثبّت بها. والإصدار 0.21.2 أو ما قبله لا يحمل شيئًا منها: فيُثبَّت كما كان، ويقول التحديث ذلك. والملف داخل حزمة wheel الذي ليس تثبيتات دقيقة يوقف التحديث.
وحين يُصلَح تنبيه أمني يصبح الإصدار المُصلَح الحد الأدنى لكاظمه في
pyproject.toml ويتحرك القفل معه، فيثبّته التحديث التالي؛ وحتى ذلك الحين يقول
الخادم عند الإقلاع أي الحزم المثبّتة دون ما يتطلبه البناء (انظر
أدناه).
كل إصدار يُختبر ترقيةً
Section titled “كل إصدار يُختبر ترقيةً”قبل أن يُنشر إصدار، يرقّي سير عمل الإصدار الإصدارَ الذي قبله إلى الجديد ويتحقق من
أن كاظمه ما زالت تعمل على بياناتها (scripts/upgrade_drill.py، منذ 2026-11-14):
- حزمة wheel للإصدار السابق، تُفحص كما يفحص
kazma updateالحزمة، وتُثبَّت في بيئة جديدة بالنسخ التي اختُبرت بها؛ - يبدأ على مجلد بيانات خاص به، ويجيب، ويتوقف، ويُكتب إعدادٌ في تلك البيانات؛
- تُثبَّت فوقه حزمة wheel الجديدة بالنسخ التي داخلها، كما يثبّت
kazma updateحزمة wheel؛ - يجب أن يذكر النسخة الجديدة، وأن يبدأ على البيانات نفسها، وأن يجيب بأنه جاهز (أو بأنه لا ينتظر إلا إعداد نموذج)، وأن يحتفظ بالإعداد وبكل قاعدة بيانات أنشأها الإصدار القديم، وألا يسجّل أي خطأ.
والإصدار الذي يفشل فيه لا يُنشر. ويشغّل CI الاختبار نفسه مع كل دفع، على Linux وWindows، من أحدث إصدار إلى حزمة wheel مبنية من ذلك الالتزام. ولا يُقرأ ولا يُكتب شيء من أي تثبيت على الجهاز الذي يشغّله.
ما يفعله (تثبيت من إصدار)
Section titled “ما يفعله (تثبيت من إصدار)”التثبيت الذي يصنعه مثبّت ويندوز
(البداية السريعة) تثبيتٌ من إصدار:
ملفات أرشيف المصدر لإصدار ما، بلا .git، ومعها علامة، .kazma-release.json،
تسمّي الإصدار والملفات التي شحنها (kazma_cli/release_tree.py). وهناك يفعل
kazma update ما يلي:
- يقرأ أحدث إصدار وينزّل أرشيف مصدره،
kazma-<version>.tar.gz، ويتحقق منه كما يتحقق من حزمة wheel: بصمة SHA-256 الخاصة به مقابلSHA256SUMSفي الإصدار (وبصمة GitHub)، وتوقيع Sigstore الخاص به (الذي يصنعه سير عمل الإصدارات في كاظمه). - يرفض أرشيفًا فيه أي شيء غير ملفات تحت
kazma-<version>/: لا روابط، ولا مسار خارجه، ولا شيء حيث تعيش ملفاتك أنت. - يستبدل الملفات التي يشحنها الإصدار الجديد ويزيل تلك التي لم يعد يشحنها. ولا
يُمسّ أبدًا
.envوkazma-dataو.venvو.kazmaوkazma.local.yamlوأي ملف أضفته. وكل ملف يُستبدل أو يُزال يُنقل أولًا إلى.kazma\update\backup-<old version>-<time>. - يثبّت إصدارات الحزم المقفلة لذلك الإصدار وكاظمه متوقف، كما بعد سحب git، ثم يشغّله مجددًا.
- إن رُفض ذلك التثبيت أو فشل، يعيد الملفات السابقة، ومعها حزمها. وتُحفظ أحدث نسخة احتياطية، وتُزال الأقدم.
ما يفعله (تثبيت git)
Section titled “ما يفعله (تثبيت git)”- فحص مسبق — git متاح، لا يوجد
.git/index.lock، الفرع هوmain/master(أو--sync-main)، ولا التزامات محلية متقدمة علىorigin/mainما لم تقبل صراحةً التخلص منها. - كنس باسم — الملفات المحلية المتتبعة وغير المتتبعة (
git stash push -uبرسالةkazma-update-…فريدة). الملفات المتجاهَلة (.env، الأسرار) تبقى مكانها. - جلب + إعادة ضبط صارمة إلى
origin/main(بلا مطالبات التزام دمج). - استعادة الكنس بالاسم (التعارضات تُبقي الكنس لاستعادة يدوية).
- إعادة تثبيت الحزمة القابلة للتحرير مع الحفاظ على الإضافات (عملية Python جديدة). ويُوقَف الخادم العامل لهذه الخطوة وحدها، عبر حارسه (انظر أدناه)، ثم يُشغَّل من جديد بعدها.
- فحص لاحق — HEAD يطابق
origin/mainوkazma_cli/kazma_coreتستورد بنجاح. يُبلَّغ عن الفشل؛ لن يدّعي CLI «اكتمال» وهو معطوب.
الحالة أثناء التشغيل: kazma-data/update-state.json (تُمسح عند النجاح).
الأوامر
Section titled “الأوامر”kazma update # check + confirm + sync main + reinstallkazma update -y # non-interactivekazma update --check # dry-run onlykazma 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قواعد الأمان
Section titled “قواعد الأمان”| الحالة | السلوك |
|---|---|
على main، متأخر عن البعيد، عمل غير متتبع غير نظيف | كنس ← إعادة ضبط ← استعادة ← إعادة تثبيت |
| على فرع ميزة | يرفض إعادة الضبط الصارمة؛ استخدم --sync-main أو بدّل بنفسك |
التزامات محلية متقدمة على origin/main | يرفض ما لم يُمرَّر --accept-discard-local-commits |
| HEAD منفصل / index.lock | يرفض مع تلميحات استعادة |
| تركت إعادة التثبيت CLI معطوبًا | التحديث يفشل مع أوامر الإصلاح |
يوقف التحديث الخادم ويعيد تشغيله بنفسه
Section titled “يوقف التحديث الخادم ويعيد تشغيله بنفسه”لا يمكن استبدال حزم كاظمه والخادم يحمّلها: على ويندوز تفشل إعادة التثبيت في منتصفها، وتترك بعض الحزم جديدة وبعضها قديمة. وفي تثبيت يشرف عليه الحارس (مهمة KazmaAgent) يتولى kazma update أمر الخادم بنفسه:
- ينتظر حتى لا تبقى أي دورة محادثة جارية. وإن بقيت دورة جارية بعد 15 دقيقة، لا يوقف شيئًا ولا يثبّت شيئًا، ويقول ذلك.
- يوقف الحارس مؤقتًا، فيوقف الحارس الخادم بلطف ويُبقيه متوقفًا. ولا يثبّت التحديث شيئًا حتى يؤكد الحارس أنه يُبقي الخادم متوقفًا.
- يثبّت الحزم.
- يرفع الإيقاف المؤقت وينتظر حتى يجيب كاظمه من جديد، على الحزم الجديدة.
يذكر سؤال التأكيد ذلك قبل أن يحدث أي شيء؛ والخيار -y يتخطى السؤال. والإيقاف المؤقت هو نفسه الذي يأخذه kazma_guard.py --pause، باسم التحديث نفسه. ويرسل الحارس رسالتي «supervision paused» و«resumed» كما يفعل مع أي إيقاف مؤقت. ولا يرفع التحديث أبدًا إيقافًا مؤقتًا أخذته أنت بنفسك.
حين يفشل التثبيت، يبقى كاظمه متوقفًا. فقد تكون حزمه مستبدَلة إلى نصفها، والحارس سيظل يعيد تشغيل خادم قد لا يقلع. يقول التحديث ذلك، والإصلاح هو الأمر نفسه: يتسلّم الإيقاف المؤقت ويشغّل كاظمه حين ينجح. ولتشغيل كاظمه كما هو بدلًا من ذلك، شغّل python scripts/service/kazma_guard.py --resume. وفي الحالتين يُرفع الإيقاف المؤقت تلقائيًا بعد ساعتين، ثم يشغّل الحارس كاظمه.
ومن دون حارس، يرفض التحديث خادمًا يعمل قبل أن يتغير أي شيء: أوقف الخادم، وشغّل التحديث، ثم شغّل الخادم من جديد.
يوقف تحديث git الخادم من أجل إعادة التثبيت وحدها. فالسحب يجري وكاظمه يخدم، كما يجري سحب النشر. وإن كان كاظمه لا يزال مشغولًا حين يحين وقت إعادة التثبيت، تُعاد النسخة المحلية إلى ما كانت عليه ولا يُثبَّت شيء.
حين يقول الخادم إن حزمه متأخرة
Section titled “حين يقول الخادم إن حزمه متأخرة”git pull يجلب شيفرة جديدة ولا يثبّت شيئًا. وحين يرفع إيداعٌ الحدَّ الأدنى لإصدار في pyproject.toml (حدًّا أمنيًّا، أو إصدارًا تحتاجه ميزة جديدة)، يفحص الخادم ذلك عند الإقلاع ويسجّل تحذيرًا (WARNING) يسمّي كل حزمة والإصدار الذي يتطلبه هذا الإصدار من كاظمه. ويطلق كذلك تنبيه التشغيل install.requirements_unmet، ويعرض فحص التبعيات في تقرير الأمان الحزم نفسها. والإصلاح أمر واحد، من مجلد التثبيت:
python -m kazma_cli update --reinstall -ypython هنا هو مفسّر التثبيت نفسه: .venv\Scripts\python.exe على ويندوز، و.venv/bin/python في غيره. فقد يكون python وحده مفسّرًا آخر، أو لا يكون موجودًا أصلًا؛ والتنبيه يطبع الأمر بالمفسّر الصحيح. ويُشغَّل التحديث بالصيغة python -m kazma_cli update لا kazma update: فعلى ويندوز يجب أن تستبدل إعادة التثبيت kazma.exe، وويندوز لا يسمح باستبدال مشغّل (ولا حتى بإعادة تسميته) ما دام يعمل. وإذا بدأ التحديث من kazma.exe (أو كانت الواجهة النصية TUI تعمل)، يرفض قبل أن يثبّت أي شيء ويسمّي الأمر الذي يجب استخدامه.
الخيار --reinstall هو مسار الحزم وحدها: يحافظ على إضافاتك الاختيارية ولا يمسّ حالة git. وفي تثبيت يشرف عليه الحارس، يوقف كاظمه ويشغّله كما ورد أعلاه.
الإصلاح بعد إعادة تثبيت معطوبة
Section titled “الإصلاح بعد إعادة تثبيت معطوبة”قد تترك إعادة تثبيت فشلت في منتصفها حزمة كاظمه نفسها نصف مُزالة: مجلدات ~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 SilentlyContinueuv 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 كما في الأعلى.
المستندات بعد التحديث
Section titled “المستندات بعد التحديث”تُحدَّث جداول المستندات عند الإقلاع التالي للخادم، على SQLite وعلى Postgres. وعلى
Postgres يأخذ الإعداد قفلًا استشاريًا واحدًا تتشاركه كل عمليات إعداد مخطط كاظمه،
ولا يرسل عبارةً إلا لجدول أو فهرس أو عمود يقول الفهرس (catalog) إنه مفقود
(kazma_core/db/pg_schema.py)، فلا ينتظر الإقلاع خلف dump نسخة احتياطية جارية ولا
يقع في جمود مع إقلاع آخر.
التحديث لا يعيد بناء صورة عامل المستندات. مع نمط الحاوية في تثبيت أصلي، شغّل
python scripts/document_worker_image.py build مباشرة بعد التحديث؛ ويخدم وسيط الحارس
الصورة الأقدم حتى ذلك الحين ثم يتحوّل من تلقاء نفسه، وتطلق كاظمه تنبيه تشغيل واحدًا
يسمّي البناء. والتحديث يدويًا يتجنّب ذلك التنبيه: اسحب، ثم ابنِ، ثم أعد التحميل —
git pullpython scripts/document_worker_image.py buildpython 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 كاملًا). انظر
معالجة المستندات ← عمال مستندات معزولون.
علامات تبويب المتصفح المفتوحة بعد التحديث
Section titled “علامات تبويب المتصفح المفتوحة بعد التحديث”تحتفظ علامة التبويب التي فُتحت قبل التحديث بشيفرة الصفحة التي حمّلتها. وتعرض “Kazma was updated” مع زر Refresh خلال 5 دقائق، أو فور عودتك إليها؛ حدّث الصفحة لتحميل الإصدار الجديد.
نسخ المطوّرين
Section titled “نسخ المطوّرين”استخدم git العادي على فروع الميزات. لا تعتمد على تحديث إعادة الضبط الصارمة
وأنت في منتصف ميزة. عندما تريد main الإنتاجي: git checkout main ثم
kazma update، أو kazma update --sync-main.
نافذة تحديث لتحديثات الجهاز نفسه
Section titled “نافذة تحديث لتحديثات الجهاز نفسه”تحديث البرامج الأخرى على الجهاز (Docker Desktop، وقاعدة البيانات، وويندوز نفسه) يوقف لبعض الوقت ما يعمل عليه كاظمه. وخارج النافذة يعامل الحارس ذلك انقطاعًا: يعيد تشغيل كاظمه وينبّهك. فاجعل العمل داخل نافذة:
kazma maintenance begin --reason "machine updates" --hours 2ينتظر حتى لا يجري أي دور محادثة، ثم يوقف الحارس مؤقتًا بسبب صيانة. ويبقى
كاظمه يعمل؛ ولا يعيد الحارس تشغيل شيء ولا ينبّه أحدًا، ويُبلَّغ المراقب الخارجي
بأن الأمر مخطَّط. وتُغلق النافذة من تلقاء نفسها بعد --hours، فلا تصير
نافذة منسيّة انقطاعًا صامتًا. وحين تنتهي التحديثات:
kazma maintenance endيستأنف الحارس وينتظر حتى خمس دقائق ليصبح كاظمه سليمًا (/health/deep)؛
وإن لم يكن كذلك نبّهك.
يستطيع topgrade أن يفتح النافذة ويغلقها بنفسه. في topgrade.toml:
[pre_commands]"Kazma maintenance" = "kazma maintenance begin --reason topgrade --hours 2"
[post_commands]"Kazma maintenance" = "kazma maintenance end"إعدادان في الجهاز يبقيان التحديثات داخل النافذة (اضبطهما مرة واحدة):
- Docker Desktop: Settings ← Software updates ← أطفئ “Automatically check for updates”، كي يتحدّث عبر topgrade داخل النافذة.
- Windows Update: اضبط ساعات النشاط على يومك، وفعّل “Notify me when a restart is required”. وبعد إعادة التشغيل تعيد مهمة الإقلاع وخدمة قاعدة البيانات كل شيء بنفسيهما.
النشر إلى تثبيت حي من نسخة مستودع
Section titled “النشر إلى تثبيت حي من نسخة مستودع”يسحب scripts/deploy_live.py --live <install> التغييرات، ويشغّل تحديث الحزم
وبناء صورة المستندات حين تتغير ملفاتهما، ويعيد التحميل عند الخمول، ويفحص
النتيجة: الإيداع الجديد يجيب، والجاهزية والصحة العميقة، ودور اختبار واحد
مُبقًى خارج الذاكرة، ولا خطأ في السجل منذ الإقلاع. وحين يفشل فحص يتراجع عن
الإيداعات المنشورة على main، ويسحب التراجع إلى التثبيت، ويعيد تحميله
وينبّهك بالفحص الذي فشل.

