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