Skip to content

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

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

bash
aiman status
aiman doctor

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

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

Симптом:

text
environment codex not found

Что сделать:

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

aiman doctor показывает permission denied вместо not found ​

Симптом:

text
✗ cursor        /home/user/.cursor   permission denied

Это не то же самое, что «среда не установлена»: директория существует, но текущий пользователь не может её прочитать. Проверьте владельца и права:

bash
ls -ld ~/.cursor

doctor таким же образом отдельной строкой в === Issues === сообщает о недоступных по правам skills/, mcp/ активного репозитория инвентаря и ~/.config/aim.

aiman doctor сообщает git: not found in PATH ​

init, sync и push вызывают git как внешнюю команду. Установите git и убедитесь, что он доступен в PATH:

bash
git --version

Битый aim.local.yaml или ~/.config/aim/config.yaml ​

Симптом:

text
• aim.local.yaml: cannot parse /path/to/aim.local.yaml: yaml: ... — fix or remove the file
• global config: cannot read /home/user/.config/aim/config.yaml: yaml: ... — fix or remove the file

doctor read-only и не падает на первой проблеме — он показывает максимум диагностики и печатает каждую причину отдельной строкой. Откройте указанный файл, исправьте YAML или удалите его: aim.local.yaml пересоздаётся командой aiman init/aiman switch, ~/.config/aim/config.yaml — теми же командами (плюс apply --loadout --pin/--unpin/--default, которые пишут в него активный loadout).

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

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

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

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

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

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

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

bash
aiman sync

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

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

Симптом:

text
required env variable API_KEY is missing

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

yaml
mcp_env:
  context7:
    API_KEY: "..."

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

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

Симптом:

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

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

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

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

bash
aiman switch ~/projects/aim-loadout

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

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

Симптом:

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

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

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

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

Симптом:

text
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 навыка: если оно задано, навык устанавливается только в перечисленные среды. Проверьте:

md
---
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 вместо полного инвентаря, включая удаление элементов вне его набора. Это ожидаемое поведение пина, а не ошибка.

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

bash
aiman status

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

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

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

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

Симптом:

text
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. Снять пин, если применять его больше не нужно:
bash
aiman apply --unpin
  1. Или вернуться к полному инвентарю:
bash
aiman apply --default
  1. Или закрепить loadout заново под новым именем, если он был переименован:
bash
aiman apply --loadout <новое-имя> --pin

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

Проверьте:

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

push/sync падает по таймауту или зависает на SSH ​

Симптом:

text
error: git push ...: timed out after 60s — check ssh-agent/network connectivity

Типичная причина: SSH-ключ репозитория защищён passphrase, а ssh-agent не запущен или не содержит этот ключ. Без ssh-agent ssh обычно спрашивает passphrase в терминале — AIM отключает этот интерактивный запрос, поэтому вместо приглашения ввести пароль команда останавливается по таймауту (60 секунд) с понятной ошибкой вместо молчаливого зависания.

Запустите ssh-agent и добавьте ключ:

bash
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519   # путь к вашему приватному ключу

Затем повторите aiman push или aiman sync. Если проблема не в passphrase — проверьте пункты из раздела Нет доступа к удалённому репозиторию выше.

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

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

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

bash
aiman status
aiman sync

Released under the Apache 2.0 License.