Qwen Validation Debugger 策略与实现记录

编写日期: 2026 年 6 月 30 日

目的

本文档记录了创建 tools/qwen-validation-debugger 的原因以及实际运行流程。

6 月 28 日，我手动使用 Qwen 生成了 Godot 代码块和 JSONL，并将 提示 + 代码块 + JSONL 直接拼接，查看 是/否 的输出情况。此方法有助于确定方向，但随着条目增多，手动复制、记住生成标准以及比较结果的成本变得非常高。

因此在 6 月 30 日，我将此过程制作成了独立的网页工具。该工具的目标不是最终模型训练，而是通过肉眼追踪 Qwen 生成的测试代码与 JSONL 之间的关系，快速发现错误的 是/否 判定。

当前界面

当前工具在 http://localhost:8520/ 运行。

界面主要分为三个区域。

• 左侧: 50 条 Godot 测试项检查清单
• 中间/右上: 所选项的 AI 标签和 Godot 代码生成结果
• 底部: docs_chunks、api_mapping、label_prototypes JSONL 生成/验证槽位

为什么需要独立工具

最初我直接在 Qwen 聊天机器人中请求以下内容。

创建一个 Godot 代码块，  
按照 `docs_chunks/api_mapping/label_prototypes` 的格式生成正确的 JSONL 和错误的 JSONL。  
然后把 `SOURCE_CODE` 和 JSONL 拼接后，检查“是/否”是否正确。

但是在进行手动测试后，实际需要确认的轴比想象中要多。

如果是通用语法，则有 6 个槽。

公共代码
  docs_chunks       说明依据 / 其他代码说明
  api_mapping       公共/不必要 / 无关 转换
  label_prototypes  公共/不必要 / 无关 转换

如果是版本分离语法，槽位有12个。

Godot 3 代码
  docs_chunks       说明依据 / 其他代码说明
  api_mapping       需要转换 / 无关转换
  label_prototypes  需要转换 / 无关转换

Godot 4 代码
  docs_chunks       说明依据 / 其他代码说明
  api_mapping       已应用 / 无关转换
  label_prototypes  已应用 / 无关转换

如果手动一直制作这个，会花比测试本身更多的时间在复制/粘贴和结果整理上。因此将项目、代码、JSONL、验证结果在 GUI 中统一到一个屏幕上。

整体流程

flowchart TD
  A["50个测试项目"] --> B["选择项目"]
  B --> C["Qwen 标注"]
  C --> D{"是公共语法吗？"}
  D -->|"公共"| E["生成公共代码"]
  D -->|"单独"| F["生成 Godot 3 代码"]
  D -->|"单独"| G["生成 Godot 4 代码"]
  E --> H["JSONL 插槽 6个"]
  F --> I["基于 Godot 3 的 JSONL 6个"]
  G --> J["基于 Godot 4 的 JSONL 6个"]
  I --> K["验证 Godot 3 代码"]
  I --> L["验证 Godot 4 代码"]
  J --> K
  J --> L
  H --> M["验证公共代码"]

工具将 Qwen 分为三次角色调用。

标注阶段

点击条目后，Qwen 首先判断是通用语法还是版本分离。

例如 _process(delta) 在 Godot 3 和 Godot 4 中都用作帧更新函数，因此可以视为通用语法。

相反，玩家移动速度及加速度应用 因为物理体和 move_and_slide() 的调用方式在不同版本中可能不同，需要分别制作 Godot 3 代码和 Godot 4 代码。

JSONL 槽设计

最初仅将槽位划分为 正确 JSONL 和 错误 JSONL。但这种标准过于笼统。

docs_chunks 是说明依据。因此，如果说明直接对应代码，则为 是；如果说明的是其他代码的行为，则为 否。

但 api_mapping 和 label_prototypes 并非单纯说明，而是从 Godot 3 迁移到 Godot 4 的转换依据。因此，如果已经是 Godot 4 的代码却标记 api_mapping 或 label_prototypes 为 是，会产生“已经是 Godot 4 了，还要迁移”的误解。

于是将槽位名称改为如下：

有了此标准，是/否 不再是单纯的相关性判断，而是符合表格用途的判定。

生成基准代码与验证目标代码的区分

今天最重要的变化就在此。

最初实现时，一个槽位仅对自身代码进行验证。

使用 Godot 3 代码生成的 JSONL  
  -> 仅在 Godot 3 代码中验证  

