JSONL‑Sammelstatus‑basierte Auswahl von Test‑Repositories – Beobachtungstagebuch

Erstellungsdatum: 27. Juni 2026

Zweck

Auf Basis der bisher erstellten JSONL‑Dateien soll beurteilt werden, welche Art von Godot‑Repository zuerst geklont und getestet werden sollte.

Dabei geht es nicht darum, „ein beliebiges bekanntes Repository auszuwählen“. Zunächst wird analysiert, in welchen Bereichen die im Datenbank‑System gesammelten Belege stark sind und in welchen Bereichen sie noch schwach sind, um dann die Repository‑Art zu wählen, für die der Retriever tatsächlich Belege finden kann.

Die Analysegrundlage bilden die folgenden beiden Dateien.

/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 enthält den Transformationsstatus, den Klassifizierungs‑Prompt und Debug‑Informationen der Originalantwort, aber da auch Laufzeit‑Einstellungen gemischt sein können, wird der Originaltext nicht in öffentlichen Dokumenten veröffentlicht. In diesem Beobachtungsprotokoll werden nur JSONL‑Statistiken und Bewertungen belassen.

Schnappschuss‑Status

Die Transformation ist zum Zeitpunkt der Beobachtung noch im Gange.

docs_chunks.jsonl: 153 records  
api_mapping.jsonl: 117 records  
label_prototypes.jsonl: Noch keine Datei erstellt

Der Web‑Umwandlungsstatus verlief ungefähr wie folgt.

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

Daher ist dieses Dokument nicht das endgültige Fazit, sondern die „erste Auswahlkriterien für Repositories basierend auf den bisher gesammelten JSONL-Daten“.

Beobachtung von docs_chunks

docs_chunks wurden 153 Datensätze erstellt.

Die Konfiguration ist wie folgt.

class_reference: 127
about: 26

Aus 95 Markdown‑Originaldateien wurden Chunks erstellt, und in 129 Datensätzen befand sich ein API‑Symbol. Datensätze mit Code‑Block waren 36.

Bis jetzt ist der stark sichtbare Bereich in docs_chunks wie folgt:

Animation‑Kategorie  
Audio‑Kategorie  
Kamera‑Kategorie  
Canvas/CanvasItem‑Kategorie  
Grundlegende APIs wie Array/Callable/GlobalScope  
Einige AnimatedSprite2D  
Einige AStar/AStarGrid2D

Im Gegenteil, die noch schwach erscheinenden Bereiche sind wie folgt.

KinematicBody / CharacterBody Migration  
move_and_slide Aufrufweise  
yield → await Umstellung  
Color8 → Color.from_rgba8 Umstellung  
TileMap Migration  
RigidBody / Physics Body Migration  
HTTPRequest / Netzwerkkommunikation

Das heißt, zum jetzigen Zeitpunkt können die docs_chunks zwar bis zu einem gewissen Grad als „Begründung aus der offiziellen Godot 4‑Dokumentation“ verwendet werden, aber es ist noch schwer zu sagen, dass ausreichend Belege für die typische Migration eines 2D‑Action‑Spiels von Godot 3 zu Godot 4 vorliegen.

Beobachtung von api_mapping

api_mapping hatte 117 Datensätze erzeugt.

Die Änderungsarten werden wie folgt unterschieden.

rename_or_replacement: 82
behavior_change: 24
deprecated: 11

Das Vertrauen aller Datensätze war in verified_from_docs enthalten.

Bis jetzt deutlich erscheinende Mapping‑Bereiche sind wie folgt.

Array‑Methoden und Verhaltensunterschiede  
AnimationPlayer / AnimationMixer / AnimationTree / AnimationNode‑Reihe  
AudioStream / AudioEffect / AudioEffectSpectrumAnalyzer‑Reihe  
Camera / Camera3D / CameraAttributes‑Reihe  
CanvasItem‑draw/modulate‑Reihe  
Einige Funktionen und veraltete Konstanten im GlobalScope  
Einige im AStarGrid2D

