Қателер және сәтсіздік режимдері

Жалпы формат

CLI пайдаланушы қателері stderr-ге мынадай форматта шығарылады:

error: <message>

Команда нөлдік емес exit code-пен аяқталады.

Жиі кездесетін бұғаттаушы жағдайлар

Жағдай	Нені білдіреді	Не жасау керек
sync кезінде бақылаусыз файл remote-пен қақтығысады	skills/, mcp/ немесе loadouts/ ішіндегі файлдың атауы remote-тан келетін файлдың атауымен сәйкес келеді	файлды қайта атау, aiman push арқылы жариялау немесе --force пайдалану (файл жойылады)
push кезінде remote жаңа	жарияланған күй алға кетті	aiman sync орындау
Git тарихы айырылды	AIM күйді қауіпсіз таңдай алмайды	Git-ті қолмен қалпына келтіру
AI ортасы табылмады	адаптер base dir таппады	aim.local.yaml-да жолды көрсету
MCP env белгіленбеген	міндетті айнымалы жоқ	sync кезінде енгізу немесе aim.local.yaml-ға қосу
Жарамсыз Skill	frontmatter жоқ, name жоқ, description жоқ немесе дене бос	skills/<name>.md түзету
Жарамсыз MCP Item	міндетті өріс жоқ немесе YAML жарамсыз	mcp/<name>.yaml түзету
import кезінде белсенді репозиторий жоқ	инвентарь репозиторийі таңдалмаған	aiman init <url> немесе aiman switch <path> орындау
import кезінде рұқсат етілмеген элемент атауы	<name> аргументі бос, /, \, .., басқару таңбаларын қамтиды немесе 255 таңбадан ұзын	файл жолын емес, элемент атауын беру; файл aiman add арқылы қосылады
import mcp кезінде қолдау көрсетілмейтін транспортты MCP-сервер	сервер command арқылы емес, http/sse немесе url арқылы жарияланған	AIM тек stdio-серверлерін басқарады; мұндай серверді ортада қолмен конфигурацияланған күйде қалдыру
apply --loadout кезінде loadout табылмады	loadouts/ ішінде осындай атаулы файл да, name өрісі де жоқ	атауды тексеру; қолжетімділер тізімі — hint жолында
Жарамсыз loadout	name жоқ, items бос, сілтеме префиксі қате немесе YAML жарамсыз	loadouts/<name>.yaml түзету
push кезінде бұзылған loadout сілтемесі	skill:<name> немесе mcp:<name> инвентарьда жоқ	items түзету немесе элементті инвентарьға қосу
sync кезінде пин жоқ loadout-қа сілтейді	apply --pin арқылы бекітілген loadout жойылған, атауы өзгертілген немесе ағымдағы репозиторийде жоқ	пинді алып тастау үшін aiman apply --default немесе aiman apply --unpin, не loadout-ты қалпына келтіру/қайта атау
apply флагтарының қақтығысы (--pin/--default/--unpin)	пин флагтарының үйлесімсіз комбинациясы	флагтарды бөлек-бөлек қолдану — қараңыз: CLI анықтамалығы
Remote-қа қол жоқ	Git репозиторийді оқи немесе жаза алмайды	желіні, credentials-ты және рұқсаттарды тексеру

Импорт қателері

Төмендегі үш қатенің бәрі де дискіге жазбас бұрын туындайды: инвентарь мен AI орталары тиіспей қалады.

Белсенді инвентарь репозиторийі жоқ — aiman import skill және aiman import mcp ағымдағы каталогқа жазбайды:

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

Репозиторийді жалғаңыз (aiman init <url>) немесе бар репозиторийге ауысыңыз (aiman switch <path>). Тексеру --print флагымен де орындалады.

Рұқсат етілмеген элемент атауы — атау жазу жолын құрастырмас бұрын тексеріледі, сондықтан импортты инвентарь репозиторийінен тыс жерге апару мүмкін емес:

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

