Перейти к содержимому

Воркфлоу

Воркфлоу в Moira — это направленный граф узлов, определяющий многошаговый процесс для выполнения AI-агентами.

Структура воркфлоу

Статический прогресс выполнения

Workflow может объявить необязательный top-level граф progress для краткого пользовательского представления. Workflow из нескольких стадий стоит его объявлять и помечать humanGate каждый шаг, где он ждёт решения человека: людям запуск показан ровно тем, что workflow объявил, а workflow без блоков показан как запуск, о прогрессе которого сказать нечего. Workflow Management Flow делает так по умолчанию и требует записанной причины, чтобы обойтись без прогресса. Определение может содержать шаблонизируемые title и goal, ограниченный набор общих facts и упорядоченные ноды. Нода содержит id, шаблонизируемый label, необязательный структурный plain-text content (summary, details, outcome, next), необязательную привязку list и статическую связь connections.default для отрисовки.

Блок, который проходит список, объявляет list с путями переменных, которые он читает: items (массив), title (путь внутри одного элемента; строковый элемент сам является своим заголовком), current (индекс текущего элемента, отсчитываемый от indexBase — 1 по умолчанию, 0 при явном объявлении), done (число завершённых) и total. Нужен хотя бы один из items, current и total; total по умолчанию равен длине items, а done — current − indexBase. Корень каждого пути — объявленная глобальная переменная или id ноды для её локального вывода; валидация отвергает неизвестный корень и title без items. Привязка называет только пути: движок ничего не знает о содержимом списка.

Граф progress — это представление воркфлоу как процесса: его ноды — блоки, а порядок массива — порядок процесса. Если progress присутствует, каждая нода основного графа, включая ноды маршрутизации, объявляет свой блок через progressNodeId; каждый блок несёт описание в content.summary; и каждая связь, которая выходит из блока либо возвращается к более раннему блоку или к своему же блоку, несёт запись connectionLabels с теми же ключами, что и connections: простую подпись или { "label": …, "cycle": { "cause": …, "exit": … } } для возврата. Переходы, циклы и блоки-хабы выводятся из основного графа и никогда не описываются дважды; отрисовочная связь connections.default этим выводом игнорируется. Шаблон результата ({{progress_*_outcome}}) стоит ровно на одном блоке, которому принадлежит нода, записывающая эту переменную. Валидация сообщает о каждом нарушении как об ошибке со стабильным кодом — unowned-node, unknown-block, empty-block, empty-description, unlabeled-edge, unexplained-cycle, outcome-duplicate, outcome-unowned, unconnected-block, — а moira-workflow <file> derive и GET /api/workflows/:id/process показывают выведенные блоки с теми же диагностиками.

Нода, на которой запуск останавливается (шаг agent-directive или другой останавливающий тип), также может объявить шаблонизируемый progressActiveLabel. Он заменяет отображаемую подпись её блока только пока именно эта нода является текущей, поэтому workflow может правдиво показывать unit, iteration, validation или repair detail без изменения стабильной подписи блока. Поле требует, чтобы нода принадлежала блоку, и не влияет на routing или сохранённое state.

Название задачи берётся из независимых метаданных запуска; произвольная заметка остаётся отдельно (см. Название задачи запуска). Та же нода может объявить progressActiveContent с теми же структурными полями. Пока эта нода активна, указанные поля заменяют соответствующие поля её блока, а пропущенные сохраняют базовые значения. Вложенные строки используют обычный реестр переменных и защиту шаблонов. Progress не хранит историю presentation: замена контекста, привязанного к revision, полностью заменяет следующую проекцию и не сохраняет устаревшие значения прежнего плана. После интерполяции текст повторно проверяется по тем же ограничениям. Слишком большое runtime-значение явно прерывает projection, а не молча обрезается до вводящей в заблуждение сводки.

