Сетапы

Повседневная сборка — intent change, повседневная установка записанного сетапа — install. Не набирайте setup compose plan, если у вас ещё нет digest.

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

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 этого харнесса.

Как собирается сетап

Упрощённый путь:

кандидаты из каталога и локального реестра
→ механические фильтры
→ вопросы агента
→ подтверждение пользователя
→ setup graph
→ deterministic compiler
→ provider plan

Агент помогает выбрать состав, но не обходит проверки совместимости, доступа и безопасности.

Этап	Кто отвечает	Что должно быть видно
Поиск кандидатов	CLI и каталог	источник, версия, харнесс, trust line
Выбор состава	пользователь и agent	почему выбран каждый компонент
Проверка графа	сборщик сетапа	конфликты, несовместимости, missing pieces
План применения	provider	target diff, backup, digest
Применение	provider	журнал операции и status

Установка

Перед изменением target provider строит план, создаёт резервную копию и только после подтверждения применяет изменения.

Работающий агент не изменяет собственный активный target по месту. Новый сетап проверяется отдельно, а переключение выполняется после проверки.

Rollback

Если применение не удалось, восстановление идёт через provider и журнал операций. Не удаляйте резервные копии вручную до завершения восстановления.

Осознанный откат из снятой копии

Это другой путь, чем восстановление после неудачи. Здесь вы заранее снимаете копию цели, позже меняете сетап, а ещё позже возвращаетесь к снятой копии.

Сначала копия:

$ 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

Позже копию не нужно помнить — её перечисляет отдельная команда:

ai-stp target backups --project <id> --harness <id> --json

Ответ содержит backup_ref, операцию, которая её сняла, и версию сетапа, установленную на тот момент. Дальше — обычные план, подтверждение и применение:

$ 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 не содержит файлов, которые вы не устанавливали, а копия их сохраняет;
• восстановление возвращает цель целиком. Восстановить один компонент нельзя, и такой запрос отклоняется.

Как думать о версии сетапа

Сетап — не папка с текущими файлами, а закреплённый состав. Если вы обновили один skill, отключили hook или поменяли setting, это уже новая версия сетапа.