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

Система валидации

Система валидации

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, уже находящийся в текущей версии, возвращается без изменений.

Мигрировать вручную не требуется. Чтобы переписать файл на диске в текущую форму, выполните:

Terminal window
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 отклоняется, а не усекается.

Лучшие практики

  1. Объявляйте нужный ввод — inputSchema задаёт значения, которые действительно нужны следующей ответственности; для пустого завершения она не обязательна
  2. Разделяйте ответственности — subgraph выделяет реальную переиспользуемую работу, а не выполняет цель по числу узлов
  3. Тестируйте валидацию - Используйте workflow с includeValidation: true
  4. Обрабатывайте ошибки по контракту — невалидный ответ ждёт исправления; поддерживаемый error connection обрабатывает только документированные отказы узла