Устранение неполадок

Решения для распространённых проблем установки и времени выполнения Apothem.

Проблемы установки

Не найден Python 3.10+

Инсталляторы и шим npx проверяют python3, python, версионированные имена (от python3.14 до python3.10) и py -3 в Windows — отклоняя шимы-лаунчеры Microsoft Store — и останавливаются с сообщением No Python >= 3.10 found in PATH, когда ни один кандидат не соответствует порогу 3.10. Установите CPython 3.10 или новее с python.org или из репозитория пакетов вашей ОС, убедитесь, что python3 --version (или py -3 --version в Windows) сообщает как минимум 3.10, затем перезапустите.

Отсутствуют зависимости времени выполнения: click, rich

Движок поставляет большинство своих сторонних зависимостей внутри дерева исходного кода, но click и rich должны быть импортируемы под интерпретатором, который выбирает инсталлятор. Если какой-либо из них отсутствует, инсталлятор называет его и предлагает установить за вас:

! Missing runtime dependencies: click rich

Примите запрос, чтобы инсталлятор выполнил pip install под этим интерпретатором. Чтобы пропустить запрос, передайте --yes (-Yes в PowerShell) или задайте APOTHEM_AUTO_INSTALL_DEPS=1 для автоматической установки. Если вы откажетесь — или pip недоступен, или вы предпочитаете менеджер пакетов вашей ОС — установите названные пакеты сами (например, python3-click и python3-rich на хостах семейства Debian, или pip install click rich) и затем перезапустите.

apothem не найден после запуска инсталлятора

Инсталлятор размещает дерево исходного кода в ~/.apothem и не добавляет исполняемый файл apothem в ваш PATH. Запускайте движок через вызов, который инсталлятор выводит по завершении:

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

или используйте форму npx (npx @ahmed-g-gad/apothem <command>), которой не нужна запись в PATH.

/plugin marketplace add завершается с ошибкой

/plugin marketplace add ahmed-g-gad/apothem загружает запись маркетплейса с GitHub. Если это не удаётся, убедитесь, что машина может достичь https://github.com/ahmed-g-gad/apothem (правила сети, прокси или брандмауэра), затем повторите. Если маркетплейс был добавлен ранее при частичной загрузке, удалите и добавьте его заново перед запуском /plugin install apothem@apothem.

npx выдаёт устаревшую версию

npx кэширует загруженные пакеты. Если npx @ahmed-g-gad/apothem --version сообщает версию старее текущего релиза, очистите кэш или закрепите dist-тег:

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

irm / iex заблокированы в Windows

Если политика выполнения PowerShell блокирует инсталлятор:

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

Проблемы времени выполнения

apothem install не находит окружений

Запустите apothem doctor, чтобы вывести список обнаруженных каталогов окружений. Если ни одного не найдено, убедитесь, что ваш инструмент написания кода установлен и был запущен хотя бы один раз.

apothem verify сообщает о неисправном адаптере

Перезапустите apothem install, чтобы заново материализовать адаптер. Если проблема сохраняется, проверьте страницу конкретного адаптера в разделе Адаптеры окружений.

Хуки не срабатывают в Claude Code

Убедитесь, что Apothem подключён, проверив наличие записей хуков в ~/.claude/settings.json. Если в файле отсутствуют хуки, запустите apothem install снова.

Получение помощи

• GitHub Issues -- отчёты об ошибках
• GitHub Discussions -- вопросы
• Часто задаваемые вопросы -- часто задаваемые вопросы