Estratégia e Registro de Implementação do Qwen Validation Debugger
Data de criação: 30 de junho de 2026
Objetivo
Este documento registra o motivo da criação do tools/qwen-validation-debugger e o fluxo de operação real.
No dia 28 de junho, criamos manualmente trechos de código Godot e arquivos JSONL com o Qwen, e colamos diretamente prompt + trecho de código + JSONL para verificar como surgiam as respostas “sim”/“não”. Esse método foi útil para definir a direção, mas à medida que o número de itens aumentava, o custo de copiar manualmente, lembrar os critérios de geração e comparar os resultados se tornava excessivo.
Portanto, em 30 de junho, transformamos esse processo em uma ferramenta web separada. O objetivo da ferramenta não é treinar o modelo final, mas permitir que o usuário acompanhe visualmente a relação entre o código de teste gerado pelo Qwen e o JSONL, identificando rapidamente avaliações incorretas de “sim”/“não”.
Tela Atual
A ferramenta atual é executada em http://localhost:8520/.

A tela está dividida em três áreas principais.
- Esquerda: lista de verificação com 50 itens de teste do Godot
- Centro / canto superior direito: rótulo de IA e resultado da geração de código Godot para o item selecionado
- Parte inferior: slots de criação/validação de JSONL para
docs_chunks,api_mappingelabel_prototypes
Por que era necessária uma ferramenta separada
Originalmente, solicitamos diretamente ao chatbot Qwen o seguinte.
Crie um chunk de código Godot,
e gere JSONL de resposta correta e JSONL de resposta incorreta de acordo com o formato `docs_chunks/api_mapping/label_prototypes`.
Em seguida, verificaremos se ao combinar `SOURCE_CODE` com o JSONL a resposta “sim/não” está correta.Mas ao fazer testes manuais, percebi que havia mais eixos a serem verificados do que eu imaginava.
| Eixo | O que deve ser verificado |
|---|---|
| Itens de teste | _ready(), _process(delta), movimento, colisão, UI, salvar/carregar etc., cerca de 50 |
| Escopo da sintaxe | Se é comum ao Godot 3/4 ou se precisa ser separado por versão |
| Critério de código | Código comum único ou código Godot 3 + código Godot 4 |
| Tabelas | docs_chunks, api_mapping, label_prototypes |
| Natureza do JSONL | Base de explicação, explicação de outro código, necessidade de conversão, já aplicado, comum/desnecessário, conversão irrelevante |
| Alvo da validação | Se a validação ocorre no mesmo código que gerou o JSONL ou no código da versão oposta |
Se for sintaxe comum, há 6 slots.
Código comum
docs_chunks descrição base / outra descrição de código
api_mapping comum/desnecessário / conversão irrelevante
label_prototypes comum/desnecessário / conversão irrelevanteSe for sintaxe de separação de versão, há 12 slots.
Código Godot 3
docs_chunks Base de explicação / Explicação de outro código
api_mapping Conversão necessária / Conversão irrelevante
label_prototypes Conversão necessária / Conversão irrelevante
Código Godot 4
docs_chunks Base de explicação / Explicação de outro código
api_mapping Já aplicado / Conversão irrelevante
label_prototypes Já aplicado / Conversão irrelevanteSe você continuar fazendo isso manualmente, gastará mais tempo copiando/colando e organizando os resultados do que no próprio teste. Portanto, agrupei itens, código, JSONL e resultados de validação em uma única tela usando a GUI.
Fluxo geral
flowchart TD
A["50 itens de teste"] --> B["Selecionar itens"]
B --> C["Rotulagem Qwen"]
C --> D{"É sintaxe comum?"}
D -->|\"comum\"| E["Gerar código comum"]
D -->|\"separado\"| F["Gerar código Godot 3"]
D -->|\"separado\"| G["Gerar código Godot 4"]
E --> H["6 slots JSONL"]
F --> I["6 JSONL baseados em Godot 3"]
G --> J["6 JSONL baseados em Godot 4"]
I --> K["Validar código Godot 3"]
I --> L["Validar código Godot 4"]
J --> K
J --> L
H --> M["Validar código comum"]Ferramenta chama o Qwen em três papéis diferentes.
| Etapa | O que o Qwen faz | O que é armazenado |
|---|---|---|
| Rotulagem | Determina se o item de teste é sintaxe comum ou separação por versão | classification |
| Geração de código | Gera código comum ou código Godot 3/4 | codes |
| Geração de JSONL | Cria JSONL adequado ao tipo de tabela e slot | slots[].jsonlText |
| Verificação | Avalia se SOURCE_CODE + JSONL é evidência direta, respondendo “sim”/“não” |
slots[].verifications |
Etapa de rotulagem
Ao clicar no item, o Qwen primeiro decide se é sintaxe comum ou separação por versão.

