التثبيت

يُثبَّت Apothem في أقل من دقيقتين ويعمل جنبًا إلى جنب مع تهيئة إطار العمل القائمة لديك. يشغّل كل مسار المحرّكَ المكتفي ذاتيًا نفسه — تحمل شجرة المصدر اعتماديّاتها المُضمَّنة وتعمل من نسخة مسحوبة على Python النظام بالنسخة 3.10 أو أحدث (راجع زمن التشغيل المكتفي ذاتيًا).

متطلّبان مُسبقان يشترك فيهما كل مسار: Python 3.10 أو أحدث المُثبَّت على النظام والموجود على PATH، مع إمكانية استيراد الحزمتين click وrich تحته. ويحتاج غلاف npm (القناة 2)، وامتداد عائلة VS Code (القناة 4)، ومداخل سطر الأوامر التمهيدية (القنوات 5–7) كذلك إلى Node.js 18 أو أحدث لتشغيل npx. تجاوزت Python 3.10 وNode.js 18 و20 نهاية عمرها لدى المصدر الأصلي؛ وهي لا تزال مدعومة ومُختبَرة، لكن النسخ الأحدث مُفضَّلة (راجع المتطلّبات المُسبقة بلمحة). يكرّر قسم كل قناة أدناه متطلّباتها المُسبقة بالضبط، وأمرًا واحدًا جاهزًا للنسخ، وخطوة تحقّق.

اختر قناةCopy Anchor Link

تتوفّر ثماني قنوات تثبيت. اختر بحسب طريقة عملك الحالية.

كل مسار متساوي الأثر عند التكرار: إعادة التشغيل آمنة وتتقارب إلى الحالة نفسها.

1. إضافة Claude CodeCopy Anchor Link

المتطلّبات المُسبقة: Claude Code، وPython 3.10+ المُثبَّت على النظام والموجود على PATH.

يعمل مسار الإضافة بالكامل داخل Claude Code. فهو يحزم محرّك Apothem مع أوامر الشرطة المائلة الخاصة به، والعمّال المُفوَّضين، والمهارات، والقواعد، والخطّافات، وكلها قابلة للتشغيل من شجرة الإضافة المكتفية ذاتيًا:

/plugin marketplace add ahmed-g-gad/apothem
/plugin install apothem@apothem

بعد التثبيت، تصبح مجموعة أوامر Apothem، والعمّال المُفوَّضون المرفقون، والمهارات، وأنماط الإخراج الأربعة (اختر أحدها عبر /output-style أو من /config) متاحةً في كل جلسة Claude Code. تشحن الإضافة كل أمر بوصفه مهارة، أي ملف SKILL.md تقع التفاصيل التي يحمّلها عند الطلب في مجلد references/ بجانبه، لذا يستدعيه Claude Code ببادئة الإضافة: /apothem:plan-spec، و/apothem:security-audit، وسائرها. واسمان يحجزهما Claude Code نفسه: /plan يدخل وضع التخطيط، و/code-review يشغّل المراجعة المرفقة، لذا اكتب /apothem:plan و/apothem:code-review لأوامر Apothem. وعندما يتولّى محرّك Apothem التثبيت في Claude Code بدلًا من الإضافة، تُكتَب المهارات نفسها في ~/.claude/skills/ بلا بادئة، وتحلّ مهارة code-review شخصية محلّ /code-review المرفق (ويظلّ اسمه البديل /review يشغّل الأمر المرفق). واسمان، projectify وworkflow، هما أيضًا مهارتان أصليّتان؛ والمهارة الأصلية هي التي تشحنها الإضافة وتثبيت المحرّك، لا مهارةً مشتقّة من الأمر. راجع Claude Code لمعرفة كيف تُقسَّم الأوامر، وأوامر الشرطة المائلة للاطّلاع على الكتالوج الكامل للأوامر.

التحقّق: شغِّل /plugin داخل Claude Code وتأكّد من أن apothem مُدرَج بوصفه مُثبَّتًا، أو افحص تقرير الانحراف من طرفية:

npx @ahmed-g-gad/apothem verify --harness claude-code

