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

Представление процесса

Каждый воркфлоу, объявляющий progress, Moira показывает как представление процесса: короткую цепочку блоков, которую новичок прочитает, не зная лежащего под ней графа. То же представление показывает запуск этого воркфлоу: какие блоки завершены, какой активен, какие повторялись или были пропущены, и какой маршрут запуск прошёл на самом деле. Этот раздел объясняет словарь и то, как строится каждая картина.

Словарь

  • Блок. Один этап процесса, как назвал бы его человек: «Набросать план», «Независимое ревью плана», «Выполнить шаги плана». Массив progress.nodes перечисляет блоки в порядке процесса; у каждого есть подпись и описание в одно предложение (content.summary).
  • Привязка к списку. Блок, который проходит список, может объявить list: пути переменных для массива элементов (items), заголовка внутри одного элемента (title), индекса текущего элемента (current, отсчитываемого от indexBase, по умолчанию 1), числа завершённых элементов (done) и общего числа (total). Нужен хотя бы один из items, current и total; total по умолчанию равен длине items, а done — current − indexBase. Тогда запуск сообщает, как далеко он продвинулся по этому списку и на каком элементе прошёл каждый проход.
  • Шаг. Одна нода графа воркфлоу: директива, которую выполняет агент, условие или выражение, которое маршрутизирует, старт или завершение. Каждый шаг принадлежит ровно одному блоку через progressNodeId, включая ноды маршрутизации, поэтому ничто из происходящего в запуске не выпадает из картины.
  • Свидетельство. То, что шаг обязан вернуть, чтобы завершиться, — его input schema. Текст результата блока (content.outcome) — шаблон над переменными, которые записывают его шаги, поэтому запуск показывает, к чему блок пришёл, а не только что он выполнялся.
  • Переход. Связь, которая уходит из блока в другой блок. У каждой есть короткая подпись из connectionLabels на ноде, например «план одобрен» или «ревью нашло дефекты». Обе схемы называют переход на порту с каждой стороны линии — порт источника говорит, куда переход ведёт, порт цели — откуда он пришёл, — поэтому связь объясняет себя, и линию не нужно прослеживать.
  • Цикл. Переход назад к более раннему блоку или к тому же блоку. Его подпись также называет причину повторения и то, что его завершает (cycle.cause, cycle.exit); схемы рисуют его как возврат и называют причину и выход на его портах.
  • Хаб. Блок, в который ведут несколько других блоков (перепланирование или остановка). Он размещается после блоков, которые в него ведут, чтобы процесс читался слева направо, а карта собирает связи от его источников в один канал, и каждая по-прежнему названа на порту, из которого она выходит, и на порту, в который входит.
  • Запуск. Одно выполнение воркфлоу. Движок записывает его маршрут: каждый выполненный шаг, связь, через которую он вышел, изменённые переменные и места ожидания.

Страница флоу: процесс без запуска

Процесс выводится только из определения воркфлоу: блоки из progress.nodes, принадлежность из progressNodeId, переходы и циклы из подписанных связей. Ничто в нём не рисуется отдельно, поэтому картина не может разойтись с графом. Валидация отвергает воркфлоу, чей процесс был бы нечитаемым: шаг без блока (unowned-node), блок без описания (empty-description) или без шагов (empty-block), граничная связь без подписи (unlabeled-edge), возврат без причины и выхода (unexplained-cycle), шаблон результата на блоке, которому не принадлежит ни одна нода, записывающая его переменную (outcome-unowned), или на двух блоках (outcome-duplicate), блок без перехода в другой блок или из него (unconnected-block; блок, владеющий стартовой нодой, не проверяется, а возврат в себя ничего не связывает). moira-workflow <file> derive печатает выведенный процесс с любыми из этих диагностик, а set-block, add-block, edit-block, set-label и clear-label редактируют его по одному изменению за раз.

