Схема общего профиля

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

Модель времени выполнения — src/apothem/lib/profile.py; JSON Schema — src/apothem/schemas/profile.schema.json.

Минимальный действительный профиль

Единственное обязательное поле — identity.name:

identity:
  name: "Example User"

Каркас, записываемый `profile init`

apothem profile init записывает несколько более полный каркас — поля идентичности-заполнители, которые оператор должен персонализировать, — и проверяет его, прежде чем сообщить об успехе:

identity:
  name: "Example User"
  email: "[email protected]"
  github: "example-user"

Команда выводит напоминание о персонализации, называя эти поля. Если идентичность, всё ещё являющаяся заполнителем, позже достигает install или update, эти команды выводят одно информационное примечание и продолжают работу — Apothem никогда не фабрикует идентичность-заполнитель и не блокируется из-за неё.

Канонические поля

Поле	Обязательно	По умолчанию	Примечания
`identity.name`	Да	нет	Непустое отображаемое имя оператора.
`identity.role`	Нет	`senior software engineer`	Общий текст роли.
`identity.email`	Нет	опущено	При наличии должно быть в формате электронной почты.
`identity.website`	Нет	опущено	При наличии должно быть в формате URI.
`identity.github`	Нет	опущено	Имя пользователя GitHub без `@`.
`preferences.language`	Нет	`python`	Нормализуется в нижний регистр.
`preferences.style`	Нет	`concise`	Одно из `concise`, `verbose`, `balanced`.
`preferences.formatter`	Нет	опущено	Непустая строка при наличии.
`preferences.test_framework`	Нет	опущено	Непустая строка при наличии.
`rules`	Нет	`[]`	Уникальные непустые строки; переводы строк нормализуются в LF.
`seriousness`	Нет	`PERSONAL_USE`	Одно из `EXPLORING`, `PERSONAL_USE`, `SHARED`, `PUBLIC_LAUNCH`.
`harnesses`	Нет	`{}`	Переопределения для конкретного окружения по ключу поддерживаемого ID окружения.
`exclude_harnesses`	Нет	`[]`	Поддерживаемые ID окружений, исключённые из `--harness all`.

Ключи окружений

Схема принимает ровно эти семнадцать ID окружений:

antigravity
claude-code
codebuddy
codex
cursor
gemini-cli
github-copilot
glm
hermes
kimi-code
kiro
open-claw
opencode
qwen-code
trae
windsurf
zed

Неизвестные поля верхнего уровня, неизвестные ключи окружений, неверные типы значений, дублирующиеся исключения и неправильно сформированные поля идентичности завершаются с ошибкой до того, как install или update что-либо запишут. Ожидаемые ошибки включают поле, причину, исправление, отредактированное безопасное значение, когда это полезно, и files_written: [] для сбоев проверки.

От поля профиля к нативному файлу

Профиль — это что; адаптеры — это как. Понимание сквозного потока объясняет, почему одна правка одного файла YAML может перекроить каждое установленное окружение.

Поле профиля несёт семантическое намерение, а не буквальный фрагмент конфигурации. identity.name — это «кто есть оператор», а не строка JSON. Упакованные когорты полезной нагрузки (commands, rules, skills, hooks, templates, statuslines, output-styles, agents) несут поведенческое содержимое в собственном нейтральном формате Apothem. Ни поле, ни когорта не знают, как выглядит конфигурация какого-либо окружения — это знание принадлежит только адаптерам.

Когда вы запускаете apothem update, поток таков:

Загрузить и проверить профиль по JSON Schema. Ничего не записывается, пока весь профиль не станет действительным, поэтому опечатка никогда не устанавливается наполовину.
Разрешить адаптеры для выбранного окружения (или all, за вычетом любых exclude_harnesses) через центральный реестр.
Материализовать — каждый адаптер читает один и тот же профиль и одни и те же когорты, а затем переводит их на диалект своего окружения. Поле вроде preferences.style становится нативным значением конфигурации в одном окружении и отрендеренным контекстом инструкций в другом; правило в rules[] становится файлом .mdc для Cursor, разделом общерепозиторных инструкций для Copilot или записью дерева поддержки там, где у окружения нет нативной поверхности правил.
Записать нативные файлы — отрендеренную единую конфигурацию, преобразованную когорту или поддерево поддержки, на которое ссылается нативный якорь окружения.

Один и тот же профиль управляет каждым окружением, поэтому материализации не могут расходиться в намерении. Ячейки возможностей, которые окружение не поддерживает (или которые всё ещё ожидают обнаружения), всплывают как структурированные предупреждения до любой записи, а не выдумываются на поверхности поставщика, которой не существует. Именно это делает реальной гарантию одна-правка-много-окружений: профиль редактируется один раз, и каждый адаптер заново выводит свои нативные файлы из этого единственного источника.