2. غلاف npm (npx)Copy Anchor Link

المتطلّبات المُسبقة: Node.js 18+ (لأجل npx) وPython 3.10+ المُثبَّت على النظام والموجود على PATH. يحدّد الغلاف موقع المُفسِّر ويمرّر كل أمر من أوامر CLI إلى المحرّك المرفق — ولا يُوضَع شيء بصفة دائمة على نظامك. يجرّب python3، ثم python، ثم py -3 بهذا الترتيب؛ اضبط APOTHEM_PYTHON على مسار مُفسِّر ليجرّبه الغلاف أولًا، وهذا ما تحتاج إليه حين يكون Python مُثبَّتًا لكنه ليس على PATH، أو حين تكون عدّة نسخ منه مُثبَّتة وتريد نسخة بعينها. ويظلّ على المُفسِّر الذي تُسمّيه أن يجتاز فحص Python 3.10+؛ وحين لا يجتازه يعود الغلاف إلى python3، ثم python، ثم py -3.

npx @ahmed-g-gad/apothem install --harness claude-code

على جهاز لا ملف تعريفي فيه، يُنشئ هذا الأمر install الأول الملفَ التعريفي الأوّلي في ~/.config/apothem/profile.yaml ويُعلِمك بذلك. حقول الهوية فيه قيم نائبة: خصِّصها (npx @ahmed-g-gad/apothem profile edit)، ثم أعِد تشغيل الأمر مع update بدلًا من install لتطبيقها.

ويعمل أيضًا مباشرةً من المستودع:

npx github:ahmed-g-gad/apothem install --harness claude-code

يعمل كل أمر في مرجع CLI بهذه الصيغة؛ ضع npx @ahmed-g-gad/apothem مكان apothem. وهذا أيضًا مسار التثبيت لـ OpenCode ولكل أداة أخرى لا تكشف سجلًّا منفصلًا للإضافات أو الامتدادات — يُزامِن Apothem تلك الأدوات مباشرةً في دليل تهيئتها الأصلي (npx @ahmed-g-gad/apothem install --harness opencode).

التحقّق:

npx @ahmed-g-gad/apothem --version
npx @ahmed-g-gad/apothem verify --harness claude-code

3. المُثبِّتات بخطوة واحدةCopy Anchor Link

المتطلّبات المُسبقة: Python 3.10+ المُثبَّت على النظام والموجود على PATH (يعرض المُثبِّت إضافة المتطلّبين المُسبقين click / rich نيابةً عنك)؛ وgit وgpg لتثبيت شبكي يستنسخ المصدر ويتحقّق من وسم الإصدار الموقَّع التابع له (يأتي كلاهما مع Git for Windows).

تحدّد سكربتات المُثبِّت أحدث وسم إصدار موقَّع، وتتحقّق من توقيعه، وتضع شجرة مصدر Apothem في ~/.apothem عند ذلك الوسم، وتُنشئ ملفًا تعريفيًا أوّليًا حين لا يوجد أي ملف تعريفي، وتُجسِّد إطار عملك الأول، وتتحقّق من النتيجة، كل ذلك في تشغيل واحد. يحمل الملف التعريفي الأوّلي حقول هوية نائبة: حرِّره، ثم شغِّل apothem update --harness <name> لتطبيق هويتك. إعادة التشغيل متساوية الأثر: تُسحَب الشجرة الموجودة من جديد عند الوسم المُحدَّد، ويُعاد تجسيد إطار العمل. التثبيت المُتحقَّق منه والمُثبَّت على وسم هو المسار الافتراضي والموصى به.

استورِد مفتاح توقيع المشرف مرةً واحدة أولًا. يتوقّف المُثبِّت حين لا يكون المفتاح في حلقة المفاتيح لديك. تحقّق من أن البصمة هي 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163، وهي القيمة التي تنشرها SECURITY.md. على Windows، يقرأ git verify-tag حلقة مفاتيح gpg الذي يأتي مع Git for Windows، لذا يُنفَّذ الاستيراد عبر bash الخاص بـGit نفسه:

curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import
gpg --fingerprint 70396FED9C634163