Zum Beispiel enthält das aktuelle JSONL die folgenden Arten von Belegen.

Camera -> Camera3D  
WorldEnvironment Belichtungseinstellung -> CameraAttributes Reihe  
Einige Funktionen von AnimationPlayer -> Trennung von AnimationMixer  
AnimationNode._process -> AnimationNodeExtension._process_animation_node  
AudioEffectLimiter -> AudioEffectHardLimiter  
Verhalten von Array.sort geändert  
Unterschied im C# Namen von Array.has  
Verhalten von CanvasItem.modulate geändert  
Verhalten von CanvasItem.draw_string / draw_rect geändert

Dieser Satz bedeutet, dass wenn man jetzt sofort einen Migrationstest durchführt, es wahrscheinlicher ist, dass Code für Camera, Animation, Audio, CanvasItem und Array eher Probleme verursacht als KinematicBody2D oder move_and_slide eines 2D‑Platformers.

Beobachtung von label_prototypes

Im aktuellen Snapshot gibt es keine Datei label_prototypes.jsonl.

Daher fehlt die Grundlage, um das Beispiel „die gesamte Art der Funktionsverwendung ändert sich“ mit dem Retriever zu testen. Zwar steht in api_mapping ein behavior_change‑Eintrag, aber das ist eher ein aus der Dokumentation extrahierter Hinweis auf API‑Änderungen als ein vollständiges Nutzungsmuster‑Beispiel.

Deshalb ist es beim Auswählen eines Repositories sinnvoller, zunächst ein Repository zu wählen, das die bereits vorhandenen Bereiche von docs_chunks und api_mapping verifiziert, anstatt ein Repository, das aktiv label_prototypes testet.

Eigenschaften eines Repositories, das sich sofort gut klonen lässt

Nach dem JSONL‑Standard ist das am besten sofort klonbare Repository eines, das „klein ist, eine klare Godot‑Version angibt und die bereits vorhandenen Mappings sowie überlappende APIs im echten Code verwendet“.

Die Prioritäten sind wie folgt:

1. Priorität: Kleines Beispiel für Camera/WorldEnvironment/Animation auf Basis von Godot 3

Der beste erste Testkandidat ist ein kleines Repository aus einem Godot‑3‑Projekt, das tatsächlich Funktionen wie Camera, WorldEnvironment, AnimationPlayer, AnimationTree, CanvasItem‑Zeichnen und AudioEffect nutzt.

Der Grund dafür ist, dass bereits entsprechende Hinweise in api_mapping vorhanden sind.

Camera -> Camera3D  
Camera.get_transform -> Camera3D.get_camera_transform  
WorldEnvironment exposure Einstellung -> CameraAttributes  
AnimationPlayer -> AnimationMixer bezogene Änderungen  
AnimationNode / AnimationTree Familienänderungen  
CanvasItem draw/modulate Verhaltensänderungen  
AudioEffect / AudioStream Familienänderungen

Wenn man dieses Repo klont, erscheinen im AST‑Fragment Hinweise wie Camera, WorldEnvironment, AnimationPlayer, CanvasItem, AudioEffect, und es ist wahrscheinlich, dass der Retriever die Belege im aktuellen JSONL findet.

Der Testzweck ist ebenfalls klar.

Godot 3 Codefragment  
-> AST-Fragment  
-> api_mapping Suche  
-> docs_chunks Hilfssuche  
-> LLM‑Bewertungs‑Prompt Vorschau

Das heißt, man kann sofort anhand der aktuellen Daten prüfen, ob dieser Code die Godot 3‑API verwendet und aus welchem Grund er in Godot 4 geändert werden muss.

2. Priorität: Kleine Animation/Audio/Camera‑Beispiele auf Basis von Godot 4

Der zweite Kandidat ist ein kleines Beispiel‑Repository, das in Godot 4 geschrieben wurde.

Dieses Repository ist eher geeignet, um die „normale Godot 4‑Code‑Beschreibung“ und zu prüfen, ob der Retriever nicht eine falsche Godot 3‑Migration mitbringt, als die Migration zu verifizieren.