Por exemplo, _process(delta) é usado como função de atualização de quadro tanto no Godot 3 quanto no Godot 4, portanto pode ser considerado sintaxe comum.

Ao contrário, Aplicar velocidade e aceleração de movimento do jogador pode ter diferenças na chamada do corpo físico e move_and_slide() entre as versões, então são criados códigos separados para Godot 3 e Godot 4.

Projeto do slot JSONL
Inicialmente, os slots eram divididos apenas em JSONL correto e JSONL incorreto. Essa classificação era muito genérica.
docs_chunks são evidências explicativas. Assim, se a explicação corresponde diretamente ao código, a resposta é “sim”; se descreve o comportamento de outro código, a resposta é “não”.
Entretanto, api_mapping e label_prototypes não são meras explicações, mas justificativas de conversão ao migrar de Godot 3 para Godot 4. Portanto, se um código já escrito para Godot 4 recebe “sim” em api_mapping ou label_prototypes, pode ser interpretado como “já está em Godot 4, por que migrar novamente?”.
Por isso, os nomes dos slots foram alterados da seguinte forma.
| Tabela | Base do código | Significado do slot | Expectativa de geração |
|---|---|---|---|
docs_chunks |
Comum/Godot 3/Godot 4 | JSONL de evidência explicativa | sim |
docs_chunks |
Comum/Godot 3/Godot 4 | JSONL de explicação de outro código | não |
api_mapping |
Godot 3 | JSONL de necessidade de conversão | sim |
api_mapping |
Godot 4 | JSONL já aplicado | não |
api_mapping |
Comum | JSONL comum/desnecessário | não |
api_mapping |
Todos os códigos | JSONL de conversão irrelevante | não |
label_prototypes |
Godot 3 | JSONL de necessidade de conversão | sim |
label_prototypes |
Godot 4 | JSONL já aplicado | não |
label_prototypes |
Comum | JSONL comum/desnecessário | não |
label_prototypes |
Todos os códigos | JSONL de conversão irrelevante | não |
Graças a esse critério, “sim/não” deixou de ser apenas uma avaliação de relevância e passou a ser uma decisão alinhada ao propósito de cada tabela.
Separação entre código de geração e código alvo da verificação
A mudança mais importante hoje está aqui.
Na implementação inicial, um slot era verificado apenas em relação ao seu próprio código.
JSONL criado com código Godot 3
→ Verificado apenas no código Godot 3
JSONL criado com código Godot 4
-> Verificado apenas no código do Godot 4Mas a validação realmente necessária é mais ampla do que isso.
Quando um JSONL criado com código Godot 3 for anexado ao código Godot 4, também deve resultar em não. Por outro lado, também é necessário verificar qual resultado ocorre quando um JSONL criado com código Godot 4 é anexado ao código Godot 3. Só assim será possível encontrar o problema em que as strings source/target se misturam e retornam incorretamente sim.
Então o botão foi dividido de um para dois.

