idea_world_labDEV JOURNAL
jueves, 25 de junio de 2026

Arquitectura de Puntuación del Análisis de Código Fuente de Godot

Fecha de creación: 25 de junio de 2026

Propósito

Utilizar RAG de la documentación oficial de Godot para clasificar el código fuente de GitHub por proyecto y organizar el flujo que conduce a la generación de datos SFT/DPO.

El núcleo de esta organización es tratar a docs_chunks, api_mapping y label_prototypes como el mismo objetivo de clasificación de Markdown de la documentación oficial → JSONL. Según la naturaleza del documento, los fragmentos explicativos van a docs_chunks, los cambios de nombres de funciones/clases/símbolos a api_mapping, y los cambios en el modo de uso de funciones, composición de argumentos y patrones de llamada a label_prototypes.

Conclusión actual

En la fase inicial de recopilación de la documentación oficial, las tablas clave que se deben preparar son las siguientes tres.

Tabla Función
docs_chunks Destino de almacenamiento de fragmentos de texto explicativo de la documentación oficial, tutoriales y referencias de clases
api_mapping Destino de almacenamiento de cómo cambian los nombres de funciones, clases y símbolos de Godot 3 a Godot 4
label_prototypes Destino de almacenamiento de cómo escribir cuando el modo de uso de funciones, la composición de argumentos o los patrones de llamada cambian por completo
Ítem Resumen
Confusión inicial Al principio se pensó que las tres tablas tenían flujos de operación diferentes.
Nueva delimitación Las tres tablas son destinos de almacenamiento utilizados al clasificar la documentación oficial en Markdown → JSONL.
Prioridad actual Mantener las tres tablas según el plan original y, según la naturaleza del documento, clasificarlas y almacenarlas en uno o más archivos JSONL.

Unidad de análisis final

La entrada es un proyecto de GitHub o un directorio de proyecto local.

El analizador recorre el sistema de archivos y divide los archivos relacionados con Godot en unidades de AST o fragmentos de código.

Objetivo inicial:

Archivo Uso
.gd Análisis de AST/línea/unidad de función de GDScript
.tscn, .tres Extracción de pistas de clase, script y tipo de nodo dentro de escenas/recursos
project.godot Extracción de pistas del proyecto como versión, características, renderizador, autoload, etc.
README/documentación Pistas auxiliares de descripción del proyecto y versión de Godot

Flujo de invocación de LLM bajo demanda

El LLM no se mantiene encendido continuamente, sino que se invoca bajo demanda para cada fragmento de AST/código necesario.

Cada fragmento de AST se envía al LLM junto con la siguiente justificación.

AST/code chunk
+ Resultados de búsqueda JSONL de la documentación oficial necesaria
+ Esquema JSONL de salida
+ Información de identificación del proyecto/archivo

El esquema de respuesta del LLM y la columna de almacenamiento en la base de datos de puntuaciones aún no están definidos. En el documento actual solo se registra qué tabla se busca en qué flujo y cómo se utiliza el resultado en la clasificación del sistema de archivos.

Flujo de datos de generación de descripción de código

Flujo de datos de generación de descripción de código

En la generación de descripción de código, docs_chunks es la evidencia principal.

Flujo:

  1. El usuario ingresa “¿Qué significa esto?” y el código fuente.

  2. El analizador AST divide el código en fragmentos.

  3. El recuperador busca la documentación oficial relevante en docs_chunks.

  4. Qwen 3.6 verifica si el prompt, el fragmento de código fuente y la evidencia de búsqueda están relacionados entre sí.

  5. Descarta los resultados de búsqueda no relevantes.

  6. Vuelve a pasar la evidencia relevante y el fragmento de código a Qwen 3.6 para generar una explicación en JSONL.

  7. El validador verifica la respuesta.

  8. Guardar los resultados verificados en la base de datos de puntuaciones.

  9. Clasificar el sistema de archivos según los resultados de la base de datos de puntuaciones.

Godot 3 -> Godot 4 flujo de conversión de nombres de funciones

Flujo de conversión de nombres de funciones de Godot 3 a Godot 4

En la migración, api_mapping es la base fundamental.

