Source Flow Debugger Implementierungsprotokoll

Erstellungsdatum: 27. Juni 2026

Zweck

Dieses Dokument ist eine Aufzeichnung der Umsetzung und Überprüfung des in docs/roadmaps/2026-06-27-source-to-ast-input-flow.md beschriebenen Ablaufs im tatsächlichen Web-Debugger.

Das heute überprüfte Kernstück ist folgendes.

Godot-Projekteingabe
  -> Dateien relativ zum Pfad ausklappen
  -> Dateityp bestimmen
  -> .gd wird in AST-ähnliche Codefragmente zerlegt
  -> Textressourcen wie .godot, .tscn werden in direkte Chunks zerlegt
  -> Nur den chunkText jedes Chunks als Retriever-Eingabe anzeigen
  -> Unterhalb des Chunks Suchschaltflächen für docs_chunks / api_mapping / label_prototypes bereitstellen
  -> Die gefundenen JSONL in eine Struktur einbinden, die an Qwen-Validierungsanfragen angehängt werden kann

Diese Implementierung ist kein fertiger Retriever, sondern ein Web‑Debugger, um die Beziehung zwischen Retriever und AST‑Eingabe visuell nachzuverfolgen. Das heißt, bevor die Qualität der DB‑Suche beurteilt wird, dient er dazu, zuerst zu prüfen, welche Datei in welche Stücke aufgeteilt wird und welcher Text als Retriever‑Sucheingabe verwendet wird.

Implementierter Web‑Ablauf

Der Web‑Debugger wurde unter http://127.0.0.1:8010/ ausgeführt.

Die im Bildschirm sichtbaren Bereiche sind:

DB‑Endpoint‑Eingabebereich
Qwen‑Validierungs‑Eingabebereich
Source‑Prompt‑Eingabebereich
Expanded‑Source‑Eingabebereich
Datei‑/Chunk‑Zusammenfassungs‑Metriken
Ergebnis‑Ein‑/Ausschluss pro Datei
Originaltext pro Chunk, Retriever‑Input, DB‑Such‑Button, Qwen‑Anfrage‑Vorschau

Der heute betrachtete Bildschirm sah folgendermaßen aus.

Source Flow Debugger Godot Analyse‑Bildschirm

Godot‑Projekt‑Eingabe prüfen

Der Test wurde in Form eines kleinen Godot‑Projekts durchgeführt.

Die Eingabedateien waren wie folgt.

minidodge/project.godot
minidodge/scripts/player.gd
minidodge/scripts/enemy.gd
minidodge/scenes/player.tscn
minidodge/README.md

Nach dem Hochladen wird die interne Eingabe wie folgt ausgeklappt.

# minidodge/project.godot
config_version=5

[application]
config/name="Mini Dodge Upload Test"
run/main_scene="res://scenes/player.tscn"

# minidodge/scripts/player.gd
extends Area2D

signal hit

@export var speed = 400
...

# <Relative Pfad> Header ist für das Tracking gedacht. Dieser Header wird nicht in den Retriever aufgenommen.

Analyseergebnis

Die Zusammenfassung, die der Web-Debugger in diesem Test gezeigt hat, lautet wie folgt.

Feld	Wert
Dateien	5
Eingeschlossen	4
Ausgeschlossen	1
Chunks	14
AST	9
Direkt	5
Retriever‑Eingaben	14

Die Bewertung pro Datei war wie folgt.

Datei	Bewertung	Verarbeitung
`minidodge/project.godot`	eingeschlossen	`project_config`, direkter Chunk
`minidodge/scripts/player.gd`	eingeschlossen	`gdscript`, AST‑Chunk
`minidodge/scripts/enemy.gd`	eingeschlossen	`gdscript`, AST‑Chunk
`minidodge/scenes/player.tscn`	eingeschlossen	`scene`, direkter Chunk
`minidodge/README.md`	ausgeschlossen	Dokumentdatei im source‑analysis‑Modus ausgeschlossen

`.gd`‑Dateiverarbeitung

.gd‑Dateien werden mit einer Logik verarbeitet, die die Rolle eines AST‑Parsers übernimmt.

Zum Beispiel wurde player.gd wie folgt aufgeteilt.

extends Area2D
signal hit
@export var speed = 400
var screen_size
func _ready():
func _process(delta):
func start(pos):

Der eigentliche Chunk enthält den Funktionskörper.

Zum Beispiel bleibt die _process‑Funktion als ein Chunk erhalten.

func _process(delta):
	var velocity = Vector2.ZERO
	if Input.is_action_pressed(&"move_right"):
		velocity.x += 1
	if Input.is_action_pressed(&"move_left"):
		velocity.x -= 1

	if velocity.length() > 0:
		velocity = velocity.normalized() * speed
		$AnimatedSprite2D.play()
	else:
		$AnimatedSprite2D.stop()

	position += velocity * delta
	position = position.clamp(Vector2.ZERO, screen_size)