Статус блока определяется записанным маршрутом запуска, а не порядком массива. Каждый запуск записывает по одному посещению на каждую выполненную ноду — ноду, связь, через которую она вышла (teleport для прыжка), изменённые переменные и факт паузы, — а execution({ action: "progress" }) проецирует этот маршрут на процесс: блок последнего посещения — active или waiting, если запуск там ждёт; посещённый блок — done или repeated с числом проходов через его рабочие шаги; блок, чья работа не выполнялась или который запуск обошёл, — skipped; остальные — pending. Возврат к раннему блоку через repair, цикл или replan снова делает его активным и добавляет проход. Ничто непосещённое никогда не отмечается завершённым, а запуск, созданный до записи маршрутов, показывает только текущий блок активным с routeRecorded: false. Та же проекция содержит маршрут с отметками циклов и каждую переменную с историей; значения, заданные извне флоу, показаны как корректировки с их автором. Отрисовочные connections графа progress не маршрутизируют execution.

Каждый визит записывает, когда в него вошли и когда его покинули, поэтому каждый блок также сообщает своё timing — каждый проход с длительностью, сумму по всем проходам и то, сколько уже длится текущий проход, — а привязанный к списку блок ещё и свой list: элементы с заголовками, какие завершены, какой выполняется сейчас и сколько времени потрачено на каждый. У визита без отметок времени длительности нет, а не ноль. Проекция сообщает версию, которой помечен запуск (executionWorkflowVersion), рядом с версией определения, на которое она спроецирована, а представление запуска добавляет statistics: сколько обычно занимают проход, всё время запуска в блоке и каждая позиция списка по остальным завершённым запускам владельца этой версии — медиана с квартилями и размахом, — чтобы запуск можно было читать в сравнении с обычным; запуски одного пользователя никогда не становятся статистикой другого. Проекция также говорит, кого ждёт приостановленный запуск (waitingFor): user на гейте, который проходит человек (PIN шага lock), или на шаге, который флоу пометил humanGate и чьё условие выполнилось при входе запуска, или пока открыт вопрос самого агента (execution (await-user)), agent на любом другом приостановленном шаге, null, когда запуск не ждёт. Она ещё говорит, что просят сделать человека (waitingForUser): { source: "agent", question, options, since } для вопроса агента — он важнее — или { source: "gate", label } для помеченного шага. Проекция на курсоре маршрута вопроса агента не несёт: его нет в маршруте. GET /api/workflows/:id/statistics?version= возвращает ту же агрегацию для любой версии по завершённым запускам вызывающего.

Если поле progress присутствует, каждая нода основного графа ссылается на существующий блок, как описано выше. Несколько нод основного графа могут ссылаться на один блок. Для активного блока фокусом является текущая нода основного графа, для остальных — первая связанная нода в порядке workflow. Pending- и skipped-блоки сохраняют summary, details и next, но скрывают outcome, чтобы результат прежней revision или unit не выглядел текущим во время engine-owned перехода.

