Pemecahan masalah

Solusi untuk masalah instalasi dan runtime Apothem yang umum.

Masalah instalasiCopy Anchor Link

Python 3.10+ tidak ditemukanCopy Anchor Link

Pemasang memeriksa python3, python, dan nama-nama berversi (python3.14 sampai python3.10) — menolak shim peluncur Microsoft Store — dan berhenti dengan No Python >= 3.10 found in PATH ketika tidak ada kandidat yang memenuhi batas bawah 3.10. Shim npx memeriksa APOTHEM_PYTHON bila variabel itu disetel, lalu python3, python, dan py -3, dan keluar dengan kode 1 beserta pesannya sendiri ketika tidak ada yang memenuhi syarat. Pasang CPython 3.10 atau yang lebih baru dari python.org atau repositori paket OS Anda, pastikan python3 --version (atau py -3 --version di Windows) melaporkan setidaknya 3.10, lalu jalankan ulang.

Dependensi runtime hilang: click, richCopy Anchor Link

Mesin mem-vendor sebagian besar dependensi pihak ketiganya di dalam pohon sumber, tetapi click dan rich harus dapat diimpor di bawah interpreter yang dipilih pemasang. Ketika salah satunya hilang, pemasang menyebutkan namanya dan menawarkan untuk memasangnya untuk Anda:

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

Terima prompt agar pemasang menjalankan pip install di bawah interpreter tersebut. Untuk melewati prompt, berikan --yes (-Yes pada PowerShell) atau setel APOTHEM_AUTO_INSTALL_DEPS=1 agar pemasangan berjalan otomatis. Jika Anda menolak — atau pip tidak tersedia, atau Anda lebih suka pengelola paket OS Anda — pasang sendiri paket yang disebutkan (misalnya python3-click dan python3-rich pada host keluarga Debian, atau pip install click rich) lalu jalankan ulang.

apothem tidak ditemukan setelah menjalankan pemasangCopy Anchor Link

Pemasang menempatkan pohon sumber di ~/.apothem dan menulis shim apothem ke ~/.local/bin secara bawaan (POSIX) atau %LOCALAPPDATA%\Microsoft\WindowsApps (Windows). Pemasang tidak menyunting PATH Anda. Jika apothem tidak ditemukan, direktori itu tidak ada di PATH; tambahkan direktori tersebut, atau gunakan bentuk PYTHONPATH di bawah sampai Anda melakukannya. Jalankan mesin melalui pemanggilan yang dicetak pemasang saat selesai:

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

atau gunakan bentuk npx (npx @ahmed-g-gad/apothem <command>), yang tidak memerlukan entri PATH.

/plugin marketplace add gagalCopy Anchor Link

/plugin marketplace add ahmed-g-gad/apothem mengambil daftar marketplace dari GitHub. Ketika perintah itu gagal, pastikan mesin dapat menjangkau https://github.com/ahmed-g-gad/apothem (aturan jaringan, proksi, atau firewall), lalu coba lagi. Jika marketplace pernah ditambahkan sebelumnya dalam keadaan pengambilan parsial, hapus lalu tambahkan ulang sebelum menjalankan /plugin install apothem@apothem.

Menambahkan marketplace host plugin mengalami batas waktuCopy Anchor Link

Perintah host plugin yang menambahkan marketplace melakukan clone repositorinya dan menyerah setelah 30 detik. Clone penuh repositori ini dapat memakan waktu lebih lama pada disk yang lambat, seperti drive Windows di bawah WSL, dan clone penuh sebelumnya juga dapat membuat plugin tertahan pada versi lama ketika penyegaran berikutnya melampaui batas waktu. Ambil hanya dua folder yang dibutuhkan plugin:

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

Daftar plugin host kemudian menampilkan versi terkini apothem@apothem.

npx menyajikan versi usangCopy Anchor Link

npx menyimpan paket yang diunduh dalam cache. Ketika npx @ahmed-g-gad/apothem --version melaporkan versi yang lebih lama daripada rilis saat ini, bersihkan cache atau sematkan dist-tag:

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

Pemasang berhenti: kunci publik pemelihara tidak ada di keyring lokalCopy Anchor Link

Pemasang memverifikasi tag rilis yang ditandatangani dan berhenti ketika kunci penandatanganan tidak ada di keyring Anda. Impor sekali, periksa bahwa sidik jari menunjukkan 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163, lalu jalankan pemasang lagi:

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'

Di Windows, impor melalui bash Git seperti yang ditunjukkan: git verify-tag membaca keyring dari gpg yang disertakan dengan Git for Windows. Host tanpa gpg dapat melakukan instalasi dengan APOTHEM_VERIFY=checksum, yang memeriksa digest arsip rilis alih-alih tanda tangan tag.

irm / iex diblokir di WindowsCopy Anchor Link

Jika kebijakan eksekusi PowerShell memblokir pemasang:

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

Masalah runtimeCopy Anchor Link

apothem install tidak menemukan harnessCopy Anchor Link

Jalankan apothem doctor untuk membaca tabel Harness Status-nya, yang memiliki satu baris per harness. Baris yang bertanda not installed berarti Apothem tidak menemukan pemasangan untuk harness tersebut. Baris yang bertanda needs --project adalah harness berlingkup-proyek, yang hanya diperiksa doctor ketika Anda memberikan --project <path>. Jika doctor melaporkan No harness is installed yet, pastikan harness Anda sudah terpasang, lalu jalankan apothem install --harness <name>.

apothem verify melaporkan adapter yang gagalCopy Anchor Link

Jalankan ulang apothem install untuk mematerialisasikan ulang adapter. Jika masalah berlanjut, periksa halaman khusus adapter di bawah Adapter Harness.

Hook tidak terpicu di Claude CodeCopy Anchor Link

Pastikan Apothem terhubung dengan memeriksa ~/.claude/settings.json untuk entri hook. Jika berkas itu tidak memuat hook tersebut, jalankan apothem install lagi.

Mendapatkan bantuanCopy Anchor Link

• GitHub Issues -- laporan bug
• GitHub Discussions -- pertanyaan
• FAQ -- pertanyaan yang sering diajukan