Journal d'observation de la sélection du dépôt de test basé sur l'état de collecte JSONL

Date de rédaction : 27 juin 2026

Objectif

En se basant sur les fichiers JSONL générés jusqu'à présent, déterminer quel type de dépôt Godot il est préférable de cloner en premier pour les tests.

L'objectif n'est pas de « choisir n'importe quel dépôt célèbre ». Il s'agit d'examiner d'abord où les preuves accumulées dans la base de données sont fortes et où elles sont encore faibles, puis de choisir un type de dépôt dont le récupérateur pourra réellement trouver des preuves.

Les critères d'analyse sont les deux fichiers suivants.

/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 contient l'état de la conversion, le prompt de classification, le débogage de la réponse originale, mais il peut également être mélangé avec des valeurs de configuration d'exécution ; ainsi, le texte original n'est pas repris dans la documentation publique. Ce journal d'observation ne conserve que les statistiques JSONL et le jugement.

État du snapshot

La conversion basée sur le moment de l'observation est toujours en cours.

docs_chunks.jsonl: 153 records  
api_mapping.jsonl: 117 records  
label_prototypes.jsonl: Pas encore de fichier créé

L'état de la conversion Web était approximativement le flux suivant.

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

Ainsi, ce document n’est pas une conclusion finale mais le « critère de sélection du premier rapport basé sur les JSONL collectés jusqu’à présent ».

Observation de docs_chunks

docs_chunks a généré 153 enregistrements.

La composition est proche de ce qui suit.

class_reference: 127
about: 26

Des chunks ont été créés à partir de 95 fichiers Markdown originaux, et 129 enregistrements contenaient un symbole d'API. Il y avait 36 enregistrements avec un bloc de code.

Jusqu'à présent, les zones les plus visibles dans docs_chunks sont les suivantes.

- Animation série
- Audio série
- Caméra série
- Canvas/CanvasItem série
- API de base comme Array/Callable/GlobalScope
- Une partie d’AnimatedSprite2D
- Une partie d’AStar/AStarGrid2D

À l'inverse, les zones qui semblent encore faibles sont les suivantes.

Migration KinematicBody / CharacterBody  
Mode d'appel de move_and_slide  
Conversion de yield -> await  
Conversion de Color8 -> Color.from_rgba8  
Migration TileMap  
Migration RigidBody / physics body  
HTTPRequest / réseau

En d'autres termes, à l'heure actuelle, les docs_chunks peuvent être utilisés dans une certaine mesure comme « justification basée sur la documentation officielle de Godot 4 », mais il est encore difficile de dire que les preuves suffisantes d'une migration typique d'un jeu d'action 2D de Godot 3 vers Godot 4 ont été accumulées.

Observation de api_mapping

api_mapping a généré 117 enregistrements.

Les types de modifications sont répartis comme suit.

rename_or_replacement: 82
behavior_change: 24
deprecated: 11

La confiance de chaque enregistrement était dans verified_from_docs.

Jusqu’à présent, les zones de mappage qui semblent fortes sont les suivantes.

Différence entre les méthodes Array et leur fonctionnement  
Série AnimationPlayer / AnimationMixer / AnimationTree / AnimationNode

AudioStream / AudioEffect / AudioEffectSpectrumAnalyzer série  
Camera / Camera3D / CameraAttributes série  
CanvasItem draw/modulate série

## Portée globale : certaines fonctions et constante obsolète
### AStarGrid2D : partie

---

Par exemple, le JSONL actuel contient des preuves de ce type.

Camera -> Camera3D  
Camera.get_transform -> Camera3D.get_camera_transform  
Paramètre d'exposition WorldEnvironment -> série CameraAttributes  
Certaines fonctionnalités d'AnimationPlayer -> séparation d'AnimationMixer  
AnimationNode._process -> AnimationNodeExtension._process_animation_node  
AudioEffectLimiter -> AudioEffectHardLimiter  
Changement du comportement de Array.sort  
Différence de nom C# pour Array.has  
Changement du comportement de CanvasItem.modulate  
Changement du comportement de CanvasItem.draw_string / draw_rect

Cette phrase signifie que si l’on effectue immédiatement un test de migration, il est plus probable que le code lié à Camera, Animation, Audio, CanvasItem ou Array pose problème que le KinematicBody2D ou move_and_slide d’un jeu de plateforme 2D.

Observation de label_prototypes

Dans la capture actuelle, le fichier label_prototypes.jsonl est absent.

Par conséquent, à ce stade, il manque de preuves pour tester « l’exemple où la façon d’utiliser une fonction change complètement » avec le Retriever. Bien que api_mapping contienne un behavior_change, il s’agit davantage d’une justification d’un changement d’API extraite de la documentation que d’un véritable « exemple d’utilisation globale ».

