Команды сетапа

Собрать, импортировать, обновить и опубликовать полный сетап.

Команды сетапа

Сетап — это полная конфигурация одного харнеса. Он фиксирует точные версии компонентов. Эти команды компонуют смешанный сетап из каталога и внешних источников, импортируют уже имеющуюся нативную конфигурацию, заменяют один встроенный элемент и планируют публикацию всего графа.

Они не записывают таргет харнеса. Повседневная сборка — intent change. Повседневная установка записанного сетапа — intent install. Не набирайте setup compose plan или install plan, если вы не восстанавливаете остановившуюся операцию.

ai-stp task start --intent change --idempotency-key change-session-01 --json

Следуйте continuations. После записи identity сетапа запустите install тем же способом. Expert compose / import / publish ниже — для операторов, у которых уже есть digest.

Установка по-прежнему идёт через Install и публичного провайдера.

Таблица команд

--json — глобальный флаг. Всегда передавайте его.

compose apply и update apply требуют --expected-plan-digest. Этот дайджест и есть решение. import register требует --plan-digest (это декларированное имя). publish confirm требует --set-digest и --confirm, потому что меняет видимость существующего объекта.

Compose plan и apply

Поместите отрецензированные метаданные и источники в 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):

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 повторяет разрешение и отклоняет изменённые байты. Передайте возвращённый идентификатор сетапа, временную метку и дайджест плана:

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 лишь записывает, где он.

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

Замена одного встроенного компонента более новым точным снапшотом. Фиксации каталога таким образом не обновляются.

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:

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

Спланируйте публикацию одного выпущенного сетапа вместе со всеми компонентами, которые он фиксирует. Подтверждение делает этот точный граф публичным: сначала фиксированные компоненты, затем сетап.

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:

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

setup compose plan --manifest setup.json --root .
→ setup compose apply --manifest setup.json --root . --id … --created-at … --expected-plan-digest …

Импорт нативного дерева (повседневный intent author):

ai-stp task start --intent author --idempotency-key author-session-01 --json

Expert import (уже есть plan digest):

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

ai-stp task start --intent publish --idempotency-key publish-session-01 --json

Expert publish (уже есть set digest):

setup publish plan --id <setup_id> --version <X.Y>
→ setup publish confirm --set-digest … --confirm

Именованные поля успеха

Отказы

Секреты, удалённые при inspect, остаются удалёнными. Не вставляйте их обратно в паспорт, чтобы «завершить» импорт.

Связанные ссылки

• Сетапы
• Select
• Install
• Источник компонента
• Публикация компонента
• Publication
• Publishing
• Карта команд

Флаги берутся из continuation argv

ai-stp task intents --json

Не дампьте help --agent как прелюдию. Флаги текущей задачи — в continuation argv.

Эта страница группирует команды сетапа, чтобы человек мог их найти. Если эта страница и CLI расходятся, следуйте CLI.