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

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

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 أبدًا. وإن شغّلت 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 الخاصة به فقط.

يثبّت التحديث النسخ التي جرت بها اختبارات كاظمه: النسخ التي يسمّيها 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 ويتحرك القفل معه، فيثبّته التحديث التالي؛ وحتى ذلك الحين يقول الخادم عند الإقلاع أي الحزم المثبّتة دون ما يتطلبه البناء (انظر أدناه).

قبل أن يُنشر إصدار، يرقّي سير عمل الإصدار الإصدارَ الذي قبله إلى الجديد ويتحقق من أن كاظمه ما زالت تعمل على بياناتها (scripts/upgrade_drill.py، منذ 2026-11-14):

  1. حزمة wheel للإصدار السابق، تُفحص كما يفحص kazma update الحزمة، وتُثبَّت في بيئة جديدة بالنسخ التي اختُبرت بها؛
  2. يبدأ على مجلد بيانات خاص به، ويجيب، ويتوقف، ويُكتب إعدادٌ في تلك البيانات؛
  3. تُثبَّت فوقه حزمة wheel الجديدة بالنسخ التي داخلها، كما يثبّت kazma update حزمة wheel؛
  4. يجب أن يذكر النسخة الجديدة، وأن يبدأ على البيانات نفسها، وأن يجيب بأنه جاهز (أو بأنه لا ينتظر إلا إعداد نموذج)، وأن يحتفظ بالإعداد وبكل قاعدة بيانات أنشأها الإصدار القديم، وألا يسجّل أي خطأ.

والإصدار الذي يفشل فيه لا يُنشر. ويشغّل CI الاختبار نفسه مع كل دفع، على Linux وWindows، من أحدث إصدار إلى حزمة wheel مبنية من ذلك الالتزام. ولا يُقرأ ولا يُكتب شيء من أي تثبيت على الجهاز الذي يشغّله.

ما يفعله (تثبيت من إصدار)

Section titled “ما يفعله (تثبيت من إصدار)”

التثبيت الذي يصنعه مثبّت ويندوز (البداية السريعة) تثبيتٌ من إصدار: ملفات أرشيف المصدر لإصدار ما، بلا .git، ومعها علامة، .kazma-release.json، تسمّي الإصدار والملفات التي شحنها (kazma_cli/release_tree.py). وهناك يفعل kazma update ما يلي:

  1. يقرأ أحدث إصدار وينزّل أرشيف مصدره، kazma-<version>.tar.gz، ويتحقق منه كما يتحقق من حزمة wheel: بصمة SHA-256 الخاصة به مقابل SHA256SUMS في الإصدار (وبصمة GitHub)، وتوقيع Sigstore الخاص به (الذي يصنعه سير عمل الإصدارات في كاظمه).
  2. يرفض أرشيفًا فيه أي شيء غير ملفات تحت kazma-<version>/: لا روابط، ولا مسار خارجه، ولا شيء حيث تعيش ملفاتك أنت.
  3. يستبدل الملفات التي يشحنها الإصدار الجديد ويزيل تلك التي لم يعد يشحنها. ولا يُمسّ أبدًا .env وkazma-data و.venv و.kazma وkazma.local.yaml وأي ملف أضفته. وكل ملف يُستبدل أو يُزال يُنقل أولًا إلى .kazma\update\backup-<old version>-<time>.
  4. يثبّت إصدارات الحزم المقفلة لذلك الإصدار وكاظمه متوقف، كما بعد سحب git، ثم يشغّله مجددًا.
  5. إن رُفض ذلك التثبيت أو فشل، يعيد الملفات السابقة، ومعها حزمها. وتُحفظ أحدث نسخة احتياطية، وتُزال الأقدم.
  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 معطوبًاالتحديث يفشل مع أوامر الإصلاح

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

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

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

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

يذكر سؤال التأكيد ذلك قبل أن يحدث أي شيء؛ والخيار -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 -y

python هنا هو مفسّر التثبيت نفسه: .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 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 كاملًا). انظر معالجة المستندات ← عمال مستندات معزولون.

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

Section titled “علامات تبويب المتصفح المفتوحة بعد التحديث”

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

استخدم 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، ويسحب التراجع إلى التثبيت، ويعيد تحميله وينبّهك بالفحص الذي فشل.