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

Редактирование Workflows

Способы редактирования

Через MCP Tools

Используйте инструмент workflow с действием edit:

mcp__moira__workflow({
action: "edit",
workflowId: "my-workflow",
changes: {
// изменения здесь
},
});

Через workflow-management-flow

Запустите управляющий workflow:

mcp__moira__execution({
action: "prepare",
workflowId: "moira/workflow-management-flow",
parentExecutionId: "none",
});
mcp__moira__execution({ action: "execute", startAttemptId: "<ID попытки запуска из prepare>" });

Выберите “edit” при запросе действия.

Используйте workflow-management-flow для сложных правок. Он проверяет дизайн до изменения, валидирует получившийся граф и независимо проверяет готовый workflow.

Через CLI для workflows

Авторы репозитория могут использовать официальный CLI moira-workflow для файловых правок. Сначала проверьте, из какой рабочей копии запускается глобально связанная команда, особенно если локально существует несколько worktree Moira:

Terminal window
moira-workflow --version

Команда выводит версию пакета и точный путь к исходнику. Длинное описание и полную схему переменной можно прочитать из файла, не полагаясь на хрупкое экранирование shell:

Terminal window
moira-workflow ./workflow.json set-description --file ./description.txt
moira-workflow ./workflow.json set-system-reminder --file ./reminder.txt
moira-workflow ./workflow.json set-tags research,verification
moira-workflow ./workflow.json set-variable-schema result --file ./result-schema.json

set-tags заменяет весь список тегов. У workflow, созданного Workflow Management Flow, ровно один тег уровня — complexity:simple, complexity:standard или complexity:complex; сохраняйте его в передаваемом списке, иначе следующая правка сочтёт историю workflow неизвестной.

Маршрутизация правится той же командой update. --cases заменяет упорядоченные case узла condition или agent-directive, --expressions — выражения, которые он вычисляет перед ними (пустой массив [] убирает их), а соединения правятся по ключу:

Terminal window
moira-workflow ./workflow.json update review \
--cases '[{"when":{"operator":"eq","left":{"contextPath":"review.verdict"},"right":"blocked"},"output":"blocked"}]'
moira-workflow ./workflow.json update review --expressions '["attempts = attempts + 1"]'
moira-workflow ./workflow.json update review --add-connection blocked fix-issues

Все три команды адресуют одну ноду-директиву, которая произвела вердикт: её case, её счётчик и соединение, которое называет case. Здесь verdict — поле объявленной схемы ответа ноды review, а attempts заранее объявлена в variableRegistry как числовая глобальная переменная с начальным значением. Локальные ответы читаются как node-id.field; простые имена в шаблонах и условиях требуют объявленных глобальных переменных.

Команды только для чтения показывают результат: schema печатает по строке CASE <output> WHEN <условие> на каждый case и по строке EDGE на каждое соединение, structure --detailed выводит каждый case как Case: <output> when …, а diff называет cases среди изменённых полей узла, — поэтому изменение маршрутизации можно проверить, не читая сырой JSON.

Структура меняется командами rename и delete. rename даёт узлу новый id в kebab-case и переписывает все ссылки на него — цели соединений, шаблоны {{узел.имя}}, пути в case и в условии humanGate, выражения, привязки списков, маппинги подграфа и разрешения на запись — и печатает каждое изменённое место. Текст, где id упомянут вне ссылки, остаётся как есть. delete отказывается, пока в удаляемый узел ещё ведёт ребро из другого узла, и называет каждое такое ребро; решите каждое через --retarget <источник.ключ>=<цель> или, для выхода, который не является основным выходом узла-источника, через --drop <источник.ключ>:

Terminal window
moira-workflow ./workflow.json rename review independent-review
moira-workflow ./workflow.json delete legacy-check --retarget review.success=deliver

Чтобы привести файл к текущей схеме definition, выполните migrate. Если миграция нужна, команда создаёт резервную копию существующего файла перед перезаписью. Иначе она сообщает «Already at schema version 1; nothing to migrate», не перезаписывая файл:

Terminal window
moira-workflow ./workflow.json migrate

Команды изменения существующего workflow сохраняют уникальную копию до записи в workflow-backups/ текущего каталога вызывающей стороны. Это не резервирование каждого вывода: create и copy создают новые файлы workflow, а export-node пишет выбранный выходной файл без автоматического резервирования этого файла.