Agora cada slot da seção de separação de versão pode executar todas as verificações a seguir.
JSONL gerado com código Godot 3
-> Verificação de código Godot 3
-> Verificação de código Godot 4
JSONL gerado com código Godot 4
-> Verificação de código Godot 3
-> Verificação de código Godot 4Dentro da ferramenta, isso é dividido da seguinte forma.
| Valor | Significado |
|---|---|
slot.versionKey |
Versão do código usada ao criar o JSONL |
sourceVersionKey |
Versão de referência usada para gerar o JSONL enviado à API de validação |
targetVersionKey |
Versão do código que será realmente usada na validação |
slot.verifications.godot3 |
Resultado da validação deste JSONL anexado ao código Godot 3 |
slot.verifications.godot4 |
Resultado da validação deste JSONL anexado ao código Godot 4 |
Critério de cálculo da resposta esperada
Os resultados da validação ainda são recebidos do Qwen como sim ou não. Contudo, a resposta esperada agora não é calculada apenas a partir de um slot, mas considerando tabela + versão de referência do JSONL + versão alvo da validação + natureza do slot.
| Caso | Resposta esperada |
|---|---|
Verificar o JSONL de justificativa docs_chunks na mesma versão de código |
sim |
Verificar o JSONL de justificativa docs_chunks em versão de código oposta |
não |
JSONL de justificativa de código diferente para docs_chunks |
não |
Verificar o JSONL que requer conversão api_mapping/label_prototypes (base Godot 3) no código Godot 3 |
sim |
Verificar o JSONL que requer conversão api_mapping/label_prototypes (base Godot 3) no código Godot 4 |
não |
JSONL já aplicado api_mapping/label_prototypes (base Godot 4) |
não |
JSONL comum/desnecessário api_mapping/label_prototypes (base código comum) |
não |
| JSONL de conversão irrelevante | não |
Esse critério serve mais como um ponto de depuração para observar onde o pareamento de justificativas do Qwen está falhando, do que como um padrão final de avaliação.
Mudança no prompt de validação
O prompt de validação agora inclui duas informações de versão.
JSONL_GENERATED_FROM_CODE_VERSION:
godot3
VERIFY_TARGET_CODE_VERSION:
godot4Assim o motivo de inserir isso é evitar que o Qwen responda “sim” apenas porque target_api no JSONL corresponde ao código atual.
Nos blocos api_mapping e label_prototypes o seguinte critério é importante:
source_api,source_pattern,input_pattern,before_code,required_when_seen_in_codeprecisam estar presentes no código atual para que a resposta seja sim- Se apenas
target_api,after_codeou a forma recomendada do alvo coincidirem com o código atual, isso indica que já está aplicado, portanto a resposta é não - Quando indica que não há necessidade de conversão, como
signature_stable,no_change,common, a resposta é não - Mesmo que o JSONL de migração esteja anexado a código Godot 4 ou a código de sintaxe comum, se não for necessária conversão adicional, a resposta é não
Registro de teste de 50 itens
1/50 Inicialização da função _ready() e definição do tamanho da viewport
No dia 3 de julho, o primeiro dos 50 itens de teste foi verificado primeiro. Esse item foi rotulado como código comum, e o código de referência era o seguinte.
func _ready():
var vp_size = get_viewport().get_visible_rect().size
position = Vector2(vp_size.x / 2, vp_size.y / 2)No início, o slot de respostas incorretas de docs_chunks foi chamado de JSONL de descrição irrelevante. Contudo, ao testar na prática, percebeu‑se que esse nome era impreciso. Esse slot não serve para gerar deliberadamente JSONL estranho ou errado, mas para inserir descrições de documentação oficial que o Retriever pode trazer como candidato de busca, permitindo verificar se o Qwen filtra corretamente na validação final.
Portanto, o significado desse slot foi reorganizado como JSONL de descrição de outro código.
No teste, o JSONL problemático descrevia Viewport.get_visible_rect e _ready(), mas o conteúdo real tratava de áreas seguras, dimensionamento de UI, $Label, $Button.rect_position e outras operações de código diferentes. O SOURCE_CODE lê o tamanho da viewport e move a position do nó atual para o centro da tela; assim, mesmo que algumas APIs coincidam, não se trata de evidência direta.
A resposta esperada era “não”, porém o Qwen retornou “sim”. O motivo foi que o prompt de validação interpretava “correspondência exata com a string/API” de forma muito ampla, aceitando descrições de documentos que continham a mesma API como evidência direta.
Alterações realizadas
- O nome do slot de respostas incorretas de
docs_chunksfoi alterado de JSONL de descrição irrelevante para JSONL de descrição de outro código. - No prompt de geração de JSONL, esse slot foi definido como “uma descrição de documentação oficial que pode compartilhar algumas APIs/temas com o candidato de busca, mas que na verdade explica o comportamento de outro código”.
- No prompt de validação, o critério de “sim” para
docs_chunksfoi reforçado: não basta a simples correspondência de strings de API, mas é necessário que o objetivo central do código, o objeto alvo e o resultado final correspondam diretamente. - Mesmo que a mesma API ou método apareça, se o JSONL descreve um objetivo, objeto ou resultado diferentes, ele será tratado apenas como candidato de busca e a resposta deve ser “não”.
- Os rótulos e textos de pré‑visualização da UI frontal foram ajustados de acordo com esse critério.
- Foi adicionado um teste em
core.test.jspara garantir que esse critério permaneça nos prompts.
2/50 _process(delta) loop de atualização por quadro
No dia 3 de julho, o item 2 foi validado. Esse item foi rotulado pelo Qwen como código comum.
Resumo da rotulagem:
label: _process(delta) atualização por quadro
reason: Nos Godot 3 e 4, a assinatura e a forma de chamada da função _process(delta) são as mesmas, e não há diferença sintática ao escrever lógica por quadro.A verificação resultou em correspondência entre as respostas esperadas e as de todos os 6 slots.
| Item | Valor |
|---|---|
| Número de slots | 6 |
| Passou | 6 |
| Não correspondência | 0 |
Este item registra um caso em que, na gramática comum, docs_chunks recebeu “sim” como justificativa explicativa, enquanto api_mapping e label_prototypes receberam “não” por serem transformações comuns/desnecessárias ou irrelevantes, e o fluxo funcionou corretamente.
3/50 Processamento de entrada de movimentação do jogador
O item 3 foi rotulado por Qwen como código de separação de versão.
Resumo da rotulagem:
syntax_scope: separate
label: Entrada de movimento do jogador
reason: A verificação de entrada em si é semelhante, mas devido à introdução do Input.get_vector() no Godot 4 e à mudança na assinatura de move_and_slide() do CharacterBody2D, a estrutura do código precisa ser separada.
godot3_focus: Herança de KinematicBody2D, cálculo manual de velocity.x/y e chamada de move_and_slide(up_direction)
godot4_focus: Herança de CharacterBody2D, simplificação do movimento diagonal com Input.get_vector() e remoção de parâmetros de move_and_slide()Resultado da verificação:
| Item | Valor |
|---|---|
| Número de slots | 12 |
| Número de verificações | 24 |
| Passou | 20 |
| Inconsistências | 4 |
Inconsistências:
| Slot | Alvo da verificação | Esperado | Resposta | Observação |
|---|---|---|---|---|
godot3:api_mapping:positive |
Código Godot 4 | Não | Sim | O JSONL de conversão baseado no padrão Godot 3 foi anexado ao código Godot 4, mas ainda resultou em “Sim”. Se já estiver no formato Godot 4, mesmo que haja explicação de conversão, não deve ser alvo de migração agora. |
godot3:label_prototypes:positive |
Código Godot 4 | Não | Sim | label_prototypes · conversão necessária JSONL deve ser “Sim” apenas quando o código atual ainda usa o padrão anterior. Se aparecer “Sim” ao ser anexado ao código Godot 4, isso indica “já está em Godot 4, mas ainda pede migração”, o que é problemático. |
godot3:label_prototypes:negative |
Código Godot 4 | Não | Sim | Um JSONL de conversão irrelevante deve ser “Não” tanto para código Godot 4 quanto para Godot 3, caso a conversão não se aplique realmente ao código. |
godot4:label_prototypes:negative |
Código Godot 3 | Não | Sim | Quando um JSONL de conversão irrelevante criado para Godot 4 é anexado ao código Godot 3 e resulta em “Sim”, isso também está errado. A pergunta de verificação deve ser “Devo aplicar esta conversão a este CÓDIGO_FONTE?” e não “Qual o grau de relevância?”. |
Observação do prompt:
Na busca híbrida, é natural que um trecho de código e um candidato JSONL semelhante apareçam juntos. Portanto, o prompt de verificação deve determinar se o candidato de busca realmente justifica a aplicação ao CÓDIGO_FONTE atual. As três inconsistências acima mostram que a pergunta não estava suficientemente fixa, levando o Qwen a interpretar api_mapping e label_prototypes como correspondência ampla de relevância, e não como necessidade de migração.
Em particular, no caso 3 surgiram os seguintes problemas:
- Se um nome de função como
move_and_slide, que pode aparecer tanto em Godot 3 quanto em Godot 4, for correspondido isoladamente, o Qwen pode tender a responder “Sim”. - Quando um JSONL baseado no padrão Godot 3 é anexado a código Godot 4 que já está na versão modificada,
label_prototypes · conversão necessárianão deve resultar em “Sim”. - Quando um JSONL de conversão irrelevante para Godot 4 é anexado a código Godot 3, também não deve resultar em “Sim” se a conversão não for realmente aplicável.
- O ponto crucial não é o método de geração do JSONL, mas a pergunta de verificação. Deve‑se determinar se o código atual está antes da mudança, já foi mudado, ou se trata‑se de uma conversão totalmente diferente.
Assim, o critério do prompt foi ajustado da seguinte forma:
- A pergunta de verificação foi alterada de “JSONL e código são relacionados?” para “Devo aplicar uma migração ao CÓDIGO_FONTE atual com base neste JSONL?”.
- Se o CÓDIGO_FONTE já estiver no formato alvo Godot 4, mesmo que o JSONL pareça relacionado à explicação da migração, deve‑se indicar “Não”, pois já está aplicado.
label_prototypes · conversão necessáriadeve ser marcado como “Sim” apenas quando o CÓDIGO_FONTE atual ainda usa o padrão anterior, com a mesma composição de argumentos e padrão de chamada.- JSONL de conversão irrelevante deve ser marcado como “Não” mesmo que o alvo da verificação seja código Godot 3, caso a conversão não seja realmente aplicável ao CÓDIGO_FONTE.
- Cada campo do JSONL fornece contexto de julgamento. Na fase de verificação, esse contexto deve ser usado para determinar se o CÓDIGO_FONTE está antes ou depois da mudança.
- Como
source_apietarget_apipodem compartilhar o mesmo nome oumatch_termspode conter termos de origem/target, a simples correspondência de um nome de função ou de termos amplos não deve ser considerada “Sim”. - Mesmo que o nome da função coincida, apenas se o padrão de argumentos, tratamento de retorno, nós herdados, estrutura de código circundante etc., descritos no JSONL como padrão pré‑mudança, estiver presente no CÓDIGO_FONTE, então a resposta deve ser “Sim”.
- Se
JSONL_GENERATED_FROM_CODE_VERSIONeVERIFY_TARGET_CODE_VERSIONforem diferentes, deve‑se primeiro distinguir se o CÓDIGO_FONTE está na versão pré‑mudança ou já na versão pós‑mudança.
4/50 Aplicação de velocidade e aceleração do jogador
O item 4 também foi rotulado pelo Qwen como código de separação de versão.
Resumo da rotulagem:
syntax_scope: separate
label: Aplicação da velocidade e aceleração de movimento do jogador
reason: No Godot 4, o nó de física foi alterado de KinematicBody para CharacterBody, e a assinatura de move_and_slide() mudou para passagem de argumentos, o que altera a estrutura do código.
godot3_focus: Atribuir velocidade à propriedade velocity e chamar move_and_slide(), usando KinematicBody2D/3D
godot4_focus: Passar o argumento com move_and_slide(velocity), usar CharacterBody2D/3D, e aplicar aceleração usando lerp() ou move_toward()Resultado da verificação:
| Item | Valor |
|---|---|
| Número de slots | 12 |
| Número de verificações | 24 |
| Passou | 23 |
| Incompatibilidade | 1 |
Incompatibilidade:
| Slot | Alvo da verificação | Esperado | Resposta | Observação |
|---|---|---|---|---|
godot3:api_mapping:positive |
Código Godot 4 | Não | Sim | Quando o JSONL de move_and_slide do Godot 3 foi inserido no código Godot 4, a resposta também foi Sim. Mesmo que já esteja no formato Godot 4, a explicação da conversão não torna o código atual um alvo para migração. |
Observação do prompt:
As 4 incompatibilidades foram menos que as 3, mas a causa é a mesma. Quando os nomes das funções de api_mapping são iguais ou semelhantes, o Qwen pode julgar que “este JSONL descreve a mudança da função” e dar Sim por uma avaliação ampla de relevância. Contudo, o que esse ferramenta precisa não é um julgamento de relevância, mas sim determinar se há necessidade de migração para o código atual.
Portanto, com base nas observações até o item 4, o prompt de verificação foi reforçado para considerar não apenas a correspondência simples de nomes de API, mas também:
- Se o código atual realmente contém o padrão antes da mudança descrito no JSONL
- Mesmo com o mesmo nome de função, se os argumentos de chamada e o tratamento de valores de retorno correspondem ao código antes da mudança
- Se o código alvo da verificação já está na forma pós-mudança, a necessidade de migração deve ser
Não - Se um JSONL de conversão irrelevante não sobe como
Simapenas por relevância superficial
Limite máximo de velocidade do jogador 5/50
O item 5 foi rotulado pelo Qwen como código de separação de versão.
Resumo da rotulagem:
syntax_scope: separate
label: Limite máximo de velocidade do jogador
reason: Devido à mudança de nome de classe entre KinematicBody2D do Godot 3 e CharacterBody2D do Godot 4, bem como diferenças na assinatura do método move_and_slide() e na forma de transmissão da velocidade, é necessário código separado.
godot3_focus: Herança de KinematicBody2D, atribuição da velocidade a self.velocity seguida de chamada a move_and_slide(), limitação de velocidade com limit_length()
godot4_focus: Herança de CharacterBody2D, atribuição da velocidade à variável velocity e transmissão explícita via move_and_slide(velocity), aplicação de limit_length()Gerado fluxo de código:
| Versão | Fluxo principal do código |
|---|---|
| Godot 3 | Cria o vetor de entrada com Input.get_action_strength(), atribui novamente o valor retornado como velocity = move_and_slide(), e se velocity.length() > max_speed normaliza para limitar a velocidade máxima. |
| Godot 4 | Escreve‑se usando extends CharacterBody2D, Input.get_vector(), velocity = direction * max_speed, velocity = velocity.limit_length(max_speed), fluxo move_and_slide(). |
Resultado da validação:
| Item | Valor |
|---|---|
| Número de slots | 12 |
| Quantidade de validações | 24 |
| Passou | 23 |
| Inconsistências | 1 |
Inconsistência:
| Slot | Alvo da validação | Esperado | Resposta | Observação |
|---|---|---|---|---|
godot3:docs_chunks:negative |
Código Godot 3 | Não | Sim | Quando um candidato docs_chunks de explicação de código foi anexado ao código Godot 3, a resposta foi “Sim”. Como pertencem à mesma família Godot 3, com pistas como move_and_slide e tratamento de velocidade/colisão semelhantes, parece que o Qwen considerou o candidato de busca como justificativa direta da explicação. |
Observação do prompt:
O caso 5 se aproxima de uma situação que pode realmente ocorrer em busca híbrida. Mais tarde, ao buscar no banco de dados, não aparecerá apenas um JSONL totalmente fora de contexto, mas também candidatos semelhantes da mesma API ou da mesma categoria de movimentação/velocidade. Nesse momento, o prompt de validação deve verificar “esse JSONL descreve diretamente o comportamento real do SOURCE_CODE atual?” em vez de “é um candidato de busca semelhante?”.
No caso 5, api_mapping e label_prototypes funcionaram conforme o esperado em ambas as validações Godot 3/4. Em particular, o fato de JSONLs já aplicados ao código Godot 4 ou de natureza no_change, pattern_validation terem sido classificados como “Não” indica um alívio parcial dos problemas de julgamento de migração observados nos casos 3 e 4.
Por outro lado, docs_chunks ainda precisa de mais análise. Como docs_chunks trata de correspondência de justificativa explicativa e não de aplicação de migração, se apenas o nome da API ou pistas de versão coincidirem e resultarem em “Sim”, haverá ruído na fase de validação de candidatos de busca híbrida. Portanto, nos próximos prompts de validação, deve‑se confirmar de forma mais rigorosa se o objetivo, o objeto alvo e o estado resultante do SOURCE_CODE coincidem com a explicação fornecida no JSONL.
6~10/50 registro de validação adicional
Do item 6 ao 10, primeiro registre o resultado e, em seguida, corrija o prompt de validação. Nesta etapa, sem modificar o prompt, registre apenas em quais slots a ferramenta acerta ou erra.
Resumo geral:
| intervalo | número de slots | validações | aprovadas | discrepâncias |
|---|---|---|---|---|
| soma 6~10 | 54 | 102 | 97 | 5 |
Resumo por item:
| número | item | rótulo | distinção de versão | resultado da validação |
|---|---|---|---|---|
| 6 | criação e disparo de projétil ao clicar o mouse | criação e movimento/colisão de projétil ao clicar o mouse | separação de versão | 24/24 aprovadas |
| 7 | gerenciamento de movimento e tempo de vida (time‑to‑live) do projétil | gerenciamento de movimento e tempo de vida do projétil | separação de versão | 22/24 aprovadas, 2 discrepâncias |
| 8 | lógica de IA de rastreamento do jogador pelo inimigo (Enemy) | lógica de IA de rastreamento do jogador pelo inimigo | separação de versão | 21/24 aprovadas, 3 discrepâncias |
| 9 | lógica de velocidade e rotação do inimigo | lógica de velocidade e rotação do inimigo | separação de versão | 24/24 aprovadas |
| 10 | remoção do jogador quando sai da tela | remoção/ocultação do nó ao sair da tela | comum | 6/6 aprovadas |
Os itens 6, 9 e 10 produziram os resultados esperados conforme o padrão atual. No item 6, o fluxo de PackedScene.instance(), Input.is_mouse_button_pressed(1), get_viewport().get_mouse_position() do Godot 3 foi separado do fluxo instantiate(), InputEventMouseButton, get_global_mouse_position() do Godot 4, e as opções corretas/incorretas foram bem discriminadas. No item 9, as opções de separação de versão para movimento e rotação do inimigo também foram avaliadas conforme o esperado. O item 10 foi classificado como sintaxe comum; a manipulação fora da tela baseada em get_viewport_rect().size, global_position, hide() recebeu “sim” nas explicações da documentação e “não” para migração de api_mapping/label_prototypes.
Discrepâncias:
| número | slot | alvo da validação | esperado | resposta | observação |
|---|---|---|---|---|---|
| 7 | godot3:api_mapping:positive |
código Godot 4 | não | sim | O JSONL de conversão baseado no Godot 3 foi validado contra código Godot 4 e ainda retornou “sim”. Ainda há confusão entre “é uma conversão que deve ser aplicada ao código atual?” e “é uma conversão relacionada?”. |
| 7 | godot3:label_prototypes:positive |
código Godot 4 | não | sim | Um protótipo que descreve padrões de uso do lado fonte do Godot 3 também recebeu “sim” para código Godot 4. Se o código já foi convertido, a necessidade de migração deveria ser “não”. |
| 8 | godot4:docs_chunks:positive |
código Godot 3 | não | sim | Evidências da documentação do Godot 4 foram marcadas “sim” também para código Godot 3, provavelmente porque o tema de rastreamento/movimento ou APIs semelhantes levaram a uma avaliação como evidência direta. |
| 8 | godot4:docs_chunks:negative |
código Godot 3 | não | sim | Outro candidato de documentação para explicação de código também recebeu “sim” para Godot 3. Quando um candidato semelhante aparece na busca híbrida, é preciso julgar mais claramente se o propósito e o resultado são diferentes. |
| 8 | godot4:docs_chunks:negative |
código Godot 4 | não | sim | Mesmo dentro da mesma família Godot 4, um candidato de documentação diferente deveria ser “não”, mas retornou “sim”. A validação de docs_chunks deve considerar mais o propósito real do código‑fonte do que apenas o nome da API. |
Observação:
Ao analisar os itens 6‑10, percebe‑se um sinal geral de melhoria. Das 102 validações, 97 coincidiram com o esperado, e os itens 6, 9 e 10 foram todos aprovados. Em particular, no item 10 (sintaxe comum), todos os candidatos de api_mapping e label_prototypes foram classificados como “não”, indicando que a política de não anexar justificativas de migração a código comum está funcionando.
As discrepâncias restantes dividem‑se em duas categorias. A primeira, como no item 7, ocorre quando justificativas de migração baseadas no Godot 3 são marcadas “sim” para código Godot 4. Nesse caso, é preciso perguntar de forma mais clara se o código atual já está na forma convertida ou ainda precisa ser alterado. A segunda, como no item 8, acontece quando candidatos de docs_chunks são marcados “sim” devido a temas ou APIs semelhantes. É necessário distinguir se a evidência descreve diretamente o comportamento real do código‑fonte ou se é apenas um candidato de busca semelhante.
É importante notar que a solução não consiste em bloquear strings ou candidatos específicos. Quando os JSONL forem inseridos no banco de dados e recuperados por busca híbrida, é normal que candidatos parecidos, porém diferentes, apareçam juntos. Portanto, as correções futuras devem focar em aprimorar o prompt de validação para que ele avalie com mais precisão a relação entre o código‑fonte atual e os candidatos retornados, em vez de filtrar manualmente.
Reforço do prompt de validação aplicado após o registro:
- Em
docs_chunks, quando a versão de geração do JSONL difere da versão alvo da validação, primeiro verifica‑se se o JSONL explica o comportamento do código da versão alvo. - Mesmo com versões diferentes, se o candidato descreve explicitamente APIs/comportamentos comuns, pode ser “sim”; porém, se descreve diferenças estruturais ou de nós/APIs entre versões, verifica‑se se corresponde ao comportamento do código atual.
- Em
api_mappingelabel_prototypes, primeiro determina‑se se o código‑fonte atual está antes ou depois da migração, ou se é irrelevante, ou se a migração é desnecessária. - “Sim” só é permitido quando o código‑fonte atual ainda está na forma pré‑migração e a conversão descrita pelo JSONL deve ser aplicada agora.
- Esse reforço não trata de strings específicas, mas fortalece o procedimento de avaliação dos candidatos trazidos pela busca híbrida com base no código atual.
Verificação dos resultados da validação
Os resultados da validação são exibidos separadamente por versão abaixo de cada slot.