使用 Godot 4 代码生成的 JSONL  
  -> 仅在 Godot 4 代码中验证

但是实际需要的验证要比这更广。

Godot 3 代码生成的 JSONL 粘贴到 Godot 4 代码时也应该出现 아니오。相反，Godot 4 代码生成的 JSONL 粘贴到 Godot 3 代码时也需要查看会出现什么结果。只有这样才能发现 source/target 字符串混合导致错误出现 예 的问题。

所以把按钮从一个分成了两个。

现在版本分离项的每个槽都可以执行以下所有验证。

Godot 3 代码生成的 JSONL  
  -> Godot 3 代码验证  
  -> Godot 4 代码验证  

Godot 4 代码生成的 JSONL  
  -> Godot 3 代码验证  
  -> Godot 4 代码验证

在工具内部，这会被如下拆分。

期望响应计算标准

验证结果仍然以 是 或 否 的形式返回给 Qwen。不过期望响应现在不再仅依据单个槽位计算，而是同时考虑 表格 + JSONL 生成基准版本 + 验证目标版本 + 槽位属性。

此标准更像是调试依据，用于查看当前阶段 Qwen 的依据匹配在哪些地方出现偏差，而非最终的完整评估标准。

验证提示的变化

验证提示现在会包含两条版本信息。

JSONL_GENERATED_FROM_CODE_VERSION:
godot3

VERIFY_TARGET_CODE_VERSION:
godot4

这样放置的原因是为了防止 Qwen 仅因为 JSONL 中的 target_api 与当前代码匹配就回答 “是”。

在 api_mapping 和 label_prototypes 中，以下标准很重要。

• source_api、source_pattern、input_pattern、before_code、required_when_seen_in_code 必须直接出现在当前代码中时才为 “是”
• target_api、after_code、仅当推荐的 target 形式与当前代码匹配时视为已应用状态，因此为 “否”
• 如 signature_stable、no_change、common 等表示无需转换时为 “否”
• 即使迁移 JSONL 附加在 Godot 4 代码或通用语法代码上，若不需要额外转换也为 “否”

50 项测试记录

1/50 _ready() 函数初始化及视口大小设置

7 月 3 日在 50 项测试中首先验证了第 1 项。该项已标记为通用代码，基准代码如下。

func _ready():
    var vp_size = get_viewport().get_visible_rect().size
    position = Vector2(vp_size.x / 2, vp_size.y / 2)

最初把 docs_chunks 的错误槽位称为 “无关说明 JSONL”。但是实际测试后发现这个名称不准确。该槽位并不是故意生成异常或错误的 JSONL，而是放入 Retriever 可以作为搜索候选获取的其他官方文档说明，观察 Qwen 在最终验证时是否会将其过滤掉。

因此将该槽位的含义整理为 “其他代码说明 JSONL”。

在本次测试中出现问题的 JSONL 本应说明 Viewport.get_visible_rect 和 _ready()，但实际内容却是关于 safe area、UI scaling、$Label、$Button.rect_position 等其他代码行为的说明。SOURCE_CODE 是读取视口大小并将当前节点的 position 移动到屏幕中心的代码，所以即使有部分 API 重叠，也不能视为直接依据。

期望的响应是 “否”，但 Qwen 返回了 “是”。原因在于验证提示将 “实际字符串/API 调用完全匹配” 解释得过于宽泛，导致即使是包含相同 API 的其他文档说明也被当作直接依据接受。

修改记录：

• 将 docs_chunks 错误槽位名称从 “无关说明 JSONL” 改为 “其他代码说明 JSONL”
• 在 JSONL 生成提示中将该槽位定义为 “类似搜索候选，可能包含部分相同的 API/主题，但实际上是解释其他代码行为的官方文档式 JSONL”
• 在验证提示中将 docs_chunks 的 “是” 标准从单纯的 API 字符串匹配，强化为必须匹配代码的核心目的、目标对象、最终行为/结果
• 即使出现相同的 API 或相同的方法，只要 JSONL 说明的是不同的目的、不同的目标对象、不同的结果，就仅视为搜索候选而非直接依据，明确标记为 “否”
• 前端 UI 的槽位标签和预览文字也按同一标准进行调整
• 在 core.test.js 中新增测试，确保该标准在提示中得到保持

2/50 _process(delta) 帧级更新循环