In enemy.gd haben wir festgestellt, dass sogar Code, der ein Hinweis auf Godot 3 sein könnte, in Chunks aufgeteilt wird.

extends KinematicBody2D

func _physics_process(delta):
	velocity = move_and_slide(velocity)

direct chunk Verarbeitung

project.godot wird nicht an den AST‑Parser gesendet, sondern in Abschnitte der Einstellung unterteilt.

Zum Beispiel ist der folgende Inhalt ein direct chunk.

[application]
config/name="Mini Dodge Upload Test"
run/main_scene="res://scenes/player.tscn"

player.tscn wird ebenfalls nicht an den AST‑Parser gesendet, sondern in resource‑Block‑Einheiten aufgeteilt.

Zum Beispiel ist der folgende Inhalt ein direct chunk.

[node name="Player" type="Area2D"]
script = ExtResource("1")

So wurde es aufgeteilt, weil .tscn‑ und .godot‑Dateien zwar für die Erkennung eines Godot‑Projekts nötig sind, aber im Gegensatz zu .gd‑Funktionen nicht auf Ebene einzelner AST‑Funktionen geparst werden müssen.

Überprüfung der Retriever‑Eingabe

Stand heute hat die Retriever‑Eingabe nur ein chunkText.

Zum Beispiel lautet die Retriever‑Eingabe für das extends KinematicBody2D‑Chunk wie folgt.

{
  "chunkText": "extends KinematicBody2D"
}

Dateipfad, Zeilennummer, Prompt, erwarteter Tabellenname werden nicht in die Retriever‑Eingabe aufgenommen.

Dateipfad und Zeilennummer dienen nur dazu, dass Menschen in der UI den Überblick behalten. Die Suche selbst muss anhand des Chunk‑Texts erfolgen.

DB‑Suchbutton pro Chunk

Anfangs hätte man die Tabellenauswahl als globale Option setzen können, aber in der Praxis kann für jeden Chunk eine andere Tabelle durchsucht werden.

Deshalb wurde der Button unterhalb des Chunks platziert.

docs_chunks Suche
api_mapping Suche
label_prototypes Suche
Validate JSONL

Der Ablauf wurde wie folgt festgelegt.

Aktueller chunkText
-> Klicken Sie auf die Tabellenschaltfläche unterhalb des Chunks
-> Suche in der entsprechenden Tabelle
-> JSONL Kandidatenanzeige
-> prompt + chunkText + retrieved JSONL zur Qwen-Validierung

Hier ist der Prompt nicht die Retriever‑Eingabe. Der Prompt wird nur in der Qwen‑Validierungsphase verwendet.

Heute überprüft

Heute wurden vier Hauptpunkte überprüft.

Erstens wurde das Problem behoben, dass automatisch Beispielcode auf einem leeren Bildschirm eingefügt wurde. Zuvor wurde beim Öffnen der Seite automatisch das Beispiel Mini Dodge geladen, sodass es so aussah, als ob Inhalte aus einem zuvor hochgeladenen leeren Ordner noch vorhanden wären. Jetzt ist die Source‑Eingabe unmittelbar nach einem Neuladen leer.

Zweitens wird beim erneuten Hochladen derselben Datei oder desselben Ordners das Browser‑change‑Ereignis erneut ausgelöst, indem der Wert des Upload‑Inputs zum Zeitpunkt des Klicks geleert wird.

Drittens wurde dem lokalen Server‑Response‑Header cache‑control: no-store hinzugefügt, damit während der Entwicklung kein statischer JS‑Cache zurückbleibt.

Viertens wurde im Web‑Interface bestätigt, dass bei einem Godot‑Projekt .gd als AST‑Chunk und .godot sowie .tscn als Direct‑Chunk behandelt werden.

Noch offen

Das Aufteilen in Chunks scheint weitgehend zu funktionieren.

Morgen wird weiter daran gearbeitet, wie die DB‑Suche durchgeführt werden soll.

Insbesondere müssen die folgenden Punkte geprüft werden:

Welche JSONL‑Einträge zurückkommen, wenn nur chunkText zur Suche in docs_chunks verwendet wird
Ob die Zuordnung von Godot 3 → 4 in api_mapping anhand von nur chunkText korrekt ermittelt wird
Ob Beispiele für Funktionsverwendungen/Aufrufmuster in label_prototypes anhand von nur chunkText gut erfasst werden
Wie nicht‑gefundene oder falsche Ergebnisse in der Qwen‑Validierungsphase verworfen werden sollen
In welchem Format die gefundenen JSONL‑Einträge angezeigt werden sollten, um die Beurteilung zu erleichtern

Der heute erstellte Web‑Debugger ist ein Beobachtungswerkzeug, um den nächsten Schritt zu prüfen. Da nun sichtbar wird, wie Dateien aufgeteilt werden, muss im nächsten Schritt nachverfolgt werden, welche Belege jeder Chunk aus der DB zieht.