Flujo:

  1. El usuario ingresa “¿Necesita esta conversión?” y el código fuente.
  2. El AST Parser extrae los símbolos candidatos de la API de Godot.
  3. El Retriever busca en api_mapping la API de origen, la API de destino y el tipo de cambio.
  4. Qwen 3.6 verifica si los resultados de la búsqueda están realmente relacionados con el fragmento de código.
  5. Se descartan los mapeos no relacionados.
  6. Solo con los mapeos relacionados se genera el JSONL de migración de Godot 3 -> 4.
  7. El Validator verifica la respuesta de la conversión.
  8. Los resultados verificados se guardan en la base de datos de puntuaciones (score DB).
  9. Con los resultados de la score DB se clasifica el sistema de archivos.

Godot 3 -> Godot 4 flujo de conversión de patrones de uso

Flujo de conversión de patrones de uso de Godot 3 a Godot 4

En la conversión de patrones de uso, label_prototypes es la base fundamental.

Flujo:

  1. El usuario ingresa “¿Necesita esta conversión?” y el código fuente.
  2. El AST Parser extrae llamadas a funciones, composición de argumentos y candidatos de patrones de llamada.
  3. El Retriever busca en label_prototypes la evidencia de conversión de modo de uso/argumentos/patrón de llamada.
  4. Qwen 3.6 verifica si los resultados de la búsqueda están realmente relacionados con el fragmento de código.
  5. Se descartan los prototipos no relacionados.
  6. Solo con los prototipos relacionados se genera el JSONL de conversión de patrones de uso de Godot 3 -> 4.
  7. El Validator verifica la respuesta de la conversión.
  8. Los resultados verificados se guardan en la base de datos de puntuaciones (score DB).
  9. Con los resultados de la score DB se clasifica el sistema de archivos.

Score DB

Los resultados de búsqueda del Retriever por fragmento de AST, los resultados de verificación del LLM y los resultados aprobados por el Validator se guardan finalmente en la score DB.

La score DB no es el origen de los datos de entrenamiento, sino un repositorio de resultados de juicio para clasificar el sistema de archivos. Registra los resultados del Retriever/LLM/Validator obtenidos durante el proceso de análisis del código fuente.

  • docs_chunks resultados de búsqueda: resultados de la verificación de si la evidencia de la documentación oficial en una solicitud de explicación de código está realmente relacionada con el código.
  • api_mapping resultados de búsqueda: resultados de la verificación de si la evidencia de la conversión de nombres de funciones/símbolos de Godot 3 a Godot 4 está realmente relacionada con el código.
  • label_prototypes resultados de búsqueda: resultados de la verificación de si la evidencia de la forma de uso de funciones, la composición de argumentos y los patrones de llamada están realmente relacionados con el código.

Las columnas, el método de agregación y las etiquetas de clasificación de la score DB aún no se han definido. En este documento, solo se fija el papel de la score DB como “un repositorio que recopila los resultados de juicio antes de la clasificación”.

Clasificación final del sistema de archivos:

project source
  -> AST/code chunks
  -> official docs JSONL retrieval
  -> on-demand LLM verification
  -> score DB
  -> classified filesystem

SFT y DPO generación

Los detalles de diseño de SFT y DPO aún no se han definido. Lo que está confirmado actualmente es que la base de datos de puntuaciones (score DB) no es la fuente de datos de entrenamiento. Primero se clasificará el sistema de archivos y, posteriormente, se creará una fuente basada en el sistema de archivos clasificado para diseñar SFT y DPO.

Criterios de seguridad para subir a Git

En esta documentación no se subirán la interfaz web, scripts de conversión locales, scripts de análisis AST, claves API, resultados JSONL ni el código fuente de pruebas.

Permiso de subida:

  • Documentación de arquitectura
  • Imágenes de diagramas de flujo
  • Texto de retrospectiva/hoja de ruta que pueda ser público

Prohibido subir:

  • Código de la aplicación web Streamlit
  • Script de experimento de conversión Markdown → JSONL
  • Script de experimento de análisis Retriever/AST
  • Clave API, endpoint, .env
  • Archivo zip con todo el Markdown original recopilado
  • Resultados del análisis de AST/chunk de código
  • Resultados intermedios JSONL
  • Código fuente de un proyecto externo de Godot clonado para pruebas