idea_world_labDEV JOURNAL
sábado, 27 de junio de 2026

Registro de implementación del depurador de flujo de origen

Fecha de creación: 27 de junio de 2026

Propósito

Este documento es un registro de la implementación y verificación del flujo descrito en docs/roadmaps/2026-06-27-source-to-ast-input-flow.md en un depurador web real.

Los puntos clave revisados hoy son los siguientes.

Godot proyecto entrada
  -> Expandir archivos basándose en rutas relativas
  -> Determinar el tipo de archivo
  -> Descomponer .gd como fragmentos de código de tipo AST
  -> Descomponer recursos de texto como .godot, .tscn en chunks directos
  -> Mostrar solo el chunkText de cada chunk como entrada para el Retriever
  -> Proveer botón de búsqueda de docs_chunks / api_mapping / label_prototypes bajo el chunk
  -> Conectar el JSONL encontrado a una estructura que pueda adjuntarse a la solicitud de verificación Qwen

Esta implementación no es un Retriever completo, sino un depurador web para rastrear visualmente la interacción entre el Retriever y la entrada AST. Es decir, antes de juzgar la calidad de búsqueda en la base de datos, sirve para verificar primero qué archivo se divide en qué fragmentos y qué texto se envía como entrada de búsqueda del Retriever.

Flujo web implementado

El depurador web se ejecutó en http://127.0.0.1:8010/.

Las áreas que se pueden observar en la pantalla son las siguientes:

  • Área de entrada del endpoint de la base de datos
  • Área de entrada de validación de Qwen
  • Área de entrada del Prompt de origen
  • Área de entrada del Origen expandido
  • Métricas de resumen de archivo/fragmento
  • Resultados de inclusión/exclusión por archivo
  • Texto original por fragmento, Entrada del Retriever, botón de búsqueda en la base de datos, vista previa de la solicitud a Qwen

La pantalla revisada hoy es la siguiente.

Pantalla de análisis del depurador de flujo de origen de Godot

Verificación de la entrada del proyecto Godot

La prueba se realizó con un proyecto pequeño de Godot.

Los archivos de entrada fueron los siguientes.

minidodge/project.godot
minidodge/scripts/player.gd
minidodge/scripts/enemy.gd
minidodge/scenes/player.tscn
minidodge/README.md

Después de cargar, la entrada interna se despliega en la siguiente forma.

# minidodge/project.godot
config_version=5

[application]
config/name="Mini Dodge Upload Test"
run/main_scene="res://scenes/player.tscn"

# minidodge/scripts/player.gd
extends Area2D

signal hit

@export var speed = 400
...

encabezado es para rastreo. No se incluye este encabezado en el Retriever.

Resultado del análisis

El resumen que mostró el depurador web en esta prueba es el siguiente.

Ítem Valor
Archivos 5
Incluidos 4
Excluidos 1
Fragmentos 14
AST 9
Directo 5
Entradas del Retriever 14

La evaluación por archivo fue la siguiente.

Archivo Evaluación Acción
minidodge/project.godot incluido project_config, fragmento directo
minidodge/scripts/player.gd incluido gdscript, fragmento AST
minidodge/scripts/enemy.gd incluido gdscript, fragmento AST
minidodge/scenes/player.tscn incluido scene, fragmento directo
minidodge/README.md excluido excluido en modo de análisis de fuente

Procesamiento de archivos .gd

Los archivos .gd se procesan mediante lógica que actúa como un Analizador AST.

Por ejemplo, player.gd se dividió de la siguiente manera.

extends Area2D
signal hit
@export var speed = 400
var screen_size
func _ready():
func _process(delta):
func start(pos):

El chunk real incluye el cuerpo de la función.

Por ejemplo, la función _process se mantiene como un solo chunk.

func _process(delta):
	var velocity = Vector2.ZERO
	if Input.is_action_pressed(&"move_right"):
		velocity.x += 1
	if Input.is_action_pressed(&"move_left"):
		velocity.x -= 1

	if velocity.length() > 0:
		velocity = velocity.normalized() * speed
		$AnimatedSprite2D.play()
	else:
		$AnimatedSprite2D.stop()

	position += velocity * delta
	position = position.clamp(Vector2.ZERO, screen_size)

