Observação da Seleção de Repositório de Teste Baseada no Status de Coleta de JSONL

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

Objetivo

Com base nos JSONL gerados até o momento, determinar qual tipo de repositório Godot deve ser clonado primeiro para teste.

Aqui o objetivo não é “escolher aleatoriamente um repositório famoso”. Primeiro analisamos em quais áreas o acúmulo de evidências no banco de dados está forte e em quais ainda é fraco, e então escolhemos o tipo de repositório que permitirá ao Retriever encontrar efetivamente as evidências.

Os critérios de análise são os dois arquivos a seguir.

/Users/joyeongjin/make_md/work/web_jsonl/docs_chunks/docs_chunks.jsonl
/Users/joyeongjin/make_md/work/web_jsonl/api_mapping/api_mapping.jsonl

state.json contém o estado da conversão, o prompt de classificação e a depuração da resposta original, mas como também pode incluir valores de configuração de tempo de execução, não copiamos o texto original para documentos públicos. Neste diário de observação, deixamos apenas as estatísticas e julgamentos do JSONL.

Estado do Snapshot

A conversão, com base no momento da observação, ainda está em andamento.

docs_chunks.jsonl: 153 records  
api_mapping.jsonl: 117 records  
label_prototypes.jsonl: Ainda não há arquivo criado

O estado da conversão da web era aproximadamente o seguinte fluxo.

done: 132 files
pending: 1425 files
deferred: 11 files
converting: 2 files
classified: 144 files

Portanto, este documento não é uma conclusão final, mas “o critério de seleção de relatórios de primeira fase baseado em JSONL coletado até o momento”.

Observação de docs_chunks

docs_chunks tinha 153 registros gerados.

A composição é aproximadamente a seguinte.

class_reference: 127
about: 26

Chunks foram criados a partir de 95 arquivos Markdown originais, e 129 registros continham símbolos de API. Houve 36 registros que continham blocos de código.

Até agora, as áreas mais proeminentes em docs_chunks são as seguintes:

- Categoria de Animação  
- Categoria de Áudio  
- Categoria de Câmera  
- Categoria de Canvas/CanvasItem  
- APIs básicas como Array/Callable/GlobalScope  
- Parte do AnimatedSprite2D  
- Parte do AStar/AStarGrid2D

Por outro lado, as áreas que ainda parecem fracas são as seguintes.

KinematicBody / CharacterBody migration  
modo de chamada de move_and_slide  
conversão de yield -> await  
conversão de Color8 -> Color.from_rgba8  
TileMap migration  
RigidBody / physics body migration  
HTTPRequest / networking

Ou seja, no momento atual o docs_chunks pode ser usado até certo ponto como “base de explicação da documentação oficial do Godot 4”, mas ainda não se pode dizer que há evidências suficientes acumuladas para a migração típica de um jogo de ação 2D do Godot 3 para o Godot 4.

Observação do mapeamento da API

api_mapping tinha 117 registros criados.

Os tipos de alteração são divididos da seguinte forma.

rename_or_replacement: 82
behavior_change: 24
deprecated: 11

Todos os registros de confiança estavam em verified_from_docs.

Até agora, a área de mapeamento que parece forte é a seguinte.

Diferenças de método e comportamento do Array  
Família AnimationPlayer / AnimationMixer / AnimationTree / AnimationNode  
Família AudioStream / AudioEffect / AudioEffectSpectrumAnalyzer  
Família Camera / Camera3D / CameraAttributes  
Família CanvasItem draw/modulate  
Algumas funções e constantes obsoletas do GlobalScope  
Algumas partes do AStarGrid2D

Por exemplo, o JSONL atual contém evidências com as seguintes características.

Camera -> Camera3D  
Camera.get_transform -> Camera3D.get_camera_transform  
Configuração de exposição do WorldEnvironment -> série CameraAttributes  
Algumas funcionalidades do AnimationPlayer -> separação do AnimationMixer  
AnimationNode._process -> AnimationNodeExtension._process_animation_node  
AudioEffectLimiter -> AudioEffectHardLimiter  
Alteração no comportamento de Array.sort  
Diferença no nome C# de Array.has  
Alteração no comportamento de CanvasItem.modulate  
Alteração no comportamento de CanvasItem.draw_string / draw_rect

Esta frase significa que, se você fizer um teste de migração agora, há uma grande chance de que o código relacionado a Camera, Animation, Audio, CanvasItem e Array seja mais problemático do que o KinematicBody2D ou move_and_slide de um 2D platformer.

Observação de label_prototypes

No snapshot atual não existe o arquivo label_prototypes.jsonl.

