---
referenceVersion: 2
---

# Архитектура

## Платформа и приложение

Ядро выполняет workflow, проверяет определения и связывает входы с выходами. Конструкции задают порядок выполнения. Блоки выполняют операции; плагины добавляют блоку драйвер, обработчик или формат.

Серверная поставка предоставляет UI, API и устойчивое хранилище состояния. Встраивание в Python и отдельный сервер используют одни определения и правила выполнения.

### Где живут сценарии

Workflow, промпты, адреса сервисов и правила приложения находятся в его репозитории. База запусков, файлы и секреты принадлежат инсталляции и хранятся вне Git. Движок не импортирует код приложения.

Прикладная логика собирается в workflow. Повторяемую интеграцию можно вызывать как вложенный сценарий. CLI запускает установленные инструменты; оркестрация остаётся видимой в определении процесса.

## Входы и выходы

Workflow объявляет JSON Schema входов и результата. Каждый блок и вложенный workflow имеет явный контракт. Внешнему вызывающему доступны только объявленные `outputs`.

## Поля YAML

| Поле | Назначение |
| --- | --- |
| `schema_version` | Версия формата определения |
| `name`, `description`, `version` | Название, описание и авторская версия |
| `input_schema`, `output_schema` | JSON Schema входов и результата |
| `inputs` | Входные значения по умолчанию |
| `steps` | Шаги выполнения |
| `outputs` | Результат для вызывающего |
| `secrets` | Объявления необходимых секретов |
| `timeout_seconds` | Лимит активного выполнения |
| `triggers`, `on_finish` | Условия запуска и последующее действие |

## Блок, шаг и конструкция

`block` выбирает тип блока, `id` именует конкретный шаг. Один блок может использоваться в процессе несколько раз с разными параметрами. `params.operation` выбирает операцию, если у блока их несколько.

`steps`, `loop`, `concurrency`, `call`, `approval` — конструкции управления. Они также отображаются узлами графа, но не требуют поля `block`.

## Параметры шага

```yaml
- id: request
  block: http
  params:
    url: "{inputs.source_url}"
```

Параметры проверяются по схеме выбранной операции. Неизвестные поля отклоняются. Справочники операций находятся у <a href="/store/" target="_self">соответствующих блоков в магазине</a>.

## Ссылки

`{inputs.text}` — вход workflow; `{request.json}` — результат шага; `{secret.KEY}` — объявленный секрет. Целая ссылка сохраняет тип значения. Отсутствующее поле считается ошибкой; `null` и пустая строка различаются.

Буквальные фигурные скобки экранируются удвоением. Данные подставляются один раз и не превращаются в код. Служебные пространства `inputs`, `secret`, `state`, `loop` нельзя подменять именами шагов. Внутренние имена групп имеют собственную область видимости.

## Файлы

`FileRef` — ссылка на сохранённый файл: ID, имя, MIME-тип и размер. Между шагами передаётся ссылка, а не копия байтов. Доступ проверяется для текущего аккаунта.

## Условия

`when` определяет, выполнять ли шаг. Условие проверяется до его параметров. Ложное условие пропускает шаг без создания результата.

| Поле | Назначение |
| --- | --- |
| `value` | Проверяемое значение |
| `op` | Оператор |
| `expected` | Ожидаемое значение |

Операторы: `equals`, `not_equals`, `in`, `gte`, `lte`, `min_length`, `max_length`, `matches`, `contains`. Все три поля обязательны; типы автоматически не приводятся. В `approval.when` условие относится к необходимости согласования результата вызова.

## Состояние выполнения · state

`state` содержит статусы шагов и решения по согласованию. Полезный результат шага и состояние его исполнения доступны отдельно:

| Ссылка | Значение |
| --- | --- |
| `{request.json}` | Результат операции |
| `{state.request.status}` | Статус шага |
| `{state.draft.approval.status}` | Решение по согласованию |
| `{loop.state}` | Данные, передаваемые между итерациями |

Пропущенный шаг не создаёт результата. Следующий шаг должен учитывать это в условии, прежде чем обращаться к его выходам.

## Ошибки и ожидания

Ошибка останавливает текущий путь, если операция явно не возвращает её как данные. При `on_error: collect` ошибка пути возвращается как `code`, `message`, `step_path`. После ожидания используются сохранённые результаты; завершённые действия не повторяются.

Запуск сохраняет свои определения и зависимости. Изменение YAML влияет на новые запуски. `on_finish` создаёт отдельный последующий запуск с явными входами.

## Поставка плагинов

Ядро, блоки и плагины выбираются независимо. Базовый блок означает часть основного инвентаря, а не обязательную зависимость ядра. [Руководство по магазину](/doc/store) объясняет выбор состава и совместимость.