En enemy.gd se confirmó que incluso el código que podría ser una pista de Godot 3 se separa en chunks.

extends KinematicBody2D
func _physics_process(delta):
	velocity = move_and_slide(velocity)

procesamiento de fragmentos directos

project.godot no se envía al AST Parser, sino que se divide por secciones de configuración.

Por ejemplo, el siguiente contenido es un fragmento directo.

[application]
config/name="Mini Dodge Upload Test"
run/main_scene="res://scenes/player.tscn"

player.tscn también se divide por bloques de recurso en lugar de enviarse al AST Parser.

Por ejemplo, el siguiente contenido es un chunk directo.

[node name="Player" type="Area2D"]
script = ExtResource("1")

Así se divide porque, aunque los archivos .tscn y .godot también son necesarios para determinar un proyecto de Godot, no son objetos de análisis a nivel de función AST como lo son los archivos .gd.

Verificación de entrada del Retriever

Según la fecha de hoy, la entrada del Retriever solo contiene chunkText.

Por ejemplo, la entrada del Retriever para el fragmento extends KinematicBody2D es la siguiente.

{
  "chunkText": "extends KinematicBody2D"
}

Archivo de ruta, número de línea, prompt, nombre de tabla esperado no se incluyen en la entrada del Retriever.

La ruta del archivo y el número de línea son información para que una persona los rastree en la UI. La búsqueda en sí debe realizarse con el texto del fragmento.

Botón de búsqueda en la base de datos por fragmento

Al principio se podría haber puesto la selección de tabla como una opción global, pero en realidad la tabla que se debe buscar puede variar para cada fragmento.

Por eso el botón se colocó debajo del fragmento.

Buscar **docs_chunks**  
Buscar **api_mapping**  
Buscar **label_prototypes**  
Validar JSONL

El flujo se estableció de la siguiente manera.

Texto actual del chunk
  -> Hacer clic en el botón de tabla debajo del chunk
  -> Buscar en esa tabla
  -> Mostrar candidatos JSONL
  -> Verificar Qwen con prompt + chunkText + JSONL recuperado

Aquí el prompt no es una entrada para el Retriever. El prompt solo se usa en la fase de verificación de Qwen.

Lo que se verificó hoy

Lo que se verificó hoy se puede resumir en cuatro puntos.

  1. Se eliminó el problema de que el código de muestra se insertaba automáticamente en una pantalla en blanco. Antes, al abrir la página, la muestra Mini Dodge se cargaba automáticamente, de modo que incluso al subir una carpeta vacía parecía que el contenido anterior permanecía. Ahora, justo después de recargar, la entrada source está vacía.

  2. Cuando se vuelve a subir el mismo archivo o carpeta, se vacía el valor del input de subida en el momento del clic para que el navegador vuelva a disparar el evento change.

  3. Durante el desarrollo, se añadió cache-control: no-store a la respuesta del servidor local para que no quede caché estático de JS.

  4. Al subir un proyecto de Godot, se observó en la pantalla web que los archivos .gd se tratan como AST chunk, mientras que .godot y .tscn se tratan como direct chunk.

Lo que aún falta

Parece que se ha logrado dividir en chunks a nivel de unidad.

Mañana continuaré con el tema central: cómo realizar la búsqueda en la base de datos.

En particular, se deben revisar los siguientes puntos:

  • Qué JSONL se devuelve al buscar docs_chunks solo con chunkText.
  • Si al buscar api_mapping solo con chunkText se captura correctamente la referencia de Godot 3 → 4.
  • Si al buscar label_prototypes solo con chunkText se capturan bien los ejemplos de uso de funciones/patrones de llamada.
  • Cómo descartar resultados en la fase de verificación de Qwen cuando no hay coincidencias o son incorrectos.
  • Qué forma de presentar el JSONL encontrado en la pantalla facilita la evaluación.

El depurador web creado hoy es una herramienta de observación para confirmar la siguiente fase. Ahora que se empieza a ver cómo se fragmentan los archivos, el próximo paso será rastrear qué evidencia extrae cada chunk de la base de datos.