2026-06-27 Retrospectiva

Hoje parece que o objetivo era melhorar a consistência do fluxo de entrada source-to-AST que eu havia escrito no dia 26.

Até ontem, as camadas completas estavam separadas na minha cabeça, mas permaneciam em um nível muito abstrato nos documentos e no código. Eu conseguia distinguir termos como AST, Retriever, validação LLM, evidência JSONL, mas não estava detalhado como, quando um projeto real chegava, quais arquivos eram desdobrados em que ordem, qual parte do texto entrava no AST Parser e qual chunk era passado diretamente ao Retriever.

Eu achava que entendia tudo na cabeça, mas ao começar a codificar nessa condição, sentia uma forte insegurança de que não seria implementado da forma que eu desejava. Então, hoje, primeiro reorganizei a estrutura completa e planejei projetá‑la em um formato GUI que pudesse ser verificado visualmente por uma pessoa.

Por que era necessário detalhar

Os papéis do AST e do Retriever estavam, de fato, diferenciados.

Arquivos .gd entram no AST Parser e devem ser divididos por funções ou declarações. O Retriever recebe os trechos de código resultantes e busca evidências JSONL relacionadas no banco de dados. A validação LLM, por sua vez, analisa o prompt, o chunk atual e o JSONL buscado para decidir se a evidência é realmente pertinente.

Mas, ao tentar organizar isso apenas em palavras, a ideia ficava nebulosa. Especialmente no fluxo real de um projeto, os arquivos são primeiro desdobrados na forma # <caminho‑relativo>, abaixo disso o conteúdo é dividido por arquivos, funções ou declarações específicas de .gd tornam‑se chunks, e somente o chunkText desses chunks deve ser enviado ao Retriever.

Eu queria observar esse fluxo claramente. Queria ver em uma tela web qual parte de qual arquivo se tornou qual chunk, se a entrada recebida pelo Retriever era exatamente aquele chunk, e se caminho de arquivo, número de linha ou prompt não se misturavam com a consulta de busca.

Por isso, não bastava apenas escrever documentos; eu precisava de uma ferramenta com GUI que fosse fácil de usar.

Depurador de Fluxo de Fonte

Como resultado, ao criar o Source Flow Debugger, consegui visualizar o fluxo entre AST e Retriever em uma única tela.

Inicialmente, eu pretendia organizar como o código‑fonte seria passado para o AST, mas acabei juntando AST chunk, direct chunk, entrada do Retriever, botão de busca no DB e pré‑visualização da validação Qwen tudo em uma tela. Acabou se tornando uma estrutura integrada de AST, Retriever e validação LLM, e ficou mais conveniente do que eu esperava.

Um ponto que me orgulha foi não tentar construir um sistema completo desde o início, mas sim uma ferramenta de observação. Nesta fase, o que eu precisava não era “uma ferramenta que gera respostas automaticamente”, mas sim algo que confirmasse se os dados estavam fluindo conforme o fluxo que eu pretendia.

Hoje verifiquei o seguinte:

• O projeto Godot é desdobrado na forma # <caminho‑relativo>.
• Arquivos .gd são divididos em chunks de natureza AST.
• Recursos de texto como .godot, .tscn são divididos em direct chunks.
• Arquivos de documentação como README.md são excluídos no modo source‑analysis, e o motivo da exclusão é exibido na tela.
• A entrada do Retriever contém apenas chunkText, sem caminho de arquivo, número de linha ou prompt.
• Embaixo de cada chunk, é possível buscar nas tabelas docs_chunks, api_mapping e label_prototypes.
• Depois, a validação Qwen recebe a estrutura prompt + chunkText + JSONL recuperado.

Ao inserir um pequeno projeto Godot, confirmei que ele foi dividido em 5 arquivos, 14 chunks, AST 9, Direct 5. Parece que o fluxo de divisão por chunks está razoavelmente bem‑sucedido.

Teste de Demo GPT