& "$env:ProgramFiles\Git\bin\bash.exe" -c 'curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import && gpg --fingerprint 70396FED9C634163'

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

irm https://apothem.ahmedgad.com/install.ps1 | iex

تُشحَن السكربتات نفسها في النسخة المسحوبة تحت scripts/installer/ — install وuninstall وupdate بصيغ .sh و.ps1 و.bat — فيمكنك تشغيلها مباشرةً بعد الاستنساخ:

APOTHEM_HARNESS=claude-code sh scripts/installer/install.sh                                 # POSIX
$env:APOTHEM_HARNESS = 'claude-code'; pwsh -NoProfile -File scripts/installer/install.ps1   # Windows

نموذج الثقةCopy Anchor Link

حين لا يكون APOTHEM_REF مضبوطًا، يحدّد المُثبِّت أعلى وسم إصدار vMAJOR.MINOR.PATCH ويسحب ذلك الوسم — ولا يسحب أبدًا فرع main المتحرّك. وقبل تجسيد أي تهيئة، يُتحقَّق من توقيع الوسم المجلوب عبر git verify-tag؛ والوسم غير الموقَّع، أو المُتلاعَب به، أو غير القابل للتحقّق يُجهِض التثبيت قبل كتابة أي شيء. أما الوسم الموقَّع الذي لم يدخل المفتاحُ العام لمشرفه حلقةَ المفاتيح المحلية بعد، فيُجهِض التثبيت مع إرشادات لاستيراد المفتاح بدلًا من ذلك: استورِد المفتاح كما هو مُبيَّن أعلاه، وطابِق بصمته مع القيمة المنشورة في SECURITY.md، ثم أعِد التشغيل. ثبِّت إصدارًا بعينه عبر APOTHEM_REF:

APOTHEM_REF=vMAJOR.MINOR.PATCH sh -c "$(curl -fsSL https://apothem.ahmedgad.com/install.sh)"

استبدل vMAJOR.MINOR.PATCH بوسم من صفحة الإصدارات. أقدم وسم إصدار وسمٌ خفيف لا يحمل توقيعًا خاصًّا به، لذا يُجهِض فحص الوسم عنده رغم أن الكوميت الخاص به موقَّع؛ وكل وسم إصدار لاحق مُعلَّق وموقَّع. يسرد قسم توقيع الإصدارات في SECURITY.md كل وسم وكيفية التحقّق منه.

تُرخي التجاوزات الصريحة السلوك الافتراضي. فـAPOTHEM_ALLOW_UNVERIFIED=1 يخفّض فشل التحقّق إلى تحذير ويتابع، وذلك للاستخدام المعزول عن الشبكة أو المحلي، أو لتثبيت إصدار يسبق توقيع الوسوم. أما APOTHEM_REF=main فيسحب الفرع المتحرّك دون تحقّق، ولكن فقط مع APOTHEM_ALLOW_UNVERIFIED=1. ومع APOTHEM_REF=main وحده، يجلب المُثبِّت الفرعَ main إلى APOTHEM_HOME ثم يُجهِض قبل تجسيد أي تهيئة، لأن الفرع ليس وسم إصدار موقَّعًا. وأما النسخة المسحوبة المحلية عبر APOTHEM_SOURCE فلا تجلب شيئًا وتتخطّى التحقّق.

APOTHEM_VERIFY=checksum هو الطريق الوسط لمضيف لا يحمل المفتاح العام للمشرف بعد: بدلًا من الاستنساخ، ينزّل المُثبِّت أرشيف المنصّة الخاص بالإصدار وملف SHA256SUMS الخاص به، ويُجهِض عند عدم تطابق البصمة قبل استخراج أي شيء، وينبّه إلى أن البصمة المطابقة تُثبت أن الأرشيف هو الذي يسرده الإصدار، لا هويةَ من نشره.

ثم يعمل المحرّك مباشرةً من الشجرة الموضوعة. كل اعتمادية من طرف ثالث باستثناء click وrich مُضمَّنة داخل شجرة المصدر، وتضع نقطة الدخول دليل الاعتماديات المُضمَّنة ذاك على sys.path بنفسها:

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

