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 not found орнына permission denied көрсетеді ​

Симптом:

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

Бұл «орта орнатылмаған» дегенмен бірдей емес: директория бар, бірақ ағымдағы пайдаланушы оны оқи алмайды. Иесі мен құқықтарын тексеріңіз:

bash
ls -ld ~/.cursor

doctor дәл осылай белсенді инвентарь репозиторийінің құқығы жетпейтін skills/, mcp/ және ~/.config/aim туралы да === Issues === ішінде бөлек жолмен хабарлайды.

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).

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

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

bash
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 өрісінде: ол белгіленген болса, дағды тек тізімде аталған орталарға ғана орнатылады. Тексеріңіз:

md
---
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-ты декларативті түрде қолданады, оның ішінде жинақтан тыс элементтерді жоюды қоса алғанда. Бұл пиннің күтілетін мінез-құлқы, қате емес.

Белсенді пинді тексеріңіз:

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 ешқашан болмаған репозиторийге ауыстырған.

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

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

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

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

Тексеріңіз:

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

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.