Observación de la selección del repositorio de pruebas basado en el estado de recolección de JSONL

Fecha de redacción: 27 de junio de 2026

Propósito

Con base en los JSONL generados hasta ahora, determinar cuál tipo de repositorio de Godot es mejor clonar primero para las pruebas.

Aquí el objetivo no es “elegir cualquier repositorio famoso”. Primero se debe observar en qué áreas los datos acumulados en la base son fuertes y en cuáles aún son débiles, y luego escoger el tipo de repositorio que permita al Retriever encontrar evidencia de manera efectiva.

Los criterios de análisis son los siguientes dos archivos.

/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 contiene el estado de la conversión, el prompt de clasificación y la depuración de la respuesta original, pero como también pueden mezclarse valores de configuración en tiempo de ejecución, no se traslada el texto original a la documentación pública. En este registro de observación solo se dejan las estadísticas JSONL y el juicio.

Estado de la instantánea

La conversión basada en el momento de la observación aún está en curso.

docs_chunks.jsonl: 153 records  
api_mapping.jsonl: 117 records  
label_prototypes.jsonl: Aún no se ha creado el archivo

El estado de la conversión web era aproximadamente el siguiente flujo.

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

Por lo tanto, este documento no es una conclusión final, sino el “criterio de selección del primer reporte basado en JSONL recopilado hasta ahora”.

Observación de docs_chunks

docs_chunks tenía 153 registros creados.

La composición se asemeja a lo siguiente.

class_reference: 127
about: 26

Se crearon fragmentos a partir de 95 archivos Markdown originales, y 129 registros contenían símbolos de API. Los registros que tenían bloques de código fueron 36.

Hasta ahora, las áreas que se destacan claramente en docs_chunks son las siguientes.

Animación (familia)  
Audio (familia)  
Cámara (familia)  
Canvas/CanvasItem (familia)  
API básicos como Array/Callable/GlobalScope  
Parte de AnimatedSprite2D  
Parte de AStar/AStarGrid2D

Por el contrario, las áreas que aún parecen débiles son las siguientes.

Migración de KinematicBody / CharacterBody  
Método de llamada de move_and_slide  
Conversión de yield -> await  
Conversión de Color8 -> Color.from_rgba8  
Migración de TileMap  
Migración de RigidBody / cuerpo físico  
HTTPRequest / redes

En este momento, docs_chunks puede servir en cierta medida como “justificación basada en la documentación oficial de Godot 4”, pero aún no se puede decir que se haya acumulado suficiente evidencia típica para la migración de un juego de acción 2D de Godot 3 a Godot 4.

Observación del mapeo de API

api_mapping tenía 117 registros creados.

Los tipos de cambio se dividen de la siguiente manera.

rename_or_replacement: 82
behavior_change: 24
deprecated: 11

La confianza de todos los registros estaba en verified_from_docs.

Hasta ahora, el área de mapeo que se ve claramente es la siguiente.

Diferencias entre los métodos de Array y su comportamiento  
Serie de AnimationPlayer / AnimationMixer / AnimationTree / AnimationNode

AudioStream / AudioEffect / AudioEffectSpectrumAnalyzer familia  
Camera / Camera3D / CameraAttributes familia  
CanvasItem draw/modulate familia

Algunas funciones y constantes obsoletas de GlobalScope  
Algunas de AStarGrid2D

Por ejemplo, el JSONL actual contiene evidencia del siguiente tipo.

Camera -> Camera3D  
Camera.get_transform -> Camera3D.get_camera_transform  
Configuración de exposición de WorldEnvironment -> serie de CameraAttributes  
Algunas funciones de AnimationPlayer -> separación de AnimationMixer  
AnimationNode._process -> AnimationNodeExtension._process_animation_node  
AudioEffectLimiter -> AudioEffectHardLimiter  
Cambio en el comportamiento de Array.sort  
Diferencia en el nombre C# de Array.has  
Cambio en el comportamiento de CanvasItem.modulate  
Cambio en el comportamiento de CanvasItem.draw_string / draw_rect

Esto significa que si se realiza una prueba de migración ahora mismo, es más probable que el código relacionado con Camera, Animation, Audio, CanvasItem o Array falle antes que el de KinematicBody2D o move_and_slide de un juego de plataformas 2D.

Observación de label_prototypes

En la instantánea actual no existe el archivo label_prototypes.jsonl.

Por lo tanto, en esta etapa no hay suficiente evidencia para probar con Retriever el “ejemplo en el que cambia todo el modo de usar una función”. Claro que api_mapping contiene behavior_change, pero eso se asemeja más a una evidencia extraída de la documentación de un cambio de API que a un “ejemplo completo de patrón de uso”.

