Выбор тестового репозитория на основе текущего состояния сбора JSONL

Дата написания: 27 июня 2026 г.

Цель

Исходя из уже созданных JSONL, определить, какой тип репозитория Godot следует сначала клонировать для тестирования.

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

Критерии анализа представлены в следующих двух файлах.

/Users/joyeongjin/make_md/work/web_jsonl/docs_chunks/docs_chunks.jsonl
/Users/joyeongjin/make_md/work/web_jsonl/api_mapping/api_mapping.jsonl

state.json содержит состояние преобразования, запрос классификации и отладку оригинального ответа, но поскольку в нём могут смешиваться также значения настроек выполнения, оригинальный текст не переносится в публичную документацию. В этом журнале наблюдений оставлены только статистика JSONL и выводы.

Состояние снимка

На момент наблюдения преобразование всё ещё продолжается.

docs_chunks.jsonl: 153 records  
api_mapping.jsonl: 117 records  
label_prototypes.jsonl: Файл еще не создан

Состояние веб‑преобразования было примерно следующим.

done: 132 files
pending: 1425 files
deferred: 11 files
converting: 2 files
classified: 144 files

Таким образом, этот документ не является окончательным выводом, а представляет собой «первичные критерии выбора репозитория на основе собранных до настоящего момента JSONL».

Наблюдение docs_chunks

docs_chunks было создано 153 записи.

Структура близка к следующей.

class_reference: 127
about: 26

Из 95 исходных файлов Markdown были созданы фрагменты, и в 129 записях содержался API‑символ. Записей с блоком кода было 36.

На данный момент в docs_chunks явно видны следующие области:

Animation категория  
Audio категория  
Camera категория  
Canvas/CanvasItem категория  
Базовые API, такие как Array/Callable/GlobalScope  
Некоторые AnimatedSprite2D  
Некоторые AStar/AStarGrid2D

С другой стороны, области, которые пока слабо видны, следующие.

KinematicBody / CharacterBody миграция  
move_and_slide вызов метода  
yield → await переход  
Color8 → Color.from_rgba8 переход  
TileMap миграция  
RigidBody / physics body миграция  
HTTPRequest / сетевое взаимодействие

То есть на текущий момент docs_chunks можно использовать в качестве некоторого обоснования из официальной документации Godot 4, но пока трудно считать, что накопилось достаточное количество доказательств типичной миграции 2D‑экшн‑игры с Godot 3 на Godot 4.

Наблюдение за api_mapping

api_mapping было создано 117 записей.

Типы изменений делятся следующим образом.

rename_or_replacement: 82
behavior_change: 24
deprecated: 11

Все confidence записей находились в verified_from_docs.

На данный момент явно видимая область сопоставления следующая.

Различия методов Array и их поведения
Серия AnimationPlayer / AnimationMixer / AnimationTree / AnimationNode
Серия AudioStream / AudioEffect / AudioEffectSpectrumAnalyzer
Серия Camera / Camera3D / CameraAttributes
Серия CanvasItem draw/modulate
Некоторые функции GlobalScope и устаревшие константы
Некоторые AStarGrid2D

Например, в текущем JSONL содержатся доказательства следующего характера.

Camera -> Camera3D
Camera.get_transform -> Camera3D.get_camera_transform
WorldEnvironment exposure настройка -> CameraAttributes семейство
AnimationPlayer некоторые функции -> AnimationMixer разделение
AnimationNode._process -> AnimationNodeExtension._process_animation_node
AudioEffectLimiter -> AudioEffectHardLimiter
Array.sort изменение поведения
Array.has различие названий в C#
CanvasItem.modulate изменение поведения
CanvasItem.draw_string / draw_rect изменение поведения

Это означает, что если сейчас сразу провести тест миграции, то код, связанный с Camera, Animation, Audio, CanvasItem, Array, скорее всего, будет проблемнее, чем KinematicBody2D или move_and_slide в 2D platformer.

Наблюдение за label_prototypes

В текущем снимке нет файла label_prototypes.jsonl.

Поэтому на данном этапе недостаточно оснований, чтобы протестировать «пример полного изменения способа использования функций» с помощью Retriever. Конечно, в api_mapping есть behavior_change, но это пока больше похоже на обоснование изменения API, извлечённое из документации, чем на «полный пример использования».

