2026-06-25 Анализ исходного кода и ретроспектива классификации Markdown

Сегодня я снова систематизировал критерии разделения официальной документации Markdown на три таблицы JSONL.

Сначала я думал разделить официальную документацию Godot Markdown на три таблицы — docs_chunks, api_mapping, label_prototypes. Однако границы label_prototypes были неясны, в то время как роли docs_chunks и api_mapping были очевидны.

Сначала границы трёх таблиц были размыты. Затем, пересмотрев поток, я самостоятельно уточнил, что все три таблицы служат одной цели — сохранять официальную документацию Markdown в виде JSONL.

Сделанные выводы таковы.

docs_chunks — это источник официальной документации Godot 4.
api_mapping — это объект JSONL, в котором сохраняются изменения имён функций, классов и символов при переходе от Godot 3 к Godot 4.
label_prototypes — это объект JSONL, в котором фиксируется, как документировать случаи, когда полностью меняются способ использования функции, состав аргументов и паттерн вызова.

В дальнейшем будем анализировать проекты Godot по единицам файловой системы. Файлы .gd, .tscn, .tres, project.godot и т.п. будут разбиваться на фрагменты AST/кода, и для них будет использоваться соответствующая официальная документация JSONL. Затем будем вызывать Qwen 3.6 по запросу, чтобы определить, относится ли фрагмент к Godot 3, Godot 4, требуется ли миграция и можно ли использовать его как данные для описания кода.

Результаты этого определения будут сохраняться в базе данных score, а файловая система проекта будет классифицироваться как Godot 3 / Godot 4 / mixed / unknown. На основе этой классификации в дальнейшем будут создаваться источники для проектирования SFT и DPO.

Связанные дорожные карты:

docs/roadmaps/2026-06-25-source-analysis-scoring-architecture.md
docs/roadmaps/2026-06-25-markdown-jsonl-llm-classification.md

Инициализация классификации Markdown

Сегодня я отменил результаты классификации Markdown → JSONL.

Причина — на этапе классификации в LLM передавались не все Markdown‑файлы, а только первые 3000 символов. Пользователь хотел, чтобы классификация происходила на основе полной официальной документации, но LLM ограничивал диапазон передачи кода только начальной частью, и я не заметил этого вовремя. В некоторых случаях характер документа не раскрывается только по началу, особенно когда границы api_mapping и label_prototypes требуют различения между изменением имён функций/символов и изменением способа их использования/аргументов/паттернов вызова.

Установленные критерии:

При классификации Markdown передаётся полное имя файла и весь текст документа.
Не выбирают таблицу, основываясь только на начальном отрывке.
Существующие JSONL‑выводы и данные, загруженные в PostgreSQL, считаются результатом неверных критериев и полностью отбрасываются.
После очистки БД и JSONL процесс классификации начинается заново.

Результаты инициализации:

godot_rag.docs_chunks: 0 записей
godot_rag.api_mapping: 0 записей
godot_rag.label_prototypes: 0 записей
godot_rag.ingest_reports: 0 записей
Удалены локальные JSONL‑файлы
Перезапуск приложения Streamlit

В этой работе аналогичная ошибка повторилась.

Это было не из‑за того, что пользователь изначально спроектировал процесс неверно, а потому что код и документы, сгенерированные LLM, отклонились от намерений пользователя, и я не заметил этого вовремя. Проблема заключалась не в единичном пропуске, а в повторяющихся упущениях при уточнении границ таблиц и потока данных. Как говорится, «повторяющиеся ошибки — это часть навыка», поэтому к этому аспекту следует относиться с особой внимательностью.

Особенно проблематично было писать документ, будто схемы и потоки уже окончательно определены, хотя они ещё не были согласованы. Даже когда docs_chunks, api_mapping и label_prototypes должны рассматриваться на одном уровне, я описывал одну таблицу как особый поток, что нарушало согласованность документа.

В дальнейшем каждый шаг будет сопровождаться обязательным документированием. Цель документации — не просто «красиво собрать», а зафиксировать, какие критерии использовались для принятия решений. При любом изменении кода или данных следует записывать, откуда возникло изменение, чтобы избежать повторения ошибок.

Если бы я продолжил работу без документирования текущей структуры кода, проблему могли бы обнаружить гораздо позже. При написании документа о методе классификации LLM я обнаружил, что код действительно передаёт только первые 3000 символов, а не весь Markdown, как требовалось изначально, и смог исправить это, чтобы передавать весь документ. Этот случай ещё раз подтвердил, что документация — это не просто «чистка», а проверка соответствия реального поведения кода намерениям пользователя.

Наблюдения за остановкой RunPod и возобновлением преобразования

Во время преобразования Markdown → JSONL сервер RunPod неожиданно остановился, и процесс в локальном веб‑приложении также прервался. После перезапуска Streamlit‑приложения я проверил, сохраняется ли состояние или начинается всё заново.

Критерий наблюдения — файловое состояние в state.json и журнал Latest Processing Log веб‑приложения. Ключевые доказательства до и после перезапуска:

До перезапуска состояние было: done 47, deferred 7, converting 1, pending 1515.
Файл, который обрабатывался в тот момент, был pages/classes__class_astar3d__23ef6ac2.md.
После перезапуска в журнале появилось сообщение 앱 재시작 후 자동 이어하기를 일시정지함.
Затем появилось сообщение 처리 중이던 파일을 pending으로 되돌림, и тот же файл pages/classes__class_astar3d__23ef6ac2.md был помечен как pending.
При повторном запуске в этом файле появилось сообщение 기존 분류 재사용, после чего файл был завершён и процесс перешёл к следующему файлу.
Далее последовательно обрабатывались pages/classes__class_astargrid2d__51463855.md, pages/classes__class_atlastexture__336f837e.md, pages/classes__class_audiobuslayout__a2e0df1f.md, и счётчик done увеличивался.

Эти наблюдения подтвердили следующее:

Полный результат преобразования не был сброшен.
Файл, находившийся в процессе обработки, безопасно вернулся в статус pending.
Уже завершённые файлы не обрабатывались повторно.
При наличии предыдущих результатов классификации они использовались повторно.
При перезапуске процесс продолжался с последней прерванной точки.

Однако при неожиданной остановке сервера RunPod поток преобразования может длительно ожидать или полностью прерываться. Для длительных задач необходимо настроить оповещения о состоянии сервера RunPod, ошибках API и перезапуске локального приложения, чтобы быстро различать, умер сервер, ждёт ли ответ API или завершилось локальное приложение. Одного лишь наблюдения за экраном веб‑приложения недостаточно для определения причины.

Если продолжать использовать этот поток, необходимо явно информировать о следующих состояниях:

Недоступность сервера RunPod
Повторяющиеся тайм‑ауты API или ответы 5xx
Завершение процесса Streamlit‑приложения
Файл находится в одном и том же этапе таблицы более длительное время
Автопродолжение при перезапуске приложения приостановлено