2026-06-21 Ретроспектива

Повторный вопрос о процессе преобразования официальной документации Godot в JSONL

Я вставил схему из 2026-06-21-initial-rag-classifier-architecture.md в Qwen и спросил о направлении кода на Python для преобразования Markdown‑документа в JSONL.

Суть первого вопроса заключалась в простом скрипте преобразования.

Нужен код на Python, который преобразует вводимый Markdown в JSONL
Было бы хорошо, если бы также предоставлялась команда для выполнения
Хочу генерировать содержимое JSONL, вызывая API Qwen
Необходимо добавить проверку, чтобы схема не нарушалась при сохранении в JSONL
Хочу проверять формат JSONL с помощью регулярных выражений или валидации схемы
Было бы полезно, если модель определяла, в какую таблицу следует выполнить сопоставление при вызове API
При необходимости нужно создать полные схемы docs_chunks, api_mapping, label_prototypes

Расширение мысли от CLI‑скрипта к веб‑инструменту

После того как стало ясно, что простого CLI‑конвертера недостаточно для визуализации процесса, было решено также рассмотреть структуру, вызываемую через веб.

Было бы удобно, если на веб‑странице можно ввести API‑ключ
Было бы полезно поддерживать загрузку Markdown‑файлов или загрузку папок
Было бы здорово, если можно будет визуально сравнить diff или изменения до и после конвертации прямо в вебе
Вместо простого создания только итогового файла, процесс конвертации и результаты должны быть проверяемы человеком

Размышляя над этим вопросом, я понял, что конвертер JSONL должен быть не просто пакетным скриптом, а инструментом обработки данных, который человек может проверять и одобрять.

Повторно проверена проблема, что один файл может попасть в несколько таблиц

Самый важный дополнительный вопрос заключался в том, что один Markdown‑файл может не соответствовать только одной таблице.

Например, один документ миграции может одновременно создавать три типа JSONL:

Официальные описательные фрагменты — docs_chunks.jsonl
Правила изменения API — api_mapping.jsonl
Примеры преобразования/классификации — label_prototypes.jsonl

Поэтому конвертер не должен принимать один файл и создавать только один JSONL, а сначала вызывать Qwen, чтобы определить, какие записи таблиц нужны, и если получено несколько ответов, он должен уметь генерировать более одного JSONL‑записи из одного файла.

Новое направление проектирования, определённое сегодня

Преобразование Markdown в JSONL делится на этапы классификация → генерация → проверка → сохранение.
Qwen может выполнять роль чтения текста и определения необходимых целевых таблиц.
Однако ответы Qwen не следует принимать без проверки; окончательное решение о сохранении должно принимать локальный валидатор схемы.
Регулярные выражения используют только для минимальной проверки формата, а реальную проверку полей лучше выполнять с помощью JSON Schema или структурных валидаторов вроде Pydantic.
Предполагается, что из одного Markdown‑файла может получаться несколько JSONL‑результатов.
Веб‑интерфейс будет не просто удобной функцией, а уровнем контроля, где человек проверяет и утверждает автоматически сгенерированные записи.

Памятка о предстоящих задачах

Составить черновики JSON Schema для docs_chunks, api_mapping и label_prototypes.
Спроектировать подсказку, которая будет заставлять Qwen определять кандидаты целевых таблиц, получая на вход один Markdown‑файл.
Разработать правила разделения и сохранения файлов, когда ответ Qwen содержит записи для нескольких таблиц.
Сначала создать скрипт проверки JSONL построчно для использования в CLI.
Затем расширить веб‑интерфейс, чтобы он поддерживал загрузку, преобразование, diff, результаты проверки и процесс утверждения/отклонения.

Оставшиеся вопросы

Поручить Qwen определять сопоставление таблиц, но в каких случаях человек обязан одобрить?
Нужно ли сразу после автоматического создания кандидата api_mapping помещать его в базу данных или сохранять только в состоянии candidate?
В веб‑интерфейсе отображать diff относительно оригинального Markdown в виде JSONL diff или относительно предыдущей версии JSONL?
Как повторно попытаться загрузить файлы при загрузке папки, если некоторые файлы завершились неудачей, а некоторые — частично успешно?