Поэтому при выборе репозитория сейчас лучше отдать предпочтение репозиторию, который проверяет области, уже покрытые docs_chunks и api_mapping, а не репозиторию, активно тестирующему label_prototypes.

Какой репозиторий удобно клонировать прямо сейчас

С учётом критериев JSONL, лучший репозиторий для первого клонирования — это «маленький, с явно указанной версией Godot и использующий API, уже присутствующие в текущем mapping, в реальном коде».

Приоритеты следующие.

1‑й приоритет: небольшой пример на Godot 3 с Camera/WorldEnvironment/Animation

Лучший кандидат для первого теста — небольшой репозиторий‑пример проекта Godot 3, в котором реально используются функции Camera, WorldEnvironment, AnimationPlayer, AnimationTree, отрисовка CanvasItem, AudioEffect и т.п.

Это потому, что в api_mapping уже есть соответствующие доказательства.

Camera -> Camera3D
Camera.get_transform -> Camera3D.get_camera_transform
WorldEnvironment exposure настройка -> CameraAttributes
AnimationPlayer -> AnimationMixer связанные изменения
AnimationNode / AnimationTree изменения в семействе
CanvasItem draw/modulate изменения поведения
AudioEffect / AudioStream изменения в семействе

Если клонировать такой репозиторий, в фрагментах AST появятся такие подсказки, как Camera, WorldEnvironment, AnimationPlayer, CanvasItem, AudioEffect, и вероятность того, что Retriever найдет доказательства в текущем JSONL, высока.

Цель теста также ясна.

Фрагмент кода Godot 3
-> AST фрагмент
-> api_mapping поиск
-> docs_chunks вспомогательный поиск
*No content provided for translation.*

То есть можно сразу проверить по текущим данным, использует ли этот код API Godot 3 и на каком основании его следует изменить для Godot 4.

2‑й приоритет: небольшой пример Animation/Audio/Camera на основе Godot 4

Второй кандидат — небольшой репозиторий примеров, написанный на Godot 4.

Этот репозиторий больше подходит для проверки «нормального описания кода Godot 4» и того, «не приводит ли Retriever к неожиданной миграции Godot 3», чем для проверки миграции.

Текущее docs_chunks содержит довольно много официальных описаний по Animation, Audio, Camera, CanvasItem, Array. Поэтому удобно проверять, будет ли объяснение опираться на docs_chunks, когда вставляешь фрагменты кода Godot 4.

Этот репозиторий был бы полезен, если бы имел следующую направленность.

полный небольшой проект с файлом project.godot  
примерно 5–30 файлов .gd  
вместе с файлами .tscn  
используется AnimationPlayer или AnimationTree  
используется AudioStreamPlayer или AudioEffect  
используется Camera2D/Camera3D  
используются базовые API, такие как Array/Callable  
нет большого количества массивных ассетов

3‑й приоритет: Примеры одной темы, разделённые версии Godot 3 и Godot 4

Если возможно, лучший вариант — предоставить примеры одной и той же темы, реализованные отдельно для Godot 3 и Godot 4.

Например, если один и тот же пример с камерой/анимацией/аудио имеет отдельные ветки для Godot 3 и Godot 4, сравнивать вывод Retriever и оценку LLM будет проще.

Эти репозитории удобно проверять по следующему.

Проверить, правильно ли работает api_mapping в фрагменте Godot 3.  
Проверить, правильно ли приводятся обоснования описания docs_chunks в фрагменте Godot 4.  
Как показать различия кода одной функции между версиями в запросе к LLM.  
Как накапливать определение проекта как godot3/godot4/mixed.

Сейчас же клонировать сомнительный репозиторий

Если смотреть только на JSONL, репозитории такого характера пока не подходят для первого теста.

Типичный Godot 3 2D платформер

KinematicBody2D, move_and_slide, yield, TileMap, Color8 — множество подсказок, характерных для Godot 3 2D платформера, позже обязательно понадобятся.

Но в текущем снепшоте этих подсказок почти нет в JSONL. Если сразу добавить такой репозиторий, Retriever может не найти доказательства или принести нерелевантные доказательства по Animation/Audio/Camera.

Поэтому такой репозиторий — «хороший кандидат для финального теста», но «не лучший первый кандидат для проверки сразу в JSONL».

Большой репозиторий всей игры

Репозиторий большой игры с множеством ассетов и сотнями файлов .gd пока рано использовать.