Бос атау, ., .., / немесе \ бар атаулар, абсолютті жолдар, басқару таңбалары және 255 таңбадан ұзын атаулар қабылданбайды. Команда аргументі — AI ортасындағы элементтің атауы, файл жолы емес.

MCP-сервер қолдау көрсетілмейтін транспортты пайдаланады — тек stdio-серверлерді импорттауға болады (command берілгендерді):

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

Мұндай сервер инвентарьда бос дайындама ретінде жасалмайды: команда тоқтап, себебін атайды. Сол конфигтің қалған серверлері әдеттегідей импортталады.

Loadout қателері

Loadout табылмады (aiman apply --loadout):

hint: available loadouts: dev, docs
error: loadout "ghost" not found in loadouts/

hint жолы жарамды loadout саны бірден беске дейін болғанда басылады және файл атауларын емес, name өрісінің мәндерін тізімдейді. loadouts/ каталогы жоқ болса немесе бос болса, сол not found қатесі шығады, бірақ кеңессіз.

Loadout жарамсыз — apply --loadout бірінші қатеде тоқтайды:

error: loadout "empty": items: cannot be empty

aiman push барлық loadouts/ файлдары бойынша формат қателерін бірден шығарады (файлға толық жолмен):

error: /home/user/aim-inventory/loadouts/empty.yaml: items: cannot be empty

Инвентарь элементіне бұзылған сілтеме (aiman push, жариялауды бұғаттайды):

error: loadout "Documentation Work" references unknown skill "missing-skill"
  hint: check loadouts/documentation-work.yaml → items

Сәтсіз валидацияның кез келгенін push error: validation failed — fix errors before publishing деген жалпы жолмен аяқтайды.

apply --loadout кезіндегі дәл сол жағдай — қате емес, ескерту: элемент өткізіліп жіберіледі, қолдану жалғасады:

warning: loadout "dev": no valid inventory item for skill:ghost (skipped)

push-ты да, apply-ды да бұғаттамайтын loadout ескертулері: description болмауы және файл атауының нормаланған name-мен сәйкес келмеуі.

Loadout пині

Пин енді жоқ loadout-қа сілтейді — aiman sync AI орталарына тимей және synced_hash-ті жаңартпай тоқтайды:

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

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

• ештеңе қолданбай пинді алып тастау: aiman apply --unpin;
• немесе толық инвентарьға оралу: aiman apply --default;
• немесе инвентарь репозиторийінде loadout-ты күтілетін атаумен қалпына келтіру/қайта атау және aiman sync-ті қайталау.

apply --pin / --default / --unpin флагтарының қақтығыстары — инвентарьды оқымас бұрын, apply-ға диспетчерлеуге дейін тексеріледі:

Комбинация	Қате
--loadout-сыз --pin	error: --pin requires --loadout <name>
--default + --loadout	error: --default and --loadout are mutually exclusive
--default + --pin	error: --pin is redundant with --default
--loadout, --pin немесе --default-пен бірге --unpin	error: --unpin does not apply — combine only alone

Флагтардың толық сипаттамасы — CLI анықтамалығында, конфиг өрісі — Конфигурация анықтамалығында.

--dry-run

Қауіпті операциялар үшін алдымен dry-run пайдаланыңыз:

aiman push --dry-run
aiman sync --dry-run
aiman apply --dry-run
aiman apply --loadout <name> --dry-run

Dry-run Git-ке, инвентарь репозиторийіне немесе AI орталарына жазбастан жоспарды көрсетеді. apply --loadout үшін dry-run — әдетке айналдыратын қадам: жоспардағы D жолдары орталардан не жойылатынын көрсетеді.

--force

aiman sync --force жарияланған күйді қолданған кезде жергілікті өзгерістердің жоғалуына рұқсат береді.

Бұл флагты тек жергілікті жұмыс ағашын қалпына келтіруге немесе жоғалтуға болатын жағдайда пайдаланыңыз.