Веб-интерфейс показывает этот вывод на странице флоу (/workflows/<id>, см. руководство «Чтение и правка флоу») двумя схемами одного и того же процесса: картой, где каждый блок — одна карточка, и техническим графом нод, где каждый блок — группа своих шагов. Рядом с обеими стоит оглавление блоков, которое переводит камеру к выбранному блоку, а панель рядом показывает выбранный блок и, из него, любой отдельный шаг с его директивой, условием завершения, ожидаемыми свидетельствами, маршрутизацией и валидацией. У обеих схем одни и те же раскладки, и обе следуют выбранной вами, а клик по порту или линии переносит к другому концу этого перехода. Владелец может править определение прямо там — блоки, подписи переходов и циклы, принадлежность и текст шагов, реестр переменных — с диагностикой выше, показываемой по мере ввода, и сохранением, которое отклоняется для невалидного определения или устаревшей ревизии.

Страница запуска: процесс с маршрутом

Запуск проецируется на процесс из записанного маршрута и никогда не угадывается по порядку блоков:

  • active — блок последнего шага, которого запуск достиг; waiting — когда этот шаг приостановлен в ожидании ввода человека или агента;
  • done — посещённый блок, чьи рабочие шаги выполнились один раз; repeated ×n — то же после n проходов через его рабочие шаги (ревью, прошедшее дважды, показывает ×2);
  • skipped — блок, который запуск обошёл или в который вошёл, не выполняя его работы (выполнились только ноды маршрутизации);
  • pending — ещё не достигнут.

Каждый блок также несёт своё время и, если он привязан к списку, сам список. Каждый визит записывает, когда в него вошли и когда его покинули — для ожидающего шага от момента, когда его директива была показана, до момента, когда ответ продвинул запуск, — поэтому блок сообщает каждый проход с его длительностью, сумму по всем проходам и то, сколько уже длится текущий проход. У визита, записанного до появления отметок времени, длительности нет: она читается как неизвестная, а не как ноль. Список сообщает элементы с их заголовками, какие из них завершены, какой выполняется сейчас и сколько времени проходы блока провели на каждом. Рядом представление запуска несёт статистику той версии, на которой запуск начался: сколько обычно занимают проход, всё время запуска в блоке и каждая позиция списка по остальным завершённым запускам владельца этой версии (медиана с квартилями и размахом), чтобы текущий запуск можно было читать в сравнении с обычным; запуски одного пользователя никогда не становятся статистикой другого. Запуски без отметки версии считаются отдельно и в выборку не попадают.

Непосещённый блок никогда не показывается завершённым. Сам маршрут доступен как упорядоченный список с отметками циклов, у каждой переменной есть история значений, а значение, заданное извне флоу (корректировка во время запуска), показано как таковое вместе с тем, кто его задал. Курсор маршрута показывает запуск на момент любого более раннего визита, а владелец выполнения может ответить ожидающему шагу прямо со страницы; ответ проверяется как ответ агента и записывается как корректировка (см. руководство «Чтение запуска»). Запуск, записанный до появления маршрутов, показывает только свой текущий блок и сообщает, что маршрут не записан.

Картинка прогресса запуска (execution (progress-image-token)) — это та же карта, растрированная: те же карточки, порты, связи, статусы, факты и обычные длительности из той же проекции (см. концепцию Воркфлоу). К уведомлению прикладывается другая картинка, сделанная для телефона, — шаги запуска, по строке на блок, из той же проекции.

Название задачи — независимые метаданные запуска, отдельные от имени собственного флоу и произвольной заметки. Чтение прогресса возвращает source: "trace" для объявленного прогресса; без него source: "metadata" показывает название и состояние запуска, не придумывая процесс или маршрут. Именование не создаёт блоки для флоу только с техническим графом.

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

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

Как сделать воркфлоу читаемым

Называйте блоки так, как человек назвал бы этап, держите описания в одно предложение, подписывайте каждую граничную связь решением, которое она выражает, и объясняйте каждый возврат причиной и выходом. Предпочитайте от трёх до пятнадцати блоков; ноды маршрутизации кладите в блок, чьё решение они маршрутизируют. Workflow Management Flow требует всего этого при создании и редактировании воркфлоу, а execution({ action: "progress" }) или GET /api/executions/:id/progress возвращают представление запуска.