Derzeit enthält docs_chunks ziemlich viele offizielle Dokumentationsbeschreibungen zu Animation, Audio, Kamera, CanvasItem und Array. Daher ist es gut zu sehen, ob beim Einfügen von Godot 4‑Code‑Snippets die Erklärungsgrundlage hauptsächlich in docs_chunks liegt.

Dieses Repository sollte die folgende Eigenschaft haben.

Vollständiges kleines Projekt mit `project.godot`  
Etwa 5–30 `.gd`‑Dateien  
`.tscn`‑Dateien sind ebenfalls vorhanden  
Verwendung von **AnimationPlayer** oder **AnimationTree**  
Verwendung von **AudioStreamPlayer** oder **AudioEffect**  
Verwendung von **Camera2D**/**Camera3D**  
Verwendung grundlegender APIs wie **Array**/ **Callable**  
Keine großen Mengen an Assets vorhanden

3. Priorität: Beispiele zum selben Thema, aufgeteilt in Godot 3‑ und Godot 4‑Versionen

Wenn möglich, ist ein Beispiel, das dasselbe Thema sowohl für Godot 3 als auch für Godot 4 bereitstellt, am besten.

Zum Beispiel lässt sich ein Kamera‑/Animations‑/Audio‑Beispiel, das sowohl einen Godot 3‑Branch als auch einen Godot 4‑Branch besitzt, leichter im Vergleich zwischen Retriever‑ und LLM‑Bewertung analysieren.

Solche Repositories lassen sich gut anhand Folgendem prüfen.

Ob das api_mapping im Godot‑3‑Fragment korrekt funktioniert  
Ob die Erklärung der docs_chunks im Godot‑4‑Fragment gut belegt ist  
Wie man die versionsspezifischen Code‑Unterschiede derselben Funktion im LLM‑Prompt darstellen kann  
Wie man die Entscheidung für godot3/godot4/mixed pro Projekt kumuliert

Jetzt sofort klonen – unklare Repo‑Natur

Wenn man nur das JSONL betrachtet, ist ein Repo mit folgendem Charakter für den ersten Test noch unklar.

Typischer Godot 3 2D‑Plattformer

Ein Godot 3 2D‑Plattformer mit vielen Hinweisen wie KinematicBody2D, move_and_slide, yield, TileMap, Color8 wird später unbedingt nötig sein.

Im aktuellen Snapshot fehlen diese Hinweise fast vollständig im JSONL. Wenn man jetzt ein solches Repo hinzufügt, könnte der Retriever keine Belege finden oder unbegründete Animation/Audio/Camera‑Belege heranziehen.

Deshalb ist ein Repo dieses Typs ein „guter End‑Test‑Kandidat“, aber kein „erstes, sofort mit JSONL zu prüfendes“ Kandidat.

Großes komplettes Spiel‑Repo

Ein großes Spiel‑Repo mit vielen Assets und hunderten .gd‑Dateien ist noch zu früh.

Was jetzt benötigt wird, ist nicht, dem Modell ein großes Projekt zu geben, sondern zu verfolgen, welche Code‑Stücke welche JSONL‑Belege finden. Ein großes Repo ist zu breit zum Debuggen, sodass man nicht mehr erkennt, warum welche Belege gefunden wurden.

Der erste Test sollte klein und funktional klar sein.

C#‑zentriertes Repo

Im aktuellen JSONL gibt es C#‑Erwähnungen und einige Unterschiede in C#‑Bezeichnungen, aber der gesamte Ablauf ist auf GDScript‑AST und .gd‑Stücke ausgelegt.

Daher ist ein C#‑zentriertes Godot‑Repo für den ersten Test in diesem Stadium nicht geeignet.

GDExtension / Native‑Plugin‑zentriertes Repo

Repos, die sich auf GDExtension, C++, Rust‑Binding oder native Plugins konzentrieren, sind ebenfalls noch zu früh.