Portanto, neste estágio, falta evidência para testar, como exemplo, “a mudança completa na forma de usar funções” com o Retriever. Embora o api_mapping contenha behavior_change, isso ainda está mais próximo de evidências de alterações de API extraídas da documentação do que de um “exemplo completo de padrão de uso”.

Assim, ao escolher um repositório agora, é melhor focar em um que verifique as áreas já cobertas por docs_chunks e api_mapping, em vez de um que teste ativamente label_prototypes.

Tipo de repositório ideal para clonar imediatamente

Com base nos critérios de JSONL, o repositório mais adequado para clonar primeiro é aquele que é pequeno, tem versão do Godot claramente especificada e utiliza APIs que já aparecem no mapeamento atual em código real.

A prioridade é a seguinte:

1ª prioridade: exemplo pequeno baseado no Godot 3 que usa Camera/WorldEnvironment/Animation

O melhor candidato para o primeiro teste são repositórios de exemplo pequenos do Godot 3 que realmente utilizam recursos como Camera, WorldEnvironment, AnimationPlayer, AnimationTree, desenho de CanvasItem e AudioEffect.

Isso porque o api_mapping já contém evidências relacionadas a esses recursos.

Camera -> Camera3D
Camera.get_transform -> Camera3D.get_camera_transform
configuração de exposição do WorldEnvironment -> CameraAttributes
AnimationPlayer -> alterações relacionadas ao AnimationMixer
alterações na família AnimationNode / AnimationTree
CanvasItem draw/modulate alterações de comportamento
alterações na família AudioEffect / AudioStream

Se você clonar este repositório, fragmentos de AST revelarão pistas como Camera, WorldEnvironment, AnimationPlayer, CanvasItem, AudioEffect, e é provável que o Retriever encontre evidências no JSONL atual.

O objetivo do teste também é claro.

Trecho de código Godot 3  
-> trecho AST  
-> pesquisa api_mapping  
-> pesquisa auxiliar docs_chunks  
-> pré-visualização do prompt de julgamento LLM

Ou seja, “é possível verificar imediatamente com os dados atuais se este código usa a API do Godot 3 e com que base ele deve ser alterado para o Godot 4”.

2ª prioridade: pequeno exemplo de Animação/Áudio/Câmera baseado no Godot 4

O segundo candidato é um pequeno repositório escrito para o Godot 4.

Esse repositório é útil mais para confirmar “a explicação do código nativo do Godot 4” e “se o Retriever não está trazendo migrações equivocadas do Godot 3”, do que para validar a migração.

Atualmente o docs_chunks contém bastante documentação oficial sobre Animação, Áudio, Câmera, CanvasItem e Array. Assim, ao inserir trechos de código do Godot 4, fica fácil observar se a explicação se baseia principalmente nos docs_chunks.

Seria ideal que esse repositório tivesse as seguintes características.

Pequeno projeto completo com project.godot  
Cerca de 5 a 30 arquivos .gd  
Arquivos .tscn incluídos  
Uso de AnimationPlayer ou AnimationTree  
Uso de AudioStreamPlayer ou AudioEffect  
Uso de Camera2D/Camera3D  
Uso de APIs básicas como Array/Callable  
Não há muitos assets de grande volume

3ª prioridade: Exemplos do mesmo tema divididos entre Godot 3 e Godot 4

Se possível, o melhor exemplo é aquele que oferece o mesmo tema tanto para a versão Godot 3 quanto para a versão Godot 4.

Por exemplo, se um mesmo exemplo de câmera/animação/áudio possui um branch para Godot 3 e outro para Godot 4, fica mais fácil comparar a avaliação do Retriever com a do LLM.

Esses repositórios são úteis para verificar isso.

Se o api_mapping está funcionando corretamente no fragmento do Godot 3  
Se a justificativa da explicação de docs_chunks está correta no fragmento do Godot 4  
Como mostrar as diferenças de código entre versões da mesma funcionalidade no prompt do LLM  
Como acumular a avaliação de godot3/godot4/mixed por projeto

Clone agora mesmo? Natureza de repositório ambígua

Considerando apenas o JSONL, repositórios com a seguinte natureza ainda são ambíguos para o primeiro teste.

Plataforma 2D típica do Godot 3

KinematicBody2D, move_and_slide, yield, TileMap, Color8 e outras pistas abundantes em um platformer 2D do Godot 3 serão necessárias mais tarde.

Entretanto, no snapshot atual essas pistas quase não aparecem no JSONL. Inserir imediatamente esse tipo de repositório pode fazer com que o Retriever não encontre evidências ou traga evidências de Animation/Audio/Camera que não são relevantes.

Portanto, esse tipo de repositório é um “bom candidato para teste final”, mas não é um “primeiro candidato ideal para validação imediata com JSONL”.

