ai_stp

# Сетапы Повседневная сборка — intent `change`, повседневная установка записанного сетапа — `install`. Не набирайте `setup compose plan`, если у вас ещё нет digest. ```bash ai-stp task start --intent change --idempotency-key change-session-01 --json ai-stp task start --intent install --idempotency-key install-session-01 --json ``` ## Сборка из каталога и внешних источников `setup compose` собирает один точный setup из каталожных компонентов и embedded компонентов из GitHub, package registry или локального пути. Внешнему компоненту не обязательно иметь собственную карточку в каталоге. Формат JSON-манифеста и полный пример находятся в английской версии этой страницы. Expert compose (уже есть digest): ```text ai-stp setup compose plan --manifest setup.json --root . --json ai-stp setup compose apply --manifest setup.json --root . --id <setup_id> --created-at <created_at> --expected-plan-digest <digest> --json ai-stp setup export --id <setup_id> --version 1.0 --output ./exported-setup --json ai-stp setup publish plan --id <setup_id> --version 1.0 --json ``` Git ref замораживается в commit, package требует точную версию, а локальный путь ограничен `--root`. `apply` повторно получает источники и откажется, если байты изменились. Embedded-компоненты публикуются внутри setup, а каталожные сохраняют своего publisher и идентичность. `setup export` пишет review-дерево уже записанного определения: паспорт, артефакт определения и README, где сказано, что хранилище — локальный реестр, а физическое дерево харнесса не создаётся. Занятый каталог отвергается. Native состояние харнесса не пишется. Сетап — итоговая конфигурация одного харнесса. Он закрепляет точные версии компонентов и применяется только через public provider этого харнесса. ## Как собирается сетап Упрощённый путь: ```text кандидаты из каталога и локального реестра → механические фильтры → вопросы агента → подтверждение пользователя → setup graph → deterministic compiler → provider plan ``` Агент помогает выбрать состав, но не обходит проверки совместимости, доступа и безопасности. | Этап | Кто отвечает | Что должно быть видно | | --- | --- | --- | | Поиск кандидатов | CLI и каталог | источник, версия, харнесс, trust line | | Выбор состава | пользователь и agent | почему выбран каждый компонент | | Проверка графа | сборщик сетапа | конфликты, несовместимости, missing pieces | | План применения | provider | target diff, backup, digest | | Применение | provider | журнал операции и status | ## Установка Перед изменением target provider строит план, создаёт резервную копию и только после подтверждения применяет изменения. Работающий агент не изменяет собственный активный target по месту. Новый сетап проверяется отдельно, а переключение выполняется после проверки. ## Rollback Если применение не удалось, восстановление идёт через provider и журнал операций. Не удаляйте резервные копии вручную до завершения восстановления. ### Осознанный откат из снятой копии Это другой путь, чем восстановление после неудачи. Здесь вы заранее снимаете копию цели, позже меняете сетап, а ещё позже возвращаетесь к снятой копии. Сначала копия: ```text $ ai-stp install plan --action backup --project <id> --harness <id> \ --provider <exe> --provider-manifest <path> --protocol-version 3 \ --target <dir> --json $ ai-stp install approve --operation <id> --plan-digest <exact> --json $ ai-stp install apply --operation <id> --provider <exe> --json ``` Позже копию не нужно помнить — её перечисляет отдельная команда: ```console ai-stp target backups --project <id> --harness <id> --json ``` Ответ содержит `backup_ref`, операцию, которая её сняла, и версию сетапа, установленную на тот момент. Дальше — обычные план, подтверждение и применение: ```text $ ai-stp install plan --action rollback --backup-ref <exact> \ --provider <exe> --provider-manifest <path> --protocol-version 3 \ --target <dir> --json $ ai-stp install approve --operation <id> --plan-digest <exact> --json $ ai-stp install apply --operation <id> --provider <exe> --json $ ai-stp target status --project <id> --harness <id> --json ``` Три отличия, которые стоит держать в голове: - `target rollback` **называет** предыдущую подтверждённую версию и ничего не восстанавливает. Это ответ на «куда откатываться», а не «откатись»; - повторная установка прошлой версии через `action=update` — не то же самое, что восстановление: bundle не содержит файлов, которые вы не устанавливали, а копия их сохраняет; - восстановление возвращает цель **целиком**. Восстановить один компонент нельзя, и такой запрос отклоняется. ??? tip "Как думать о версии сетапа" Сетап — не папка с текущими файлами, а закреплённый состав. Если вы обновили один `skill`, отключили `hook` или поменяли `setting`, это уже новая версия сетапа.