Así que, al elegir un repositorio ahora, es mejor optar por uno que verifique primero las áreas que ya están cubiertas por docs_chunks y api_mapping, en lugar de uno que intente probar activamente label_prototypes.

Tipo de repositorio ideal para clonar de inmediato

Según el criterio JSONL, el repositorio más adecuado para clonar primero es “pequeño, con una versión de Godot claramente indicada y que use en código real las APIs que ya aparecen en el mapping acumulado”.

El orden de prioridad es el siguiente:

1ª prioridad: ejemplo pequeño basado en Godot 3 que incluya Camera/WorldEnvironment/Animation

El mejor candidato para la primera prueba es un pequeño repositorio de proyecto Godot 3 que utilice realmente funciones como Camera, WorldEnvironment, AnimationPlayer, AnimationTree, dibujo de CanvasItem y AudioEffect.

La razón es que ya existen evidencias correspondientes en api_mapping.

Camera -> Camera3D  
Camera.get_transform -> Camera3D.get_camera_transform  
WorldEnvironment exposure configuración -> CameraAttributes  
AnimationPlayer -> AnimationMixer cambios relacionados  
Cambios en la familia AnimationNode / AnimationTree  
CanvasItem draw/modulate cambios de comportamiento  
Cambios en la familia AudioEffect / AudioStream

Si clonas este repositorio, aparecerán pistas como Camera, WorldEnvironment, AnimationPlayer, CanvasItem, AudioEffect en fragmentos del AST, y es probable que el Retriever encuentre evidencia en el JSONL actual.

El propósito de la prueba también está claro.

Fragmento de código de Godot 3  
-> fragmento AST  
-> búsqueda de api_mapping  
-> búsqueda auxiliar de docs_chunks  
-> vista previa del prompt de juicio LLM

En otras palabras, “puedes verificar inmediatamente con los datos actuales si este código usa la API de Godot 3 y con qué fundamento debería cambiarse en Godot 4”.

Prioridad 2: Pequeño ejemplo de Animación/Audio/Cámara basado en Godot 4

El segundo candidato es un pequeño repositorio de ejemplos escrito para Godot 4.

Este repositorio es útil más para confirmar que “la explicación del código normal de Godot 4” sea correcta y que “Retriever no traiga una migración equivocada de Godot 3”, que para validar la migración.

Actualmente docs_chunks contiene bastantes explicaciones oficiales sobre Animación, Audio, Cámara, CanvasItem y Array. Por eso, al insertar fragmentos de código de Godot 4, es fácil ver si la justificación de la explicación se basa en docs_chunks.

Sería ideal que este repositorio tuviera las siguientes características.

Proyecto pequeño completo que contiene **project.godot**  
Alrededor de 5 a 30 archivos **.gd**  
Archivos **.tscn** incluidos  
Uso de **AnimationPlayer** o **AnimationTree**  
Uso de **AudioStreamPlayer** o **AudioEffect**  
Uso de **Camera2D/Camera3D**  
Uso de API básicas como **Array**/ **Callable**  
No hay muchos recursos de gran tamaño.

3ª prioridad: Ejemplos del mismo tema divididos en versiones Godot 3 y Godot 4

Si es posible, los ejemplos que ofrecen el mismo tema tanto para Godot 3 como para Godot 4 son los mejores.

Por ejemplo, si el mismo ejemplo de cámara/animación/audio está disponible en una rama de Godot 3 y en otra rama de Godot 4, resulta más fácil comparar la evaluación de Retriever y LLM.

Este tipo de repositorios son útiles para verificar lo siguiente.

¿Se está aplicando correctamente api_mapping en el fragmento de Godot 3?  
¿Se está justificando adecuadamente la explicación de docs_chunks en el fragmento de Godot 4?  
Cómo mostrar las diferencias de código por versión de la misma funcionalidad en un prompt de LLM.  
Cómo acumular la determinación de godot3/godot4/mixed por proyecto.

Clone ahora mismo: naturaleza del repositorio ambigua

Actualmente, si solo consideramos JSONL, los repositorios con la siguiente naturaleza aún son ambiguos para la primera prueba.

Plataforma 2D típica de Godot 3

Un juego de plataformas 2D de Godot 3 con muchas pistas como KinematicBody2D, move_and_slide, yield, TileMap, Color8 será necesario más adelante.

Sin embargo, en la instantánea actual esas pistas casi no aparecen en JSONL. Si se incluye ahora un repositorio de este tipo, el Retriever podría no encontrar evidencia o podría traer evidencia de Animation/Audio/Camera que no está relacionada.