Ainsi, lorsqu’on choisit un dépôt maintenant, il vaut mieux privilégier un dépôt qui vérifie d’abord les zones déjà couvertes par docs_chunks et api_mapping, plutôt qu’un dépôt qui teste activement label_prototypes.

Type de dépôt idéal à cloner immédiatement

Selon les critères JSONL, le meilleur dépôt à cloner en premier est « petit, avec une indication claire de la version de Godot, et qui utilise dans le code réel les API déjà présentes dans le mapping actuel ».

Les priorités sont les suivantes :

1ᵉʳ priorité : Exemple petit basé sur Godot 3 avec Camera/WorldEnvironment/Animation

Le meilleur candidat pour un premier test est un petit dépôt d’exemple Godot 3 qui utilise réellement des fonctionnalités telles que Camera, WorldEnvironment, AnimationPlayer, AnimationTree, le dessin CanvasItem, ou AudioEffect.

La raison en est que le api_mapping contient déjà les justifications correspondantes.

Camera -> Camera3D  
Camera.get_transform -> Camera3D.get_camera_transform  
WorldEnvironment réglage d'exposition -> CameraAttributes  
AnimationPlayer -> changements liés à AnimationMixer  
AnimationNode / AnimationTree changements de la série  
CanvasItem draw/modulate changements du comportement  
AudioEffect / AudioStream changements de la série

Si vous clonez ce dépôt, des indices tels que Camera, WorldEnvironment, AnimationPlayer, CanvasItem, AudioEffect apparaîtront dans les fragments AST, et il est probable que le Retriever trouve des preuves dans le JSONL actuel.

Le but du test est également clair.

Godot 3 extrait de code  
-> extrait AST  
-> recherche api_mapping  
-> recherche auxiliaire docs_chunks  
-> aperçu du prompt de décision LLM

En d'autres termes, on peut vérifier immédiatement avec les données actuelles si ce code utilise l'API Godot 3 et sur quelle base il doit être modifié pour Godot 4.

Priorité 2 : Petit exemple Animation/Audio/Camera basé sur Godot 4

Le deuxième candidat est un petit dépôt d'exemples écrit pour Godot 4.

Ce dépôt est plus utile pour vérifier la “description du code Godot 4 normal” et s'assurer que le Retriever n'apporte pas de migration Godot 3 inappropriée, plutôt que pour la validation de migration.

Actuellement, docs_chunks contient pas mal de descriptions officielles sur l'Animation, l'Audio, la Camera, CanvasItem et Array. Ainsi, lorsqu'on insère un fragment de code Godot 4, il est facile de voir si les justifications d'explication se trouvent principalement dans docs_chunks.

Ce dépôt serait idéal s'il possède les caractéristiques suivantes.

Projet complet petit avec `project.godot`  
Environ 5 à 30 fichiers `.gd`  
Des fichiers `.tscn` sont également présents  
Utilisation de **AnimationPlayer** ou **AnimationTree**  
Utilisation de **AudioStreamPlayer** ou **AudioEffect**  
Utilisation de **Camera2D/Camera3D**  
Utilisation d’API de base comme **Array** / **Callable**  
Pas beaucoup d’actifs volumineux.

3ᵉ priorité : exemples du même sujet séparés en versions Godot 3 et Godot 4

Si possible, les exemples qui proposent le même sujet à la fois pour Godot 3 et pour Godot 4 sont les meilleurs.

Par exemple, si un même exemple de caméra/animation/audio possède une branche Godot 3 et une branche Godot 4, il est plus facile de comparer les jugements du Retriever et du LLM.

Ces dépôts sont utiles pour vérifier cela.

Vérifier si le api_mapping fonctionne correctement dans le fragment Godot 3  
Vérifier si les preuves d'explication de docs_chunks sont correctes dans le fragment Godot 4  
Comment montrer les différences de code entre versions pour la même fonctionnalité dans une invite LLM  
Comment accumuler le jugement godot3/godot4/mixed par projet

Clonez dès maintenant un dépôt au caractère ambigu

Actuellement, si l’on ne considère que le JSONL, les dépôts de ce type sont encore ambigus pour un premier test.

Plateforme 2D typique Godot 3

Les indices comme KinematicBody2D, move_and_slide, yield, TileMap, Color8 sont nombreux dans un jeu de plateforme 2D Godot 3 et seront indispensables plus tard.

Cependant, dans le snapshot actuel, ces indices sont presque inexistants dans le JSONL. Si l’on ajoute immédiatement un tel dépôt, le Retriever pourrait ne pas trouver de preuves ou bien récupérer des preuves d’Animation/Audio/Camera qui ne sont pas pertinentes.

