Система валидации
Система валидации
Moira выполняет всестороннюю валидацию на нескольких уровнях для обеспечения целостности workflow и корректности ответов агентов.
Уровни валидации
1. Валидация JSON Schema
Workflow валидируются против определения JSON Schema:
- Валидация структуры против схемы workflow
- Проверка обязательных полей (id, metadata, nodes)
- id узлов записываются в kebab-case (
^[a-z0-9][a-z0-9-]*$); id с точкой, заглавной буквой или подчёркиванием — ошибка схемы на этом узле - Валидация типов для всех свойств
- Ветви схемы встроенных типов и форма типа расширения с пространством имён
2. Структурная валидация
Структура графа анализируется на корректность:
- Связность нод - Все connections указывают на валидные ноды
- Обязательные ноды - Нода start должна существовать
- Циклические зависимости - Циклы обнаруживаются и помечаются
- Недостижимые ноды - Ноды, к которым не ведёт ни одна точка входа. Точки входа — нода start и каждый
teleport: у телепорта нет обычных входящих связей, поэтому всё, куда он ведёт, достижимо черезexecution({ action: "step", teleportTo })и в предупреждение не попадает - Записи реестра - Каждая запись
variableRegistryдолжна быть валидной JSON Schema (некорректныйitems/pattern/и т.п. — blocking-ошибка) с непустым описанием - Объявления materialize - У каждой записи ровно один источник (
fromили пустойcontent), источники реестра имеют строковый default, объявленные пути безопасны и уникальны, а все цели соединений существуют - Блоки процесса - Если
progressприсутствует, каждая нода объявляетprogressNodeIdсуществующего блока, у каждого блока естьcontent.summary, каждая связь, выходящая из блока или возвращающаяся назад, несёт записьconnectionLabels(у возвратов — сcycle.causeиcycle.exit), а каждый шаблон{{progress_*_outcome}}стоит на одном блоке, владеющем записывающей нодой; каждое нарушение — ошибка со стабильным кодом (unowned-node,unknown-block,empty-block,empty-description,unlabeled-edge,unexplained-cycle,outcome-duplicate,outcome-unowned,unconnected-block) - Привязки блока к списку - Привязка
listблока называет хотя бы один изitems,currentиtotalи только поляitems,title,current,done,totalиindexBase(0или1). Каждый изitems,current,doneиtotal— путь переменной, корень которого является объявленной глобальной переменной или id ноды; неизвестный корень — ошибка, называющая блок, поле и путь.title— путь внутри одного элемента, поэтому безitemsон тоже ошибка - Case маршрутизации - Каждый case узла
conditionилиagent-directiveпроверяется так, как описано ниже в разделе Диагностика маршрутизации - Пометка ожидания человека -
humanGateуagent-directive— закрытый объект:labelдлиной 1–120 символов,notify—autoилиoff,remindAfter— положительное число иm,hилиd; неизвестное поле — ошибка. Егоwhenпроходит ту же проверку структуры и объявленных переменных, что иwhenу case маршрутизации - Типы узлов расширений - Для типов из live-реестра расширений или опубликованного snapshot проверяется объявленная ими схема конфигурации. Если live-реестр не содержит тип, это ошибка; если типа нет в snapshot или доступных данных реестра нет, валидатор выдаёт предупреждение о невозможности разрешить тип
3. Валидация ввода
Ответы агентов валидируются против inputSchema:
- Валидация JSON Schema на основе AJV
- Проверка типов для полей ответа
- Валидация обязательных полей
- Валидация pattern и format
Версия схемы и миграция
metadata.schemaVersion — целое число, описывающее форму самого definition, рядом с semver-полем
metadata.version, которое описывает его содержание. Текущее значение — 1; definition без этого
поля считается версией 0.
Каждый definition приводится к текущей версии до проверки, поэтому валидация никогда не видит старую форму. Обновление выполняется везде, где definition попадает в систему: при валидации, при загрузке через API, MCP или CLI, во встроенном каталоге и при чтении сохранённых definition, — а также однократно при старте для сохранённых definition, базовых снимков сверки и записанных конфликтов. Оно чистое и идемпотентное: definition, уже находящийся в текущей версии, возвращается без изменений.
Мигрировать вручную не требуется. Чтобы переписать файл на диске в текущую форму, выполните:
moira-workflow <file> migrateПри перезаписи существующего файла команда сначала создаёт резервную копию. При повторном запуске она сообщает «Already at schema version 1; nothing to migrate».
Диагностика маршрутизации
Узел condition или agent-directive маршрутизирует по упорядоченным cases, каждый из которых
называет ключ из connections этого узла. Валидатор проверяет их так. Идентификатор в скобках —
код, который появляется в сообщении.
| Уровень | Условие |
|---|---|
| ошибка | Case называет выход, которого нет в connections (unknown-case-output) |
| ошибка | Case называет зарезервированный управляющий выход (error или timeout) |
| ошибка | У узла condition нет cases или нет connections.default |
| предупреждение | Case выбирает собственный выход узла по умолчанию, то есть он избыточен |
| предупреждение | Авторский выход, который не назван ни одним case, недостижим (unreachable-output) |
unreachable-output — предупреждение, а не ошибка: definition правят по шагам, и соединение часто
добавляют раньше, чем case, который его выбирает; definition остаётся валидным. Выход по умолчанию
(default у узла condition, success у узла agent-directive) и управляющие выходы error и
timeout не требуют отдельного case.
Поле when каждого case проходит те же проверки оператора и структуры, что и любое структурированное
условие, а к читаемым им путям применяется описанная ниже проверка объявленных переменных.
expressions на узле маршрутизации проходят те же проверки синтаксиса и реестра, что и отдельный
узел expression.
Результаты валидации
Валидация возвращает структурированные результаты:
{ valid: boolean; errors: ValidationError[]; warnings: ValidationWarning[];}Типы ошибок
| Тип | Описание | Пример |
|---|---|---|
schema | Невалидная JSON структура | Отсутствует обязательное поле |
structure | Невалидная структура графа | Orphan нода |
connection | Невалидное соединение | Указывает на несуществующую ноду |
reference | Невалидная ссылка | Невалидный subgraph ID |
Типы предупреждений
| Тип | Описание | Порог |
|---|---|---|
structure | Много agent-directive нод | Более 20; рекомендация, а не предел исполнения |
node | Уведомление показывает внутреннее значение | Путь, голый счётчик или сырой вывод шага в message |
node | Два сообщения об одном ожидании | Узел уведомления, ведущий прямо в шаг humanGate с notify: "auto" |
Примеры валидации
Валидный Workflow
{ "id": "valid-workflow", "metadata": { "name": "Valid Workflow", "version": "1.0.0", "description": "A valid workflow" }, "nodes": [ { "id": "start", "type": "start", "connections": { "default": "task" } }, { "id": "task", "type": "agent-directive", "directive": "...", "completionCondition": "...", "connections": { "success": "end" } }, { "id": "end", "type": "end" } ]}Результат:
{ "valid": true, "errors": [], "warnings": [] }Невалидный Workflow - Отсутствует соединение
{ "nodes": [ { "id": "start", "type": "start", "connections": { "default": "missing" } }, { "id": "end", "type": "end" } ]}Результат:
{ "valid": false, "errors": [ { "type": "connection", "message": "Node 'start' references non-existent node 'missing'", "nodeId": "start" } ]}Workflow с предупреждением
Большой workflow вызывает предупреждение о производительности:
{ "valid": true, "errors": [], "warnings": [ { "type": "structure", "severity": "warning", "message": "High number of agent-directive nodes (25). Consider using subgraphs for better organization." } ]}Валидация Input Schema
Ответы агентов валидируются против inputSchema определенной на agent-directive нодах.
Ноды без inputSchema
Ноды без inputSchema требуют пустой ввод от агента. Непустые ответы отклоняются:
// Нода без inputSchema{ "id": "task", "type": "agent-directive", "directive": "Выполните задачу", "completionCondition": "Результат проверен", "connections": { "success": "end" } }
// Валидно: пустой ответ{}
// Невалидно: непустой ответ{ "result": "done" } // Отклоняется с ошибкой валидацииОпределение схемы
Далее показан фрагмент полей полного agent-узла; сохраните его id, directive, completionCondition и connections.
{ "type": "agent-directive", "inputSchema": { "type": "object", "properties": { "result": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 10 } }, "required": ["result"] }}Валидный ответ
{ "result": "completed", "confidence": 8 }Невалидный ответ
{ "confidence": "high" }Ошибка:
{ "valid": false, "errors": [ { "field": "result", "message": "Required field missing" }, { "field": "confidence", "message": "Expected number, got string" } ]}Предупреждение о переменной, объявленной без default
Валидатор выдаёт warning (severity warning, не ошибка — workflow остаётся валидным), когда переменная из variableRegistry используется в directive, completionCondition, message или в when case маршрутизации, но у переменной нет default и её не записывает ни один вышестоящий узел через globalInputs (и она отсутствует в initialData стартового узла).
В рантайме такая ссылка отображается как литеральный плейсхолдер [[UNDEFINED_VARIABLE]] вместо значения.
{ "valid": true, "errors": [], "warnings": [ { "type": "structure", "severity": "warning", "nodeId": "do-work", "message": "Variable 'iteration' is referenced in node 'do-work' but has no default and is never written by an upstream node. It will render [[UNDEFINED_VARIABLE]] at runtime." } ]}Исправить можно одним из двух способов:
- Добавить
defaultдля переменной вvariableRegistry. - Сделать так, чтобы вышестоящий узел записывал переменную через
globalInputsдо узла, который на неё ссылается.
Предупреждение о содержании уведомлений
Уведомление читает человек, часто с телефона: он не может открыть ни файл на машине агента, ни
сырой вывод шага. message у нод user-notification и telegram-notification получает
предупреждение — никогда не ошибку — за каждое значение, которым человек не сможет
воспользоваться:
- файл или путь: переменная с именем
*_path,*_file,*_dirили*_directory, объявленная глобальная переменная, в описании которой говорится о пути к файлу, каталоге или папке, или путь, написанный прямо в сообщении (./report.md,~/notes/today.txt,docs/final/report.md). Опишите содержимое словами или дайте ссылку-URL. - голый счётчик:
*_index,*_revision,max_*илиcurrent_step, если в сообщении нет ничего, что называет считаемое (значения с…title,…name,…labelили…summary). Поставьте рядом название или положитесь на список плана, который уведомление и так несёт. - сырой вывод шага:
{{node-id.field}}, где поле не URL и не название. Покажите название, фразу или URL.
{{this.…}} внутри циклов и системные значения ({{runUrl}}, {{executionId}}, …) не
отмечаются. Проверка эвристическая — по именам и описаниям; предупреждение показывают
moira-workflow validate, загрузка workflow и веб-редактор, и ни один из них не отказывается
сохранять.
⚠ 1 warning(s): • Notification notify-completion shows {{delivery_file}}, a file or path: the reader cannot open it from a message. Say what it contains in words, or link a URL.Предупреждение об уведомлении перед шагом ожидания
Шаг с пометкой humanGate и notify: "auto" (по умолчанию) заставляет Moira уведомить человека,
когда запуск начинает на нём ждать. Узел user-notification или telegram-notification, чьё
соединение ведёт прямо в такой шаг, шлёт второе сообщение о том же ожидании, поэтому получает
предупреждение — никогда не ошибку — с именем шага: оставьте сообщение workflow и поставьте на шаге
humanGate.notify: "off" (обычный выбор, когда в сообщении то, о чём человек решает) или уберите узел.
⚠ 1 warning(s): • Node notify-plan-approval: leads straight into "approve-plan", whose humanGate notifies the person itself (notify: auto); the person gets two messages about one wait (gate-notified-twice). Set humanGate.notify to "off" on "approve-plan" to keep this message, or remove this nodeВалидация ссылок на playbook
Определение, называющее playbook через {{playbook:name}}, принимается только если автор может его
прочитать: это либо его собственный playbook, либо опубликованный playbook другого аккаунта.
Недоступная ссылка — блокирующая ошибка на любом пути записи определения: инструмент workflow
отказывает в создании и в правке, а сохранённое через API определение остаётся невалидным. Сообщение
называет playbook и три выхода: создать его, опубликовать или убрать ссылку.
То же правило применяется ещё раз при старте запуска, потому что playbook может исчезнуть между
последней правкой и стартом. execution (execute) отказывает до создания запуска, а не показывает шаг, в котором
текст поведения отсутствует.
Ссылка с ведущим обратным слэшем (\{{playbook:name}}) — литеральный текст, и она не проверяется:
так документ объясняет синтаксис, не называя ни одного playbook.
Безопасность от инъекций
Подставленные ЗНАЧЕНИЯ переменных и данных никогда не выполняются повторно как шаблоны. Когда движок подставляет значение в directive или message, это значение трактуется как литеральная строка — синтаксис фигурных скобок, пришедший из подставленных данных, нейтрализуется и не парсится повторно.
Это означает, что шаблоны выполняются только в статических полях узла, контролируемых автором, а не в значениях, которые приходят из ввода агента или внешних данных.
Содержимое playbook подчиняется той же границе. Собственный playbook — авторский текст, и он обрабатывается как остальная часть определения; playbook другого аккаунта нейтрализуется перед подстановкой, поэтому опубликованный текст не может выполнить шаблоны внутри вашего запуска.
Не склеивайте недоверенный текст с авторским исходником шаблона. Возвращайте его как объявленные
литеральные данные и ссылайтесь на них явно. Предпочитайте именованные переменные вместо полных дампов
{{context.variables}}, которые могут раскрыть всю коллекцию переменных.
Валидация Materialize
Нода materialize допустима, только если basePath непустой, files содержит хотя бы одну запись,
а connections.success задан. Каждый объявленный files[].path должен быть нормализованным
относительным путём без NUL, абсолютного или начинающегося с обратной косой черты корня, пустых
сегментов, . и ..; объявленные пути должны быть уникальны. Каждая запись задаёт ровно одно из:
from: имя записиvariableRegistryсtype: "string"и строковымdefault;content: "": пустой каркасный файл. Непустой inline-контент отклоняется.
Поскольку пути могут содержать шаблоны, те же проверки безопасности и коллизий повторяются после
рендеринга с текущим контекстом выполнения. У архивной доставки нет общих потолков числа файлов и байтов;
выбранный контроллер проверяет пути, кодирует текст и хранит неизменяемую tar-публикацию. Ошибка подготовки шага переходит по необязательному
connections.error, а без него выбрасывается. Каждая HTTP-загрузка заново проверяет пятиминутное
разрешение и привязки пользователя, выполнения, ноды и контекста, в том числе после асинхронной работы.
Первая отправка закрепляет проверенную identity контроллера и исходный ID запроса; повторы только
читают ту же публикацию без нового рендера и отправки. Новое сопряжение не подменяет эти права. Доставка в контекст проверяет те же привязки и
добавляет ещё одно ограничение: набор суммарно больше 256 KiB отклоняется, а не усекается.
Лучшие практики
- Объявляйте нужный ввод — inputSchema задаёт значения, которые действительно нужны следующей ответственности; для пустого завершения она не обязательна
- Разделяйте ответственности — subgraph выделяет реальную переиспользуемую работу, а не выполняет цель по числу узлов
- Тестируйте валидацию - Используйте
workflowсincludeValidation: true - Обрабатывайте ошибки по контракту — невалидный ответ ждёт исправления; поддерживаемый error connection обрабатывает только документированные отказы узла