| name | round-trip-yaml |
| description | Диагностирует полный metadata round-trip (XML -> модель -> YAML -> модель -> XML) и показывает single/triage diff'ы без создания reproducer. |
round-trip-yaml — диагностика полного round-trip
Перед диагностикой metadata round-trip обязательно прочитай:
.agents/knowledge/metadata/INDEX.md.agents/knowledge/metadata/sources-of-truth.md.agents/knowledge/metadata/round-trip-cycle.md.agents/knowledge/metadata/yaml-contract.md
Что делает скилл
Скилл запускает полный цикл:
XML -> модель -> YAML -> модель -> XML
На выходе он показывает XML diff'ы, появившиеся после nkdk import <xml-dir> <tmp-yaml-dir>, nkdk sync <tmp-yaml-dir> <tmp-xml-dir> --reference <xml-dir> и полной замены активного XML-каталога результатом временного XML-каталога.
У скилла два режима:
- Single — показывает один diff-файл. Без явного выбора берётся первый по алфавиту diff найденного каталога.
- Triage-пачка — показывает несколько diff-файлов для обзорного анализа.
Скилл только диагностирует. Он не создаёт ветки, slug, фикстуры, тесты, планы исправления, коммиты и PR.
Жёсткие инварианты
- Triage-пачка только информирует. В triage-режиме AI показывает список diff'ов, вероятные модули, вероятные файлы кода, категории, описания и фрагменты diff.
- Single тоже только информирует. Single-режим показывает один полный diff и краткий разбор, но не начинает reproducer workflow.
- Чистое рабочее дерево
nkdk-core. Если git status не чистый — стоп, попросить пользователя.
- Временный YAML-каталог очищается перед прогоном. Старые YAML-файлы и миграции не должны влиять на новый результат.
- Временный YAML-каталог остаётся после прогона. Он нужен для диагностики YAML-слоя.
- XML-репо после прогона остаётся с diff'ами. Не откатывай XML-репо после диагностики: diff является результатом анализа.
- Не писать новые правила fromXML/toXML/fromYAML/toYAML. Скилл ничего не исправляет.
- Не запускать полный
pnpm test. Это диагностический skill.
Запуск round-trip
Вызови ./.agents/skills/round-trip-yaml/round-trip.sh из корня nkdk-core.
Скрипт:
- читает
NKDK_XML_REPO (обязательная), NKDK_XML_DIR (опциональная) и NKDK_ROUND_TRIP_YAML_DIR (опциональная) из .env;
- проверяет, что рабочее дерево
nkdk-core чистое;
- проверяет, что
NKDK_XML_REPO является git-репозиторием;
- определяет каталоги запуска;
- перед каждым прогоном делает
git restore . в XML-репо;
- перед каждым прогоном удаляет временный YAML-каталог для активного XML-каталога;
- перед каждым прогоном очищает временный XML-каталог;
- запускает
nkdk import <xml-dir> <tmp-yaml-dir>;
- запускает
nkdk sync <tmp-yaml-dir> <tmp-xml-dir> --reference <xml-dir>;
- после успешного
sync копирует reference-only файлы, которые не являются частью YAML-договора, из активного XML-каталога во временный XML-каталог;
- полностью заменяет активный XML-каталог содержимым временного XML-каталога;
- собирает XML diff'ы через
git diff;
- если после каталога появился хотя бы один diff — останавливается на этом каталоге и дальше не смотрит, если не указан
--all-configs.
Если скрипт написал === Round-trip чистый: диффов нет === — стоп, нечего анализировать.
Если скрипт упал на guard'е dirty-tree — попроси пользователя сохранить/откатить правки. Не запускай git stash, git restore, git clean сам.
Каталог YAML
По умолчанию временный YAML-каталог создаётся в ${TMPDIR:-/tmp}/round-trip-yaml/<config>.
Если в .env задан NKDK_ROUND_TRIP_YAML_DIR, скрипт использует этот каталог как базу выгрузки YAML. Для одиночного запуска YAML пишется прямо в указанный каталог, например:
NKDK_ROUND_TRIP_YAML_DIR=/Users/nikita/git/erp_nkdk
При запуске нескольких конфигураций через --all-configs каждая конфигурация получает подпапку внутри NKDK_ROUND_TRIP_YAML_DIR, чтобы результаты не перетирали друг друга.
Временный XML-каталог
Для экспорта YAML обратно в XML скрипт использует временный XML-каталог ${TMPDIR:-/tmp}/round-trip-yaml-xml/<config>.
Перед sync каталог очищается. Активный XML-каталог передаётся в sync только как --reference: старые XML-файлы не копируются во временный XML-каталог. Результат после успешного sync полностью заменяет активный XML-каталог, поэтому любые файлы, которые не были восстановлены из YAML, становятся удалениями в git diff. Сам временный XML-каталог не считается диагностическим результатом; анализировать нужно diff в XML-репо и сохраненный YAML-каталог.
Исключение: reference-only файлы, которые намеренно не входят в YAML-договор, копируются из активного XML-каталога во временный XML-каталог после sync и до замены активного каталога. Сейчас это Ext/ParentConfigurations.bin и Ext/ParentConfigurations/*.cf.
Single-режим
Команды:
./.agents/skills/round-trip-yaml/round-trip.sh
./.agents/skills/round-trip-yaml/round-trip.sh --diff-index 3
После запуска сформируй краткий разбор:
XML-файл: <абсолютный локальный путь из SELECTED_XML_FILE_ABS>
XML-каталог: <значение ACTIVE_XML_DIR>
YAML-каталог: <значение YAML_DIR>
Diff: <SELECTED_DIFF_FILE>
Вероятный модуль: packages/core/metadata/<...> или неизвестно
Вероятный код: packages/core/metadata/<...>/rules.ts или неизвестно
Категория: потеря пустого тега / порядок XML-узлов / лишний default / потеря атрибута / потеря xsi:type / потеря id или ссылки / YAML-default / YAML-исключение / неизвестно
Описание: <что изменилось при полном round-trip>
Diff:
<релевантный фрагмент или полный diff, если он короткий>
Сомнения: <почему модуль или причина неочевидны, если есть сомнения>
Triage-пачка
Используй этот режим, когда пользователь просит показать несколько ошибок для анализа: «покажи следующие 5 ошибок», «дай пачку с 6-й», «покажи 10 diff'ов».
Команды:
./.agents/skills/round-trip-yaml/round-trip.sh --triage --batch-size 5
./.agents/skills/round-trip-yaml/round-trip.sh --triage --batch-size 5 --start-index 6
./.agents/skills/round-trip-yaml/round-trip.sh --triage --all-configs --batch-size 20
После запуска сформируй краткий список. Каждый пункт должен содержать:
1. <относительный XML-путь из diff>
XML-файл: <абсолютный локальный путь из XML_FILE_ABS>
XML-каталог: <значение ACTIVE_XML_DIR>
YAML-каталог: <значение YAML_DIR>
Вероятный модуль: packages/core/metadata/<...> или неизвестно
Вероятный код: packages/core/metadata/<...>/rules.ts или неизвестно
Категория: потеря пустого тега / порядок XML-узлов / лишний default / потеря атрибута / потеря xsi:type / потеря id или ссылки / YAML-default / YAML-исключение / неизвестно
Описание: <что изменилось при полном round-trip>
Diff:
<короткий релевантный фрагмент>
Сомнения: <почему модуль или причина неочевидны, если есть сомнения>
Правила triage-ответа:
XML-файл всегда бери из XML_FILE_ABS. Если путь абсолютный и файл существует локально, оформи его кликабельной ссылкой.YAML-каталог всегда бери из YAML_DIR.- Для определения вероятного модуля и кода можно читать
packages/core/metadata/**/rules.ts, types.ts, fromYAML.test.ts, toYAML.test.ts, fromXML.test.ts, toXML.test.ts.
- Показывай diff-фрагмент как источник истины.
- Если несколько пунктов похожи на одну категорию, отметь связь, но не объединяй пункты.
- Не создавай ветку, slug, фикстуры, тесты и план исправления. После списка остановись и жди, какую проблему пользователь захочет разобрать отдельно.
Тупиковые ситуации
Остановись и спроси пользователя, если:
nkdk import падает;nkdk sync падает;- один diff содержит несколько независимых причин и краткая классификация будет вводить в заблуждение;
- невозможно понять, расхождение появилось из-за XML-слоя или YAML-слоя.
Политика коммитов
Скилл не коммитит, не пушит, не создаёт PR, не запускает тесты и не исправляет код.