يقرأ كلا السكربتين متغيّرات بيئة التهيئة نفسها (APOTHEM_HOME، وAPOTHEM_REPO، وAPOTHEM_REF، وAPOTHEM_ALLOW_UNVERIFIED، وAPOTHEM_VERIFY، وAPOTHEM_RELEASE_BASE، وAPOTHEM_SOURCE، وAPOTHEM_HARNESS، وAPOTHEM_PROFILE، وAPOTHEM_SKIP_VERIFY، وAPOTHEM_AUTO_INSTALL_DEPS، وAPOTHEM_BIN_DIR)؛ راجع متغيّرات بيئة المُثبِّت للجدول الكامل، وزمن التشغيل المكتفي ذاتيًا لمعرفة كيف يعمل نموذج الاستدعاء python -m.

الأمر apothem. بعد تثبيت ناجح، يكتب المُثبِّت غلاف apothem يمرّر الأوامر إلى المحرّك المرفق — على POSIX في $HOME/.local/bin، وعلى Windows في %LOCALAPPDATA%\Microsoft\WindowsApps (وهو دليل مستخدم موجود أصلًا على PATH الافتراضي في Windows). لا يحرّر المُثبِّت PATH الخاص بك أبدًا. وبمجرّد أن يصبح الدليل على PATH تشغّل apothem <command> مباشرةً، دون PYTHONPATH يدوي.

التحقّق:

apothem verify --harness claude-code

# or, before the shim is on PATH, from the bundled source:
PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code

4. امتداد عائلة VS CodeCopy Anchor Link

المتطلّبات المُسبقة: VS Code، وNode.js 18+، وPython 3.10+ المُثبَّت على النظام والموجود على PATH.

امتداد Apothem for VS Code متاح على Visual Studio Marketplace بالمعرّف ahmed-g-gad.apothem-vscode، ويُثبَّت من عرض الامتدادات أو بالأمر code --install-extension ahmed-g-gad.apothem-vscode. ويُثبَّت أيضًا من حزمة apothem.vsix: code --install-extension apothem.vsix، أو أمر Install from VSIX… في المحرِّر. يوقّع سير عمل الإصدار الحزمةَ ويرفقها بكل إصدار GitHub. الإصدارات المنشورة قبل أن يحزّم سير العمل الامتداد لا تحمل أي ملف .vsix؛ وحين يخلو منه أحدث إصدار، ابنِ الحزمة من نسخة مسحوبة باستخدام إصدار vsce المقفل في tools/vsce/ (يتطلّب إصدار vsce هذا Node.js 22 أو أحدث): شغِّل npm ci --prefix tools/vsce --ignore-scripts، ثم cd vscode-extension && ../tools/vsce/node_modules/.bin/vsce package --no-dependencies --out apothem.vsix. تحمل نسخةٌ مُثبَّتة سابقًا من apothem.vsix المُعرِّفَ ahmed-g-gad.apothem؛ أزِلها (code --uninstall-extension ahmed-g-gad.apothem) حتى لا تسجّل النسختان معًا الأوامرَ نفسها. يغطّي امتداد واحد محرِّرات عائلة VS Code. تشغّل أوامره في لوحة الأوامر (Apothem: Install، وVerify، وUpdate، وUninstall، وDoctor) المحرّكَ نفسه عبر المُشغِّل المُهيَّأ (npx @ahmed-g-gad/apothem@<extension version> افتراضيًا، فيشغّل الامتداد نسخة المحرّك التي شُحن معها؛ وجِّه إعداد المستخدم apothem.runner إلى نسخة مسحوبة محلية للتشغيل من المصدر). تسأل الأوامر Install وVerify وUpdate وUninstall عن إطار العمل الذي تعمل عليه، وتعرض إطار عمل المحرِّر نفسه أولًا؛ وall أحد الخيارات، ولا يكون الافتراضي أبدًا. إعداد apothem.runner على نطاق الجهاز، فلا تستطيع مساحة عمل تغييره، ولا يعمل الامتداد إلا في مساحة عمل موثوقة.