Сопряжённый владелец рисует картинку прогресса запуска как карту страницы запуска, растрированную: те же карточки с портами (полоса заголовка с номером блока, именем, числом проходов и словом статуса — waiting for you только когда действовать должен человек, agent on the step пока на шаге работает агент, completed, repeated, skipped (имя зачёркнуто), pending — с тоном по статусу; входные порты называют исходный блок, выходные названы подписью перехода, порты возврата пунктирные, двойной порт для переходов блока на себя; строка фактов с затраченным временем и, у блока, привязанного к списку, done/total с текущим элементом; у блока, который ещё не выполнялся, времени нет, а — стоит вместо счётчика, который привязка не разрешила; строка typically … из статистики версии по другим завершённым запускам владельца) и те же связи (forward, skip, hub, return, self), уложенные той же раскладкой, что и веб-карта; светлая или тёмная, из той же проекции. Текст переносится по ширине карточки, и каждая подпись остаётся внутри своего поля; при viewport 720 px и меньше картинка использует масштаб шрифта для телефона и раскладку столбиком, более широкие — раскладку рядами, когда она помещается, иначе столбиком. Агент получает короткоживущую, привязанную к revision и одноразовую ссылку через execution (progress-image-token); бинарные данные через MCP не передаются. Токен принимает необязательные theme (light|dark), viewportWidth (480–4096), view — cards (по умолчанию: карточка хранит краткое содержание, детали, результат и следующий шаг блока) или process (только компактная карточка — карта, как её показывает страница запуска; причина и выход цикла есть на портах страницы запуска, а не в картинке) — и hide / collapse: идентификаторы блоков или авторских нод (нода называет свой блок), которые исключаются из картинки с переносом их переходов на соседей или рисуются чипом только с названием. Неизвестные идентификаторы отклоняются при выпуске токена. Нода user-notification может задать attachProgressImage: true и использовать обычное сообщение как подпись к изображению. Такая нода обязана принадлежать существующему блоку. К уведомлению прикладывается не эта карта, а шаги запуска, сделанные для телефона: задача сверху, затем по строке на блок в порядке процесса — номер, название, статус и, для блока с привязанным списком, done/total: current item; картинка шириной 390 px, никогда не уменьшается и для длинного флоу растёт вниз. Под сообщением идут строки плана привязанного списка (см. planList у ноды), а затем тот, кого запуск ждёт после неё — ⏳ agent on the step: <block> или 🙋 waiting for you: <block>, когда нода ведёт прямо на останавливающий шаг (гейт lock ждёт человека, как и directive с пометкой humanGate, чьё when выполняется; ожидание любой другой directive, teleport, materialize или subgraph — агента); приложенная картинка показывает то же состояние. Устаревшая нода совместимости telegram-notification поддерживает то же вложение для provider-specific workflow.

PNG рисует и публикует доступный сопряжённый контроллер. Выберите его через device_id в execution({ action: "progress-image-token", executionId, device_id }); без этого поля нужен ровно один доступный подходящий контроллер. COMMUNICATION_OWNER_UNAVAILABLE возвращается как кодированная ошибка MCP и HTTP 503 при выдаче или публичном чтении. Восстановите сопряжённое соединение вместо пересоздания VM. Обычный прогресс и текстовые уведомления не требуют владельца; недоступная необязательная картинка пропускается с независимой попыткой доставки текста.

Одноразовый URL прогресса и неизменяемая публикация владельца имеют разные сроки. Успешное завершение HTTP расходует разрешение прогресса; ошибка рендера или потока освобождает резервирование, а завершение ответа с ошибкой не расходует его. Публикация допускает повторное чтение до собственного истечения при действующих правах.

Облачные уведомления передают владельцу описание графа и запуска; PNG рисует поставляемый рендерер владельца без зависимости от пакетов проекта.

Страница флоу (см. руководство «Чтение и правка флоу») показывает выведенный процесс самого определения и позволяет владельцу править его на месте. На странице запуска (см. руководство «Чтение запуска») та же проекция показана как карта — процесс как схема с оглавлением — с панелью блока, которая раскрывает шаги, время и список каждого блока и фокусирует технический граф нод, второй вид страницы. Страница и PNG содержат одинаковую существенную информацию. Воркфлоу без progress показывает вместо этого технический граф нод и панель переменных.

Название задачи запуска

Название задачи отделено от имени воркфлоу, текущего шага и произвольной заметки. Задайте его на первом шаге, который устанавливает фактическую задачу, до отправки результата этого шага. Прочитайте execution({ action: "execution_context", executionId }) и используйте ревизии ответа:

execution({
action: "update-task-title",
executionId,
taskTitle: "Импортировать октябрьские заказы",
expectedRevision: current.revision,
expectedTaskIdentityRevision: current.metadataRevisions.taskIdentity,
});

Здесь current — результат чтения контекста запуска. Владелец может именовать активный запуск (running, включая сохранённое состояние waiting); завершённые и остановленные запуски отклоняют изменения. Название очищается от пробелов по краям, остаётся непустым и ограничено 500 кодовыми единицами строки JavaScript. Управляющие и форматирующие символы Unicode запрещены до удаления пробелов. Должны совпасть ревизия шага и независимая ревизия названия; при конфликте перечитайте авторитетный контекст и согласуйте название с фактической задачей.