Вид процесса использует тот же файловый authoring surface. Задайте полный список блоков из JSON командой set-progress (или наращивайте его через add-block / edit-block), затем назначьте каждой ноде её блок командой set-block — включая маршрутизирующие ноды: вывод процесса отклоняет ноду без блока. Вложение прогресса доступно для user-notification и устаревшей telegram-notification; значения none и false удаляют соответствующие опциональные поля.

Terminal window
moira-workflow ./workflow.json set-progress --file ./progress.json
moira-workflow ./workflow.json update implement --progress-node-id implementation
moira-workflow ./workflow.json update implement --progress-active-label "Implement {{unit}}/{{total}}"
moira-workflow ./workflow.json update notify --progress-node-id review --attach-progress-image true
moira-workflow ./workflow.json update approve --human-gate '{"label":"Approve the plan","notify":"off","remindAfter":"1d"}'

--human-gate помечает agent-directive как шаг, который ждёт решения человека (см. humanGate в справочнике нод), а --human-gate none снимает пометку; schema, structure и diff её показывают.

У контракта блоков есть собственные команды: привязать ноду к блоку, добавить или изменить блок с его описанием, привязать блок к списку, который проходят его шаги, подписать связь, выходящую из блока, и объяснить возврат причиной цикла и условием его завершения. Каждая запись сообщает, сколько диагностик контракта блоков осталось, поэтому flow размечается итеративно, пока derive не покажет ни одной; --no-version-bump сохраняет версию во время итераций. Флаг --list, который принимают add-block и edit-block, задаёт привязку как JSON (items, title, current, done, total, indexBase), а --list none её удаляет; неизвестное поле, пустой путь, indexBase не 0 и не 1, а также привязка без items, current и total отклоняются при записи.

Terminal window
moira-workflow ./workflow.json set-block present-plan plan
moira-workflow ./workflow.json add-block deliver "Deliver" "Hand the result over" --after execute
moira-workflow ./workflow.json edit-block deliver --summary "Present the result"
moira-workflow ./workflow.json edit-block work \
--list '{"items":"tasks","title":"action","current":"current_task","total":"total_tasks"}'
moira-workflow ./workflow.json set-label present-plan approved "plan approved"
moira-workflow ./workflow.json set-label review success "review found defects" \
--cause "The independent review reported blocking findings." --exit "The review passes."
moira-workflow ./workflow.json derive

Команды сохраняют schema fields, но не выводят процесс и не судят о его смысле; они не заменяют итоговые validate, derive, schema, поведенческие scenarios и независимое semantic review.

Для полной спланированной замены sync сохраняет идентичность целевого workflow и его catalog migration aliases в previousSlugs. Catalog reader проверяет aliases отдельно, а в engine validator передаётся только executable graph. Aliases всегда берутся из реальной цели, а не из workspace-копии. При ошибке metadata или graph validation целевой файл не меняется. Отдельная команда validate завершается с ненулевым кодом для обоих классов ошибок, поэтому агент или CI может использовать её как настоящий гейт без ослабления runtime/upload graph validation.

Terminal window
moira-workflow ./workspace/workflow.json sync ./workflows/production/flows/<flow>.json
moira-workflow ./workflows/production/flows/<flow>.json validate

Перед проверкой или изменением большого графа выведите его полную детерминированную схему потока:

Terminal window
moira-workflow ./workflows/production/flows/<flow>.json schema

Схема показывает каждую реальную ноду и именованный переход, условия, циклы, объявленные выходы и маппинги, ссылки на контекст, обычные пути от start, отдельные области, доступные только через teleport, и несвязанные компоненты. Если workflow определяет вид процесса, та же проекция включает все упорядоченные блоки, сохранённые на них устаревшие отрисовочные связи и принадлежность каждой ноды блоку. Это структурная проекция только для чтения и анализа агентом или человеком: команда не запускает workflow, не интерпретирует его предметный смысл и не утверждает семантическую корректность видимого маршрута.

Как workflow-management-flow выполняет правку

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

При начальном выборе также фиксируется, разрешён ли доступ к серверу. Явное указание local-only или offline используется без повторного вопроса и запрещает edit-ветке скачивать либо сравнивать серверное определение.

На том же первом шаге фиксируется режим работы. В режиме interactive все согласования остаются как сейчас: дизайн, план и результат подтверждает пользователь. В режиме autonomous workflow обходит эти три согласования и вместо них выдаёт один финальный отчёт в конце. Агент использует режим, который пользователь уже назвал, выводит однозначный сам — в том числе когда запуск является дочерним для уже автономного процесса, — и спрашивает один раз только тогда, когда режим не назван и не выводится.

