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

Полное пошаговое руководство от пустой машины до материализованной и проверенной конфигурации среды.

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

Уже настроили?

Если вам нужна лишь лаконичная справка по четырём основным командам, см. Основные рабочие процессы. Эта страница — сопровождаемое пошаговое руководство от нуля до первого запуска.

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

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

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

Что нужно первым делом

Unix-подобная оболочка (macOS, Linux или WSL). Установщик PowerShell покрывает Windows; этот туториал показывает путь bash.
Python 3.10 или новее в вашем PATH. Проверьте его с помощью python3 --version.
Две библиотеки времени выполнения, которые движок импортирует из вашего интерпретатора: click и rich. Остальная часть стека (pyyaml, jsonschema) встроена (vendored) в дерево, поэтому импортируемыми должны быть только эти две. Установщик проверяет их, называет отсутствующие и предлагает установить их за вас, чтобы вы подтвердили и продолжили.

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

Шаг 1 — Установка Apothem

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

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

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

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

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

# Install a different harness as the default, and point at a project profile.
APOTHEM_HARNESS=cursor \
APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

Другие распознаваемые переменные — это APOTHEM_REPO и APOTHEM_REF (какой удалённый репозиторий клонировать и какой git-ref загрузить; без задания разрешает и проверяет последний подписанный тег версии, задайте тег для фиксации или main для подвижной ветки), APOTHEM_ALLOW_UNVERIFIED=1 (понижает сбой проверки подписи тега до предупреждения), 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 — Сделайте профиль своим

Общий профиль в ~/.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 — Материализация конфигурации среды

Установщик уже материализовал среду по умолчанию на шаге 1. Чтобы сделать это явно — или материализовать вторую среду — запустите install:

apothem install --harness claude-code

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

apothem harnesses list

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

apothem install --harness cursor --project .

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

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

apothem verify --harness claude-code

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

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

apothem doctor

doctor сообщает статус установки каждого адаптера и завершается с ненулевым кодом, если какой-либо зарегистрированный адаптер сообщает, что он не установлен: полезный шлюз в скрипте настройки.

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

Что вы создали

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

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

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