Com esse método, é possível ver imediatamente o que ocorre dentro de um único slot.
Godot 3 código verificação antes / resposta / expectativa / correspondência
Godot 4 código verificação antes / resposta / expectativa / correspondênciaAnteriormente, apenas “este JSONL está correto/incorreto” era exibido. Agora, também é possível ver “se está correto/incorreto quando anexado a determinado código”.
Problemas resolvidos pela ferramenta atual
| Método anterior | Método atual |
|---|---|
| Solicitar código e JSONL diretamente ao chatbot Qwen | Acumular, na interface web, rótulo, código, JSONL e resultado da validação por item |
| Diferenciar apenas JSONL correto/incorreto | Separar por justificativa da explicação, explicação de outro código, necessidade de conversão, já aplicado, comum/desnecessário, conversão irrelevante |
| JSONL do Godot 3 era validado apenas em código Godot 3 | Possibilidade de validar em códigos tanto do Godot 3 quanto do Godot 4 |
| Copiar manualmente o resultado para lembrar | Armazenar, por slot, resposta bruta, prompt e resultado da validação |
| Dificuldade em rastrear a causa da falha | Ver imediatamente em qual slot e em qual alvo de validação ocorreu o erro |
| Teste de 50 itens era praticamente trabalho manual | Oferecer carregamento de amostras, adição/remoção de itens e botões de geração completa/validação completa |
Mudança na produtividade de desenvolvimento
Antes de criar a ferramenta, para realizar um único teste era necessário fazer o seguinte manualmente.
1. Explicação dos itens de teste para o Qwen
2. Solicitação de código para Godot 3
3. Solicitação de código para Godot 4
4. Solicitação de JSONL de respostas corretas/incorretas para docs_chunks
5. Solicitação de JSONL de respostas corretas/incorretas para api_mapping
6. Solicitação de JSONL de respostas corretas/incorretas para label_prototypes
7. Validar cada JSONL novamente junto com o SOURCE_CODE
8. Registrar manualmente os resultados de sim/não
9. Comparar mentalmente se o valor esperado está corretoAgora o mesmo fluxo está fixado na tela.
1. Clique no item
2. Criar rótulo de IA
3. Gerar código comum ou Godot 3/4
4. Gerar por slot JSONL
5. Validar código Godot 3 / Validar código Godot 4
6. Verificar resultados e prompt/respostaParticularmente, a parte em que a produtividade melhorou está mais próxima de “não ficar confuso” do que de “produzir muito rapidamente”. Nessa tarefa, é mais importante que o critério de julgamento não oscile do que a quantidade simples gerada. Com a ferramenta, o seguinte ficou mais fácil.
- Fixar primeiro se é gramática comum ou separação por versão
- Ver continuamente na tela o uso de JSONL por tabela
- Separar as expectativas de critério de geração dos resultados de verificação reais
- Verificar cruzadamente o mesmo JSONL no código Godot 3/4
- Consultar imediatamente o prompt e a resposta bruta dos slots que falharam
- Reduzir o estado que a pessoa precisa lembrar ao repetir 50 itens
Problemas ainda em aberto
Esta ferramenta ainda não é o avaliador final. No momento, ela é uma ferramenta de depuração.
Os problemas em aberto são os seguintes.
- A justificativa de
docs_chunkspode, em alguns casos, ser aceita como explicação comum mesmo que a versão seja diferente. - Em
api_mapping, se as strings source/target estiverem ambas no JSONL, o Qwen pode ver apenas a string target e responder “sim”. - Em
label_prototypes, a distinção de padrões before/after pode ser mais importante que a simples correspondência de strings. - O cálculo da resposta esperada atual serve como critério de depuração; posteriormente, o cálculo real de score/F1 precisará ser refinado separadamente.
- A seleção de candidatos de busca e a avaliação do prompt de verificação são difíceis de separar imediatamente apenas pelos resultados.
Conclusão atual
Em 28 de junho, a sensação era “vamos fazer os 50 testes manualmente”. Na prática, havia muitos eixos a serem testados, e quando gramática comum, separação por versão, critério de geração e versão de verificação se misturavam, ficava confuso rapidamente.
Ao criar a ferramenta em 30 de junho, esse problema foi bastante organizado. Agora, ao invés de apenas marcar o JSONL gerado pelo Qwen como correto/incorreto, podemos ver em qual código foi gerado e em qual código foi verificado.
Esta ferramenta pode ser usada da mesma forma quando os resultados reais de busca de docs_chunks, api_mapping e label_prototypes forem adicionados. Ou seja, tornou‑se uma ferramenta base que pode ser estendida não só para dados de demonstração manual, mas também para a verificação de resultados de busca em bancos de dados.