Первые шаги: от нуля до рабочего окружения

Этот туториал проводит вас через всю вашу первую настройку Apothem. Вы начинаете, когда ничего не установлено, и заканчиваете реальной конфигурацией окружения — сгенерированной из написанного вами профиля, проверенной и подтверждённой как рабочая. Рассчитывайте примерно на пятнадцать минут. Каждая команда ниже настоящая, её можно скопировать, вставить и запустить.

К концу у вас будет сделано следующее:

1. Apothem установлен с помощью скриптового установщика.
2. Общий профиль, который управляет каждым окружением, отредактирован.
3. Нативная конфигурация окружения материализована.
4. Эта конфигурация проверена, и рабочий первый запуск подтверждён.

На протяжении всего туториала мы будем использовать Claude Code в качестве примера окружения, потому что это значение установщика по умолчанию. Те же шаги применимы к любому поддерживаемому окружению — замените имя, когда дойдёте до списка окружений.

Что нужно заранееCopy Anchor Link

• Оболочка, похожая на Unix (macOS, Linux или WSL). Установщик PowerShell рассчитан на Windows; этот учебник показывает путь через bash.
• Python 3.10 или новее в вашем PATH. Проверьте командой python3 --version.
• Две библиотеки времени выполнения, которые движок импортирует из вашего интерпретатора: click и rich. Остальной стек (pyyaml, jsonschema) вендорен в дерево, поэтому импортируемыми должны быть только эти две. Если click или rich отсутствует, установщик останавливается и выводит команду установки. Однострочная команда передаёт скрипт в bash, поэтому он не может запросить подтверждение; задайте APOTHEM_AUTO_INSTALL_DEPS=1 (например, curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash) или сначала установите два пакета.

Apothem поставляется как упакованное дерево исходного кода, а не как опубликованный пакет — шага pip install нет. Установщик клонирует дерево и запускает движок прямо из него.

Шаг 1 — Установка ApothemCopy Anchor Link

Запустите сетевой установщик:

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

Установщик выполняет следующие шаги:

1. Проверка предварительных условий. Установщик находит настоящий интерпретатор Python 3.10+ и проверяет, что обе библиотеки времени выполнения (click и rich) импортируются. Если одной из них нет, он называет её, останавливается и выводит команду установки; задайте APOTHEM_AUTO_INSTALL_DEPS=1, чтобы установить без запроса, поскольку запуск через конвейер не может запросить подтверждение.
2. Размещение исходного кода. Поставляемое дерево клонируется в ~/.apothem (переопределяется переменной окружения APOTHEM_HOME). Повторный запуск переключает существующий клон на релизный тег, а не дублирует его.
3. Начальное создание профиля. Если у вас ещё нет профиля, установщик копирует пример профиля в ~/.config/apothem/profile.yaml, устанавливает и проверяет Claude Code по нему в том же запуске и предупреждает, что поля идентичности — это заполнители.

Установкой можно управлять с помощью переменных окружения. Те, которые вы, скорее всего, будете использовать:

# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
  APOTHEM_HARNESS=codex \
  APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  bash

Установщик устанавливает только окружения уровня пользователя. Окружение уровня проекта установите после этого, указав проект:

apothem install --harness cursor --project /path/to/project

Другие распознаваемые переменные: APOTHEM_REPO и APOTHEM_REF (какой удалённый репозиторий клонировать и какую git-ссылку переключить — если не задано, выбирается и проверяется последний подписанный релизный тег; задайте тег, чтобы закрепить его, или main для подвижной ветки (ветка не является подписанным тегом, поэтому ей также нужен APOTHEM_ALLOW_UNVERIFIED=1)), APOTHEM_ALLOW_UNVERIFIED=1 (понижает сбой проверки подписи тега до предупреждения и разрешает ссылку, не являющуюся тегом, например main), APOTHEM_SOURCE (использовать существующий локальный чекаут вместо клонирования) и APOTHEM_SKIP_VERIFY=1 (пропустить проверку после установки, которую мы хотим выполнить, поэтому оставьте эту переменную не заданной).

Когда установщик завершает полный проход, он выводит баннер, показывающий, как вызывать движок. Он размещает shim apothem в вашем PATH (POSIX: $HOME/.local/bin; Windows: %LOCALAPPDATA%\Microsoft\WindowsApps), поэтому, как только этот каталог окажется в PATH, вы запускаете движок напрямую:

apothem <command>

Если shim не удалось разместить — или его каталог ещё не находится в PATH, — баннер выводит самодостаточный запасной вариант, которому не нужен shim:

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

Далее в этом туториале используется запись apothem <command>; если вы пользуетесь запасной формой, добавляйте перед командой точный префикс, который вывел баннер вашего установщика.

Шаг 2 — Сделайте профиль своимCopy Anchor Link

Общий профиль в ~/.config/apothem/profile.yaml — единственный источник истины. Каждый адаптер окружения читает его и выводит из него нативную конфигурацию своего окружения. Отредактируйте его один раз, и каждое устанавливаемое вами окружение останется согласованным.

Откройте его через редактор движка или в любом текстовом редакторе:

apothem profile edit

Минимальный валидный профиль выглядит так:

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

Замените заполнитель name своим именем и добавьте любые правила, которые должно применять каждое окружение. Примерные значения оставляйте фиктивными — профиль рассчитан на то, чтобы им было безопасно делиться.

Убедитесь, что движок без ошибок читает ваши правки:

apothem profile show --json

Если YAML некорректен, вы увидите это именно здесь — исправьте и запустите снова, прежде чем двигаться дальше.

Шаг 3 — Материализация конфигурации окруженияCopy Anchor Link

Если ваш запуск на шаге 1 создал профиль, он уже установил Claude Code, используя заполнители идентичности. Отредактируйте профиль на шаге 2, затем примените свою идентичность командой:

apothem update --harness claude-code

apothem install --harness claude-code

Эта команда читает ваш профиль и записывает нативную конфигурацию Claude Code. Чтобы увидеть все окружения, на которые можно нацелиться:

apothem harnesses list

Некоторые окружения относятся к уровню проекта, а не пользователя, и им нужен путь --project, чтобы адаптер знал, куда записывать:

apothem install --harness cursor --project .

Шаг 4 — Проверка и подтверждение первого запускаCopy Anchor Link

Материализация — лишь половина дела. Теперь убедитесь, что конфигурация записана правильно:

apothem verify --harness claude-code

verify проверяет, что управляемые файлы конфигурации окружения существуют и успешно разбираются. Добавьте --profile PATH, и команда также завершится сбоем, если установленный файл отклонился от того, что создал бы этот профиль. Чистый запуск означает, что материализация прошла успешно.

Для проверки работоспособности всей машины по всем зарегистрированным адаптерам выполните:

apothem doctor

doctor проверяет каждое установленное окружение (оно должно проходить проверку, а его зарегистрированные команды хуков должны запускаться) и завершается с ненулевым кодом, если какая-либо проверка не пройдена. Окружения, которые вы не установили, указываются в списке, но не приводят к сбою, поэтому эта команда — полезный шлюз в скрипте настройки.

Ваш первый запуск. Откройте окружение, которое вы только что настроили, — в нашем примере Claude Code — и начните сессию в любом проекте. Правила и предпочтения, которые вы записали в профиль, теперь являются частью поведения этого инструмента. Это и есть рабочий первый запуск: профиль, который вы отредактировали на шаге 2, формирует реальную сессию.

Что вы построилиCopy Anchor Link

Начав с пустой машины, вы установили Apothem, составили общий профиль, материализовали из него нативную конфигурацию окружения, проверили результат и подтвердили, что он работает. Профиль — это долговечный артефакт: измените его один раз и снова выполните apothem update --harness <name>, чтобы доставить изменение в любое окружение.

Куда двигаться дальшеCopy Anchor Link

• Добавьте ещё один инструмент. Список окружений охватывает каждую поддерживаемую платформу и имя её адаптера. Повторите шаг 3 с новым --harness.
• Углубитесь в отдельную задачу. Практические рецепты охватывают добавление окружения, редактирование профиля и управление установщиком. Руководства по использованию охватывают написание правил, составление планов и запуск шлюза соответствия.
• Найдите конкретные сведения. Справочник документирует каждый класс артефактов и схему профиля, а справочник CLI охватывает каждую команду. У каждого адаптера есть собственная страница в разделе Окружения.
• Планируйте работу, которая переживает сессию. Возобновляемое планирование объясняет, как Apothem выносит длительную работу в локальный для проекта набор планов .apothem/plans/, чтобы новая сессия на любой машине возобновляла её на месте.

Рекомендуемый следующий шагCopy Anchor Link

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