Сервер хранит taskIdentity: { title, changedAt, changeId } и сам задаёт время и токен изменения. Именование сохраняет текущую попытку шага, вопрос, переменные и ревизии остальных метаданных. То же нормализованное название не меняет ревизии, активность или события. Настоящее переименование учитывается как активность. Ответственный за разрешённое изменение самой задачи обновляет название; обычное продвижение, перестановка работы и техническая тактика его сохраняют. Название не даёт полномочий менять задачу.

Заголовки используют явное название, затем разрешённый авторский progress.title, затем имя собственного воркфлоу запуска. Заметки не задают заголовки и доступны отдельно. Доставленные сообщения сохраняют прежнее название; следующие уведомления разрешают актуальное перед доставкой.

execution (progress) и GET /api/executions/:id/progress возвращают source: "trace" для авторского прогресса. Без него возвращается source: "metadata" с названием, именем и версией воркфлоу, ревизией и статусом запуска, без выдуманных блоков, маршрута, переменных и статистики. У запуска без явного названия taskIdentity: null и тот же порядок подстановки. PNG требует авторского прогресса; разрешение привязано также к независимому названию. Переименование делает его устаревшим, даже если текст вернули при том же времени часов. Получите новое разрешение после устаревшего запроса или если в разрешении нет привязки к названию.

Определение воркфлоу

Каждый воркфлоу состоит из:

{
"id": "my-workflow",
"metadata": {
"name": "Мой воркфлоу",
"version": "1.0.0",
"description": "Описание того, что делает этот воркфлоу"
},
"variableRegistry": {
"project_name": { "type": "string", "description": "Название проекта" }
},
"nodes": [
// Массив определений узлов
]
}

Метаданные

ПолеОбязательноеОписание
nameДаЧеловекочитаемое имя воркфлоу
versionДаСтрока семантической версии
descriptionДаЧто выполняет воркфлоу
schemaVersionНетЦелочисленная версия схемы definition; текущее значение — 1

schemaVersion описывает форму самого definition — рядом с semver-полем version, которое описывает его содержание. Definition без этого поля считается версией 0 и обновляется автоматически везде, где он попадает в систему: при валидации, при загрузке через API, MCP или CLI, во встроенном каталоге и при чтении сохранённых definition, — поэтому мигрировать вручную не нужно. Команда moira-workflow <file> migrate перезаписывает файл на месте, если обновлённая форма нужна на диске.

Реестр переменных

variableRegistry объявляет глобальные переменные воркфлоу один раз — единый источник истины для типа и описания каждой переменной. Каждая запись имеет ключ-имя переменной:

ПолеОбязательноеОписание
typeДаstring, number, integer, boolean, object, array или null
descriptionДаЧто хранит переменная
defaultНетНачальное значение, заданное при старте воркфлоу

Глобальные переменные используются по короткому имени ({{project_name}}); узел записывает глобальную переменную, перечислив её имя в inputSchema.globalInputs.

Массив узлов

Узлы — это шаги вашего воркфлоу. Каждый узел имеет id и type, определяющий его поведение. id уникален в воркфлоу и записывается в kebab-case — строчные латинские буквы и цифры через дефис, например review-plan, — потому что ребро адресуется как <узел>.<ключ>, а выходы узла — как {{<узел>.<имя>}}.

Выполнение воркфлоу

При запуске воркфлоу:

  1. Движок создаёт экземпляр выполнения с уникальным processId
  2. Находит start узел (type: start)
  3. Возвращает первую директиву и выданный сервером идентификатор попытки шага
  4. Агент выполняет работу и отправляет результат с Process ID и идентификатором попытки шага
  5. Движок атомарно сохраняет переход, точный ответ для повторов и следующую попытку
  6. Повторяет до достижения end узла (type: end)

