Устранение проблем

Проверить общее состояние

aiman status
aiman doctor

status отвечает на вопрос «что изменено и что опубликовано». doctor отвечает на вопрос «готова ли локальная машина применять инвентарь».

AI-среда не найдена

Симптом:

environment codex not found

Что сделать:

1. Убедитесь, что AI-инструмент установлен.
2. Проверьте стандартную директорию среды.
3. Если путь нестандартный, задайте его в aim.local.yaml.

environments:
  codex: ~/.codex

aiman sync останавливается с ошибкой конфликта файлов

sync блокируется только если неотслеживаемый файл в skills/, mcp/ или loadouts/ совпадает по имени с файлом из remote. Неотслеживаемые файлы без конфликтов sync не затрагивает.

При конфликте sync выводит список проблемных файлов. Варианты:

• опубликовать конфликтующий файл:

aiman push
aiman sync

• переименовать или переместить файл вручную;
• применить опубликованное состояние с удалением конфликтующих файлов:

aiman sync --force

Внимание: sync --force безвозвратно удаляет конфликтующие файлы из рабочего дерева.

Удалённый репозиторий новее локального состояния

Если push сообщает, что удалённый репозиторий ушёл вперёд, сначала примените опубликованное состояние:

aiman sync

После этого повторите локальные правки или опубликуйте актуальное состояние.

Не задана обязательная MCP env-переменная

Симптом:

required env variable API_KEY is missing

Запустите aiman sync — AIM запросит значение интерактивно. Или задайте значение напрямую в aim.local.yaml:

mcp_env:
  context7:
    API_KEY: "..."

Не коммитьте aim.local.yaml.

aiman import не находит репозиторий инвентаря

Симптом:

error: no active inventory repository; run 'aiman init' first

aiman import skill и aiman import mcp пишут только в активный репозиторий инвентаря и никогда — в текущую директорию. Если репозитория ещё нет, подключите его:

aiman init git@github.com:you/aim-loadout.git

Если репозиторий уже склонирован локально, сделайте его активным:

aiman switch ~/projects/aim-loadout

Проверить, какой репозиторий активен, можно в первой строке вывода aiman doctor (Active Repo:).

aiman import сообщает invalid item name

Симптом:

error: invalid item name "../evil": must not contain "/" or "\"

Аргумент команды — это имя элемента в AI-среде (aiman import skill create-spec --from claude-code), а не путь к файлу. Отклоняются пустое имя, ., .., имена с / или \, абсолютные пути, управляющие символы и имена длиннее 255 символов. Чтобы добавить элемент из файла или папки на диске, используйте aiman add:

aiman add skill ~/Downloads/create-spec.md
aiman add skill ~/Downloads/create-spec

aiman import mcp отказывается импортировать сервер

Симптом:

error: MCP server "remote-tool": unsupported transport "http" (only stdio servers can be imported)

AIM управляет только stdio-серверами — теми, у которых в конфигурации среды задан command. Серверы, объявленные через "type": "http", "type": "sse" или голый "url", не импортируются: раньше такой сервер попадал в инвентарь пустой заготовкой без команды, теперь команда останавливается и называет причину. Оставьте такой сервер настроенным в AI-среде вручную; остальные серверы того же конфига импортируются как обычно.

Повторный точечный импорт не подхватывает изменения в ресурсных файлах навыка

aiman import skill <name> --from <env> и aiman add skill <dir> сравнивают папочный навык только по содержимому SKILL.md. Если в среде изменились только ресурсные файлы (references/, скрипты), а SKILL.md остался прежним, команда сообщит already identical и не перенесёт изменения — --overwrite в этом случае тоже не помогает. Скопируйте изменившиеся файлы вручную.

Это ограничение только точечного импорта: aiman import без имени (discovery) сравнивает весь пакет навыка целиком — SKILL.md, ресурсные файлы и исполняемый бит, — поэтому изменение любого файла пакета там будет замечено.

Невалидный Skill или MCP Item

Проверьте:

