Kiro

Поставщик: AWS Имя установки: kiro Статус: GA Нативная конфигурация: <project>/.kiro/steering/apothem-rules.md

УстановкаCopy Anchor Link

apothem install --harness kiro --project /path/to/project

Адаптер записывает один steering-файл Kiro с областью действия проекта на основе общей поверхности правил и управления Apothem, помощников Apothem как файлы пользовательских агентов Kiro в проекте (см. Файлы пользовательских агентов) и один хук (см. Хуки).

Кроме того, он записывает навыки Apothem, а также правила и шаблоны, на которые они ссылаются, в ваш домашний каталог пользователя, прежде чем затронуть проект (см. Файлы за пределами проекта).

Записываемые файлы:

• <project>/.kiro/steering/apothem-rules.md — steering-файл.
• <project>/.kiro/agents/<name>.md для каждого помощника Apothem, в проекте.
• <project>/.kiro/hooks/apothem.json — файл хуков, в проекте. Ваши собственные файлы хуков в этой папке не затрагиваются.
• <project>/.apothem/support/kiro/hooks/ — скрипты хуков, в проекте.
• ~/.kiro/skills/<name>/SKILL.md для каждого навыка и каждой команды Apothem, в вашем домашнем каталоге пользователя.
• ~/.config/apothem/rules/ и ~/.config/apothem/templates/, в вашем домашнем каталоге пользователя.

Файлы за пределами проектаCopy Anchor Link

Установка также записывает навыки Apothem в ваш домашний каталог пользователя, прежде чем что-либо изменить в проекте:

Эти папки являются общими. Они не принадлежат исключительно проекту:

• Каждый проект, в который вы устанавливаете kiro, использует одну и ту же копию ~/.kiro/skills/, и установка каждый раз записывает в неё одни и те же файлы. Kiro — единственный инструмент, который читает эту папку. Правила и шаблоны в ~/.config/apothem/ записываются также установками для других инструментов, с теми же файлами.
• --project выбирает, какой steering-файл записать и к какому проекту относится установка. Он не меняет место, куда попадают навыки.
• Установка не добавляет в ваш репозиторий ни одного файла навыка или правила. Проект получает steering-файл, файлы пользовательских агентов в .kiro/agents/, файл хуков .kiro/hooks/apothem.json, а также папку .apothem/, которую создаёт каждая установка в проект и в которой также лежат скрипты хуков.
• Папки в домашнем каталоге записываются первыми. Если это не удаётся, например потому что папка на пути является ссылкой, ведущей за пределы вашего домашнего каталога (ссылка, остающаяся внутри него, разрешается), или в неё нельзя записать, установка останавливается с ошибкой до того, как в проекте что-либо изменится.
• Папка навыка с именем навыка Apothem, которую Apothem не записывал, остаётся нетронутой, а установка выводит предупреждение с её именем. Переименуйте или переместите её, затем запустите apothem update. apothem verify завершается неудачей, пока это имя занято.
• В сумме файлы занимают несколько мегабайт.

Установка выводит примечание с названиями папок, которые она записывает за пределами --project, а --dry-run их перечисляет.

Файлы пользовательских агентовCopy Anchor Link

Kiro читает пользовательского агента из файла Markdown в <project>/.kiro/agents/ согласно документации Kiro по пользовательским агентам. Установка записывает в эту папку по одному файлу на каждого помощника Apothem, всех четырнадцати. Она нацелена на Kiro IDE 1.0 и Kiro CLI V3 (kiro-cli --v3) — версии, которые читают формат Markdown. Она не записывает ни JSON-профиль, ни какие-либо более старые ключи CLI 2.x, потому что V3 пропускает JSON-профиль, в котором есть allowedTools и нет блока permissions. Она выполняет установку только для проекта: пользовательская папка ~/.kiro/agents/ не записывается.

Каждый файл сохраняет инструкции помощника без изменений и содержит следующие ключи фронтматтера:

В Kiro один список для инструментов, поэтому разрешённые и запрещённые инструменты помощника становятся этим списком. Категории: read, write, shell, web и subagent:

Инструмент без категории (TodoWrite, Monitor, Artifact, TaskCreate, TaskUpdate, запись MCP) не включается. Категория не включается, если помощнику запрещён любой инструмент из неё, поэтому помощник никогда не получает запрещённый ему инструмент: помощник, который не может редактировать файлы, не получает категорию write. Помощник, все разрешённые инструменты которого отпадают, записывается с tools: [], чтобы ему не были даны все инструменты. Два помощника (mcp-builder и refactor-surgeon) получают write, девять получают shell, а три получают web. Установка не записывает ключ model, поэтому помощник работает на модели, которую выбирает Kiro, а также не записывает ни permissions, ни excludedTools, ни resources, ни mcpServers, ни hooks.

Что нужно знать:

• Kiro не загружает файлы пользовательских агентов рабочей области, пока вы не доверитесь этой рабочей области. Kiro CLI 2.33 и новее спрашивает «Trust this workspace?», когда вы впервые запускаете интерактивную сессию V3 в папке. Если Kiro не показывает ни одного помощника, доверьтесь папке и начните новую сессию.
• Apothem не подтвердил, загружает ли Kiro CLI 2.x агента V3 в формате Markdown. Используйте IDE или запустите kiro-cli --v3.
• Файлы агентов — обычные файлы проекта. Зафиксируйте их вместе с проектом или укажите .kiro/agents/ в .gitignore; Apothem не делает этот выбор за вас.
• Ваш файл с именем помощника Apothem сохраняется в ~/.apothem/backups/, а затем заменяется. Удаление не возвращает его на место. Файлы с другими именами, включая JSON-профили, никогда не затрагиваются.
• Страницы Kiro расходятся в том, видит ли пользовательский агент навыки в ~/.kiro/skills/ по умолчанию: страница о навыках говорит, что агенту нужен ресурс skill://, а справочник по конфигурации говорит, что агент наследует навыки по умолчанию. Установка не добавляет ключ resources, поэтому помощники видят навыки, только если верно второе прочтение.
• Страница встроенных инструментов Kiro перечисляет инструменты, которые обычно входят в каждую категорию. Категория read включает инструменты поиска файлов и поиска текста (glob и grep из CLI 2.x), поэтому Glob и Grep сопоставляются с ней. Она также включает code (анализ кода по синтаксическому дереву) и introspect (отвечает на вопросы о самом Kiro), поэтому помощник с read может использовать оба. Страница перечисляет code также в write и не сообщает, редактирует ли этот инструмент файлы.
• Apothem не подтвердил, что Kiro делает с опущенным ключом tools и какие ключи фронтматтера Kiro требует помимо name.

ХукиCopy Anchor Link

Kiro запускает хуки из файлов JSON в <project>/.kiro/hooks/ согласно документации Kiro по хукам. Установка записывает туда один файл, apothem.json (версия файла хуков v1), с одним хуком:

Хук добавляет контекст для модели. Он не блокирует ни вызов инструмента, ни сессию.

Apothem не регистрирует в Kiro хуки PreToolUse или PostToolUse. Kiro добавляет вывод команды в контекст модели только для SessionStart и UserPromptSubmit и игнорирует его для событий инструментов. Защита, зарегистрированная на событии инструмента, стоила бы запуска процесса при каждом вызове инструмента и ничего бы не доставляла, поэтому защиты записи, редактирования и оболочки, рекомендация по размеру контекста и протокол завершения сессии остаются в инструментах, которые их доставляют. Установка не записывает хук для UserPromptSubmit и не записывает хуков в пользовательскую папку ~/.kiro/hooks/.

Куда попадают файлы

Команда в файле хуков выглядит так, с вашим интерпретатором и путём проекта на месте двух путей:

"/path/to/python" "/path/to/project/.apothem/support/kiro/hooks/dispatch.py" --contract kiro SessionStart

--contract kiro заставляет диспетчер выводить контекст обычным текстом — именно его Kiro добавляет в контекст для SessionStart. Kiro не документирует оболочку для действий-команд в Windows. Команда записана для sh и cmd.exe, с путём интерпретатора с прямыми косыми чертами в кавычках; если Kiro на вашей машине запускает её через PowerShell, перед путём в кавычках нужен оператор вызова (&), и вы можете добавить его вручную.