Автономность убирает ожидание человека, но не полномочия. Загрузка по-прежнему требует явного решения, и в автономном режиме загрузка без предварительной авторизации разрешается в «нет», а не эскалируется до нестандартного метода. Запись отредактированного определения в уже определённую локальную цель — это и есть заказанная работа запуска, поэтому отдельного согласования она не требует ни в одном режиме.

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

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

Создание и редактирование используют одно независимое ревью дизайна до изменения workflow. Подробные findings остаются в стабильном файле workspace, а через граф передаётся только один из исходов: pass, repair или replan. repair допустим только для подтверждённого дефекта самого проверяемого артефакта; ошибочный критерий, модель доказательства, интерпретация требования, план или процесс возвращаются к владельцу самого раннего ошибочного контракта. После реального исправления reviewer получает ограниченное описание класса причины и изменившегося знания. Повтор того же класса без более сильного свидетельства и циклы, меняющие только validation-инфраструктуру, ведут к перепланированию, а не к следующему слою проверки. Структурную валидацию штатным валидатором Moira по-прежнему выполняет нода, создающая или изменяющая workflow.

Типы изменений

Обновление метаданных

mcp__moira__workflow({
action: "edit",
workflowId: "my-workflow",
changes: {
metadata: {
version: "2.0.0",
description: "Updated description",
},
},
});

Обновление содержимого узла

mcp__moira__workflow({
action: "edit",
workflowId: "my-workflow",
changes: {
updateNodes: [
{
nodeId: "task-node",
changes: {
directive: "New directive text",
completionCondition: "New condition",
},
},
],
},
});

Добавление узлов

mcp__moira__workflow({
action: "edit",
workflowId: "my-workflow",
changes: {
addNodes: [
{
type: "agent-directive",
id: "new-node",
directive: "New task",
completionCondition: "Task complete",
connections: { success: "existing-node" },
},
],
},
});

Удаление узлов

mcp__moira__workflow({
action: "edit",
workflowId: "my-workflow",
changes: {
removeNodes: ["node-to-remove"],
},
});

При удалении узлов обновите соединения в других узлах, которые ссылались на удалённый узел. Команда CLI delete делает это вместе с вами: она отказывается, пока каждое входящее ребро не перенаправлено или не удалено.

Безопасный процесс редактирования

  1. Загрузите полную исходную версию

    mcp__moira__workflow({
    action: "get",
    workflowId: "my-workflow",
    includeNodes: true,
    includeValidation: true,
    });

    Сохраните возвращённую revision и прочитайте определения всех нод, связи, объявления переменных, runtime policy и привязки прогресса до выбора затронутых зависимостей. Здесь не задавайте пагинацию нод; если намеренно читаете постранично, соберите все страницы. get-structure даёт сводку, а не базу для правки. Изучите связанные подграфы и playbook, если изменение от них зависит, в пределах разрешённого объёма работы.

  2. Найдите узлы для редактирования

    mcp__moira__workflow({
    action: "search-nodes",
    workflowId: "my-workflow",
    query: "search term",
    });
  3. Получите детали узла

    mcp__moira__workflow({
    action: "get-node",
    workflowId: "my-workflow",
    nodeId: "node-id",
    });
  4. Примените изменения

    Передайте возвращённую revision исходной версии как expectedRevision. При конфликте загрузите текущее определение и согласуйте с ним намеренную правку, не затирая более новый граф вслепую.

    mcp__moira__workflow({
    action: "edit",
    workflowId: "my-workflow",
    expectedRevision: baselineRevision,
    changes: {/* ... */},
    });
  5. Проверьте сохранённое определение

    mcp__moira__workflow({
    action: "get",
    workflowId: "my-workflow",
    includeNodes: true,
    includeValidation: true,
    });

    Прочитайте возвращённую validation вместе с полным сохранённым определением. Для проверки авторского определения до сохранения вызовите workflow({ action: "validate", workflow: completeWorkflow }). Здесь completeWorkflow — полный авторский JSON workflow, а не ID, сводка структуры или оболочка ответа get. Сохраните весь граф и поля расширений.

Редактирование без лишней машинерии

Вносите изменение официальными MCP-действиями или CLI workflow и валидируйте реальный артефакт до завершения. Одноразовый генератор, скрипт миграции или промежуточный формат, написанный ради одной правки, становится необъявленной зависимостью: workflow корректно проходит цикл правки только там, где этот инструмент есть, и в определении об этом ничего не сказано. Артефакт записи — сам JSON workflow.

Сверка копий в репозитории и на сервере