Originalmente, eu pretendia, a partir de um conjunto de JSONL coletado, encontrar repositórios GitHub relacionados, cloná‑los e testá‑los.

Mas percebi que não era necessário buscar um repositório real desde o início. O que eu queria confirmar era: “O LLM consegue julgar corretamente se o JSONL buscado está realmente relacionado ao chunk de código Godot atual?”. Então, achei mais rápido gerar, com o GPT, um chunk de Godot de demonstração junto com JSONL relevantes e JSONL irrelevantes, e testar primeiro.

Assim, deliberadamente criei um chunk de código Godot 3, gerei JSONL de conversão Godot 3 → Godot 4 correspondentes e também JSONL totalmente não relacionados, para testar.

No início, perguntei simplesmente assim.

Este JSONL contém o conteúdo que corresponde ao código‑fonte?  
Responda apenas Sim / Não.

Então o JSONL relacionado também saiu como sim, e o JSONL não relacionado também saiu como sim.

No começo pode parecer decepcionante, mas acabei pensando que, na verdade, era um alívio. Se esse problema não tivesse surgido nesta fase, ao conectar a busca real no banco de dados mais tarde, o LLM poderia ter anexado de forma plausível JSONLs aleatórios usando seu próprio conhecimento.

Por isso, tornei o prompt ainda mais forte.

Você é um avaliador de correspondência de evidências JSONL.

Determine se o JSONL abaixo contém evidência direta de conversão para o SOURCE_CODE abaixo.

Critérios de avaliação:
- É necessário que um dos campos source_api, source_pattern, match_terms, required_when_seen_in_code ou before_code do JSONL corresponda exatamente a uma string real ou chamada de API dentro do SOURCE_CODE para que a resposta seja "sim".
- Palavras genéricas como Godot, Godot3, Godot4, migration, 2D, physics não são consideradas relevantes.
- Conteúdos negativamente mencionados no JSONL, como "does not describe", "not related", "unrelated", "does not apply", não são reconhecidos como evidência relevante.
- Se o JSONL tratar de outra API, outro nó ou outro sistema, a resposta é "não".
- Não use seu conhecimento prévio sobre Godot; utilize apenas as evidências textuais presentes no JSONL.
- A resposta deve ser apenas "sim" ou "não".

Assim vamos mudar: JSONL relacionado é sim, JSONL irrelevante é não.

O critério obtido neste experimento de hoje é importante. Quando o Retriever traz candidatos JSONL e o LLM deve verificá‑los, não se deve usar uma medida de similaridade ampla. Primeiro, deve‑se conferir se campos como source_api, source_pattern, match_terms, required_when_seen_in_code, before_code dentro do JSONL correspondem exatamente à string/chamada de API real do chunk atual.

Tarefas para amanhã

Amanhã parece que será necessário criar mais conjuntos de demonstração.

É preciso gerar vários JSONL relacionados ao chunk do Godot e JSONL irrelevantes, e testar repetidamente como o Qwen gera respostas. Ainda é cedo para adotar como padrão algo que funcionou apenas uma ou duas vezes.

Em especial, devemos confirmar os seguintes casos:

• Quando vários JSONL relacionados estão misturados, o Qwen escolhe corretamente a evidência real;
• Quando JSONL irrelevantes têm apenas palavras‑chave semelhantes, ele os descarta adequadamente como não;
• Se o Qwen diferencia corretamente, com base em evidências textuais, api_mapping de label_prototypes;
• Se JSONL de natureza documental, como docs_chunks, podem ser validados da mesma forma;
• Se, ao parecer um código Godot 3, mas sem evidência JSONL, ele não realiza migrações arbitrárias.

Hoje foi um dia em que a estrutura abstrata foi trazida para a tela e fluxo de entrada reais. Ideias que eu achava já conhecer mentalmente ficaram muito mais claras ao serem exibidas, fragmentadas e pesquisadas na web.

Agora o próximo passo é repetir várias vezes a busca no banco de dados e a validação pelo Qwen, para garantir que esse fluxo permaneça estável.