7 月 3 日对第 2 项进行了验证。该项被 Qwen 标记为公共代码。

标签摘要：

syntax_scope: common
label: _process(delta) 帧别更新
reason: 在 Godot 3 和 4 中，_process(delta) 函数的签名和调用方式相同，编写帧级逻辑没有语法差异。

验证结果显示所有 6 个槽位均与预期响应一致。

本项记录了在公共语法中 docs_chunks 作为说明依据得到 “是”，api_mapping 和 label_prototypes 作为公共/不必要或无关转换得到 “否” 的流程正常运行的案例。

3/50 玩家移动输入处理

第 3 项被 Qwen 通过版本分离代码标记。

标记摘要：

syntax_scope: separate  
label: 玩家移动输入处理  
reason: 输入检查本身相似，但由于 Godot 4 引入的 Input.get_vector() 和 CharacterBody2D 的 move_and_slide() 签名更改，需要拆分代码结构。  
godot3_focus: 继承 KinematicBody2D，手动计算 velocity.x/y 并调用 move_and_slide(up_direction)  
godot4_focus: 继承 CharacterBody2D，使用 Input.get_vector() 简化对角线移动并去除 move_and_slide() 参数

验证结果：

不匹配：

提示观察：

在混合搜索中，代码块与相似的 JSONL 候选一起出现是自然的。因此验证提示需要判断搜索候选是否是实际需要在当前 SOURCE_CODE 上应用的依据。第 3 条不匹配显示该问题未被充分固定，导致 Qwen 将 api_mapping 和 label_prototypes 解释为宽泛的相关性匹配，而非迁移必要性。

尤其在第 3 条中出现以下问题：

• 像 move_and_slide 这样在 Godot 3/4 两侧都可能出现的函数名单独匹配时，Qwen 可能倾向于 “是”。
• 当基于 Godot 3 的 JSONL 粘贴到已是迁移后代码的 Godot 4 中时，label_prototypes · 需要转换 不应返回 “是”。
• 当基于 Godot 4 的无关转换 JSONL 粘贴到 Godot 3 代码中时，只要该转换并非实际要应用，也不应返回 “是”。
• 核心在于验证问题，而非 JSONL 的生成方式。需要判断当前代码是迁移前、迁移后，还是完全不同的转换。

因此我们将提示基准改为如下：

• 将验证问题从 “JSONL 与代码是否相关” 改为 “是否应基于此 JSONL 对当前 SOURCE_CODE 进行迁移”。
• 如果当前 SOURCE_CODE 已是 Godot 4 目标形式，即使 JSONL 与迁移说明有关，也应标记为 “否”，因为已经应用。
• label_prototypes · 需要转换 仅在当前 SOURCE_CODE 包含迁移前的使用方式、参数结构、调用模式时才标记为 “是”。
• 对于无关转换 JSONL，即使验证对象是 Godot 3 代码，只要当前 SOURCE_CODE 并非实际要应用的转换，也应标记为 “否”。
• JSONL 的每个字段都是判断上下文。验证阶段应依据这些上下文判断当前 SOURCE_CODE 是迁移前状态还是已迁移后状态。
• 因为 source_api 与 target_api 可能共享相同名称，或 match_terms 中同时出现 source/target 术语，仅函数名或宽泛的 match_terms 匹配不应视为 “是”。
• 即使函数名相同，只有当调用参数、返回值处理、继承节点、周边代码结构等 JSONL 所描述的 source‑side 迁移前模式在 SOURCE_CODE 中直接出现时，才标记为 “是”。
• 若 JSONL_GENERATED_FROM_CODE_VERSION 与 VERIFY_TARGET_CODE_VERSION 不同，应先区分当前 SOURCE_CODE 是 JSONL 的迁移前代码还是已迁移后代码。

4/50 玩家移动速度及加速度应用

第 4 项也被 Qwen 标记为版本分离代码。

标记摘要：

**label:** 玩家移动速度及加速度应用  

**reason:** 在 Godot 4 中，物理节点从 KinematicBody 改为 CharacterBody，move_and_slide() 的签名改为参数传递方式，导致代码结构发生变化。  

**godot3_focus:** 在 Godot 3 中，将速度分配给 velocity 属性后调用 move_and_slide()，使用 KinematicBody2D/3D  