Por lo tanto, este tipo de repositorio es un “buen candidato para la prueba final”, pero no es el “primer candidato ideal para validar directamente con JSONL”.

Repositorio de juego grande completo

Un repositorio de juego grande con muchos assets y cientos de archivos .gd aún es prematuro.

Lo que se necesita ahora no es lanzar al modelo un proyecto grande, sino rastrear hasta el final qué fragmento de código busca qué evidencia en JSONL. Un repositorio grande tiene un ámbito de depuración demasiado amplio, lo que dificulta ver por qué evidencia se buscó.

La primera prueba debe ser con un ejemplo pequeño y con una funcionalidad clara.

Repositorio centrado en C#

En JSONL actual hay menciones a C# y algunas diferencias en nombres de C#, pero el flujo general está diseñado en torno a fragmentos de GDScript AST y .gd.

Por lo tanto, un repositorio de Godot centrado en C# no es adecuado como primer objetivo de prueba en esta etapa.

Repositorio centrado en GDExtension / Plugin nativo

Los repositorios centrados en GDExtension, C++, enlaces Rust o plugins nativos también son prematuros.

El objetivo actual es dividir los proyectos de Godot (.gd, .tscn, project.godot) en fragmentos y observar cómo el Retriever busca evidencia en la documentación oficial. Los repositorios centrados en extensiones nativas cambian el eje de análisis.

Criterios de selección de repositorios

Con los criterios actuales, los candidatos a clonar deberían cumplir las siguientes condiciones.

Debe poder verificarse la versión de Godot en el README o en project.godot  
Debe existir el archivo project.godot  
Debe existir el archivo .gd  
Sería bueno que hubiera también el archivo .tscn  
Debe haber pocos recursos de gran tamaño  
El alcance de la funcionalidad debe ser pequeño y claro  
Debe haber código que se superponga con la API presente en el JSONL actual

Las palabras clave que actualmente coinciden bien con JSONL son las siguientes.

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

Por el contrario, las palabras clave que aún son demasiado tempranas para considerarlas como criterios principales en la primera prueba son las siguientes.

KinematicBody2D
CharacterBody2D
move_and_slide
yield
await
Color8
TileMap
RigidBody2D
HTTPRequest
multiplayer
GDExtension

Juicio

Según los JSONL recopilados hasta ahora, el primer objetivo de clonación debería ser el “pequeño repositorio candidato para migración a Godot 3”. Sin embargo, no se trata de un platformer 2D típico, sino de un proyecto que realmente utilice las familias Camera/WorldEnvironment/Animation/Audio/CanvasItem.

La razón es simple.

Actualmente api_mapping ya cuenta con referencias a Camera, Animation, Audio, CanvasItem y Array. En cambio, los indicadores principales de la migración de física 2D de Godot 3, como KinematicBody2D, move_and_slide, yield y TileMap, casi no aparecen en el JSONL actual.

Por lo tanto, la primera prueba más realista sigue el siguiente flujo.

Pequeña clon de ejemplo de Godot 3 Camera/Animation/Audio  
-> Fragmentación de .gd y .tscn  
-> Búsqueda de Retriever con JSONL actual  
-> Verificar si el hit de api_mapping está relacionado con el código real  
-> Revisar la vista previa del prompt que entrará en el LLM

El siguiente paso es clonar un pequeño ejemplo de Animation/Audio/Camera escrito en Godot 4 y verificar el flujo de generación de documentación basado en docs_chunks.

Finalmente, cuando se haya creado label_prototypes y se hayan acumulado referencias a KinematicBody2D, move_and_slide, yield, Color8 y la familia TileMap, será el momento adecuado para clonar un repositorio típico de un platformer 2D o action game de Godot 3 y probar la decisión de migración.

Conclusión

El tipo de repositorio que se clonará de inmediato se define a continuación.

**Primer candidato:**
  - Ejemplo pequeño y con versión clara de Godot 3
  - Uso real de algunos de Camera / WorldEnvironment / AnimationPlayer / AnimationTree / Audio / CanvasItem
  - Incluye .gd, .tscn, project.godot
  - Los assets no son excesivamente grandes

**Segundo candidato:**
  - Ejemplo de Godot 4 que usa la misma área
  - Se usa para validar la calidad de búsqueda de explicación de código y docs_chunks más que la migración

**En espera:**
  - Plataforma 2D de Godot 3 centrada en KinematicBody2D / move_and_slide / yield / TileMap
  - Prueba después de acumular más evidencia de migración relacionada con label_prototypes

Esta secuencia parece ser la forma más eficiente de validar el JSONL recopilado actualmente.