Registro de Implementação do Depurador de Fluxo de Origem

Data de criação: 27 de junho de 2026

Objetivo

Este documento registra a implementação e verificação do fluxo descrito em docs/roadmaps/2026-06-27-source-to-ast-input-flow.md no depurador web real.

O ponto principal verificado hoje é o seguinte.

Projeto de entrada do Godot
  -> Expandir arquivos com base em caminho relativo
  -> Determinar o tipo de arquivo
  -> .gd é dividido em fragmentos de código de natureza AST
  -> Recursos de texto como .godot, .tscn são divididos em chunks diretos
  -> Apenas o chunkText de cada chunk é exibido como entrada para o Retriever
  -> Fornecer botão de busca para docs_chunks / api_mapping / label_prototypes abaixo de cada chunk
  -> Conectar o JSONL encontrado a uma estrutura que pode ser anexada à solicitação de validação do Qwen

Esta implementação não é um Retriever concluído, mas sim um depurador web para rastrear visualmente a relação entre o Retriever e a entrada AST. Ou seja, antes de avaliar a qualidade da pesquisa no banco de dados, serve para verificar quais arquivos são divididos em quais fragmentos e quais textos são enviados como entrada de pesquisa do Retriever.

Fluxo Web Implementado

O depurador web foi executado em http://127.0.0.1:8010/.

As áreas visíveis na tela são as seguintes:

• Área de entrada do endpoint do DB
• Área de entrada de validação do Qwen
• Área de entrada do Prompt de Origem
• Área de Entrada de Origem Expandida
• Métricas de resumo de arquivos/fragmentos
• Resultados de inclusão/exclusão por arquivo
• Texto original por fragmento, Entrada do Retriever, botão de pesquisa no DB, pré‑visualização da solicitação ao Qwen

A tela verificada hoje é a seguinte.

Verificação da Entrada do Projeto Godot

O teste foi realizado em forma de um pequeno projeto Godot.

Os arquivos de entrada eram os seguintes.

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

Após o upload, a entrada interna é expandida da seguinte 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
...

# <caminho relativo> cabeçalho é para rastreamento. Não é incluído no Retriever.

Resultado da análise

O resumo mostrado pelo depurador web neste teste foi o seguinte.

A avaliação por arquivo foi a seguinte.

Processamento de arquivos .gd

Arquivos .gd são encaminhados para a lógica de Parser AST.

Por exemplo, player.gd foi dividido da seguinte forma.

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

O chunk real inclui o corpo da função.

Por exemplo, a função _process é mantida como um único 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)

No enemy.gd, verificou‑se que o código que pode ser uma pista do Godot 3 também é dividido em chunks.

extends KinematicBody2D

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

processamento de chunk direto

project.godot não é enviado ao AST Parser, mas dividido por seções de configuração.

Por exemplo, o conteúdo a seguir é um chunk direto.

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

player.tscn também não é enviado ao AST Parser, sendo dividido por unidades de bloco de recurso.

Por exemplo, o conteúdo a seguir é um direct chunk.

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

Assim dividimos porque arquivos .tscn e .godot também são necessários para determinar um projeto Godot, mas não são objetos de análise como funções AST individuais, como as funções .gd.

Verificação da Entrada do Retriever

Com base na data de hoje, a entrada do Retriever contém apenas um chunkText.

Por exemplo, a entrada do Retriever para o chunk extends KinematicBody2D é a seguinte.

{
  "chunkText": "extends KinematicBody2D"
}

Não inclua o caminho do arquivo, número da linha, prompt ou nome de tabela esperado na entrada do Retriever.

O caminho do arquivo e o número da linha são informações para que o usuário possa rastrear na UI. A própria busca deve ser feita com o texto do chunk.

Botão de busca no DB por chunk

Inicialmente, a seleção de tabela poderia ser configurada como uma opção global, mas na prática a tabela a ser pesquisada pode variar para cada chunk.

Portanto, o botão foi colocado abaixo do chunk.

Pesquisar docs_chunks  
Pesquisar api_mapping  
Pesquisar label_prototypes  

Validate JSONL

Defini o fluxo da seguinte maneira.

Texto atual do chunk  
  -> Clique no botão da tabela abaixo do chunk  
  -> Pesquise na tabela correspondente  
  -> Exiba os candidatos JSONL  
  -> Verifique o Qwen com prompt + chunkText + JSONL recuperado

Aqui o prompt não é a entrada do Retriever. O prompt é usado apenas na fase de validação do Qwen.

O que foi verificado hoje

O que foi verificado hoje pode ser resumido em quatro pontos.

1. Foi removido o problema em que um código de amostra era inserido automaticamente em uma tela vazia. Antes, ao abrir a página, a amostra Mini Dodge era carregada automaticamente, fazendo parecer que o conteúdo anterior permanecia mesmo ao fazer upload de uma pasta vazia. Agora, logo após atualizar a página, a entrada source está vazia.

2. Quando o mesmo arquivo ou pasta é enviado novamente, o navegador dispara o evento change outra vez ao limpar o valor do input de upload no momento do clique.

3. Para evitar que o cache estático de JS persista durante o desenvolvimento, foi adicionado cache-control: no-store nas respostas do servidor local.

4. Ao inserir um projeto Godot, verificou‑se na interface web que arquivos .gd são tratados como AST chunk, enquanto .godot e .tscn são tratados como direct chunk.

O que ainda falta

A divisão em chunks parece estar funcionando em boa parte.

A continuação amanhã será focada em como executar a busca no banco de dados.

Em especial, os seguintes itens precisam ser verificados:

• Ao buscar docs_chunks apenas com chunkText, qual JSONL é retornado;
• Ao buscar api_mapping apenas com chunkText, se a correspondência entre Godot 3 e Godot 4 está bem capturada;
• Ao buscar label_prototypes apenas com chunkText, se os exemplos de uso de funções/padrões de chamada são identificados corretamente;
• Como descartar resultados inexistentes ou inadequados na fase de validação do Qwen;
• Em que formato exibir o JSONL encontrado na tela para facilitar a avaliação.

O depurador web criado hoje serve como ferramenta de observação para confirmar a próxima etapa. Agora já é possível ver como os arquivos são fragmentados; o próximo passo é rastrear quais evidências cada chunk obtém do banco de dados.