**godot4_focus:** 在 Godot 4 中，通过 move_and_slide(velocity) 传递参数，使用 CharacterBody2D/3D，应用加速度时使用 lerp() 或 move_toward()

验证结果：

不一致：

提示观察：

4 次不一致比 3 次少，但原因相同。api_mapping 中 source 和 target 函数名相同或相似时，Qwen 会因 “该 JSONL 解释了该函数的更改” 的宽泛相关性判断而给出 “是”。但此工具所需的不是相关性判断，而是当前代码是否需要迁移。

因此，以 4 次观察为基准，验证提示被强化为不仅检查 API 名称匹配，还要一起查看：

• 当前代码是否实际包含 JSONL 的变更前模式
• 即使函数名相同，调用参数和返回值处理方式是否符合变更前代码
• 若验证对象代码已经是变更后形式，迁移需求是否为 “否”
• 无关的转换 JSONL 是否不会因单纯相关性而被标记为 “是”

5/50 玩家最大速度限制

第 5 项被 Qwen 标记为版本分离代码。

标记摘要：

syntax_scope: separate  
label: 玩家最大速度限制  
reason: 由于 Godot 3 的 KinematicBody2D 与 Godot 4 的 CharacterBody2D 之间类名更改、move_and_slide() 方法签名以及 velocity 传递方式的差异，需要单独的代码。  
godot3_focus: 继承自 KinematicBody2D，在 self.velocity 中分配速度后调用 move_and_slide()，使用 limit_length() 限制速度  
godot4_focus: 继承自 CharacterBody2D，在 velocity 变量中分配速度后通过 move_and_slide(velocity) 明确传递，应用 limit_length()

生成的代码流程：

验证结果：

不一致：

提示观察：

第 5 条接近混合搜索实际可能出现的情况。以后在数据库中搜索时，不会只出现完全不相关的 JSONL，而是会出现同一 API 或同一移动/速度处理系列的相似候选一起出现。这时验证提示应关注 “这个 JSONL 是否直接说明当前 SOURCE_CODE 的实际行为”，而不是 “是否为相似的搜索候选”。

在本次第 5 条中，api_mapping 和 label_prototypes 在 Godot 3/4 双方验证中都按期待工作。特别是当已经应用于 Godot 4 代码的形式或 no_change、pattern_validation 性质的 JSONL 被附加时，结果为 “否”，这可以视为对之前第 3/4 条中出现的迁移判定问题的某种缓解信号。

相反，docs_chunks 仍需进一步观察。docs_chunks 并非判断迁移是否应用，而是说明依据匹配，因此仅凭相同的 API 名称或相同的版本线索就得到 “是”，会在混合搜索候选验证阶段留下噪声。因此后续验证提示需要更强力度地确认 docs_chunks 中的说明与 SOURCE_CODE 的目的、目标对象、结果状态是否真正一致。

6~10/50 追加验证记录

从 6 到 10 号先记录结果，然后再修改验证提示的顺序进行。本阶段不对提示进行修改，只记录当前工具在各槽位的正确与错误情况。

整体摘要：

按项摘要：

6、9、10 号在当前基准下全部符合预期。6 号中 Godot 3 的 PackedScene.instance()、Input.is_mouse_button_pressed(1)、get_viewport().get_mouse_position() 流程与 Godot 4 的 instantiate()、InputEventMouseButton、get_global_mouse_position() 流程被分离，正确/错误候选也各自区分清晰。9 号的敌人移动与旋转的版本分离候选也全部符合预期。10 号归为公共语法，get_viewport_rect().size、global_position、hide() 为依据的屏幕外处理在文档说明上为“是”，而 api_mapping/label_prototypes 类型的迁移候选为“否”。

不一致：

观察：

本次 6~10 号整体显示出改进信号。102 次验证中有 97 次符合期望，6、9、10 号全部通过。尤其是公共语法的 10 号，api_mapping 与 label_prototypes 均为“否”，说明“对公共代码不强行附加迁移依据”的方向已经起效。

剩余的不一致分为两类。其一如 7 号，Godot 3 基准的迁移依据在 Godot 4 代码上仍被标记为“是”。此时需要更清晰地询问当前代码是已经迁移后的形式还是仍为迁移前的形式。其二如 8 号，docs_chunks 候选因相同主题或相似 API 被误标为“是”。此时需判断说明依据是否直接解释了 SOURCE_CODE 的实际行为，还是仅仅是相似的检索候选。

