استكشاف الأخطاء وإصلاحها

حلول لمشكلات تثبيت Apothem وزمن تشغيله الشائعة.

مشكلات التثبيتCopy Anchor Link

لم يُعثَر على Python 3.10+Copy Anchor Link

تفحص المُثبِّتات python3 وpython والأسماء المُرقَّمة بالإصدار (من python3.14 حتى python3.10) — مع رفض أغلفة مُشغِّل Microsoft Store — وتتوقّف برسالة No Python >= 3.10 found in PATH عندما لا يبلغ أي مرشّح الحدّ الأدنى 3.10. ويفحص غلاف npx المتغيّر APOTHEM_PYTHON إن كان مضبوطًا، ثم python3 وpython وpy -3، ويخرج بالقيمة 1 مع رسالته الخاصة عندما لا يستوفي أي مرشّح الشرط. ثبّت CPython 3.10 أو أحدث من python.org أو من مستودع حِزَم نظام التشغيل لديك، وتأكّد من أنّ python3 --version (أو py -3 --version على Windows) يُبلِغ عن 3.10 على الأقل، ثم أعِد التشغيل.

اعتماديات زمن تشغيل مفقودة: click، richCopy Anchor Link

يُضمِّن المحرّك معظم اعتمادياته من الأطراف الثالثة داخل شجرة المصدر، لكن يجب أن يكون click وrich قابلَيْن للاستيراد تحت المُفسِّر الذي يختاره المُثبِّت. وعندما يكون أيٌّ منهما مفقودًا، يُسمّيه المُثبِّت ويعرض تثبيته نيابةً عنك:

! Missing Python prerequisites under <python>: click rich
  Install click rich under <python> now? [y/N]

اقبَل الطلب ليُشغّل المُثبِّت pip install تحت ذلك المُفسِّر. ولتخطّي الطلب، مرِّر --yes (-Yes على PowerShell) أو اضبط APOTHEM_AUTO_INSTALL_DEPS=1 للتثبيت تلقائيًا. وإن رفضت — أو كان pip غير متاح، أو فضّلت مدير حِزَم نظام التشغيل لديك — فثبّت الحِزَم المُسمّاة بنفسك (مثل python3-click وpython3-rich على مضيفات عائلة Debian، أو pip install click rich) ثم أعِد التشغيل.

لم يُعثَر على apothem بعد تشغيل المُثبِّتCopy Anchor Link

يضع المُثبِّت شجرة المصدر في ~/.apothem، ويكتب غلافًا باسم apothem في ~/.local/bin افتراضيًا (POSIX)، أو في %LOCALAPPDATA%\Microsoft\WindowsApps (Windows). ولا يعدّل PATH لديك. وإذا لم يُعثَر على apothem، فذلك الدليل ليس على PATH؛ أضِفه، أو استخدم صيغة PYTHONPATH الواردة أدناه حتى تفعل ذلك. شغّل المحرّك عبر صيغة الاستدعاء التي يطبعها المُثبِّت عند الاكتمال:

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

أو استخدم صيغة npx (npx @ahmed-g-gad/apothem <command>)، التي لا تحتاج إلى إدخال في PATH.

فشل /plugin marketplace addCopy Anchor Link

يجلب /plugin marketplace add ahmed-g-gad/apothem قائمة سوق الإضافات من GitHub. وعندما يفشل، تأكّد من قدرة الجهاز على الوصول إلى https://github.com/ahmed-g-gad/apothem (قواعد الشبكة أو الوكيل أو جدار الحماية)، ثم أعِد المحاولة. وإذا أُضيف سوق الإضافات سابقًا أثناء عملية جلب جزئية، فأزِله وأعِد إضافته قبل تشغيل /plugin install apothem@apothem.

تنتهي مهلة إضافة سوق مضيف الإضافاتCopy Anchor Link

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

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

يُظهِر سرد إضافات المضيف بعد ذلك النسخة الحالية من apothem@apothem.

يقدّم npx نسخة قديمةCopy Anchor Link

يخزّن npx الحِزَم المُنزَّلة مؤقتًا. وعندما يُبلِغ npx @ahmed-g-gad/apothem --version عن نسخة أقدم من الإصدار الحالي، امسح الذاكرة المؤقتة أو ثبّت وسم التوزيع (dist-tag):

npx clear-npx-cache
npx @ahmed-g-gad/apothem@latest --version

يتوقّف المُثبِّت: المفتاح العام للمشرف غير موجود في حلقة المفاتيح المحليةCopy Anchor Link

يتحقّق المُثبِّت من وسم الإصدار الموقَّع، ويتوقّف حين لا يكون مفتاح التوقيع في حلقة المفاتيح لديك. استورِده مرةً واحدة، وتحقّق من أن البصمة هي 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163، ثم أعِد تشغيل المُثبِّت:

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'

على Windows، استورِد عبر bash الخاص بـGit كما هو مبيّن: يقرأ git verify-tag حلقة مفاتيح gpg الذي يأتي مع Git for Windows. ويمكن لمضيف لا يملك gpg أن يثبّت باستخدام APOTHEM_VERIFY=checksum، الذي يتحقّق من بصمة أرشيف الإصدار بدلًا من توقيع الوسم.

حجب irm / iex على WindowsCopy Anchor Link

إذا حجبت سياسة تنفيذ PowerShell المُثبِّت:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://apothem.ahmedgad.com/install.ps1 | iex

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

لا يجد apothem install أي أُطُر عملCopy Anchor Link

شغّل apothem doctor لقراءة جدول Harness Status، الذي يحوي صفًّا واحدًا لكل إطار عمل. ويعني الصف المُعلَّم بـ not installed أن Apothem لم يجد تثبيتًا لذلك الإطار. والصف المُعلَّم بـ needs --project يخص إطار عمل ذا نطاق مشروع، ولا يفحصه doctor إلا حين تمرّر --project <path>. وإذا أبلغ doctor بـ No harness is installed yet، فتأكّد من تثبيت إطار العمل لديك، ثم شغّل apothem install --harness <name>.

يُبلِغ apothem verify عن محوّل فاشلCopy Anchor Link

أعِد تشغيل apothem install لإعادة تجسيد المحوّل. وإذا استمرّت المشكلة، فراجع الصفحة الخاصة بالمحوّل ضمن محوّلات أُطُر العمل.

الخطّافات لا تُطلَق في Claude CodeCopy Anchor Link

تأكّد من أنّ Apothem موصول عبر فحص ~/.claude/settings.json بحثًا عن إدخالات الخطّاف. وإذا كان الملف يفتقر إلى الخطّافات، فشغّل apothem install مجدّدًا.

الحصول على المساعدةCopy Anchor Link

• مشكلات GitHub -- تقارير الأخطاء
• مناقشات GitHub -- الأسئلة
• الأسئلة الشائعة -- الأسئلة المتكرّرة