Сейчас нужно не бросать модель в большой проект, а отслеживать, какие фрагменты кода ищут какие доказательства в JSONL до конца. Большой репозиторий слишком широк для отладки, и трудно увидеть, почему найдено то или иное доказательство.

Первый тест лучше провести на небольшом и явно функциональном примере.

Репозиторий, ориентированный на C#

В текущем JSONL упоминаются C# и есть некоторые различия в названиях C#, но общий поток построен вокруг AST GDScript и фрагментов .gd.

Поэтому репозиторий Godot, ориентированный на C#, не подходит как первый тестовый объект на данном этапе.

Репозиторий, ориентированный на GDExtension / Native plugin

Репозитории, сосредоточенные на GDExtension, C++, Rust‑биндингах, native‑плагинах, тоже пока рано.

Текущая цель — разбить файлы проекта Godot (.gd, .tscn, project.godot) на фрагменты и посмотреть, как Retriever ищет доказательства в официальной документации. Репозитории, сосредоточенные на native‑extensions, меняют направление анализа.

Критерии отбора репозитория

На текущий момент кандидат на клон должен удовлетворять следующим условиям.

Версия Godot должна быть проверяема в README или project.godot  
Файл project.godot должен присутствовать  
Файл .gd должен присутствовать  
Файл .tscn желательно иметь вместе  
Большие ассеты должны быть минимальны  
Объём функций должен быть небольшим и чётким  
Код должен пересекаться с API, находящимся в текущем JSONL

Следующие ключевые слова хорошо подходят к текущему JSONL.

Camera
Camera3D
WorldEnvironment
CameraAttributes
AnimationPlayer
AnimationTree
AnimationNode
AnimationMixer
AudioStream
AudioEffect
CanvasItem
draw_string
draw_rect
modulate
Array.sort
Array.has
AnimatedSprite2D
AStar2D
AStarGrid2D

С другой стороны, в текущем первом тесте ключевые слова, которые ещё слишком рано использовать в качестве основного критерия, следующие.

KinematicBody2D
CharacterBody2D
move_and_slide
yield
await
Color8
TileMap
RigidBody2D
HTTPRequest
multiplayer
GDExtension

Оценка

Исходя из собранных до сих пор JSONL, первым объектом клонирования будет «маленький репозиторий‑кандидат для миграции на Godot 3». Однако более подходящим будет проект, в котором действительно используются компоненты Camera/WorldEnvironment/Animation/Audio/CanvasItem, а не обычный 2D‑платформер.

Причина проста.

Сейчас api_mapping уже содержит данные по Camera, Animation, Audio, CanvasItem, Array. В то время как ключевые элементы миграции 2D‑физики Godot 3, такие как KinematicBody2D, move_and_slide, yield, TileMap, почти отсутствуют в текущем JSONL.

Поэтому наиболее реалистичным первым тестом будет следующий порядок действий.

Небольшой клон примера Godot 3 Camera/Animation/Audio  
-> Фрагментация .gd и .tscn  
-> Поиск Retriever с помощью текущего JSONL  
-> Проверить, связан ли hit api_mapping с реальным кодом  
-> Проверить предварительный просмотр подсказки для LLM

Затем рекомендуется клонировать небольшой пример Animation/Audio/Camera, написанный на Godot 4, и проверить процесс создания описаний на основе docs_chunks.

В конечном итоге, когда будет создан label_prototypes и накопятся основания из KinematicBody2D, move_and_slide, yield, Color8, TileMap, тогда будет более уместно протестировать решение о миграции, клонировав типичный репозиторий Godot 3 2D platformer или action game.

Заключение

Сейчас же определяем характер репозитория для клонирования следующим образом.

Первый вариант:
  Маленький пример Godot 3 с чёткой версией
  Фактически используется часть Camera / WorldEnvironment / AnimationPlayer / AnimationTree / Audio / CanvasItem
  Включает .gd, .tscn, project.godot
  Активы не слишком большие

Второй вариант:
  Пример Godot 4, использующий ту же область
  Используется для проверки качества поиска docs_chunks и объяснения кода, а не миграции

Отложено:
  2D платформер Godot 3, основанный на KinematicBody2D / move_and_slide / yield / TileMap
  Тестировать после накопления дополнительных доказательств миграции, связанных с label_prototypes

Этот порядок кажется наименее расточительным способом проверки текущего собранного JSONL.