2026-06-27 Revisión

Hoy parece que me propuse mejorar la consistencia del flujo de entrada source-to-AST que había escrito el día 26.

Hasta ayer, todas las capas estaban diferenciadas en mi cabeza, pero en la documentación o el código permanecían en un nivel demasiado abstracto. Podía distinguir términos como AST, Retriever, verificación LLM, evidencia JSONL, pero no estaba especificado cómo, al recibir un proyecto real, qué archivos se despliegan en qué orden, cuál contenido entra al AST Parser y qué fragmento se pasa directamente al Retriever.

Pensaba que lo entendía mentalmente, pero al comenzar a codificar con esa visión sentía una fuerte incertidumbre de que no se implementaría como quería. Así que hoy primero volví a estructurar todo y diseñé esa estructura en una forma GUI que una persona pueda inspeccionar visualmente.

Razones por las que se necesitaba concretar

Los roles de AST y Retriever estaban, de hecho, diferenciados.

Los archivos .gd deben pasar al AST Parser y dividirse por funciones o declaraciones. El Retriever debe tomar los fragmentos de código resultantes y buscar la evidencia JSONL correspondiente en la base de datos. Luego, la verificación LLM debe observar el prompt, el fragmento actual y la JSONL encontrada para determinar si esa evidencia está realmente relacionada.

Sin embargo, al describirlo solo con palabras se volvía confuso. En el flujo real del proyecto, los archivos se despliegan primero en forma # <ruta relativa>, bajo esa cabecera el contenido se divide por archivo, una función o declaración específica del archivo .gd se convierte en un chunk, y solo el chunkText de ese chunk debe pasar al Retriever.

Quería observar ese flujo con claridad. Saber qué parte de qué archivo se convirtió en qué chunk, si la entrada del Retriever era exactamente ese chunk, y si la ruta del archivo, número de línea o prompt se mezclaban con la búsqueda, todo directamente en la pantalla web.

Por eso pensé que no bastaba con solo escribir documentación, sino que necesitaba una herramienta con una GUI fácil de usar para la verificación.

Depurador de Flujo de Fuente (Source Flow Debugger)

Al final, al crear el Source Flow Debugger pude visualizar el flujo entre AST y Retriever en una sola pantalla.

Al principio intenté organizar cómo pasar el código fuente al AST, pero terminé integrando en la misma vista el chunk de AST, el chunk directo, la entrada del Retriever, el botón de búsqueda en la base de datos y la vista previa de la verificación Qwen. Así, el AST, el Retriever y la verificación LLM quedaron en una estructura unificada, resultando más cómoda de lo esperado.

Lo que realmente aproveché fue no intentar construir un sistema completo desde el inicio, sino crear una herramienta de observación. En esta etapa lo que necesitaba no era “una herramienta que genere la respuesta automáticamente”, sino una que confirmara que los datos se movían según el flujo que había planeado.

Lo que verifiqué hoy es lo siguiente:

• Desplegar el proyecto Godot en forma # <ruta relativa>.
• Dividir los archivos .gd en chunks de tipo AST.
• Dividir recursos de texto como .godot, .tscn en chunks directos.
• Excluir archivos de documentación como README.md del modo source-analysis y dejar el motivo de exclusión en pantalla.
• En la entrada del Retriever no incluir la ruta del archivo, número de línea ni prompt, solo el chunkText.
• Permitir buscar en cada chunk dentro de docs_chunks, api_mapping y label_prototypes por tabla.
• Luego la verificación Qwen se realiza con la estructura prompt + chunkText + JSONL recuperado.

Al probar con un pequeño proyecto Godot, confirmé que se descompone en 5 archivos, 14 chunks, AST 9, Direct 5. Con eso, el flujo de división por chunks parece haber tenido éxito.

Prueba de demostración con GPT

Originalmente quería, a partir del conjunto de JSONL recopilado, encontrar el repositorio de GitHub relacionado, clonarlo y probarlo.

