زمن التشغيل المكتفي ذاتيًاCopy Anchor Link

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

شجرة الاعتماديات المُضمَّنةCopy Anchor Link

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

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

تتقدّم النُّسَخ المُضمَّنة على أي نسخة مُثبَّتة على النظام: فكلٌّ من تمهيد الإضافة، وغلاف npm، والمُثبِّتات، ونقطة الدخول python -m apothem نفسها يضع دليل الاعتماديات المُضمَّنة في sys.path قبل site-packages. وسياسة الاختيار — ما الذي يُضمَّن، وما الذي لا يُضمَّن، وكيف تُحدَّث الحزم المُضمَّنة — موثَّقة في استراتيجية تضمين الاعتماديات.

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

نموذج الاستدعاء python -mCopy Anchor Link

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

• يُشغِّل python -m apothem الملف src/apothem/__main__.py، الذي يضع src/apothem/_vendor في sys.path، ويتحقّق من أن click وrich قابلتان للاستيراد، ثم يستدعي apothem.cli:main — مجموعة أوامر Click.
• تستدعي مدخلات الخطّافات في settings.json / hooks.json المُجسَّدين المُوزِّعَ (وبالنسبة إلى Claude Code، بوابةَ المطابقة في <harness-root>/.apothem/support/conformity/gate.py) بمسار السكربت المطلق. وكلاهما سكربت قائم بذاته من المكتبة القياسية يُمهِّد sys.path الخاص به، وتنتقل تجهيزات مخططات البوابة بجوارها في <harness-root>/.apothem/support/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>

عندما لا يكون مُشغِّل apothem على PATH، يطبع install.sh هذه الصيغة عند اكتماله، مع وضع الدليل المُضمَّن قبل src/، وبمُفسِّر CPython الذي حلّه المُثبِّت بدلًا من python. ويطبع install.ps1 الإعدادين نفسيهما بصيغة PowerShell: إسنادٌ إلى $env:PYTHONPATH يصل الدليل المُضمَّن ودليل src/ بالفاصلة المنقوطة ;، ثم & '<CPython>' -m apothem <command>.

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

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

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

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

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

كيف يعثر زمن التشغيل على PythonCopy Anchor Link

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

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

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