Das aktuelle Ziel ist, die .gd, .tscn, project.godot‑Dateien eines Godot‑Projekts in Stücke zu zerlegen und zu sehen, wie der Retriever offizielle Dokumentations‑Belege findet. Bei nativen Extension‑Repos ändert sich die Analyse‑Achse.

Auswahlkriterien für Repos

Nach dem aktuellen Stand sollten die Clone‑Kandidaten die folgenden Bedingungen erfüllen.

Die Godot-Version muss in der README oder project.godot einsehbar sein.  
Eine project.godot-Datei muss vorhanden sein.  
Eine .gd-Datei muss vorhanden sein.  
Eine .tscn-Datei ist ebenfalls wünschenswert.  
Großformatige Assets sollten gering sein.  
Der Funktionsumfang muss klein und klar sein.  
Es muss Code geben, der mit den in JSONL vorhandenen APIs überschneidet.

Die folgenden Schlüsselwörter passen gut zu JSONL.

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

Im Gegenteil, die folgenden Schlüsselwörter sind für den ersten Test noch zu früh, um als Kernkriterien zu gelten.

KinematicBody2D
CharacterBody2D
move_and_slide
yield
await
Color8
TileMap
RigidBody2D
HTTPRequest
multiplayer
GDExtension

Beurteilung

Basierend auf den bisher gesammelten JSONL ist das erste Clone‑Ziel das „kleine Godot‑3‑Migrationskandidaten‑Repo“. Allerdings sollte es sich nicht um ein übliches 2D‑Platformer‑Projekt handeln, sondern um ein Projekt, das tatsächlich die Klassen Camera/WorldEnvironment/Animation/Audio/CanvasItem verwendet.

Der Grund ist einfach.

Derzeit enthält api_mapping bereits Referenzen zu Camera, Animation, Audio, CanvasItem und Array. Im Gegensatz dazu fehlen im aktuellen JSONL fast vollständig die typischen Hinweise für die Godot‑3‑2D‑Physik‑Migration wie KinematicBody2D, move_and_slide, yield und TileMap.

Daher ist der erste Testablauf am realistischsten:

# Kleines Godot 3 Kamera/Animation/Audio Beispiel‑Klone
- → .gd‑ und .tscn‑Fragmentierung
- → Aktuell JSONL‑basiertes Retriever‑Suchen
- → Prüfen, ob der api_mapping‑Hit mit dem tatsächlichen Code zusammenhängt
- → Vorschau des Prompts, der an das LLM übergeben wird, überprüfen

Als Nächstes ist es sinnvoll, ein kleines Animation/Audio/Camera‑Beispiel, das mit Godot 4 erstellt wurde, zu klonen und den auf docs_chunks basierenden Erstellungs‑Workflow zu überprüfen.

Wenn schließlich label_prototypes erzeugt und Belege für KinematicBody2D, move_and_slide, yield, Color8 und die TileMap‑Familie gesammelt sind, ist es sinnvoll, ein typisches Godot‑3‑2D‑Plattform‑ oder Action‑Game‑Repository zu klonen, um die Migration zu beurteilen.

Fazit

Der Typ des Repositorys, das jetzt sofort geklont werden soll, wird wie folgt festgelegt.

Erster Kandidat:
  Kleine, klar versionierte Godot 3‑Beispiele
  Einige von Camera / WorldEnvironment / AnimationPlayer / AnimationTree / Audio / CanvasItem werden tatsächlich verwendet
  .gd, .tscn, project.godot enthalten
  Assets sind nicht übermäßig groß

Zweite Auswahl:
  Beispiel für Godot 4, das denselben Bereich verwendet
  Wird zur Überprüfung der Code‑Erklärung und der Suchqualität von docs_chunks anstelle von Migration verwendet

Zurückgestellt:
  Godot 3 2D‑Plattformspiel, das sich auf KinematicBody2D / move_and_slide / yield / TileMap konzentriert
  Testen, nachdem weitere Belege für die Migration im Zusammenhang mit label_prototypes gesammelt wurden

Diese Reihenfolge scheint die effizienteste Methode zu sein, um das aktuell gesammelte JSONL ohne Verschwendung zu validieren.