Узлы
Узлы — это строительные блоки воркфлоу Moira. Каждый узел представляет шаг в процессе со специфическим поведением, определяемым его типом.
Типы узлов
Ниже перечислены встроенные типы узлов Moira. Установленные расширения могут добавлять типы с
пространством имён, например extension-name.node-name. Live-реестр расширений передаёт их схемы
конфигурации валидатору, а каталог типов узлов Moira описывает их средству просмотра workflow.
Start
Точка входа для выполнения воркфлоу.
End
Терминальный узел, отмечающий завершение воркфлоу.
Agent Directive
Задача агента с директивой и условием завершения.
Condition
Ветвление выполнения в один из нескольких выходов по упорядоченным case.
Expression
Вычисление значений с помощью арифметических выражений.
Subgraph
Делегирование другому воркфлоу.
User Notification
Отправка уведомления через все включённые каналы связи, настроенные текущим пользователем. Каждое сообщение начинается с названия воркфлоу и задачи прогона — ссылкой на страницу прогона — и может нести план прогона.
Telegram Notification (устаревшая)
Telegram-only нода совместимости для существующих provider-specific workflow. Её сообщения несут
тот же заголовок, строку плана progress и строку ожидания, что и user-notification.
Teleport
Цель перехода, доступная только через явный teleport.
Lock
PIN-блокировка с подтверждением через Telegram. Сообщение с PIN начинается с того же заголовка, что и уведомление: название воркфлоу и задача прогона, на следующей строке — страница прогона.
Materialize
Доставка файлов из реестра через пятиминутное разрешение, привязанное к ноде.
Start Node
Точка входа для выполнения воркфлоу. Каждый воркфлоу должен иметь ровно один start node.
{ "id": "start", "type": "start", "connections": { "default": "first-task" }}| Свойство | Обязательно | Описание |
|---|---|---|
id | Да | Любой уникальный ID по схеме; “start” — имя примера |
type | Да | Должен быть "start" |
connections.default | Да | ID следующего узла |
Start узел заполняет глобальные переменные воркфлоу из значений default в variableRegistry. Объявляйте глобальные переменные в variableRegistry уровня воркфлоу, а не на start узле.
End Node
Терминальный узел, отмечающий завершение воркфлоу. Нет исходящих соединений.
{ "id": "end", "type": "end", "finalOutput": ["result", "summary"]}| Свойство | Обязательно | Описание |
|---|---|---|
id | Да | Любой уникальный ID по схеме; “end” — имя примера |
type | Да | Должен быть "end" |
finalOutput | Нет | Ключи контекста для включения в финальный результат |
note: End узлы не имеют соединений — это терминальные узлы.
Agent Directive Node
Основной тип узла для задач агента. Содержит директиву (что делать) и условие завершения (когда готово).
{ "id": "analyze-requirements", "type": "agent-directive", "directive": "Проанализируй документ требований и определи ключевые фичи", "completionCondition": "Фичи перечислены с приоритетами", "inputSchema": { "type": "object", "globalInputs": ["analysis_done"], "properties": { "features": { "type": "array", "items": { "type": "string" } } }, "required": ["analysis_done", "features"] }, "connections": { "success": "next-step" }}| Свойство | Обязательно | Описание |
|---|---|---|
directive | Да | Что агент должен сделать |
completionCondition | Да | Когда шаг завершен |
inputSchema | Нет | JSON Schema для валидации ответа |
inputSchema.globalInputs | Нет | Имена глобальных переменных variableRegistry, которые пишет узел |
inputSchema.properties | Нет | Локальные выводы узла (используются как node-id.name) |
expressions | Нет | Арифметические выражения, вычисляемые после валидации ответа |
cases | Нет | Упорядоченные case маршрутизации по проверенному ответу узла |
connections.success | Да | Выход по умолчанию: берётся, когда ни один case не сработал |
connections.error | Нет | Управляющий выход при сбое выражения на узле |
connections.timeout | Нет | Зарезервированный управляющий выход; кейс не может его называть |
humanGate | Нет | Помечает шаг, на котором запуск ждёт человека |
В примере analysis_done — объявленная глобальная переменная (должна существовать в variableRegistry), которую пишет этот узел и которая доступна в других местах как {{analysis_done}}; features — локальный вывод узла, доступный как {{analyze-requirements.features}}. Возвращённый ключ, не являющийся ни объявленной глобальной, ни описанным локальным выводом, отклоняется.
Используйте inputSchema для структурированных ответов. globalInputs перечисляет глобальные
переменные, которые пишет узел; properties описывает его локальные выводы. Движок автоматически
валидирует и маршрутизирует ответ.
Если ответ не соответствует inputSchema, движок записывает ошибку и снова приостанавливается на
том же узле. Сообщение объясняет ожидаемую схему и ошибки, но не повторяет отклонённый payload.
У этого цикла валидации нет ограничения или перенаправления на уровне узла; бизнес-логику retry и
эскалации нужно явно моделировать в графе workflow.
Маршрутизация по ответу
Узел agent-directive может сам решать, куда продолжится выполнение, исходя из своего проверенного
ответа. cases содержит упорядоченные записи { "when": <структурированное условие>, "output": "<ключ соединения>" }; первое сработавшее when выбирает свой выход, а если не сработало ни одно,
узел берёт success. Условия читают контекст уже после того, как ответ влит в него, поэтому поле
ответа доступно по краткому имени (review_outcome для объявленной глобальной переменной) и по
локальному пути узла (review.review_outcome).
{ "id": "review", "type": "agent-directive", "directive": "Проверь изменение", "completionCondition": "Вердикт зафиксирован", "inputSchema": { "type": "object", "globalInputs": ["review_outcome"], "required": ["review_outcome"] }, "cases": [ { "when": { "operator": "eq", "left": { "contextPath": "review_outcome" }, "right": "blocked" }, "output": "blocked" } ], "connections": { "success": "merge", "blocked": "fix-issues" }}error и timeout — зарезервированные управляющие выходы: case не может их называть, и отдельный
case для них не нужен.
Ожидание человека
На некоторых шагах флоу останавливается ради решения человека: агент показывает план или результат и
ждёт ответа в чате. Пометьте такой шаг свойством humanGate — пока запуск стоит на нём, он показан
как ждёт вас, а не как ожидающий агента: на странице запуска, в его прогрессе и в строке
ожидания уведомления, ведущего к этому шагу. Директива, её вход и маршрутизация не меняются: вопрос
по-прежнему задаёт и ответ сдаёт агент.
{ "id": "approve-plan", "type": "agent-directive", "directive": "Покажи план и попроси человека его одобрить", "completionCondition": "Решение человека записано", "humanGate": { "label": "Одобрить план", "when": { "operator": "neq", "left": { "contextPath": "operating_mode" }, "right": "autonomous" } }, "connections": { "success": "execute" }}| Свойство | Обязательно | Описание |
|---|---|---|
humanGate.label | Нет | Что просят сделать человека, в нескольких словах; иначе — подпись шага в прогрессе |
humanGate.when | Нет | Структурированное условие: шаг ждёт человека, только если оно выполнено при входе в шаг |
humanGate.notify | Нет | auto (по умолчанию): движок уведомляет человека, когда запуск начинает ждать; off: первое сообщение шлёт сам флоу |
humanGate.remindAfter | Нет | Сколько ожидание длится без ответа до одного напоминания от движка, при любом notify: число и m, h или d (30m, 4h, 1d) |
Условие записывается так же, как when у case маршрутизации, и вычисляется один раз — когда запуск
приходит на шаг; без условия шаг ждёт человека всегда. Оно нужно шагу, в который входит и запуск в
автономном режиме и решает его сам, чтобы запуск без человека не показывался ждущим кого-то. Шагу,
который ждёт человека в любом режиме, — например, внешнему блокеру, снять который может только
человек, — условие не нужно. Шаг, где агент сначала долго работает и спрашивает только в конце,
лучше не помечать: пометка показывала бы запуск ждущим вас во время этой работы; его директива велит
агенту задать вопрос через execution (await-user), когда он спрашивает. Если в новой версии
флоу шаг пометить, снять пометку или изменить её, для запусков, уже стоящих на нём, решение
принимается заново, и они продолжают работу с текущей попыткой шага; новая версия, которая пометку
не трогает, условие заново не вычисляет.
Когда запуск начинает ждать на помеченном шаге, человек получает уведомление через свои каналы (те же,
что у user-notification): флоу и задача, что его просят сделать, и ссылка на запуск; отвечает он
агенту в чате. Уведомление уходит один раз на ожидание — повтор шага или переподключение агента его не
повторяют, — а если ожидание всё ещё открыто через remindAfter, приходит ровно одно напоминание.
Поставьте notify: "off", если флоу уже шлёт своё сообщение прямо перед этим шагом — обычно потому,
что в нём то, о чём человек решает, например план или причина блокера, — чтобы человек не получил
два; валидатор предупреждает (gate-notified-twice) об узле уведомления, ведущем прямо в шаг с
notify: "auto". При notify: "off" первым приходит сообщение флоу, а remindAfter по-прежнему
даёт одно напоминание от движка. Напоминание отсчитывается от момента, когда запуск начал ждать на
шаге, а для запуска, уже стоявшего на шаге, когда новая версия его пометила, — от этого обновления.
Страница запуска показывает под плашкой, ушло ли уведомление или напоминание, когда и куда, или что
каналы не настроены; для шага с notify: "off" до отправки напоминания она ничего не показывает.
CLI moira-workflow ставит пометку командой update <узел> --human-gate '<json>' и снимает её
ключом --human-gate none.
Condition Node
Ветвление выполнения по упорядоченным case. Каждый case связывает структурированное условие с
ключом соединения, который он выбирает; побеждает первый case, чьё when сработало, а если не
сработало ни одно, узел берёт default. Решение с двумя исходами — это один case плюс default:
{ "id": "check-result", "type": "condition", "cases": [ { "when": { "operator": "eq", "left": { "contextPath": "status" }, "right": "success" }, "output": "passed" } ], "connections": { "passed": "success-path", "default": "retry-step" }}Любое число исходов записывается так же — по одному case на каждый авторский выход:
{ "id": "triage", "type": "condition", "cases": [ { "when": { "operator": "eq", "left": { "contextPath": "size" }, "right": "small" }, "output": "fast" }, { "when": { "operator": "eq", "left": { "contextPath": "size" }, "right": "large" }, "output": "slow" } ], "connections": { "fast": "quick-path", "slow": "long-path", "default": "normal-path" }}| Свойство | Обязательно | Описание |
|---|---|---|
cases | Да | Упорядоченные записи { when, output }; минимум одна |
cases[].when | Да | Объект структурированного условия |
cases[].output | Да | Ключ соединения, который выбирает этот case |
expressions | Нет | Арифметические выражения, вычисляемые до case |
connections.default | Да | Выход, когда ни один case не сработал |
connections.error | Нет | Управляющий выход при сбое выражения на узле |
Любой другой ключ connections — авторский выход, названный в одном из case. error зарезервирован
для управления потоком: case не может его называть, и отдельный case для него не нужен.
Выражения на узлах маршрутизации
И condition, и agent-directive принимают expressions — тот же песочный арифметический
интерпретатор и та же проверка по реестру, что и у отдельного узла expression.
Присваивания должны обращаться к объявленным глобальным переменным. Выражения выполняются до case
(на узле agent-directive — после валидации его ответа), поэтому case может прочитать вычисленное, а
присваивания публикуются только при успехе узла. Сбой выражения ведёт в connections.error, если он
есть у узла; иначе узел падает — ровно как отдельный узел expression.
{ "id": "count-attempt", "type": "condition", "expressions": ["attempts = attempts + 1"], "cases": [ { "when": { "operator": "gte", "left": { "contextPath": "attempts" }, "right": 3 }, "output": "exhausted" } ], "connections": { "exhausted": "escalate", "default": "retry-step", "error": "handle-error" }}Структурированные условия
Условия используют структурированный формат (не строковую оценку):
{ "operator": "and", "conditions": [ { "operator": "gt", "left": { "contextPath": "score" }, "right": 80 }, { "operator": "eq", "left": { "contextPath": "validated" }, "right": true } ]}Поддерживаемые операторы:
eq,neq— равно, не равноgt,gte,lt,lte— операторы сравненияcontains— вхождение в строку/массивexists— проверка существованияand,or,not— логические операторы
Expression Node
Вычисление значений с помощью арифметических выражений. Полезно для счётчиков, расчётов и трансформации переменных:
{ "id": "increment-counter", "type": "expression", "expressions": ["counter = counter + 1", "result = counter * multiplier"], "connections": { "default": "next-step", "error": "error-handler" }}| Свойство | Обязательно | Описание |
|---|---|---|
expressions | Да | Массив выражений присваивания |
connections.default | Да | Следующий узел после успешного вычисления |
connections.error | Нет | Следующий узел при ошибке вычисления |
Синтаксис выражений
Выражения поддерживают базовые арифметические операции:
- Арифметика:
+,-,*,/ - Скобки:
(a + b) * c - Присваивание:
result = a + b - Пути в контексте:
step.index,plan.items[0].value,tasks[current_index].action
{ "expressions": ["total = price * quantity", "tax = total * 0.1", "final_price = total + tax"]}Выражения вычисляются собственным изолированным парсером, а НЕ через JavaScript eval. Чтение использует только собственные свойства; постоянный или переменный индекс массива должен быть целым, неотрицательным и находиться в границах. Цель присваивания — безопасное простое имя. При наличии реестра присваивание обязано обращаться к объявленной глобальной переменной и соответствовать её JSON Schema; при ошибке нода ничего не публикует.
Обработка ошибок
Expression node может завершиться с ошибкой в следующих случаях:
- Деление на ноль
- Некорректное, небезопасное, неразрешимое или выходящее за границы чтение пути
- Необъявленная цель присваивания или значение вне схемы реестра
При ошибке выполнение переходит к connection error если он определён, иначе воркфлоу завершается с ошибкой.
Subgraph Node
Делегирование выполнения другому воркфлоу:
{ "id": "run-tests", "type": "subgraph", "graphId": "test-workflow", "inputMapping": { "codeDir": "projectPath" }, "outputMapping": { "testResults": "results" }, "connections": { "success": "next-step" }}| Свойство | Обязательно | Описание |
|---|---|---|
graphId | Да | ID ссылаемого воркфлоу |
inputMapping | Да | Родительский контекст -> контекст подграфа |
outputMapping | Да | Контекст подграфа -> родительский контекст |
connections.success | Да | Следующий узел при успехе |
Подграфы обеспечивают композицию и повторное использование воркфлоу. Агент видит это как непрерывный воркфлоу.
connections.error необязателен и в текущем runtime не используется для исключений выполнения
дочернего workflow или ошибок mapping. Такие ошибки записываются, а выполнение приостанавливается
на subgraph node, чтобы агент исправил причину и повторил шаг.
User Notification Node
Отправляет сообщение через все корректные включённые каналы пользователя выполнения. Workflow не может выбирать provider, получателя или credential:
{ "id": "notify-complete", "type": "user-notification", "message": "🏁 *Готово* — {{deliver-result.result_summary}}", "planList": "full", "format": "markdown", "silent": false, "connections": { "default": "next-step", "error": "notification-failed" }}| Свойство | Обязательно | Описание |
|---|---|---|
message | Да | Текст уведомления с поддержкой шаблонов |
format | Нет | Переносимый формат: plain, markdown или html |
silent | Нет | Запрос тихой доставки, если provider её поддерживает |
attachProgressImage | Нет | Приложить шаги запуска как PNG шириной телефона |
planList | Нет | Строки плана: progress (по умолчанию), full или none |
attachment | Нет | Одно inline base64-вложение image или document с именем/MIME |
connections.default | Да | Путь при полной, частичной доставке или отсутствии подходящих каналов |
connections.error | Нет | Путь при полном провале попыток; иначе используется default |
Каждое доставленное сообщение начинается с заголовка: имя воркфлоу и каноническое
название задачи запуска — ссылкой на страницу прогона. Дальше идут message, план прогона
и, когда нода ведёт прямо на шаг, на котором запуск останавливается, тот, кого там ждут:
⏳ agent on the step: <block> или 🙋 waiting for you: <block> (гейт lock или шаг, помеченный
humanGate). Произвольная заметка не задаёт заголовок. Без явного названия используется
разрешённый авторский progress.title, затем имя собственного воркфлоу. План берётся из привязанного списка, ближайшего
к прогону на момент этой ноды, включая то, что текущий шаг только что записал; planList задаёт,
сколько плана несёт сообщение:
progress(по умолчанию) — одна строка📝 сделано/всего: текущий пункт;full— строка📝 сделано/всегои все пункты с номерами и состоянием:✓сделан,▶в работе,○впереди; слишком длинный для канала план сворачивается вокруг текущего пункта в… N earlier/… N more;none— без плана.
Уведомление, чьё соединение default ведёт прямо в ноду end, — последнее сообщение прогона:
ни один пункт уже не в работе, поэтому невыполненный пункт отмечен ○, а строка progress не
называет текущий пункт.
Пока прогон не дошёл до блока, к которому привязан план, берётся первый привязанный блок с уже
записанными пунктами, поэтому сообщение «план готов» может показать план. При format: "markdown"
или "html" каждое подставленное в сообщение значение экранируется для этого формата и не может
добавить разметку; разметка автора сохраняется, а значение внутри авторской ссылки или
code-разметки покажет свои экранирующие символы, поэтому значения ставьте вне её. Текст подгоняется
под предел канала: план занимает оставшееся место, а слишком длинное сообщение обрезается по
строке с …. В Telegram предпросмотр ссылок выключен для всех сообщений.
Явное attachment и включённый attachProgressImage взаимоисключающие.
Вложение и рендер прогресса обрабатывает выбранный владелец файлов: зарегистрированный
workspace-сервис или сопряжённый контроллер. Имя должно быть безопасным basename, MIME —
корректным type/subtype. Владелец хранит неизменяемый источник, исходный результат доставки
и этапы каналов; собственные пределы изображений и документов Telegram сохраняются.
Недоставленное явное вложение следует заданной политике error/default; текстовая отправка
не подменяет его успех. Для необязательного attachProgressImage недоступный рендер или
владелец пропускает картинку, но обычное текстовое уведомление всё равно отправляется
независимо. Текст, напоминания ожидания и доверенная доставка PIN не требуют владельца файлов.
Результат содержит attachmentStatus и, когда исходный владелец известен, ссылку operation.
Передавайте её без изменений в communication (collect) для чтения неопределённой доставки.
Если первый ответ потерян, найдите исходные записи через communication (find) и выберите явно.
Не повторяйте визит workflow ради повторной отправки: новый визит — отдельное намерение.
Чтение результата ничего не отправляет; перед доставкой провайдеру повторно проверяются
привязки запуска и названия задачи.
Результат ноды хранится под её ID. Для обычного текста userNotificationStatus принимает
delivered, partial, no_configured_channels или all_failed; результат содержит счётчики
и очищенные per-channel status/reason. Успешная доставка владельца сообщает delivered либо
no_configured_channels, а channels содержит исходные этапы операций доставки.
Выбираются только настроенные каналы с поддержкой запрошенного вида файла.
Credentials, получатели, тело сообщения и байты вложения в результаты и ошибки не попадают.
Устаревшая Telegram-specific нода
telegram-notification остаётся исполняемой для существующих workflow. Она отправляет только через
Telegram, а заданный chatId сохраняет точное provider-specific значение получателя. Для новых
обычных уведомлений используйте user-notification; переход explicit legacy recipient к generic
fan-out требует намеренной миграции workflow.
Teleport Node
Цель перехода, доступная только через явный teleport, а не через обычные соединения. Работает как agent-directive: приостанавливается для ввода и валидирует его схему, но достигается только по явному запросу агента.
{ "id": "teleport-replan", "type": "teleport", "directive": "Перепиши план разработки", "completionCondition": "Новый план создан и проверен", "hint": "Используй, когда текущий план нужно перестроить", "inputSchema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": ["reason"] }, "connections": { "success": "plan-node" }}| Свойство | Обязательно | Описание |
|---|---|---|
hint | Да | Понятное человеку описание, когда нужен teleport |
directive | Да | Инструкция, показанная агенту после teleport |
completionCondition | Да | Критерии успешного завершения шага teleport |
inputSchema | Нет | JSON Schema для валидации ответа агента |
connections.success | Да | Следующий узел после ввода для teleport |
connections.error | Нет | Узел обработки ошибки |
У teleport-узлов не должно быть входящих соединений от других узлов. При валидации они исключены из предупреждений о недостижимых узлах.
Использование Teleport во время выполнения
Если воркфлоу содержит teleport-узлы, их подсказки добавляются к каждому ответу шага в разделе
«Available Teleport Jumps». Для перехода вызовите execution с action: "step", processId,
attemptId и teleportTo, не передавая input:
execution({ action: "step", processId: "abc123", attemptId: "attempt-current", teleportTo: "teleport-replan" })- Целью может быть только узел типа teleport
- Используйте идентификатор попытки шага из текущего предъявления
- Не передавайте
inputпри переходе: teleport-узел сначала покажет собственную директиву - Контекст выполнения сохраняется целиком
- После ввода для teleport-узла выполнение продолжается через
connections.success
Lock Node
PIN-блокировка выполнения. Она доставляет PIN в настроенный Telegram-чат текущего пользователя с inline-клавиатурой Approve и приостанавливает workflow только после успешной доставки.
{ "type": "lock", "id": "approval-gate", "reason": "Деплой на продакшен для {{workflow_name}}", "connections": { "unlocked": "proceed-node" }}| Свойство | Обязательно | Описание |
|---|---|---|
reason | Да | Причина блокировки (поддерживает шаблоны {{var}}) |
connections.unlocked | Да | Следующий узел после разблокировки |
Поведение:
- Для запуска любого workflow с lock node текущему пользователю нужны корректные bot token и chat ID. Ни
skipNotificationCheck, ни его устаревший aliasskipTelegramCheckне обходят это требование. - При первом посещении Moira сохраняет только хеш ожидающего доставки PIN, отправляет открытый PIN в настроенный chat, активирует блокировку, сохраняет
_lockIdи приостанавливает выполнение. - При отсутствующих или некорректных настройках и при ошибке доставки не возникает доступной активной блокировки или context reference. Повторное посещение запускает новую попытку доставки с новым PIN.
- Следующие посещения проверяют активную блокировку или введённый пользователем PIN и после разблокировки переходят через
connections.unlocked.
MCP-ответы и ответы workflow никогда не содержат сгенерированный PIN. Пользователь может передать PIN отдельно или подтвердить блокировку в Telegram.
Materialize Node
Доставляет объявленные автором файлы в файловую систему агента, удерживая их отрендеренное
содержимое вне контекста агента. Сервер создаёт пятиминутное разрешение на tar-загрузку, привязанное
к ноде; агент выполняет или повторяет точную команду из сгенерированной директивы и завершает шаг
значением null или {}. Хост, который не может выполнить эту команду, использует указанный в
директиве fallback-маршрут доставки в контекст: он расходует контекст и завершает шаг так же.
{ "id": "materialize-standards", "type": "materialize", "basePath": "{{workspace_path}}", "files": [ { "path": "standards/planning.md", "from": "planning_standards" }, { "path": "plans/.keep", "content": "" } ], "connections": { "success": "create-plan", "error": "materialize-failed" }}| Свойство | Обязательно | Описание |
|---|---|---|
basePath | Да | Результат рендеринга должен быть непустым и не содержать NUL |
files | Да | Одна или несколько записей архива |
files[].path | Да | Безопасный шаблонизируемый путь относительно basePath |
files[].from | Одно из | Строковая запись variableRegistry, чей текущий default служит исходником |
files[].content | Одно из | Должен быть ровно ""; создаёт каркасный файл |
connections.success | Да | Следующая нода после пустого completion input |
connections.error | Нет | Путь при ошибке валидации, конфигурации или выдачи разрешения |
from и content взаимоисключающие. from должен ссылаться на объявленную строковую переменную
со строковым default; произвольный inline-текст отклоняется. При показе шага сервер рендерит
basePath и сводку путей файлов в директиве. Отрендеренный basePath становится частью выданной
команды. При первом HTTP-запросе облако разрешает текущие пути и текст из реестра, собственных Notes и
Playbooks с привязанным контекстом. Сопряжённый контроллер кодирует UTF-8, создаёт tar и хранит
неизменяемую публикацию. До отправки разрешение закрепляет полную identity контроллера и исходный
ID запроса. Повтор читает тот же результат без нового рендера, выбора владельца или отправки;
последующая правка определения не меняет опубликованные байты. Новый показ шага выдаёт новое
разрешение для отдельной явной попытки.
Сгенерированная POSIX-команда имеет следующую форму; все аргументы уже безопасно заключены в кавычки для shell:
mkdir -p -- '<basePath>' && curl -sSf -- '<reusable-url>' | tar -x -C '<basePath>'Копируйте выданную команду без изменений. Записи архива относительны к basePath; сам basePath
в tar не входит. Пути должны быть нормализованными, относительными, непустыми и уникальными после
рендеринга; запрещены пустые сегменты, ., .., абсолютный или начинающийся с обратной косой
черты путь и NUL. Общих потолков количества и размера архивных файлов нет; действуют хранилище владельца и права.
URL живёт пять минут и привязан к текущим пользователю, выполнению и ноде. Его можно скачивать
повторно, пока выполнение ожидает на этой ноде; сразу после перехода выполнения URL становится
недействительным. Сгенерированная директива объясняет окно повторов и напоминает, что доставка не
доказывает чтение; каждый последующий потребитель всё равно должен явно требовать чтения нужных ему
файлов. Вызов execution({ action: "current_step" }) на паузе выдаёт свежий URL без продвижения графа.
Хост, который не может выполнить команду, использует execution (materialize) для существующей
ограниченной доставки в контекст. Восстановление на эту ноду заново предъявляет доставку, не
продвигая граф; доставка разрешает текущие значения реестра по умолчанию. Само изменение контекста
не перезаписывает файлы вызывающей стороны.
Полный контракт архива, путей, разрешений и ошибок, а также применение в Workflow Management Flow описаны в разделе Материализация файлов.
Ноды расширений
Установленные расширения добавляют типы в собственном пространстве имён, например
corporate-messenger.send. Манифест задаёт форму конфигурации и схемы валидации; браузер строит по
ним универсальный редактор и не загружает frontend-код расширения. Успешный результат сохраняется
под ID ноды. Ошибки входа, обработчика, срока, runner и выхода переходят по connections.error,
если эта связь есть; иначе Moira записывает диагностику и приостанавливается на ноде для повтора.
Живой каталог типов отличает недоступный runner от доступного реестра, в котором не установлено конкретное расширение. Контракты манифеста, SDK и исполнения описаны в Написании расширения.
Input Schema
Определение ожидаемой структуры ответа с использованием JSON Schema:
{ "inputSchema": { "type": "object", "properties": { "summary": { "type": "string", "description": "Краткое резюме находок" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "priority": { "type": "number" } } } } }, "required": ["summary"] }}Автоматические типы узлов
Автоматические узлы выполняются на сервере без участия агента и сразу переходят к следующему узлу. Они используются для операций с постоянными заметками.
Read Note Node
Читает заметки по фильтру в переменную контекста:
{ "type": "read-note", "id": "load-notes", "outputVariable": "projectNotes", "filter": { "tag": "{{projectTag}}", "keyPattern": "project-" }, "singleMode": false, "connections": { "default": "next-node", "error": "error-handler" }}| Свойство | Обязательно | Описание |
|---|---|---|
outputVariable | Да | Переменная контекста для результатов |
filter.tag | Нет | Фильтр по точному тегу |
filter.keyPattern | Нет | Поиск внутри ключа |
filter.keySearch | Нет | Поиск подстроки в ключе |
singleMode | Нет | Объект только при одном результате в странице; иначе массив |
connections.error | Нет | Узел обработки ошибки |
Read-note сохраняет outputVariable локально: используйте {{load-notes.projectNotes}}. Он читает одну страницу стандартного размера, а не все совпадения. Примеры предполагают объявленные глобалы для коротких имён шаблонов и целевые узлы в содержащем графе.
Write Note Node
Записывает данные из контекста в заметки:
{ "type": "write-note", "id": "save-results", "key": "results-{{timestamp}}", "source": "{{analysisResults}}", "tags": ["analysis"], "connections": { "default": "next-node" }}| Свойство | Обязательно | Описание |
|---|---|---|
key | Нет* | Ключ заметки, обязательный в одиночном режиме |
source | Да | Одиночный режим: текст или шаблон; пакетный: сырой путь в контексте |
tags | Нет | Назначаемые теги |
batchMode | Нет | Массив по сырому source-пути без шаблонных скобок |
Пример одиночной записи предполагает, что analysisResults объявлена в variableRegistry и
заполнена до этого узла. Чистая ссылка {{analysisResults}} или {{analyze-requirements.features}}
сохраняет разрешённое значение, сериализуя объекты и массивы в JSON. Имя analysisResults без
скобок сохраняется как буквальный текст. При batchMode: true используйте сырой путь в контексте
без скобок; его значением должен быть массив записей с key, value и необязательными tags.
Upsert Note Node
Ищет существующую заметку или создаёт новую:
{ "type": "upsert-note", "id": "upsert-config", "search": { "tag": "config-{{projectId}}" }, "keyTemplate": "{{projectId}}-config", "value": "{{configData}}", "tags": ["config-{{projectId}}"], "connections": { "default": "next-node" }}| Свойство | Обязательно | Описание |
|---|---|---|
search.tag | Нет | Поиск по тегу |
search.keyPattern | Нет | Поиск внутри ключа |
keyTemplate | Да | Ключ новой заметки, если она не найдена |
value | Да | Буквальный текст или шаблон значения заметки |
Здесь configData должна быть объявленной и заполненной глобальной переменной. Как и при
одиночной записи, чистая ссылка в скобках сохраняет разрешённое значение, сериализуя объекты и
массивы в JSON; имя без скобок сохраняет буквальный текст. Для локального результата производящего
узла используйте {{producer-id.field}}.
Все параметры фильтра и ключа поддерживают шаблонные выражения {{ variable }}.
Upsert обновляет первое совпадение и не обеспечивает уникальности. Ограничьте поиск нужной заметкой. Результаты автоматических note-узлов остаются под ID производящего узла, а не в глобалах с коротким именем.
Лучшие практики
- Начинайте со start — Каждый воркфлоу должен иметь ровно один start узел
- Заканчивайте end — Используйте end узлы для отметки точек завершения
- Четкие директивы — Будьте конкретны в том, что агент должен сделать
- Проверяемые условия — Условия завершения должны быть объективно измеримы
- Валидация схемы — Используйте
inputSchemaдля структурированных ответов - Пути ошибок — Используйте error connection только там, где его маршрутизирует документированное поведение конкретного типа узла