Source Flow Debugger 实现记录

编写日期：2026年6月27日

目的

本文记录了将 docs/roadmaps/2026-06-27-source-to-ast-input-flow.md 中整理的流程实现到实际网页调试器并进行验证的过程。

今天确认的要点如下。

Godot 项目输入
  -> 基于相对路径展开文件
  -> 判断文件类型
  -> 将 .gd 拆分为 AST 性质的代码片段
  -> 将 .godot、.tscn 等文本资源拆分为直接块
  -> 仅将每个块的 chunkText 作为 Retriever 输入显示
  -> 在块下方提供 docs_chunks / api_mapping / label_prototypes 搜索按钮
  -> 将检索到的 JSONL 连接成可附加到 Qwen 验证请求的结构

此次实现不是完整的 Retriever，而是用于在 Retriever 与 AST 输入之间进行目视追踪的网页调试器。也就是说，在判断数据库检索质量之前，先确认哪些文件被划分为哪些片段，以及哪些文本会作为 Retriever 的检索输入。

实现的网页流程

网页调试器在 http://127.0.0.1:8010/ 上运行。

在界面上可以看到的区域如下。

• DB endpoint 输入区域
• Qwen 验证输入区域
• Source Prompt 输入区域
• Expanded Source 输入区域
• 文件/块摘要指标
• 按文件的包含/排除结果
• 按块的原文、Retriever 输入、DB 检索按钮、Qwen 请求预览

今天看到的界面如下。

Godot 项目输入确认

测试以小型 Godot 项目形式进行。

输入文件如下。

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

上传后，内部输入将展开为以下形式。

# 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
...

# <相对路径> 标题用于追踪。Retriever 中不包含此标题。

分析结果

本次测试中网页调试器显示的摘要如下。

文件的判定如下。

.gd 文件处理

.gd 文件作为 AST Parser 角色的逻辑进行处理。

例如 player.gd 被划分如下。

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

实际块包含函数体。

例如，_process函数保持为一个块。

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)

在 enemy.gd 中，确认了即使是可能成为 Godot 3 线索的代码也会被拆分为块。

extends KinematicBody2D

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

direct chunk 处理

project.godot不作为 AST Parser 发送，而是按设置章节划分。

例如以下内容是 direct chunk。

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

player.tscn也不发送到 AST Parser，而是按 resource block 单位划分。

例如，以下内容是 direct chunk。

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

这样划分的原因是，虽然 .tscn、.godot 文件在判断 Godot 项目时是必需的，但它们不像 .gd 函数那样需要按 AST 函数单元进行解析。

Retriever 输入检查

截至今天，Retriever 的输入仅包含一个 chunkText。

例如，extends KinematicBody2D 代码块的 Retriever 输入如下。

{
  "chunkText": "extends KinematicBody2D"
}

文件路径、行号、提示、预期表名不要放入 Retriever 输入。

文件路径和行号是用于 UI 中人工追踪的信息。搜索本身应使用 chunk 文本进行。

按 chunk 的 DB 搜索按钮

最初可以像全局选项那样放置表选择，但实际上每个 chunk 需要搜索的表可能不同。

因此按钮放在 chunk 下面。

docs_chunks 搜索
api_mapping 搜索
label_prototypes 搜索
Validate JSONL

流 程 如 下 所 示。

当前 chunkText  
  -> 点击 chunk 下面的表格按钮

-> 在该表中搜索

-> JSONL 候选显示

-> prompt + chunkText + 使用检索到的 JSONL 验证 Qwen

这里的 prompt 不是 Retriever 的输入。prompt 只在 Qwen 验证阶段使用。

今天确认的内容

今天确认的内容主要有四点。

第一，去除了在空白页面自动插入示例代码的问题。以前页面打开时会自动加载 Mini Dodge 示例，即使上传空文件夹，也会看起来像是保留了之前的内容。现在刷新后 source 输入为空。

第二，当再次上传相同的文件或文件夹时，浏览器会重新触发 change 事件，上传 input 的值在点击时会被清空。

第三，开发期间为防止静态 JS 缓存残留，在本地服务器响应中加入了 cache-control: no-store。

第四，确认在网页上，上传 Godot 项目时 .gd 被划分为 AST chunk，.godot 和 .tscn 被划分为 direct chunk。

仍未完成的事项

按块（chunk）拆分的工作似乎已经取得了一定进展。

明天要继续关注的核心是如何执行 DB 检索。

特别需要确认以下部分：

• 仅使用 chunkText 检索 docs_chunks 时会返回什么 JSONL
• 仅使用 chunkText 检索 api_mapping 时，能否正确捕获 Godot 3 → 4 的依据
• 仅使用 chunkText 检索 label_prototypes 时，函数使用方式/调用模式示例是否能被正确捕获
• 当没有检索结果或结果不相关时，如何在 Qwen 验证阶段废弃它们
• 以何种形式在界面上展示检索到的 JSONL，才能更容易判断

今天制作的网页调试器是用于确认下一步的观察工具。现在已经开始看到文件是如何被拆分的，接下来需要追踪每个 chunk 在数据库中获取的依据。