متغيّرات بيئة المُثبِّت
تحكّم في مُثبِّت السكربت (الوجهة، والمصدر، وإطار العمل، والملف التعريفي، والتحقّق) بمتغيّرات البيئة.
الهدف: التحكّم في install.sh / install.ps1 دون تحرير السكربت،
بضبط متغيّرات البيئة قبل تشغيله.
المتطلّبات المسبقة
- صدفة POSIX (
bash) أو PowerShell 5.1+. تُشغِّل أمثلة PowerShell أدناه الأمرpwsh(PowerShell 7+). وفي Windows PowerShell 5.1 شغِّل بدلًا من ذلك الأمرpowershell -NoProfile -ExecutionPolicy Bypass -File install.ps1. - تُقرأ المتغيّرات مرة واحدة في بداية المُثبِّت، لذا اضبطها في الأمر نفسه (أو صدِّرها أولًا)، ثم شغِّل المُثبِّت.
متغيّرات المُثبِّت
| المتغيّر | يتحكّم في | القيمة الافتراضية |
|---|---|---|
APOTHEM_HOME | وجهة التثبيت لشجرة المصدر المُستنسَخة | $HOME/.apothem |
APOTHEM_REPO | مستودع Git البعيد المراد استنساخه | https://github.com/ahmed-g-gad/apothem |
APOTHEM_REF | مرجع Git المراد سحبه؛ وغير المضبوط يَحُلّ أحدث وسم vMAJOR.MINOR.PATCH موقَّع، وقيمة الوسم تثبّته، وmain يختار الفرع المتحرّك. ويُجهَض التثبيت عند أي مرجع ليس وسمًا، مثل main، ما لم يُضبَط APOTHEM_ALLOW_UNVERIFIED=1 | غير مضبوط (أحدث وسم موقَّع) |
APOTHEM_ALLOW_UNVERIFIED | يُخفِّض فشل التحقّق من توقيع الوسم من إجهاض فادح إلى تحذير عند ضبطه على 1 | 0 (يتحقّق، ويرفض عند الفشل) |
APOTHEM_VERIFY | signature يتحقّق من توقيع GPG لوسم الإصدار؛ وchecksum يُثبِّت أرشيف المنصّة الخاص بالإصدار بعد فحص بصمة SHA-256 الخاصة به مقابل ملف SHA256SUMS الخاص بالإصدار (سلامة، لا إثبات لهوية من نشره) | signature |
APOTHEM_RELEASE_BASE | قاعدة التنزيل لوضع التحقّق بالمجموع الاختباري | <APOTHEM_REPO>/releases/download |
APOTHEM_SOURCE | شجرة مصدر محلية صريحة تُستخدَم بدلًا من الاستنساخ | غير مضبوط (استنساخ) |
APOTHEM_HARNESS | إطار العمل ذو نطاق المستخدم المراد تثبيته (antigravity، claude-code، codex، hermes، open-claw، opencode، qwen-code). لا يمرّر المُثبِّت --project، لذا يفشل إطار العمل ذو نطاق المشروع بالرمز project.required؛ ثبِّت تلك الأُطُر بعد ذلك بالأمر apothem install --harness NAME --project PATH. | claude-code |
APOTHEM_PROFILE | مسار ملف YAML للملف التعريفي المشترك | $HOME/.config/apothem/profile.yaml |
APOTHEM_SKIP_VERIFY | يتخطّى خطوة التحقّق اللاحقة للتثبيت عند ضبطه على 1 | 0 (يعمل التحقّق) |
APOTHEM_AUTO_INSTALL_DEPS | يُثبِّت المتطلّبات المسبقة المفقودة click / rich تلقائيًا، دون مطالبة، عند ضبطه على 1 | 0 (يطالب، أو يرفض في أنبوب غير تفاعلي) |
APOTHEM_BIN_DIR | دليل غلاف الأمر apothem الذي يضعه المُثبِّت | $HOME/.local/bin (POSIX)؛ %LOCALAPPDATA%\Microsoft\WindowsApps (Windows) |
NO_COLOR | يُطفئ الخرج الملوَّن عند ضبطه على أي قيمة (no-color.org)؛ ويكون التلوين مُطفأً أيضًا كلما لم يكن الخرج طرفية (أنبوب، أو ملف، أو سجلّ CI) | غير مضبوط (التلوين على طرفية تفاعلية فقط) |
يتقدّم APOTHEM_SOURCE على الاستنساخ: عند ضبطه على نسخة مسحوبة تحتوي
على src/apothem، يستخدمها المُثبِّت مباشرةً، ولا يمسّ
APOTHEM_REPO / APOTHEM_REF أبدًا، ويتخطّى حلّ الوسم
والتحقّق من التوقيع (لا يُجلَب شيء للتحقّق منه).
عندما يشير APOTHEM_HOME إلى دليل موجود ليس نسخة git
مُستنسَخة، يرفض المُثبِّت حذفه: انقله جانبًا، أو وجِّه APOTHEM_HOME
إلى مكان آخر، أو مرِّر --yes (-Yes على
Windows) للتصريح بالاستبدال. أما الدليل الفارغ المتقادم فيُستبدَل دون
الراية.
نموذج الثقة
حين لا يكون APOTHEM_REF مضبوطًا، يَحُلّ المُثبِّت أحدث وسم إصدار
موقَّع ويتحقّق من توقيعه بالأمر git verify-tag قبل تجسيد أي إعداد؛
والوسم غير الموقَّع أو المُتلاعَب به يُجهِض التثبيت. أما الوسم الموقَّع الذي يغيب
المفتاح العام لمشرفه عن حلقة المفاتيح المحلية فيُجهِض التثبيت بدلًا من ذلك مع
إرشادات لاستيراد المفتاح — استورِد المفتاح وطابِق بصمته مع القيمة المنشورة في
SECURITY.md.
ثبِّت إصدارًا معروفًا عبر APOTHEM_REF=<tag>، آخذًا الوسم من
صفحة الإصدارات؛ ويُتحقَّق من
الوسم المثبَّت بالطريقة نفسها. اختر الفرع المتحرّك عبر APOTHEM_REF=main
مع APOTHEM_ALLOW_UNVERIFIED=1؛ ذلك التثبيت غير مُتحقَّق منه، ويُجهِض
main وحده التثبيت لأن الفرع ليس وسمًا موقَّعًا. اضبط
APOTHEM_ALLOW_UNVERIFIED=1 وحده للمضيّ بعد فشل التحقّق مع تحذير
(للاستخدام المعزول عن الشبكة، أو المحلي، أو مع الإصدارات السابقة لاعتماد التوقيع).
APOTHEM_REF=vMAJOR.MINOR.PATCH bash install.shAPOTHEM_VERIFY=checksum bash install.shAPOTHEM_ALLOW_UNVERIFIED=1 bash install.shالخطوات (POSIX bash)
-
ثبِّت إطار عمل غير افتراضي ذا نطاق المستخدم:
APOTHEM_HARNESS=codex bash install.sh -
قيِّد وجهة التثبيت، واختر الفرع المتحرّك
main. فالفرع ليس وسمًا موقَّعًا، لذلك يحتاج المُثبِّت أيضًا إلىAPOTHEM_ALLOW_UNVERIFIED=1:APOTHEM_REF=main APOTHEM_ALLOW_UNVERIFIED=1 APOTHEM_HOME=/opt/apothem bash install.sh -
استخدم نسخة مسحوبة محلية وملفًا تعريفيًا مخصّصًا، مع تخطّي التحقّق:
APOTHEM_SOURCE=/work/apothem \ APOTHEM_PROFILE=/work/profile.yaml \ APOTHEM_SKIP_VERIFY=1 \ bash install.sh
الخطوات (PowerShell)
اضبط كل متغيّر على $env: قبل تشغيل المُثبِّت:
$env:APOTHEM_HARNESS = 'codex'
pwsh -NoProfile -File install.ps1$env:APOTHEM_ALLOW_UNVERIFIED = '1'
$env:APOTHEM_REF = 'main'
$env:APOTHEM_HOME = 'C:\opt\apothem'
pwsh -NoProfile -File install.ps1$env:APOTHEM_SOURCE = 'C:\work\apothem'
$env:APOTHEM_PROFILE = 'C:\work\profile.yaml'
$env:APOTHEM_SKIP_VERIFY = '1'
pwsh -NoProfile -File install.ps1التحقّق
يطبع المُثبِّت ✓ Harness <name> installed، ثم (ما لم يكن
APOTHEM_SKIP_VERIFY=1) ✓ verify passed. أكِّد ذلك بشكل
مستقل:
apothem verify --harness codexلإطار عمل ذي نطاق المشروع مثل Cursor، شغِّل التثبيت والتحقّق بنفسك بعد
المُثبِّت، مع --project:
apothem install --harness cursor --project /path/to/project
apothem verify --harness cursor --project /path/to/projectعندما لا يكون الملف التعريفي موجودًا بعد، يُنشئ المُثبِّت ملفًا من المثال ويتابع
إلى التثبيت والتحقّق في التشغيل نفسه. حقول الهوية في المثال عناصر نائبة، لذا
يطبع التثبيت ملاحظة؛ حرِّر $APOTHEM_PROFILE، ثم شغِّل
apothem update --harness <name> لتطبيق هويتك. وتشغيل
--dry-run دون ملف تعريفي يُعايِن باستخدام المثال في مكانه ولا يكتب
شيئًا.
ذات صلة
- يغطّي التثبيت التثبيت الشبكي بخطوة واحدة.
- يغطّي إضافة إطار عمل إضافة أُطُر العمل عبر CLI بعد التثبيت الأول.