Ақауларды жою

Жалпы күйді тексеру

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-ды commit жасамаңыз.

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, aiman add skill <dir>) және дағдыны AI ортасына орнатқанда қатынау құқықтары сақталмайды — файлдар 0644 ретінде жазылады. Скрипттердің орындалу биті екі қадамда да жоғалады, сондықтан оны қайтару керек жер — скрипт іске қосылатын жер, яғни AI ортасының каталогы — және мұны әрбір aiman apply немесе aiman sync-тен кейін қайталау керек:

chmod +x ~/.claude/skills/<name>/<script>

Сонымен қатар ескеріңіз: қалталық дағдының тек анықтамалық файлдарындағы өзгерістер қайта импорттау кезінде тасымалданбайды — команда тек SKILL.md-ті салыстырады және already identical деп хабарлайды. Өзгерген файлдарды қолмен көшіріңіз.

Жарамсыз Skill немесе MCP Item

Тексеріңіз:

• файл атауы name-мен сәйкес келеді;
• Skill-де name және description бар frontmatter және 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 ортасында жоқ.

Себебі әдетте дағдының frontmatter-індегі targets өрісінде: ол белгіленген болса, дағды тек тізімде аталған орталарға ғана орнатылады. Тексеріңіз:

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

Мұнда дағды тек claude-code-ке түседі, тіпті машинада cursor мен codex де анықталса да.

Бөлек ескеріңіз:

• targets-тегі орта атаулары валидацияланбайды — жазу қатесі (claude-code-тің орнына claud-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 ешқашан болмаған репозиторийге ауыстырған.

Бұл қате пинсіз apply --loadout беретін loadout "X" not found in loadouts/ қатесінен өзгеше — мәтіндер қате көзін оңай ажырату үшін әдейі әр түрлі жасалған.

Не істеу керек:

1. Loadout қазір қандай атаумен бар екенін тексеріңіз — aiman status бекітілген атауды көрсетеді, инвентарь репозиторийіндегі loadouts/ мазмұны ағымдағы атауларды көрсетеді.
2. Оны қолданудың қажеті болмаса, пинді алып тастаңыз:

aiman apply --unpin

3. Немесе толық инвентарьға оралыңыз:

aiman apply --default

4. Немесе loadout атауы өзгертілген болса, оны жаңа атаумен қайта бекітіңіз:

aiman apply --loadout <жаңа-атау> --pin

Қашықтағы репозиторийге қол жоқ

Тексеріңіз:

• SSH кілті немесе HTTPS аутентификациясы;
• репозиторийге қол жеткізу құқықтары;
• origin remote бар екені;
• желілік қосылым.

Git тарихы айырылып кетті

AIM пайдаланушы үшін merge орындауды әдейі жасамайды.

Тарих айырылып кетсе, стандартты Git командаларымен репозиторийді қолмен қалпына келтіріңіз, содан кейін қайталаңыз:

aiman status
aiman sync