Pero me di cuenta de que no era necesario buscar el repositorio real desde el principio. Lo que quería comprobar era “si el LLM juzga correctamente que la JSONL encontrada está realmente relacionada con el chunk de código Godot actual”. Entonces pensé que sería más rápido generar con GPT un chunk de Godot de demostración, una JSONL relacionada y una JSONL no relacionada, y probar primero con eso.

Así que deliberadamente creé un chunk de código Godot 3 y generé tanto la JSONL de conversión Godot 3 → Godot 4 como una JSONL totalmente irrelevante para probar.

Al principio pregunté simplemente:

¿Este JSONL contiene contenido que corresponde al código fuente?  
Responda solo sí / no.

¡Entonces el JSONL relacionado también salió como 예, y el JSONL no relacionado también salió como 예.

Al principio podría parecer decepcionante, pero en realidad me pareció un alivio. Si este problema no se hubiera manifestado en esta etapa, cuando se añadiera la búsqueda real en la base de datos más adelante, el LLM podría haber concatenado de manera convincente un JSONL incorrecto usando su propio conocimiento.

Por eso cambié el prompt para hacerlo más fuerte.

Eres un evaluador de coincidencia de evidencia JSONL.

Determina si el siguiente JSONL contiene evidencia de transformación directa para el **SOURCE_CODE** proporcionado.

Criterios de evaluación:
- Sólo se considera **“sí”** si al menos uno de los campos `source_api`, `source_pattern`, `match_terms`, `required_when_seen_in_code` o `before_code` del JSONL coincide exactamente con una cadena real o una llamada a API presente en el **SOURCE_CODE**.
- No se acepta coincidencia basada únicamente en palabras genéricas como *Godot*, *Godot3*, *Godot4*, *migration*, *2D*, *physics*, etc.; esas coincidencias no son relevantes.
- Las menciones negativas en el JSONL, como “does not describe”, “not related”, “unrelated”, “does not apply”, no se consideran evidencia válida.
- Si el JSONL se refiere a una API, nodo o sistema diferente, la respuesta es **“no”**.
- No utilices tu conocimiento previo sobre Godot; basa tu respuesta únicamente en la evidencia textual presente en el JSONL.
- La respuesta debe ser **únicamente** “sí” o “no”.

Así cambiemos, los JSONL relacionados son sí, los JSONL no relacionados son no.

El criterio obtenido en este experimento de hoy es importante. Cuando el Retriever trae candidatos JSONL y se verifica con el LLM, no se debe observar una similitud amplia. Primero se debe comprobar si campos como source_api, source_pattern, match_terms, required_when_seen_in_code, before_code dentro del JSONL coinciden directamente con la cadena real / llamada a la API del fragmento actual.

Tareas para mañana

Mañana parece que tendremos que crear más conjuntos de demostración.

Es necesario crear varios JSONL relacionados con fragmentos de Godot, JSONL no relacionados, y probar varias veces cómo Qwen genera sus respuestas. Aún es temprano para considerarlo un criterio solo porque haya funcionado una o dos veces.

En particular, hay que verificar los siguientes casos:

• Cuando hay varios JSONL relacionados mezclados, si Qwen elige correctamente la evidencia real.
• Si los JSONL no relacionados, al tener solo palabras clave similares, se descartan correctamente con no.
• Si Qwen distingue bien la diferencia entre api_mapping y label_prototypes basándose en la evidencia de texto.
• Si los JSONL de tipo documento explicativo, como docs_chunks, pueden verificarse del mismo modo.
• Si, al parecer código de Godot 3 pero sin evidencia JSONL, no se realiza una migración arbitraria.

Hoy fue un día en que extrajimos la estructura abstracta hacia la pantalla real y el flujo de entrada. Incluso cosas que pensé que ya conocía mentalmente se volvieron mucho más claras al desplegarlas, fragmentarlas y mostrarlas como entradas de búsqueda en la web.

Ahora el siguiente paso es repetir varias veces la búsqueda en la base de datos y la verificación con Qwen, para asegurarnos de que este flujo no se tambalee.