التحقّق: شغِّل الأمر Apothem: Verify من لوحة أوامر المحرِّر، أو من طرفية:

npx @ahmed-g-gad/apothem verify --harness claude-code

5. مدخل سطر الأوامر التمهيدي (مضيف الامتدادات)Copy Anchor Link

المتطلّبات المُسبقة: أداة سطر الأوامر المضيفة له، وNode.js 18+، وPython 3.10+ المُثبَّت على النظام والموجود على PATH.

ثبِّت Apothem بوصفه امتدادًا مباشرةً من المستودع — يحمل الأمر المضيفَ ومُعرِّفَ إطار العمل الدقيقين:

gemini extensions install https://github.com/ahmed-g-gad/apothem

هذا الامتداد مدخل تمهيدي، لا التثبيت الكامل بمفرده: فهو يحمّل ملف سياق Apothem ويضيف أمر /apothem يستدعي المحرّك عبر الصدفة (npx @ahmed-g-gad/apothem). جسِّد إطار العمل الكامل بتشغيل التثبيت عبره:

npx @ahmed-g-gad/apothem install --harness gemini-cli --project .

التحقّق:

npx @ahmed-g-gad/apothem verify --harness gemini-cli --project .

6. مدخل سطر الأوامر التمهيدي (مضيف qwen-code)Copy Anchor Link

المتطلّبات المُسبقة: أداة سطر الأوامر المضيفة له، وNode.js 18+، وPython 3.10+ المُثبَّت على النظام والموجود على PATH.

ثبِّت Apothem بوصفه امتداد --harness qwen-code مباشرةً من المستودع:

qwen extensions install ahmed-g-gad/apothem

مثل امتداد القناة 5، هذا مدخل تمهيدي: يحمّل ملف سياق Apothem ويستدعي المحرّك عبر الصدفة. جسِّد إطار العمل الكامل بتشغيل التثبيت عبره:

npx @ahmed-g-gad/apothem install --harness qwen-code

التحقّق:

npx @ahmed-g-gad/apothem verify --harness qwen-code

7. مدخل سطر الأوامر التمهيدي (مضيف الإضافات)Copy Anchor Link

المتطلّبات المُسبقة: أداة سطر الأوامر المضيفة له، وNode.js 18+، وPython 3.10+ المُثبَّت على النظام والموجود على PATH.

أضِف المستودع بوصفه سوق إضافات، ثم ثبِّت الإضافة — يحمل الأمر المضيفَ ومُعرِّفَ إطار العمل الدقيقين:

codex plugin marketplace add ahmed-g-gad/apothem --sparse .agents/plugins --sparse plugins/apothem
codex plugin add apothem@apothem

يجلب مسارا --sparse قائمةَ السوق والإضافةَ فقط، لا المستودع كله؛ فقد يتجاوز الاستنساخ الكامل حدّ الاستنساخ لدى المضيف البالغ 30 ثانية على قرص بطيء، مثل محرّك أقراص Windows تحت WSL.

مثل امتدادَي القناتين 5 و6، هذا مدخل تمهيدي يستدعي المحرّك عبر الصدفة. تحزم الإضافة مهارة دخول واحدة؛ وبيانها ملف plugin.json في الجذر، وتصف صفحة إطار العمل الخاصة بمضيف الإضافات البنيةَ وما تتركه الإضافة للمحرّك. جسِّد إطار العمل الكامل بتشغيل التثبيت عبره:

npx @ahmed-g-gad/apothem install --harness codex

التحقّق:

npx @ahmed-g-gad/apothem verify --harness codex

8. المحرّك المباشر (python -m apothem)Copy Anchor Link

المتطلّبات المُسبقة: Python 3.10+ المُثبَّت على النظام مع إمكانية استيراد الحزمتين click وrich، إضافةً إلى نسخة مسحوبة من المستودع. لا يلزم Node.js.

شغِّل المحرّك مباشرةً من نسخة مستنسَخة. تضع نقطة الدخول الاعتماديات المُضمَّنة (src/apothem/_vendor) على sys.path، فمع إمكانية استيراد click وrich، يكون PYTHONPATH=src هو الإعداد كله:

git clone https://github.com/ahmed-g-gad/apothem
cd apothem
PYTHONPATH=src python -m apothem install --harness claude-code

كما في غلاف npm، يُنشئ أول install على جهاز لا ملف تعريفي فيه الملفَ التعريفي الأوّلي في ~/.config/apothem/profile.yaml ويتابع.

التحقّق:

PYTHONPATH=src python -m apothem verify --harness claude-code

التحقّق من أي تثبيتCopy Anchor Link

تُسمّي كل قناة أعلاه أمر التحقّق الخاص بها. والصيغتان العامّتان هما:

PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code

npx @ahmed-g-gad/apothem verify --harness claude-code

استبدل اسم إطار العمل بأيّ محوّل ثبّتَّه؛ راجع قائمة أُطُر العمل لكل الأسماء المدعومة. ولفحص كل محوّل مُثبَّت دفعةً واحدة (أمر التحقّق الخاص به وأوامر خطّافاته)، شغِّل doctor بدلًا من verify --harness NAME، بأيّ صيغة استخدمتها أعلاه: apothem doctor، أو PYTHONPATH="$HOME/.apothem/src" python -m apothem doctor، أو npx @ahmed-g-gad/apothem doctor. وفي مسار الإضافة، شغِّل /plugin داخل Claude Code وتأكّد من أن apothem مُدرَج بوصفه مُثبَّتًا.

المتطلّبات المُسبقة بلمحةCopy Anchor Link

• Python 3.10 أو أحدث — المسارات التي تحدّد موقعه تفعل ذلك بالاسم، وتختلف الأسماء من مسار إلى آخر. يجرّب غلاف npm الأسماء python3، ثم python، ثم py -3. وتجرّب المُثبِّتات python3، وpython، والأسماء المقرونة برقم النسخة من python3.14 نزولًا إلى python3.10.
• إمكانية استيراد click وrich تحت ذلك المُفسِّر — وهما الاعتماديتان المواجهتان للطرفية اللتان لا يُضمِّنهما المحرّك. تفحص المُثبِّتات كلتيهما، وتُسمّي أي ناقص منهما، وتعرض تثبيته نيابةً عنك — بتأكيد منك، أو تلقائيًا عبر --yes (-Yes في PowerShell) أو APOTHEM_AUTO_INSTALL_DEPS=1. وفي كل قناة أخرى، تُوقِف الحزمة الناقصة المحرّكَ بخطأ (رمز الخروج 1) يُسمّي الأمر الدقيق للمُفسِّر الذي وجده، مع قيود النسخ التي يُختبَر Apothem عليها (<interpreter> -m pip install "click==…" "rich>=…")؛ ومع --json يصل الخطأ نفسه بوصفه مُغلَّف JSON بالرمز runtime.dependency_missing.
• Node.js 18 أو أحدث — فقط المسارات التي تشغّل npx: غلاف npm (2)، وامتداد عائلة VS Code (4)، ومداخل سطر الأوامر التمهيدية (5–7).
• بيئات التشغيل المنتهية العمر. بلغ Python 3.10 نهاية عمره لدى المصدر الأصلي في 2026-10-01، وبلغها Node.js 18 و20 في 2025-04-30 و2026-04-30. لا يزال Apothem يدعمها بوصفها حدوده الدنيا المُعلَنة ويختبر كلًّا منها في CI، لكنها لم تعد تتلقّى إصلاحات أمنية من المصدر الأصلي، لذا فضِّل Python 3.11 أو أحدث وNode.js 22 أو أحدث. تشرح سياسة الحدود الدنيا لبيئة التشغيل كيف يُرفَع حدّ أدنى.
• Git — لمسار المُثبِّت فقط، وللصيغة الشبكية فقط (يستنسخ السكربت المصدر؛ ولا تحتاج النسخة المسحوبة المحلية إلى استنساخ).
• Claude Code — لمسار الإضافة فقط. أما VS Code والأداة المضيفة الخاصة بكل مدخل تمهيدي لسطر الأوامر فلا تلزم إلا لقناتها الخاصة (4–7).

الأدلّة التاليةCopy Anchor Link