Встроенный workflow существует дважды: как файл в репозитории и как запись каталога на инстансе, который его отдаёт. Перед правкой определите, какие идентичности указывают на один и тот же workflow — публичный owner/slug, внутренний UUID и локальный путь, — и сравните определения, а не считайте их совпадающими.

Terminal window
# Получить отдаваемое определение по одноразовому download-токену
mcp__moira__workflow({ action: "download", workflowId: "moira/quick-task" })

Если они различаются, выберите базу осознанно: какое определение затрагивает запрошенное изменение, какое новее по metadata.version и что потеряет каждая сторона. Механическое объединение двух JSON даёт граф, который никто не проверял.

Смена slug встроенного workflow меняет его идентичность в каталоге. Чтобы при обновлении старый workflow не остался активным рядом с новым, добавьте прежний slug в служебный массив каталога previousSlugs. Загрузчик перенесёт существующую запись в рамках того же владельца и сохранит её внутренний ID; если найдётся больше одной объявленной прежней идентичности, загрузка завершится ошибкой вместо догадки или создания дубля. Не используйте previousSlugs для объединения разных workflow.

Обновление соединений

Обновление одного соединения

{
updateNodes: [
{
nodeId: "source-node",
changes: {
connections: {
success: "new-target-node",
},
},
},
];
}

Маршрутизация

Обе маршрутизирующие ноды — condition и agent-directive — решают через упорядоченные cases, и обе принимают expressions, которые выполняются перед ними. Исходы ноды — это её cases и ключи connections, которые они называют, поэтому меняйте их вместе, чтобы каждый case по-прежнему называл существующий ключ:

{
updateNodes: [
{
nodeId: "condition-node",
changes: {
cases: [
{
when: { operator: "eq", left: { contextPath: "inspection.status" }, right: "success" },
output: "passed",
},
],
connections: {
passed: "success-node",
default: "retry-node",
},
},
},
];
}

Здесь inspection.status — поле результата существующей ноды inspection. У ноды agent-directive те же три поля правятся так же. Её выход по умолчанию — success, а не default, её case читают контекст, в который уже влит её собственный валидированный ответ, а error/timeout остаются зарезервированными под управление потоком: их не может назвать ни один case:

{
updateNodes: [
{
nodeId: "review",
changes: {
expressions: ["review_round = review_round + 1"],
cases: [
{
when: { operator: "eq", left: { contextPath: "review.verdict" }, right: "blocked" },
output: "blocked",
},
],
connections: {
success: "merge",
blocked: "fix-issues",
},
},
},
];
}

Нода review должна объявлять verdict в схеме ответа, а review_round до увеличения выражением должна быть объявленной числовой глобальной переменной с начальным значением.

Решай на той ноде, у которой есть свидетельство. Когда направление прогона определяет собственный ответ шага, перенесите case на этот шаг, а оставшийся исход отдайте success; одиночный счётчик или производная сумма становятся записью в expressions уже работающей там ноды. Каждая лишняя нода — это переход, который читателю приходится проследить, и ещё одно место, где решение расходится со свидетельством. Оставьте отдельную ноду condition или expression, когда так читается лучше: решение общее для нескольких производителей, оно читает состояние, которого не произвела ни одна отдельная нода, именованная точка решения помогает читателю вида процесса или вычисление заслуживает собственного места в маршруте. Нода, единственная работа которой — маршрутизировать или считать то, что предыдущая нода уже знает, — это избыточная маршрутизирующая обвязка; сложить её означает удалить ноду и перенести её cases и connections на предшественника.

Те же поля правятся на файле командами update --cases и update --expressions, описанными выше в разделе «Через CLI для workflows».

Контроль версий

Версии определения и история сохранений

Три значения обозначают разные вещи:

  • metadata.version — семантическая версия автора, например 1.1.0.
  • revision из workflow (get) — текущий токен записи. Передавайте его как expectedRevision при защищённой правке или откате; это не номер исторического снимка.
  • revision в workflow (history) — номер неизменяемого снимка полного сохранённого определения. Разные сохранения оставляют отдельные снимки, даже если их семантические версии совпадают.

История сжимает полные определения и повторно использует одинаковое содержимое в рамках одного workflow. У каждого сохранения остаются собственные номер истории, автор и время; совместное хранение содержимого не удаляет редакции. Для чтения или восстановления снимка не требуется воспроизводить предыдущие изменения, а JSON возвращается в читаемом формате.

