Arquitetura de Pontuação de Análise de Fonte do Godot

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

Objetivo

Usar o RAG da documentação oficial do Godot para classificar o código-fonte do GitHub por projeto e organizar o fluxo que leva à geração de dados SFT/DPO.

O ponto central desta organização é tratar docs_chunks, api_mapping e label_prototypes como alvos de classificação do Markdown da documentação oficial → JSONL. Dependendo da natureza do documento, os trechos explicativos vão para docs_chunks, alterações de nomes de funções/classes/símbolos vão para api_mapping e mudanças no modo de uso de funções, composição de argumentos e padrões de chamada vão para label_prototypes.

Conclusão Atual

As três tabelas principais a serem preparadas na fase inicial de coleta da documentação oficial são as seguintes.

Unidade de Análise Final

A entrada pode ser um projeto do GitHub ou um diretório de projeto local.

O analisador varre o sistema de arquivos e divide arquivos relacionados ao Godot em unidades de AST ou fragmentos de código.

Alvo inicial:

Fluxo de Chamada de LLM sob Demanda

O LLM não fica ligado continuamente; ele é chamado sob demanda para cada fragmento de AST/código necessário.

Cada fragmento de AST é enviado ao LLM juntamente com a seguinte justificativa.

AST/code chunk
+ Resultados da pesquisa JSONL da documentação oficial necessária
+ Esquema JSONL de saída
+ Informações de identificação do projeto/arquivo

O esquema de resposta do LLM e as colunas de armazenamento do score DB ainda não foram definidos. No documento atual, apenas registramos quais tabelas são pesquisadas em qual fluxo e como o resultado é usado na classificação do sistema de arquivos.

Geração de explicação de código Fluxo de dados

Na geração de explicação de código, docs_chunks é a evidência principal.

Fluxo:

1. O usuário insere “O que isso significa?” e o código‑fonte.

2. O analisador AST divide o código em fragmentos.

3. O Retriever pesquisa a documentação oficial relevante em docs_chunks.

4. O Qwen 3.6 verifica se o prompt, o fragmento de código‑fonte e a evidência de pesquisa estão relacionados.

5. Resultados de pesquisa não relacionados são descartados.

6. As evidências relevantes e o fragmento de código são enviados novamente ao Qwen 3.6 para gerar um JSONL explicativo.

7. O validador verifica a resposta.

8. Salvar o resultado verificado no banco de dados de pontuação.

9. Classificar o sistema de arquivos com base nos resultados do banco de dados de pontuação.

Fluxo de Conversão de Nomes de Funções Godot 3 → Godot 4

Na migração, api_mapping é a evidência central.

Fluxo:

1. O usuário insere “Preciso converter isso?” junto com o código-fonte.
2. O AST Parser extrai os símbolos candidatos da API do Godot.
3. O Retriever pesquisa na api_mapping a API de origem, a API de destino e o tipo de mudança.
4. O Qwen 3.6 verifica se o resultado da pesquisa está realmente relacionado ao trecho de código.
5. Mapeamentos não relacionados são descartados.
6. Apenas os mapeamentos relevantes são usados para gerar o JSONL de migração Godot 3 → 4.
7. O Validator verifica a resposta da conversão.
8. O resultado validado é armazenado no banco de dados de pontuação (score DB).
9. O score DB classifica o sistema de arquivos com base nos resultados.

Fluxo de Conversão de Padrões de Uso Godot 3 → Godot 4

Na conversão de padrões de uso, label_prototypes é a evidência central.

Fluxo:

1. O usuário insere “Preciso converter isso?” junto com o código-fonte.
2. O AST Parser extrai chamadas de função, composição de argumentos e candidatos a padrões de chamada.
3. O Retriever pesquisa em label_prototypes as evidências de conversão de modo de uso/argumentos/padrões de chamada.
4. O Qwen 3.6 verifica se o resultado da pesquisa está realmente relacionado ao trecho de código.
5. Prototipos não relacionados são descartados.
6. Apenas os protótipos relevantes são usados para gerar o JSONL de conversão de padrões de uso Godot 3 → 4.
7. O Validator verifica a resposta da conversão.
8. O resultado validado é armazenado no banco de dados de pontuação (score DB).
9. O score DB classifica o sistema de arquivos com base nos resultados.

Banco de Pontuações

Os resultados da pesquisa do Retriever por fragmento de AST, a validação pelo LLM e os resultados aprovados pelo Validador são armazenados finalmente no banco de pontuações.

O banco de pontuações não é a origem dos dados de treinamento, mas sim um repositório de resultados de julgamento usado para classificar o sistema de arquivos. Ele registra os resultados do Retriever/LLM/Validador obtidos durante o processo de análise de código.

• docs_chunks resultados da pesquisa: resultado da verificação de que a evidência da documentação oficial está realmente relacionada ao código ao solicitar explicação do código
• api_mapping resultados da pesquisa: resultado da verificação de que a base de conversão de nomes/símbolos de funções de Godot 3 → Godot 4 está realmente relacionada ao código
• label_prototypes resultados da pesquisa: resultado da verificação de que a base de conversão de modo de uso da função, composição de argumentos e padrão de chamada está realmente relacionada ao código

As colunas, o método de agregação e os rótulos de classificação do banco de pontuações ainda não foram definidos. Neste documento, o banco de pontuações tem apenas o papel fixo de “repositório que reúne os resultados de julgamento antes da classificação”.

Classificação final do sistema de arquivos:

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

Criação de SFT e DPO

O detalhamento do design de SFT e DPO ainda não foi definido. O que já está confirmado é que o banco de dados de pontuações (score DB) não será a fonte dos dados de treinamento. Primeiro, o sistema de arquivos será classificado e, posteriormente, será usado como fonte para projetar SFT e DPO com base no sistema de arquivos classificado.

Critérios de Segurança para Upload no Git

Nesta documentação, não serão enviados a interface web UI, scripts de conversão local, scripts de análise AST, chaves de API, arquivos JSONL resultantes, nem o código-fonte de testes.

Uploads permitidos:

• Documentação de arquitetura
• Imagens de diagramas de fluxo
• Texto de retrospectiva/roteiro que pode ser divulgado publicamente

Uploads proibidos:

• Código do aplicativo web Streamlit
• Script de experimento de conversão Markdown → JSONL
• Script de experimento de análise Retriever/AST
• Chave de API, endpoint, .env
• Arquivo zip contendo todo o Markdown original coletado
• Resultados da análise de AST/trechos de código
• Arquivos JSONL intermediários
• Código-fonte de projetos externos do Godot clonados apenas para teste