Repositório de jogo grande

Um repositório de jogo grande, com muitos assets e centenas de arquivos .gd, ainda é prematuro.

O que precisamos agora não é lançar um grande projeto ao modelo, mas rastrear até o fim quais fragmentos de código buscam quais evidências no JSONL. Repositórios grandes tornam a depuração muito ampla, dificultando a visualização de por que certas evidências foram buscadas.

O primeiro teste deve usar exemplos pequenos e com funcionalidades bem definidas.

Repositório centrado em C#

O JSONL atual contém menções a C# e algumas diferenças de nomenclatura, mas o fluxo geral foi projetado com base em AST de GDScript e fragmentos .gd.

Assim, um repositório Godot centrado em C# não é adequado como primeiro teste nesta fase.

Repositório centrado em GDExtension / plugin nativo

Repositórios focados em GDExtension, C++, Rust binding ou plugin nativo ainda são prematuros.

O objetivo atual é dividir .gd, .tscn, project.godot de projetos Godot em fragmentos e observar o fluxo em que o Retriever busca evidências na documentação oficial. Repositórios centrados em extensões nativas mudam o eixo de análise.

Critérios de seleção de repositório

Com base nos critérios atuais, o candidato a clone deve atender às seguintes condições.

A versão do Godot deve ser verificável no README ou no project.godot  
O arquivo project.godot deve estar presente  
Um arquivo .gd deve estar presente  
É desejável que um arquivo .tscn esteja incluído  
Deve haver poucos assets de grande tamanho  
O escopo das funcionalidades deve ser pequeno e claro  
Deve haver código que se sobreponha à API presente no JSONL atual

As palavras‑chave que combinam bem com JSONL atualmente são as seguintes.

Camera
Camera3D
WorldEnvironment
CameraAttributes
AnimationPlayer
AnimationTree
AnimationNode
AnimationMixer
AudioStream
AudioEffect
CanvasItem
draw_string
draw_rect
modulate
Array.sort
Array.has
AnimatedSprite2D
AStar2D
AStarGrid2D

Por outro lado, como palavras‑chave ainda prematuras para serem usadas como critério principal no primeiro teste agora, são as seguintes.

KinematicBody2D
CharacterBody2D
move_and_slide
yield
await
Color8
TileMap
RigidBody2D
HTTPRequest
multiplayer
GDExtension

Julgamento

Com base nos JSONL coletados até agora, o primeiro alvo de clonagem seria o “pequeno repositório candidato à migração para Godot 3”. Contudo, não deve ser um platformer 2D comum, mas sim um projeto que realmente utilize as famílias Camera/WorldEnvironment/Animation/Audio/CanvasItem.

A razão é simples.

Atualmente o api_mapping já possui referências para Camera, Animation, Audio, CanvasItem e Array. Por outro lado, as pistas principais da migração de física 2D do Godot 3, como KinematicBody2D, move_and_slide, yield e TileMap, ainda quase não aparecem no JSONL atual.

Portanto, o fluxo de teste inicial mais realista é o seguinte.

# Pequeno exemplo de clonagem de Camera/Animation/Audio do Godot 3
-> Fragmentação de .gd e .tscn  
-> Busca de Retriever atualmente em JSONL  
-> Verificar se o hit de api_mapping está realmente relacionado ao código  
-> Visualizar a prévia do prompt que será inserido no LLM

Depois, é recomendável clonar um pequeno exemplo de Animation/Audio/Camera escrito em Godot 4 e gerar a explicação baseada em docs_chunks para verificar o fluxo de criação.

Finalmente, quando label_prototypes for gerado e houver evidências acumuladas de KinematicBody2D, move_and_slide, yield, Color8 e da família TileMap, será o momento adequado para clonar um repositório típico de Godot 3 – seja um platformer 2D ou um jogo de ação – e testar a decisão de migração.

Conclusão

O tipo de repositório a ser clonado imediatamente será definido a seguir.

1ª opção:  
    Exemplo pequeno e com versão clara do Godot 3  
    Alguns recursos reais de Camera / WorldEnvironment / AnimationPlayer / AnimationTree / Audio / CanvasItem  
    Inclui .gd, .tscn, project.godot  
    Os assets não são excessivamente grandes  

2ª opção:  
    Exemplo do Godot 4 que usa a mesma área  
    Utilizado para validar a qualidade da busca de explicação de código e docs_chunks, em vez de migração  

Em espera:  
    Plataforma 2D do Godot 3 centrada em KinematicBody2D / move_and_slide / yield / TileMap  
    Testes após acumular mais evidências de migração relacionadas a label_prototypes

Esta ordem parece ser a maneira mais eficiente de validar o JSONL coletado atualmente.