بيئة تشغيل مكتفية بذاتها

محرّك Apothem هو بيئة تشغيل مكتفية بذاتها: يعمل دون سجلّ، مباشرةً من أيّ نسخة محلية أو شجرة مصدر مُوضَعة، لأنّ تبعياته من طرف ثالث تسافر معه. قطعتان تجعلان ذلك ممكنًا — شجرة تبعيات مُدمَجة، ونموذج استدعاء python -m لا يحتاج إلى سكربتات وحدة تحكّم مثبَّتة.

شجرة التبعيات المُدمَجة

تُدمَج حزمة التحقّق والتسلسل بوصفها مصدرًا بلغة Python الخالصة تحت src/apothem/_vendor/، كلّ حزمة بجوار ملفّ ترخيصها المنبع:

• yaml (المُحلِّل/الباعث بلغة Python الخالصة؛ امتداد libyaml الاختياري بلغة C ليس محمولًا)
• jsonschema، مع سلسلة تبعياته attrs (واسمه البديل attr) وreferencing وjsonschema_specifications
• rpds — رقعة بلغة Python الخالصة تُعيد تنفيذ سطح HashTrieMap وHashTrieSet وList الذي يستخدمه jsonschema وreferencing، مدعومةً بالأنواع المُضمَّنة، حتى تعمل الحزمة بصفر امتدادات مُصرَّفة
• typing_extensions

تتقدّم النسخ المُدمَجة على أيّ إصدار مُثبَّت على النظام: يُقدِّم التمهيد دليل vendor في مقدّمة sys.path أمام site-packages. سياسة الانتقاء — ما الذي يُدمَج، وما الذي لا يُدمَج، وكيف تُحدَّث الحزم المُدمَجة — موثَّقة في استراتيجية إدماج التبعيات.

تبقى تبعيتان خارج الشجرة: click وrich، وهما المكتبتان الموجَّهتان نحو الطرفية اللتان تستوردهما CLI. يجب أن تكونا قابلتين للاستيراد تحت المفسّر الذي يُشغِّل المحرّك؛ يتحقّق المُثبِّتون من كلتيهما، ويُسمّيان أيّ واحدة ناقصة، ويعرضان تثبيتها لك — بتأكيدك، أو تلقائيًّا عبر --yes / APOTHEM_AUTO_INSTALL_DEPS=1.

نموذج الاستدعاء python -m

يُصرِّح Apothem عمدًا بعدم وجود سكربتات وحدة تحكّم في pyproject.toml — لا توجد سكربتات وحدة التحكّم إلّا حين يضعها مدير حزم على PATH، وبيئة التشغيل المكتفية بذاتها لا تفترض وجود واحد قطّ. للمحرّك بدلًا من ذلك سطحان للاستدعاء:

• python -m apothem يُشغِّل src/apothem/__main__.py، الذي يستدعي apothem.cli:main — مجموعة أوامر Click.
• تستدعي مدخلات الخطّافات في settings.json / hooks.json المُجسَّدة المُوزِّع (وبالنسبة إلى Claude Code، بوّابة المطابقة في <harness-root>/apothem/conformity/gate.py) بمسار سكربت مطلق. كلاهما سكربتان قائمان بذاتهما من المكتبة القياسية يُمهِّدان sys.path الخاصّ بهما، وتسافر تجهيزات مخطّط البوّابة بجانبه في <harness-root>/apothem/schemas/، فتعمل الخطّافات دون أيّ حزمة apothem قابلة للاستيراد على المضيف. تحمل القوالب رمزًا ${HARNESS_ROOT} يُحوِّله apothem install إلى مسار جذر إطار العمل الحقيقي بصيغة الشرطة المائلة الأمامية.
• من نسخة مصدر محلية، تُشغِّل صيغتا الوحدة python -m apothem.hooks.dispatch و python -m apothem.conformity.gate الشيفرة نفسها للتطوير.

يصبح دليل الحزمة قابلًا للاستيراد بتقديم دليل src/ من النسخة المحلية إلى مقدّمة PYTHONPATH:

PYTHONPATH="$HOME/.apothem/src" python -m apothem <command>

هذا هو الاستدعاء نفسه الذي يطبعه المُثبِّت ذو الخطوة الواحدة عند الاكتمال.

تمهيد شجرة الإضافة

تَحزِم إضافة Claude Code المحرّك تحت <plugin_root>/lib/apothem بدلًا من الاعتماد على PYTHONPATH. تكشف وحدة التمهيد apothem.lib.plugin_bootstrap عن bootstrap_syspath، الذي يُقدِّم بصورة عَطُوفة <plugin_root>/lib ودليل vendor إلى مقدّمة sys.path بحيث يُحَلّ import apothem وكلّ تبعية مُدمَجة من شجرة الإضافة. الشجرة المُشوَّهة (غياب lib/) تُطلِق PluginBootstrapError بدلًا من استيراد نسخة نظام بائتة في صمت.

ما يضعه المُثبِّت على القرص

يضع المُثبِّتون المعتمدون على السكربتات نسخة git من شجرة المصدر في ~/.apothem (يُتجاوَز بـ APOTHEM_HOME) ويُشغِّلون المحرّك منها — لا تُثبَّت أيّ حزم Python في site-packages بخلاف عرض المتطلّب الاختياري click / rich. النسخة هي المستودع الكامل، بما في ذلك مجموعة الاختبارات وموقع التوثيق اللذين لا تستوردهما بيئة التشغيل أبدًا، لسببين مقصودين: المحرّك يُجسِّد cohort الخاصّة به — القواعد والمهارات والأوامر والقوالب — مباشرةً من الشجرة إلى كلّ إطار عمل، فتكون الشجرة مصدر الحقيقة الحيّ لا بيئة تشغيل فحسب؛ ويبقى دليل .git في مكانه ليُسرِّع apothem update النسخة الموجودة قُدُمًا بدلًا من إعادة التنزيل.

هذا التخطيط القائم على التشغيل-من-المصدر هو النمط نفسه الذي تستخدمه أدوات مثل nvm وpyenv وoh-my-zsh — بضعة ميغابايت من المصدر زائد التاريخ، قابلة للإزالة في خطوة واحدة بأداة إلغاء التثبيت (لا توجد حالة نظام يلزم فكّها). البصمة الأنحف — نسخة محلية ضحلة أو متفرّقة تُسقِط tests/ وsite/ — ممكنة، لكنّها ستُبادل مسار التحديث الموضعي المُتحقَّق بالتوقيع المعتمد على git؛ يُفضِّل التخطيط الحالي تحديثًا بسيطًا قابلًا للتحقّق على أقلّ قرص.

كيف تجد بيئة التشغيل Python

يحدِّد المُثبِّتون ذوو الخطوة الواحدة ورقعة npx المفسّر بالطريقة نفسها: يسبرون python3 وpython والأسماء المُؤصَّلة بالإصدار (من python3.14 إلى python3.10) وpy -3 على Windows؛ ويرفضون رقع مُشغِّل Microsoft Store؛ ويقبلون أوّل مرشّح يُبلِّغ عن الإصدار 3.10 أو أحدث. عند التشغيل من شجرة مصدر، يُعيد المُثبِّتون استخدام المُحدِّد المُجمَّع hooks/lib/find-python، الذي يطبّق الحدّ الأدنى نفسه.

الخطوة التالية المُوصى بها

شغِّل python -m apothem --help مع دليل src/ من النسخة المحلية على PYTHONPATH للتأكّد من أنّ مسار CLI المكتفي بذاته يُحَلّ على مضيفك.