• имя файла совпадает с name;
• Skill содержит frontmatter с name и description и непустое тело после frontmatter (aiman doctor называет причину: missing name, missing description, empty body);
• MCP Item содержит name, command, args, targets, env (description у MCP Item и у env-переменной — необязательное поле);
• YAML валиден.

Форматы описаны в Формате инвентаря.

Навык не появился в ожидаемой AI-среде

Симптом: aiman apply/aiman sync прошли без ошибок, но навык отсутствует в конкретной AI-среде.

Причина почти всегда — поле targets в frontmatter навыка: если оно задано, навык устанавливается только в перечисленные среды. Проверьте:

---
name: my-skill
targets:
  - claude-code
---

Здесь навык попадёт только в claude-code, даже если на машине обнаружены и cursor, и codex.

Отдельно учтите:

• имена сред в targets не валидируются — опечатка (claud-code вместо claude-code) не даёт ошибки, навык просто не установится никуда;
• на аддитивных путях (aiman apply, aiman sync без активного пина) сужение targets никогда не убирает навык из среды, где он уже стоял, — уберёт его только aiman apply --loadout <name> или pinned sync, и только если навык входит в loadout, но не перечислил эту среду в своём targets.

Чтобы применить навык во все обнаруженные среды, удалите поле targets или оставьте список пустым.

Loadout не найден или не появился на другой машине

Если aiman apply --loadout <name> сообщает loadout "<name>" not found in loadouts/, проверьте:

• файл лежит в loadouts/<name>.yaml активного репозитория инвентаря;
• имя совпадает либо с именем файла, либо с полем name (пробелы и регистр нормализуются: Documentation Work → documentation-work);
• подсказка hint: available loadouts: … перечисляет доступные значения поля name.

Если loadout есть на одной машине, но отсутствует на другой, он, скорее всего, ещё не доехал: опубликуйте его через aiman push на первой машине и получите через aiman sync на второй.

aiman sync неожиданно применяет только часть инвентаря

Симптом: после aiman sync в средах появился не весь инвентарь, а только некоторые навыки и MCP-серверы, и вывод начинается со строки applying loadout "X" (pinned).

Причина: на этой машине закреплён пин (aiman apply --loadout <name> --pin) — sync декларативно применяет именно этот loadout вместо полного инвентаря, включая удаление элементов вне его набора. Это ожидаемое поведение пина, а не ошибка.

Проверьте активный пин:

aiman status

Поле Pinned loadout: покажет имя закреплённого loadout или none. Чтобы вернуться к полному инвентарю:

aiman apply --default    # применить весь инвентарь и снять пин
# или
aiman apply --unpin      # снять пин, ничего не применяя — следующий sync применит весь инвентарь

Подробнее о пине — в Концепциях и в Рабочих циклах.

Пин указывает на loadout, которого больше нет

Симптом:

error: pinned loadout "documentation-work" not found in inventory

aiman sync останавливается, не трогая AI-среды и не обновляя synced_hash — вместо того, чтобы молча откатиться к полному инвентарю. Типичные причины: loadout переименовали или удалили на другой машине и уже опубликовали, либо aiman switch переключил на репозиторий, где loadout с таким именем никогда не было.

Эта ошибка отличается от loadout "X" not found in loadouts/, которую выдаёт apply --loadout без пина, — тексты различаются намеренно, чтобы источник ошибки было легко отличить.

Что сделать:

1. Проверить, под каким именем loadout существует сейчас — aiman status покажет закреплённое имя, содержимое loadouts/ в репозитории инвентаря покажет актуальные имена.
2. Снять пин, если применять его больше не нужно:

aiman apply --unpin

3. Или вернуться к полному инвентарю:

aiman apply --default

4. Или закрепить loadout заново под новым именем, если он был переименован:

aiman apply --loadout <новое-имя> --pin

Нет доступа к удалённому репозиторию

Проверьте:

• SSH-ключ или HTTPS-аутентификацию;
• права доступа к репозиторию;
• наличие remote origin;
• сетевое соединение.

История Git разошлась

AIM намеренно не выполняет merge за пользователя.

Если история разошлась, восстановите репозиторий стандартными Git-командами вручную, затем повторите:

aiman status
aiman sync