Редактирование 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:
moira-workflow --versionКоманда выводит версию пакета и точный путь к исходнику. Длинное описание и полную схему переменной можно прочитать из файла, не полагаясь на хрупкое экранирование shell:
moira-workflow ./workflow.json set-description --file ./description.txtmoira-workflow ./workflow.json set-system-reminder --file ./reminder.txtmoira-workflow ./workflow.json set-tags research,verificationmoira-workflow ./workflow.json set-variable-schema result --file ./result-schema.jsonset-tags заменяет весь список тегов. У workflow, созданного Workflow Management Flow, ровно один
тег уровня — complexity:simple, complexity:standard или complexity:complex; сохраняйте его в
передаваемом списке, иначе следующая правка сочтёт историю workflow неизвестной.
Маршрутизация правится той же командой update. --cases заменяет упорядоченные case узла
condition или agent-directive, --expressions — выражения, которые он вычисляет перед ними (пустой массив [] убирает их), а
соединения правятся по ключу:
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 <источник.ключ>:
moira-workflow ./workflow.json rename review independent-reviewmoira-workflow ./workflow.json delete legacy-check --retarget review.success=deliverЧтобы привести файл к текущей схеме definition, выполните migrate. Если миграция нужна, команда
создаёт резервную копию существующего файла перед перезаписью. Иначе она сообщает
«Already at schema version 1; nothing to migrate», не перезаписывая файл:
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
удаляют соответствующие опциональные поля.
moira-workflow ./workflow.json set-progress --file ./progress.jsonmoira-workflow ./workflow.json update implement --progress-node-id implementationmoira-workflow ./workflow.json update implement --progress-active-label "Implement {{unit}}/{{total}}"moira-workflow ./workflow.json update notify --progress-node-id review --attach-progress-image truemoira-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 отклоняются при записи.
moira-workflow ./workflow.json set-block present-plan planmoira-workflow ./workflow.json add-block deliver "Deliver" "Hand the result over" --after executemoira-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.
moira-workflow ./workspace/workflow.json sync ./workflows/production/flows/<flow>.jsonmoira-workflow ./workflows/production/flows/<flow>.json validateПеред проверкой или изменением большого графа выведите его полную детерминированную схему потока:
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 делает это вместе с вами: она отказывается, пока каждое входящее ребро не
перенаправлено или не удалено.
Безопасный процесс редактирования
-
Загрузите полную исходную версию
mcp__moira__workflow({action: "get",workflowId: "my-workflow",includeNodes: true,includeValidation: true,});Сохраните возвращённую revision и прочитайте определения всех нод, связи, объявления переменных, runtime policy и привязки прогресса до выбора затронутых зависимостей. Здесь не задавайте пагинацию нод; если намеренно читаете постранично, соберите все страницы.
get-structureдаёт сводку, а не базу для правки. Изучите связанные подграфы и playbook, если изменение от них зависит, в пределах разрешённого объёма работы. -
Найдите узлы для редактирования
mcp__moira__workflow({action: "search-nodes",workflowId: "my-workflow",query: "search term",}); -
Получите детали узла
mcp__moira__workflow({action: "get-node",workflowId: "my-workflow",nodeId: "node-id",}); -
Примените изменения
Передайте возвращённую revision исходной версии как
expectedRevision. При конфликте загрузите текущее определение и согласуйте с ним намеренную правку, не затирая более новый граф вслепую.mcp__moira__workflow({action: "edit",workflowId: "my-workflow",expectedRevision: baselineRevision,changes: {/* ... */},}); -
Проверьте сохранённое определение
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 и локальный путь, — и сравните определения, а не
считайте их совпадающими.
# Получить отдаваемое определение по одноразовому 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-реестр без этого типа сообщает об ошибке.
Смотрите также
- Создание Workflows - Создание новых workflows
- MCP Tools - Справочник инструментов