ai_stp

# Команды сетапа Сетап — это полная конфигурация одного харнеса. Он фиксирует точные версии компонентов. Эти команды компонуют смешанный сетап из каталога и внешних источников, импортируют уже имеющуюся нативную конфигурацию, заменяют один встроенный элемент и планируют публикацию всего графа. Они не записывают таргет харнеса. Повседневная сборка — intent `change`. Повседневная установка записанного сетапа — intent `install`. Не набирайте `setup compose plan` или `install plan`, если вы не восстанавливаете остановившуюся операцию. ```bash ai-stp task start --intent change --idempotency-key change-session-01 --json ``` Следуйте `continuations`. После записи identity сетапа запустите `install` тем же способом. Expert compose / import / publish ниже — для операторов, у которых уже есть digest. Установка по-прежнему идёт через [Install](install.md) и публичного провайдера. ## Таблица команд | Команда | Мутабельность | Подтверждение | Когда | | --- | --- | --- | --- | | `ai-stp task start --intent change` | `apply` | `none` | повседневная сборка; записывает новый identity сетапа | | `ai-stp task start --intent install` | `apply` | `none` | повседневная установка записанного сетапа | | setup compose plan | `plan` | `none` | expert: разрешить и зафиксировать новый сетап из каталога, Git, пакетов и path-источников | | setup compose apply | `apply` | `plan_digest` | expert: записать точный, по-прежнему актуальный смешанный сетап как одну неизменяемую локальную версию | | setup import inspect | `read` | `none` | прочитать одну нативную конфигурацию; ничего не записывать | | setup import plan | `plan` | `none` | спланировать точные черновики компонентов и сетапа из одной нативной конфигурации | | setup import register | `apply` | `plan_digest` | зарегистрировать проинспектированную конфигурацию как свой сетап | | setup update plan | `plan` | `none` | предпросмотр замены одного встроенного компонента более новым точным снапшотом | | setup update apply | `apply` | `plan_digest` | применить одно точное встроенное обновление и создать новую версию сетапа | | setup publish plan | `plan` | `none` | спланировать публикацию одного выпущенного сетапа со всеми компонентами, которые он фиксирует | | setup publish confirm | `apply` | `explicit_flag` | подтвердить один точный отрецензированный набор публикации | `--json` — глобальный флаг. Всегда передавайте его. `compose apply` и `update apply` требуют `--expected-plan-digest`. Этот дайджест и есть решение. `import register` требует `--plan-digest` (это декларированное имя). `publish confirm` требует `--set-digest` и `--confirm`, потому что меняет видимость существующего объекта. ## Compose plan и apply Поместите отрецензированные метаданные и источники в JSON-манифест. Внешние компоненты не требуют записи в каталоге. ```json { "schema_version": 1, "name": "Frontend developer", "description": "Playwright automation with local project checks.", "harness_id": "codex", "components": [ { "source": { "kind": "catalog", "stable_id": "component_...", "version": "1.0", "passport_digest": "sha256:..." } }, { "source": { "kind": "git", "repository_url": "https://github.com/example/context7", "tracked_ref": "main", "subpath": "." }, "component_type": "mcp", "name": "Context7 MCP", "description": "Upstream Context7 MCP snapshot.", "license_spdx": "MIT", "redistribution_allowed": true, "upstream_project": "Context7" }, { "source": {"kind": "path", "relative_path": "hooks/check"}, "component_type": "hook", "name": "Project check", "description": "Locally authored project check.", "license_spdx": "LicenseRef-Proprietary", "redistribution_allowed": true } ] } ``` Expert recovery (уже есть digest): ```text ai-stp setup compose plan --manifest setup.json --root . --json ``` `--manifest` обязателен. `--root` ограничивает источники `path:`. `--id` — это идентификатор сетапа, возвращённый предыдущим планом, когда вы перепроверяете ту же идентичность. Ответ плана несёт `setup_id`, `version`, `harness_id`, `created_at`, `definition_digest`, `plan_digest`, `members`. У каждого элемента есть `stable_id`, `version`, `source`, `embedded`. Apply повторяет разрешение и отклоняет изменённые байты. Передайте возвращённый идентификатор сетапа, временную метку и дайджест плана: ```text ai-stp setup compose apply \ --manifest setup.json \ --root . \ --id <setup_id> \ --created-at <created_at> \ --expected-plan-digest sha256:... \ --json ``` Git-ссылки разрешаются в коммиты, источники-пакеты требуют точных версий, а локальные пути остаются в пределах `--root`. Встроенные элементы публикуются только внутри сетапа; элементы каталога сохраняют своего существующего издателя. Поля успеха: `setup_id`, `version`, `created_at`, `passport_digest`, `definition_digest`, `plan_digest`, `created`. ## Import inspect, plan, register Import вносит нативную конфигурацию харнеса в локальный реестр как ваш собственный сетап. Значения секретов не сохраняются. Таргет не затрагивается: провайдер уже сделал бэкап; register лишь записывает, где он. ```text ai-stp setup import inspect --root <native-dir> --harness codex --json ai-stp setup import plan --root <native-dir> --harness codex --json ai-stp setup import register \ --root <native-dir> \ --harness codex \ --backup-ref <ref> \ --plan-digest sha256:... \ --json ``` `--root` и `--harness` обязательны для всех трёх. Register также требует `--backup-ref` и `--plan-digest`. `--target` указывает, с какого таргета был сделан бэкап. `--partial` регистрирует даже если некоторые файлы были пропущены; паспорт записывает режим и точные пути. Поля успеха inspect: `root`, `harness_id`, `detection_rule`, `files`, `redacted_keys`, `oversized`, `unreadable`. Поля plan: `plan_digest`, `inspection_digest`, `components`, `effects`, `excluded`, `blocked_by`. Поля register: `stable_id`, `revision_id`, `backup_id`, `component_ids`, `plan_digest`, `redacted_keys`. ## Update plan и apply Замена одного **встроенного** компонента более новым точным снапшотом. Фиксации каталога таким образом не обновляются. ```text ai-stp setup update plan \ --id <setup_id> \ --version 1.0 \ --component-id <embedded_id> \ --source git:https://github.com/example/context7 \ --commit abcdef0123456789abcdef0123456789abcdef01 \ --subpath . \ --harness codex \ --project . \ --json ``` `--id`, `--version`, `--component-id`, `--source` и `--harness` обязательны. `--source` — это точная координата `git`, `package:ecosystem:name@version` или `path:relative`. `--commit` — точный lowercase 40-символьный Git SHA. `--project` — корень проекта, чей выбранный сетап проверяется. Apply повторяет те же опции и добавляет `--expected-plan-digest`: ```text ai-stp setup update apply \ --id <setup_id> \ --version 1.0 \ --component-id <embedded_id> \ --source git:https://github.com/example/context7 \ --commit abcdef0123456789abcdef0123456789abcdef01 \ --harness codex \ --expected-plan-digest sha256:... \ --json ``` Поля plan включают `plan_digest`, `setup_id`, `component_id`, `from_version`, `to_version`, `snapshot_coordinate`, `snapshot_identity`, `suggested_catalog_stable_id`, `suggested_catalog_version`, `suggested_catalog_dismissible`. Поля apply: `created`, `setup_id`, `from_version`, `to_version`, `selected_stable_id`, `selected_version`, `plan_digest`. Результат — **новая** версия сетапа. ## Publish plan и confirm Спланируйте публикацию одного выпущенного сетапа вместе со всеми компонентами, которые он фиксирует. Подтверждение делает этот точный граф публичным: сначала фиксированные компоненты, затем сетап. ```text ai-stp setup publish plan --id <setup_id> --version 1.0 --json ai-stp setup publish confirm \ --set-digest sha256:... \ --confirm \ --json ``` Plan требует `--id` и `--version`. Confirm требует `--set-digest` (дайджест, который вернул plan) и `--confirm`. Поля успеха: `set_digest`, `setup_stable_id`, `setup_version`, `state`, `expires_at`, `members`. У каждого элемента есть `plan_id`, `plan_hash`, `role`, `object_kind`, `stable_id`, `version`, `state`, `already_published`. ## Счастливый путь Compose: ```text task start --intent change --idempotency-key change-session-01 --json → follow continuations until there are none → task start --intent install --idempotency-key install-session-01 --json ``` Expert compose (уже есть digest): ```text setup compose plan --manifest setup.json --root . → setup compose apply --manifest setup.json --root . --id … --created-at … --expected-plan-digest … ``` Импорт нативного дерева (повседневный intent `author`): ```bash ai-stp task start --intent author --idempotency-key author-session-01 --json ``` Expert import (уже есть plan digest): ```text setup import inspect --root <dir> --harness <id> → setup import plan --root <dir> --harness <id> → setup import register --root <dir> --harness <id> --backup-ref … --plan-digest … ``` Публикация графа (повседневный intent `publish`): ```bash ai-stp task start --intent publish --idempotency-key publish-session-01 --json ``` Expert publish (уже есть set digest): ```text setup publish plan --id <setup_id> --version <X.Y> → setup publish confirm --set-digest … --confirm ``` ## Именованные поля успеха | Команда | Поля для чтения | | --- | --- | | `compose plan` | `setup_id`, `created_at`, `plan_digest`, `members` | | `compose apply` | `setup_id`, `version`, `passport_digest`, `created` | | `import inspect` | `files`, `redacted_keys`, `unreadable` | | `import plan` | `plan_digest`, `components`, `blocked_by` | | `import register` | `stable_id`, `backup_id`, `component_ids` | | `update plan` | `plan_digest`, `from_version`, `to_version` | | `update apply` | `created`, `to_version`, `selected_version` | | `publish plan` / `confirm` | `set_digest`, `members`, `state` | ## Отказы | Что вы видите | Что это значит | Что делать | | --- | --- | --- | | `AI_STP_USER_DECISION_REQUIRED` | `--confirm` был пропущен при publish confirm | передайте `--confirm` после ревью набора публикации | | `AI_STP_VALIDATION_ERROR` | отсутствует `--expected-plan-digest`, `--plan-digest` или `--set-digest` | скопируйте дайджест, который вернул plan | | `AI_STP_PLAN_STALE` | байты Git, байты пакетов или локальные пути изменились | спланируйте заново; apply отклоняет изменённые байты | | `AI_STP_PRECONDITION_FAILED` | import register без бэкапа провайдера или несвязанный элемент | сделайте бэкап через install; исправьте манифест | | `AI_STP_AUTH_REQUIRED` | publish требует выполненного входа | `task start --intent account --idempotency-key account-session-01 --json` | | `AI_STP_PERMISSION_DENIED` | эта учётная запись не может публиковать этот сетап | проверьте владельца и гранты | | путь за пределами `--root` | локальные источники ограничены | переместите файлы или измените `--root` | | плавающая версия пакета | источники-пакеты требуют точную версию | зафиксируйте `name@version` | | выдумывание `--expected-plan-digest` для import register | эта команда декларирует `--plan-digest` | используйте декларированное имя | Секреты, удалённые при inspect, остаются удалёнными. Не вставляйте их обратно в паспорт, чтобы «завершить» импорт. ## Связанные ссылки - [Сетапы](../setups/index.md) - [Select](select.md) - [Install](install.md) - [Источник компонента](component-source.md) - [Публикация компонента](component-publish.md) - [Publication](publication.md) - [Publishing](../publishing/index.md) - [Карта команд](commands.md) ## Флаги берутся из continuation argv ```bash ai-stp task intents --json ``` Не дампьте `help --agent` как прелюдию. Флаги текущей задачи — в continuation `argv`. Эта страница группирует команды сетапа, чтобы человек мог их найти. Если эта страница и CLI расходятся, следуйте CLI.