Повтор той же попытки с теми же данными возвращает сохранённый ответ с текущей общей языковой инструкцией без повторного перехода. Байты сохранённого оригинала и identity попытки не меняются. Каждое последующее приостановленное предъявление получает новый идентификатор попытки.

Контекст выполнения

Каждое выполнение поддерживает объект контекста:

{
variables: Record<string, unknown>; // Глобальные в variables[name]; локальные выводы узла в variables[nodeId]
nodeStates: Record<string, unknown>; // Состояние по узлам
executionId: string; // Уникальный ID выполнения
workflowId: string; // ID исходного воркфлоу
currentNodeId: string; // Текущая позиция
}

Глобальные переменные (объявленные в variableRegistry) хранятся в variables[name] и разрешаются по короткому имени ({{name}}). Выводы узла хранятся в variables[nodeId] и разрешаются как {{node-id.name}}.

Переменные сохраняются между шагами. Глобальные переменные несут значения уровня воркфлоу, выводы узлов — результаты конкретных шагов.

Типы узлов

Ниже показаны распространённые встроенные типы узлов. Таблица содержит примеры, а не полный перечень; встроенные типы и их актуальные контракты приведены в разделе Узлы. Установленные расширения могут добавлять типы с пространством имён; их актуальные название, источник, версия и схема конфигурации поступают из каталога типов узлов текущей установки.

ТипНазначение
startТочка входа для выполнения воркфлоу
endТерминальный узел, отмечающий завершение
agent-directiveЗадача агента с директивой и условием завершения
conditionВетвление в один из нескольких выходов по упорядоченным case
expressionВычисление значений с помощью арифметических выражений
subgraphДелегирование другому воркфлоу
user-notificationУведомление через настроенные каналы текущего пользователя
telegram-notificationУстаревшая Telegram-only нода совместимости

Соединения

Узлы связываются через объект connections, определяющий поток. Каждый тип узла имеет специфические типы соединений:

Agent Directive Node

{
"id": "analyze-task",
"type": "agent-directive",
"directive": "Проанализируй требования к задаче",
"completionCondition": "Анализ завершен",
"connections": {
"success": "next-step",
"error": "error-handler"
}
}

Condition Node

{
"id": "check-status",
"type": "condition",
"cases": [
{
"when": { "operator": "eq", "left": { "contextPath": "status" }, "right": "success" },
"output": "passed"
}
],
"connections": {
"passed": "success-path",
"default": "retry-path"
}
}

Полный пример воркфлоу

{
"id": "simple-workflow",
"metadata": {
"name": "Простой воркфлоу задачи",
"version": "1.0.0",
"description": "Базовый воркфлоу, демонстрирующий соединения узлов"
},
"nodes": [
{
"id": "start",
"type": "start",
"connections": { "default": "main-task" }
},
{
"id": "main-task",
"type": "agent-directive",
"directive": "Выполни назначенную задачу",
"completionCondition": "Задача успешно выполнена",
"connections": { "success": "end" }
},
{
"id": "end",
"type": "end"
}
]
}

Видимость воркфлоу

Воркфлоу имеют настройки видимости:

  • private — Доступ имеют владелец и пользователи с актуальным прямым или групповым grant в пределах разрешённых действий; операторский доступ определяется политикой установки.
  • public — Доступен авторизованным пользователям в рамках текущей политики admission и доступа. Видимость не даёт полномочий на эффекты, описанные workflow.

Лучшие практики

  1. Начинайте со start — Каждый воркфлоу должен иметь start узел
  2. Заканчивайте end — Используйте end узлы для отметки завершения
  3. Четкие директивы — Пишите недвусмысленные инструкции
  4. Измеримые условия — Условия завершения должны быть проверяемы
  5. Обработка ошибок — Используйте поддерживаемый error-выход узла для документированных отказов. Невалидный ответ агента останавливается для исправления; наличие error connection не превращает любую ошибку обработчика в ветку.
  6. Документация — Добавляйте описания к сложным узлам

Связанное

  • Узлы — Типы узлов и конфигурация
  • Шаблоны — Динамический контент в воркфлоу