Материализация файлов
Нода materialize доставляет файлы, заданные workflow, в файловую систему агента, удерживая их
отрендеренные тела вне ответа шага. Moira выдаёт команду загрузки короткоживущего архива,
приостанавливает выполнение и продолжает его только после пустого ответа агента. Хост, который не
может выполнить эту команду, доставляет файлы описанным ниже fallback-маршрутом в контекст и
завершает шаг так же.
Используйте эту ноду для стабильных файлов, которыми владеет определение workflow: инструкций,
стандартов или пустого каркаса директорий. Файлы, чьё содержимое зависит от анализа агента, остаются
ответственностью создающей их agent-directive ноды.
Объявление ноды
Храните переиспользуемый текст в строковой записи variableRegistry и ссылайтесь на неё через
from:
Это фрагмент объявления. Содержащий граф должен также объявить и задать доверенный строковый глобал workspace_path до этой ноды, определить start и целевые узлы connections.
{ "variableRegistry": { "workspace_reference": { "type": "string", "description": "Инструкции, доставляемые в рабочее пространство", "default": "# Workspace reference\n\nFollow the project contract." } }, "nodes": [ { "id": "materialize-workspace", "type": "materialize", "basePath": "{{workspace_path}}", "files": [ { "path": "reference.md", "from": "workspace_reference" }, { "path": "plans/.keep", "content": "" } ], "connections": { "success": "work", "error": "materialize-failed" } } ]}| Свойство | Обязательно | Контракт |
|---|---|---|
basePath | Да | Шаблонизируемая директория назначения; отрендеренное значение должно быть непустым и не содержать NUL |
files | Да | Одна или несколько записей архива |
files[].path | Да | Безопасный шаблонизируемый путь относительно basePath |
files[].from | Одно из | Имя строковой записи реестра, чей текущий default задаёт тело файла |
files[].content | Одно из | Должен быть ровно ""; создаёт пустой каркасный файл |
connections.success | Да | Следующая нода после пустого ответа |
connections.error | Нет | Маршрут ошибки валидации, конфигурации, базы данных или выдачи разрешения во время показа шага |
Каждый файл должен объявлять ровно одно из полей from и content. Непустой inline-content
отклоняется; вместо него используйте одну запись реестра как источник истины.
Запуск сгенерированной команды
При показе ноды Moira рендерит basePath и сводку путей, создаёт разрешение на пять минут и
возвращает POSIX-команду, где каждый аргумент уже безопасно заключён в shell-кавычки:
mkdir -p -- '<basePath>' && curl -sSf -- '<reusable-url>' | tar -x -C '<basePath>'Запускайте выданную команду без изменений. URL — непрозрачный bearer credential: не собирайте его
самостоятельно, не редактируйте, не записывайте в лог и не передавайте другим. Одну и ту же команду
можно повторять в течение пяти минут, пока выполнение ожидает на этой ноде: повтор читает исходную публикацию, а не отправляет неопределённую публикацию заново. После успешной распаковки
завершите шаг значением null или {}. Иная форма ответа не принимается.
Сгенерированная директива сообщает срок и правила повтора, предупреждает, что переход выполнения
делает URL недействительным, называет описанный ниже fallback-маршрут доставки в контекст при
условии, что этот хост не может выполнить команду, и объясняет, что доставка не доказывает чтение
ни на одном из маршрутов. Вызов
execution({ action: "current_step", executionId }) во время паузы выдаёт новые команду и разрешение, не продвигая
граф. Поздняя директива всё равно должна явно требовать чтения каждого используемого файла.
Контракт архива и путей
Первое скачивание разрешает текущие значения реестра, собственные Notes и Playbooks как авторизованный текст. Доступный сопряжённый контроллер кодирует его в UTF-8, создаёт tar потоком и хранит неизменяемую публикацию. Облачная Moira не собирает и не сохраняет архив. Для этой работы контроллеру не нужны Local VM или включённая физическая Local-возможность; подключите его до загрузки.
До отправки разрешение закрепляет полную identity контроллера — пользователя, устройство,
поколение и соединение — вместе с исходным ID вида ws1-<lowercase UUID>.
Каждый повтор читает результат того же владельца до нового рендера или обращения к источникам.
Последующая правка определения не меняет опубликованные байты, а новое сопряжение не подменяет
закреплённые права. Если исходная отправка отсутствует или не подтверждена, чтение не отправляет
её снова и не выбирает другого владельца. Новый current_step нужен только для отдельной
явной попытки.
Записи архива содержат только пути относительно basePath; сама директория назначения в архив не
входит. Объявленные и отрендеренные пути должны быть нормализованными, непустыми, относительными и
уникальными. Moira отклоняет NUL, абсолютные и начинающиеся с обратной косой черты пути, пустые
сегменты, а также сегменты . и ...
У архивной доставки нет общих потолков числа файлов, размера одного файла или суммарных байтов. Действуют доступное хранилище владельца и текущие права. Отдельная доставка в контекст отклоняет текстовые наборы больше 256 KiB.
Файлы создаются с режимом 0644. Движок проверяет basePath, но не ограничивает назначение
директорией проекта. Авторы workflow должны получать его из доверенного пути рабочего пространства,
а агенты — проверять назначение в выданной команде перед запуском.
Восстановление на заблокированную materialize-ноду предъявляет доставку на той же ноде заново, не продвигая её. Доставка разрешает текущие значения реестра workflow по умолчанию; сохранённый контекст может содержать прежний справочник. Запишите и проверьте полученные файлы до продолжения. Само изменение переменной контекста не обновляет уже записанные файлы вызывающей стороны.
Разрешение и обработка ошибок
Пятиминутное разрешение хранится на сервере и привязано к текущим пользователю, выполнению и ноде. Выполнение должно оставаться в состоянии running и ожидать на той же materialize-ноде. Сервер заново проверяет эти привязки при каждом запросе, поэтому одно разрешение поддерживает повторные загрузки в течение абсолютного пятиминутного окна, но перестаёт работать сразу после перехода выполнения. Логи запросов скрывают credential из materialize-URL.
| Ошибка | Результат |
|---|---|
| Некорректная нода или директория назначения, ошибка конфигурации, БД или выдачи разрешения при показе шага | Переход по connections.error, если он задан; иначе ошибка выходит из выполнения |
| Некорректный, истёкший или неверно привязанный URL | HTTP 401 с Invalid or expired materialize token |
| Некорректный отрендеренный путь, отсутствующий источник в реестре, ошибка шаблона | HTTP 400 с Materialize archive could not be generated |
Локальная ошибка curl, pipe, файловой системы или tar | Недоступная сеть подпадает под fallback-доставку в контекст; ошибка файловой системы или tar остаётся блокером, о котором агент сообщает, не завершая шаг |
| Доставка в контекст набора больше 256 KiB | Инструмент отвечает именованным отказом и не доставляет файлы |
Недоступный контроллер возвращает HTTP 503 с COMMUNICATION_OWNER_UNAVAILABLE.
Отсутствующий, принятый или неопределённый исходный результат возвращает HTTP 409 с
COMMUNICATION_OUTCOME_UNCONFIRMED и request_id; повторите то же разрешение для чтения результата.
Завершённый отказ владельца возвращает HTTP 422 с безопасным кодом и исходным request_id.
Эти ответы не доказывают доставку файла. Права пользователя, ноды и контекста проверяются
после асинхронной подготовки текста и повторно перед передачей потока.
connections.error не перехватывает ошибку загрузки или распаковки: эти операции выполняются уже
после показа шага.
Доставка в контекст агента
У хоста, который в текущем ходе не может выполнить shell-команду или обратиться к сети, есть второй маршрут:
execution({ action: "materialize", executionId: "<process-id>" })Он напрямую разрешает текущий авторизованный текст workflow: по одному текстовому блоку на файл, с заголовком в виде пути, и ничего не пишет в файловую систему. Владелец файлов не требуется; архив не создаётся и не читается. Параметр разрешения не передаётся: сервер сам находит разрешение текущего показа ноды по выполнению вызывающего, поэтому URL архива не обязан проходить через ответ.
Этот маршрут расходует контекст, поэтому он именно fallback, а не основной путь, и предъявляемая директива прямо это говорит. Когда хост способен выполнить выданную команду, используйте её.
Разрешение здесь то же, что и у архивного канала: тот же пользователь, то же выполнение, всё ещё ожидающее на той же ноде, та же ревизия контекста, то же пятиминутное окно. Любой отказ отвечает одним и тем же сообщением, не называя несработавшее условие, поэтому отказ не раскрывает, принадлежит ли выполнение другому пользователю.
Поскольку тела попадают в контекстное окно, а не на диск, этот маршрут дополнительно отклоняет набор суммарно больше 256 KiB. Это бюджет ответа в контексте, а не квота архива. Он именно отклоняет, а не усекает: укороченный файл неотличим для читающего его агента от полного, а для набора такого размера остаётся выданная команда.
Доставка по-прежнему не доказывает чтение. Прочитайте каждый доставленный файл, который требуется
последующей директиве, и завершите шаг значением null или {} как обычно.
Применение в Workflow Management Flow
Workflow Management Flow один раз определяет рабочее пространство, затем материализует стабильные bootstrap-файлы и только после этого выбирает ветку создания или редактирования:
get-action-type -> materialize-workspace-bootstrap -> route-action-type | create -> gather-workflow-requirements | edit -> prepare-edit-workflowЕго объявление доставки файлов без метаданных прогресса:
{ "id": "materialize-workspace-bootstrap", "type": "materialize", "basePath": "{{workspace_path}}", "files": [ { "path": "process-id.txt", "from": "workspace_process_id_file" }, { "path": "reference/engine.md", "from": "workflow_reference_engine" }, { "path": "reference/design.md", "from": "workflow_reference_design" }, { "path": "reference/artifacts.md", "from": "workflow_reference_artifacts" }, { "path": "reference/review-repair.md", "from": "workflow_reference_review_repair" }, { "path": "reference/validation.md", "from": "workflow_reference_validation" }, { "path": "reference/authority.md", "from": "workflow_reference_authority" }, { "path": "reference/patterns.md", "from": "workflow_reference_patterns" }, { "path": "reference/antipatterns.md", "from": "workflow_reference_antipatterns" }, { "path": "reference/progress.md", "from": "workflow_reference_progress" }, { "path": "reference/conversation.md", "from": "workflow_reference_conversation" }, { "path": "reference/templates/checklist.json", "from": "workflow_template_checklist" }, { "path": "reference/templates/do-check-redo.json", "from": "workflow_template_do_check_redo" }, { "path": "reference/templates/approval-gate.json", "from": "workflow_template_approval_gate" } ], "connections": { "success": "route-action-type" }}Предыдущий владелец задаёт глобальный workspace_path. Значение workspace_process_id_file
по умолчанию — {{executionId}}; остальные defaults предоставляют тематические справочники автора,
руководство по разговору о требованиях и стартовые шаблоны workflow. Каждый потребитель обязан
прочитать применимые файлы: сбор требований для create использует правила полномочий и руководство
по разговору, а подготовка edit-источника — контракты движка и артефактов. Последующие владельцы
веток create и edit записывают динамические требования, provenance, планы и отчёты ревью,
не перезаписывая стабильные bootstrap-файлы.
Перевод ручного bootstrap
Чтобы заменить директиву агента, вручную записывающую стабильные файлы workflow:
- Перенесите каждое стабильное тело в
defaultотдельной строковой записиvariableRegistry. - Поручите существующей ранней ответственности вернуть доверенный глобальный путь для
basePath. - Вставьте одну ноду
materializeпосле этого владельца и перед первым потребителем файлов. - Удалите из последующих директив только инструкции записи соответствующих статических файлов. Динамические файлы оставьте ответственности, определяющей их содержимое.
- Провалидируйте workflow и проверьте выданную команду, записи архива, отрендеренные тела, а также успешный и ошибочный маршруты.