重要的是，这个问题不应通过屏蔽特定字符串或特定候选来解决。以后将 JSONL 放入数据库并通过混合搜索检索时，出现相似但不同的候选是正常现象。因此后续修改应不是人为过滤候选，而是让验证提示更准确地判断当前 SOURCE_CODE 与检索候选之间的关系。

记录后应用的验证提示加强：

• 在 docs_chunks 中，当 JSONL 生成基准版本与验证目标版本不同时，首先确认 JSONL 是否解释了当前验证目标版本代码的行为。
• 即使版本不同，只要明确说明了公共 API/公共行为，可仍标记为“是”；但若候选解释的是各版本代码结构或节点/API 差异，则需单独确认其是否与当前 SOURCE_CODE 的行为一致。
• 在 api_mapping 与 label_prototypes 中，首先判断当前 SOURCE_CODE 是迁移前代码、已迁移后代码、无关代码，还是不需要转换的代码。
• 将“是”仅限于当前 SOURCE_CODE 为迁移前代码且 JSONL 所述的转换需要立即应用的情形，并据此明确表述。
• 此次加强不是针对特定字符串的处理，而是强化了对混合搜索上来的候选依据当前代码进行判定的流程。

验证结果查看

验证结果会在每个槽位下按版本单独显示。

通过这种方式，可以在同一槽位内直接看到以下信息。

Godot 3 代码验证前 / 响应 / 期望 / 是否匹配  
Godot 4 代码验证前 / 响应 / 期望 / 是否匹配

以前只显示“这个 JSONL 对/错”。现在可以看到“将代码附加到哪个代码时对/错”。

当前工具解决的问题

开发生产力的变化

在制作工具之前，要进行一次测试需要手动完成以下工作。

1. 向 Qwen 说明测试项目  
2. 请求 Godot 3 代码  
3. 请求 Godot 4 代码  
4. 请求 docs_chunks 正确/错误 JSONL  
5. 请求 api_mapping 正确/错误 JSONL  
6. 请求 label_prototypes 正确/错误 JSONL  
7. 将每个 JSONL 与 SOURCE_CODE 重新拼接并验证  
8. 手动记录是/否结果  
9. 在脑中比较是否符合预期值

现在相同的流程已固定在屏幕内。

1. 项目点击
2. AI标签生成
3. 通用或 Godot 3/4 代码生成
4. 按 JSONL 插槽生成
5. 验证 Godot 3 代码 / 验证 Godot 4 代码
6. 查看结果和提示/响应

尤其生产力提升的部分更接近于“不会混乱”，而不是“快速大量产出”。这项工作比单纯的产量更重要的是判定标准不动摇。随着工具的出现，以下工作变得更容易。

• 先固定是通用语法还是版本分离
• 在屏幕上持续查看各表的 JSONL 用途
• 将生成标准的期望与实际验证结果分离
• 将相同的 JSONL 在 Godot 3/4 代码中交叉验证
• 立即查看失败槽位的 Prompt 和 raw response
• 在重复 50 项时减少人需要记住的状态

仍未解决的问题

该工具尚不是最终评估器。现在它是调试工具。

未解决的问题如下。

• docs_chunks 的说明依据即使版本不同也可能被认可为通用说明的情况。
• 在 api_mapping 中，如果 source/target 字符串都写入 JSONL，Qwen 只看到 target 字符串就可能回答“是”。
• label_prototypes 中，区分 before/after 模式可能比单纯的字符串匹配更重要。
• 目前的期望响应计算仅作为调试依据，后续实际的 score/F1 计算标准需要另行完善。
• 搜索候选的筛选问题和验证 Prompt 判定问题仅凭结果难以直接分离。

当前结论

6 月 28 日时的感觉是“手动做 50 条测试”。实际操作后发现需要测试的维度太多，通用语法与版本分离、生成标准版本与验证目标版本混在一起时很快就会混乱。

6 月 30 日制作工具后，这个问题基本得到整理。现在可以不仅仅把 Qwen 生成的 JSONL 看作对/错，还能看到它是在哪段代码中生成、在何处验证。

该工具以后在加入 docs_chunks、api_mapping、label_prototypes 的实际搜索结果时，也可以以同样方式使用。也就是说，它不仅适用于手动演示数据，也能用于数据库搜索结果的验证，成为后续工作的基础工具。