Ainsi, ce type de dépôt est un « bon candidat pour le test final », mais pas le « premier candidat idéal à valider immédiatement avec le JSONL ».

Grand dépôt de jeu complet

Un grand dépôt de jeu contenant de nombreux assets et des centaines de fichiers .gd est encore prématuré.

Ce dont nous avons besoin maintenant, ce n’est pas de lancer un gros projet au modèle, mais de suivre jusqu’au bout quels fragments de code recherchent quelles preuves dans le JSONL. Un grand dépôt rend le débogage trop vaste, rendant difficile la compréhension du pourquoi de chaque preuve recherchée.

Le premier test doit porter sur un petit exemple aux fonctionnalités clairement définies.

Dépôt centré sur C#

Le JSONL actuel mentionne C# et quelques différences de noms C#, mais le flux global est conçu autour des fragments GDScript AST et .gd.

Par conséquent, un dépôt Godot centré sur C# n’est pas adapté comme premier test à ce stade.

Dépôt centré sur GDExtension / plugin natif

Les dépôts axés sur GDExtension, C++, liaison Rust, ou plugins natifs sont également trop précoces.

L’objectif actuel est de découper les projets Godot (.gd, .tscn, project.godot) en fragments et d’observer le flux où le Retriever trouve des preuves dans la documentation officielle. Un dépôt centré sur les extensions natives change l’axe d’analyse.

Critères de sélection des dépôts

Selon les critères actuels, le candidat au clonage doit satisfaire les conditions suivantes.

La version de Godot doit pouvoir être vérifiée dans le README ou le fichier project.godot.  
Le fichier project.godot doit être présent.  
Un fichier .gd doit être présent.  
Il est souhaitable d'avoir également un fichier .tscn.  
Il doit y avoir peu d'actifs de grande taille.  
La portée des fonctionnalités doit être petite et claire.  
Il doit y avoir du code qui chevauche les API présentes dans le JSONL actuel.

Les mots‑clés qui correspondent bien à JSONL actuellement sont les suivants.

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

À l'inverse, les mots‑clés trop précoces pour être considérés comme critères principaux dès le premier test sont les suivants.

KinematicBody2D
CharacterBody2D
move_and_slide
yield
await
Color8
TileMap
RigidBody2D
HTTPRequest
multiplayer
GDExtension

Jugement

En se basant sur les JSONL collectés jusqu'à présent, le premier projet cible de clonage devrait être le « petit dépôt candidat à la migration Godot 3 ». Cependant, il vaut mieux choisir un projet qui utilise réellement les familles Camera/WorldEnvironment/Animation/Audio/CanvasItem, plutôt qu'un simple platformer 2D classique.

La raison est simple.

Actuellement, api_mapping possède déjà des références aux catégories Camera, Animation, Audio, CanvasItem et Array. En revanche, les indices majeurs de la migration de la physique 2D de Godot 3, tels que KinematicBody2D, move_and_slide, yield et TileMap, sont presque absents du JSONL actuel.

Ainsi, le premier test le plus réaliste suit le flux suivant.

Petit clone d'exemple Godot 3 Camera/Animation/Audio  
-> Fragmentation de .gd et .tscn  
-> Recherche Retriever actuelle en JSONL  
-> Vérifier si le hit api_mapping est lié au code réel  
-> Vérifier l'aperçu du prompt à insérer dans le LLM

Ensuite, il est recommandé de cloner un petit exemple d'Animation/Audio/Camera écrit avec Godot 4 pour vérifier le flux de génération de documentation basé sur docs_chunks.

Une fois que label_prototypes est créé et que les bases concernant KinematicBody2D, move_and_slide, yield, Color8, TileMap sont accumulées, il est alors plus approprié de cloner un dépôt typique de plateforme 2D ou de jeu d'action sous Godot 3 pour tester la décision de migration.

Conclusion

Nous définissons dès maintenant le type de dépôt à cloner comme suit.

1ᵉʳ candidat :
  petit exemple Godot 3 avec version clairement indiquée  
  utilisation réelle de certains éléments parmi Camera / WorldEnvironment / AnimationPlayer / AnimationTree / Audio / CanvasItem  
  comprend les fichiers .gd, .tscn, project.godot  
  les assets ne sont pas excessivement volumineux  

2ᵉ candidat :
  exemple Godot 4 utilisant la même zone  
  utilisé pour la validation de la qualité de recherche de docs_chunks plutôt que pour la migration  

En attente :
  plateforme 2D Godot 3 centrée sur KinematicBody2D / move_and_slide / yield / TileMap  
  test après accumulation de davantage de justifications de migration liées à label_prototypes

Cette séquence semble être la méthode la plus efficace pour valider le JSONL actuellement collecté.