Доверьтесь рабочей области. Kiro CLI 2.33 и новее загружает хуки рабочей области только после того, как вы доверитесь этой рабочей области: он спрашивает «Trust this workspace?», когда вы впервые запускаете интерактивную сессию V3 (kiro-cli --v3) в папке. Сессии Kiro Web не запускают хуков. Установка выводит это как примечание.

Фиксируйте с осторожностью. Команда называет интерпретатор, который Apothem нашёл при запуске, и абсолютный путь проекта, поэтому файл привязан к вашей машине, а скрипты, которые он запускает, находятся в .apothem/, которую игнорирует фрагмент .gitignore проекта. Если вы зафиксируете .kiro/hooks/apothem.json, checkout коллеги получит хук, указывающий в никуда: Kiro показывает предупреждение о неудавшейся команде, и сессия продолжается. Добавьте .kiro/hooks/apothem.json в .gitignore или фиксируйте его только для команды с такой же структурой. Установка не редактирует .gitignore.

Ваши собственные хуки. Ваши файлы хуков в .kiro/hooks/ никогда не читаются и не изменяются. Хук, который вы добавили в сам apothem.json, остаётся: обновление и удаление заменяют или удаляют только хуки, команда которых запускает диспетчер Apothem (.apothem/support/kiro/hooks/dispatch.py с --contract kiro, под каким бы путём проекта он ни был записан). Ваш хук, который лишь совпадает по имени или запускает python -m apothem.conformity.gate, никогда не принимается за хук Apothem. Файл, который не является допустимым JSON, сохраняется в ~/.apothem/backups/ и заменяется.

Пути, которые оболочка прочитала бы неверно. Путь проекта или интерпретатора, содержащий $, обратную кавычку, двойную кавычку или обратную косую черту, отклоняется до того, как что-либо записано: внутри команды в кавычках он запустил бы другой файл или сломал бы JSON, в который записана команда. Ошибка называет путь; переместите или переименуйте проект и запустите установку снова. Пробел или апостроф в пути допустимы.

Отключение хука. Задайте APOTHEM_HOOKS_DISABLE=1 в окружении Kiro, чтобы заглушить хук Apothem. Обновление перезаписывает запись Apothem, поэтому правка в ней не сохраняется, за одним исключением: задайте для неё "enabled": false — Kiro документирует это как пропуск хука без его удаления, — и обновление это сохранит.

Сопоставление профиля с нативной конфигурациейCopy Anchor Link

Адаптер читает общий профиль Apothem и рендерит steering-файл проекта при каждом запуске apothem install или apothem update. Общий профиль является источником истины; для локальных правок сгенерированного файла в проекте создаётся резервная копия, прежде чем следующая синхронизация заменит содержимое, управляемое Apothem.

Файл начинается с фронтматтера inclusion: always, потому что Kiro требует, чтобы конфигурация включения была первым содержимым файла. За ним следует управляемый Apothem блок; текст, который вы добавляете после блока, сохраняется при каждой синхронизации.

Заметки о совместимостиCopy Anchor Link

Поверхность steering в Kiro имеет область действия проекта и находится в .kiro/steering/. Адаптер записывает выделенный steering-файл apothem-rules.md с фронтматтером inclusion: always и никогда не перезаписывает базовые файлы Kiro, созданные оператором (product.md, tech.md, structure.md). Спецификации Kiro (.kiro/specs/) принадлежат оператору; Apothem их не записывает. Он записывает один файл хуков, .kiro/hooks/apothem.json, и никаких других файлов в .kiro/hooks/.

Kiro документирует ~/.kiro/skills/ для глобальных навыков и не упоминает ~/.agents/skills/, поэтому установка записывает папку Kiro, а не общую для инструментов. Навык рабочей области с тем же именем побеждает глобальный. Apothem не подтвердил, как Kiro обрабатывает ключ заголовка SKILL.md, который в документации не указан.