Для чтения, сравнения и восстановления истории нужно право редактирования: владение workflow или явное разрешение edit, выданное напрямую либо через группу. Публичность или разрешение use сами по себе не открывают прежние приватные определения. История учитывает записи определения, включая синхронизацию каталога и обновление сохранённой схемы. Если записанной истории нет, фактическое текущее содержимое становится исходным снимком перед следующей записью содержимого; более ранние незаписанные сохранения восстановить нельзя. Резервные копии файлов CLI существуют отдельно от серверной истории.

Получите список снимков, затем прочитайте выбранный снимок или сравните два возвращённых номера:

mcp__moira__workflow({ action: "history", workflowId: "my-workflow" });
mcp__moira__workflow({ action: "get-revision", workflowId: "my-workflow", revision: 1 });
mcp__moira__workflow({
action: "compare-revisions",
workflowId: "my-workflow",
fromRevision: 1,
toRevision: 2,
});

Замените 1 и 2 номерами снимков из истории. Отсутствующий снимок означает ошибку, а не пустое сравнение. Снимок содержит весь граф, включая реестр переменных, runtime policy и представление процесса, а не только поля, доступные в браузерном редакторе.

Перед восстановлением прочитайте текущее определение через workflow (get) и сохраните его токен записи. После изучения выбранного содержимого передайте этот токен в rollback:

mcp__moira__workflow({
action: "rollback",
workflowId: "my-workflow",
revision: 1,
expectedRevision: currentWriteRevision,
});

Здесь currentWriteRevision — revision из текущего чтения, а 1 — выбранный номер истории. Откат валидирует и мигрирует определение, сохраняет ID, владельца и текущие права доступа существующего workflow и добавляет новый снимок. Результат возвращает новую revision записи, новую historyRevision и restoredFrom. Устаревший токен даёт WORKFLOW_REVISION_CONFLICT, не меняя граф и историю: перечитайте определение и заново оцените намеренное восстановление перед повтором. Мягкое удаление сохраняет историю, окончательное удаление убирает её. Откат содержимого отличается от административного восстановления удалённого workflow.

Восстановление меняет сохранённое определение, а не состояние уже идущего запуска. Запуски читают текущее определение; совместимый приостановленный шаг может продолжиться обычным способом, а изменившаяся семантика шага требует проверки через execution (diagnose) и разрешённого решения execution (recover). Не повторяйте старую попытку, не пропускайте незавершённую работу и не повторяйте эффект с неизвестным исходом. См. диагностику и восстановление устаревшего предъявления. Просмотр и защищённое восстановление в браузере описаны на странице флоу.

Инкремент версии

Используйте семантическую версию, чтобы обозначить смысл авторского изменения:

{
metadata: {
version: "1.1.0"; // было 1.0.0
}
}

Семантика версий:

  • Major (2.0.0): Ломающие изменения, перестроенный поток
  • Minor (1.1.0): Новые функции, новые узлы
  • Patch (1.0.1): Исправления ошибок, правки текста

Сравнение версий

Чтобы сравнить определения двух разных workflow, а не снимки одного workflow, используйте diff:

mcp__moira__workflow({
action: "diff",
workflowId: "my-workflow",
compareWorkflowId: "my-workflow-old",
});

Типичные правки

Исправление опечатки в директиве

{
updateNodes: [
{
nodeId: "task-node",
changes: {
directive: "Corrected directive text",
},
},
];
}

Добавление обязательного поля в InputSchema

{
updateNodes: [
{
nodeId: "input-node",
changes: {
inputSchema: {
type: "object",
properties: {
existing_field: { type: "string" },
new_field: { type: "string" }, // добавлено
},
required: ["existing_field", "new_field"], // обновлено
},
},
},
];
}

Вставка узла в поток

{
addNodes: [
{
type: "agent-directive",
id: "inserted-node",
directive: "New step",
completionCondition: "The new step's stated result is verified",
connections: { success: "original-target" }
}
],
updateNodes: [
{
nodeId: "original-source",
changes: {
connections: { success: "inserted-node" }
}
}
]
}

Ошибки валидации

Отсутствует цель соединения

Error: Node 'task-1' connection target 'missing-node' not found

Решение: обновите соединение на валидный ID узла.

Изолированный узел

Warning: Node 'orphan-node' is not reachable from start

Решение: добавьте соединение от другого узла или удалите изолированный узел.

Неверный тип узла

Error: Unknown node type 'custom-type'

Решение: выберите встроенный тип из справочника узлов. Для типа расширения с пространством имён убедитесь, что расширение установлено. Валидатор без достоверных live-данных реестра сообщает, что тип не удалось разрешить; live-реестр без этого типа сообщает об ошибке.

Смотрите также