ПроверкаCopy Anchor Link

apothem verify --harness kiro --project /path/to/project

Команда verify подтверждает, что:

1. Нативная конфигурация существует по ожидаемому пути.
2. Каждая управляемая цель существует, включая папку .kiro/agents/; управляемые файлы не пусты, а конфигурации JSON или YAML разбираются. Добавьте --profile PATH, чтобы дополнительно подтвердить, что установленные файлы соответствуют этому профилю. Для .kiro/agents/ проверяется, что папка существует, а не что в ней есть файл каждого помощника; команда apothem diff --harness kiro --project /path/to/project перечисляет файлы помощников, которые отсутствуют или устарели. Файл хуков .kiro/hooks/apothem.json должен существовать, быть непустым, разбираться как JSON и содержать хук, запускающий диспетчер Apothem, а скрипты хуков должны находиться в .apothem/support/kiro/hooks/. Проверка не запускает хук.
3. Каждая папка навыка Apothem на месте и содержит SKILL.md, какая бы установка её ни записала, и ни одна папка навыка с именем Apothem не принадлежит тому, что Apothem не записывал. Неудачная проверка называет отсутствующие или чужие папки.
4. Процедура проверки, специфичная для адаптера, сообщает об успехе.

ОбновлениеCopy Anchor Link

apothem update --harness kiro --project /path/to/project

Повторно выводит steering-файл проекта из текущего состояния общего профиля.

Обновление также перезаписывает каждую папку навыка, файлы которой отличаются от текущих. Если вы устанавливали более ранним выпуском, который не записывал навыки, обновление их добавляет. Оно перезаписывает файлы пользовательских агентов, которые отличаются от текущих, и добавляет отсутствующие. Оно также обновляет скрипты хуков и хук Apothem в .kiro/hooks/apothem.json, сохраняя любой ваш хук в этом файле.

УдалениеCopy Anchor Link

apothem uninstall --harness kiro --project /path/to/project

Удаляет блок Apothem и фронтматтер, который Apothem записал над ним, из <project>/.kiro/steering/apothem-rules.md и сохраняет любой другой текст в этом файле. Файл удаляется, только если в нём больше ничего не остаётся. Перед изменением копия файла с отметкой времени сохраняется в ~/.apothem/backups/; резервных файлов в проекте не остаётся. YAML общего профиля и движок Apothem не затрагиваются.

Удаление также удаляет файлы пользовательских агентов, которые оно записало в <project>/.kiro/agents/, и сохраняет любой другой файл там; папка удаляется, если остаётся пустой. Оно удаляет хук Apothem из <project>/.kiro/hooks/apothem.json, распознавая его по пути диспетчера в его команде, поэтому работает без записи об установке, и сохраняет любой ваш хук в этом файле. Файл удаляется, когда в нём не остаётся ничего другого, а ваши другие файлы хуков не затрагиваются. Если в файле есть комментарии, которые удаление не может прочитать, оно оставляет файл как есть и сообщает о хуке как о пропущенном, с причиной; удалите хук Apothem вручную. Скрипты хуков в <project>/.apothem/support/kiro/hooks/ тоже удаляются. Оно удаляет папки навыков, которые записало в ~/.kiro/skills/, а также правила и шаблоны в ~/.config/apothem/, но только когда никакая другая установка Apothem их больше не использует. Их может использовать другой проект или другой инструмент, разделяющий эту папку. В таком случае удаление сохраняет папки, выводит, какая установка их использует, и их удаляет последнее удаление. Файлы, которые вы добавили в эти папки, остаются, а папка, оставшаяся пустой, удаляется. Перед удалением каждая папка сохраняется в резервную копию в ~/.apothem/backups/.

Шлюз соответствияCopy Anchor Link

python -m apothem.conformity.gate --all .

Устранение неполадокCopy Anchor Link

Параметры конфигурацииCopy Anchor Link

См. такжеCopy Anchor Link

• Все окружения — полный каталог поддерживаемых инструментов
• Руководство по установке — установка Apothem в это окружение
• Справочник по apothem harnesses — вывод списка и просмотр адаптеров из CLI