idea_world_labDEV JOURNAL
2026年6月27日星期六

2026-06-27 回顾

今天似乎把目标定在了改进 26 日编写的 source-to-AST 输入流程文档的一致性上。

到昨天为止，整体层次在脑海中是区分开的，但在文档或代码里停留在过于抽象的阶段。虽然能够区分 AST、Retriever、LLM 验证、JSONL 依据等词汇，但在实际项目出现时，哪些文件以什么顺序展开、哪段正文进入 AST Parser、哪些 chunk 直接传给 Retriever 等细节并未具体化。

虽然在脑中觉得已经理解，但一旦开始编写代码，就会强烈担心实现不会朝着自己想要的方向进行。因此今天先重新梳理整体结构，并尝试将该结构设计成可以让人眼睛直接确认的 GUI 形式。

需要具体化的原因

AST 和 Retriever 的角色事实上是区分开的。

.gd 文件会进入 AST Parser，并且需要按函数或声明单元进行切分。Retriever 则需要接收这些代码片段，在数据库中搜索相关的 JSONL 依据。而 LLM 验证则要根据提示、当前 chunk、检索到的 JSONL 来判断这些依据是否真的相关。

仅用语言描述这些会一直模糊不清。尤其在实际项目流程中，文件会先以 # <相对路径> 形式展开，下面的正文按文件划分，.gd 文件的特定函数或声明成为 chunk，而该 chunk 的 chunkText 才会传给 Retriever。

我想要清晰地看到这个流程：哪个文件的哪段正文成为了哪个 chunk，Retriever 接收到的输入是否真的就是该 chunk 本身，文件路径、行号或提示是否没有混入检索输入中，这些都希望在网页界面上直接确认。

于是我认为不仅要写文档，还需要一个用户友好的 GUI 工具来查看。

Source Flow Debugger

最终在实现 Source Flow Debugger 时，能够在同一界面上看到 AST 与 Retriever 的流向。

起初想整理如何把源码交给 AST 处理，结果把 AST chunk、direct chunk、Retriever 输入、数据库检索按钮、Qwen 验证预览等全部拼到了一屏。于是 AST、Retriever、LLM 验证就形成了一个统一的结构，感觉比想象中更方便。

我比较得意的地方在于，没有从一开始就把它做成完整系统，而是作为观察工具来实现。此阶段需要的不是“自动给出答案的工具”，而是确认数据是否按照我设想的流程移动的工具。

今天确认的内容如下。

  • 将 Godot 项目以 # <相对路径> 形式展开。
  • .gd 文件被划分为 AST 性质的 chunk。
  • .godot、.tscn 等文本资源被划分为 direct chunk。
  • README.md 等文档文件在 source-analysis 模式下被排除，并在界面上留下排除原因。
  • Retriever 输入不放入文件路径、行号、提示，只放入 chunkText。
  • 在每个 chunk 下方可以分别搜索 docs_chunks、api_mapping、label_prototypes 表。
  • 随后 Qwen 验证以 prompt + chunkText + retrieved JSONL 结构进行。

在放入一个小的 Godot 项目时，确认被拆分为 5 files、14 chunks、AST 9、Direct 5。这样看来，按 chunk 拆分的流程已经基本成功。

GPT 演示测试

原本计划基于收集的 JSONL 集合寻找相关的 GitHub 仓库，克隆后进行测试。

但思考后发现并不一定要从一开始就去找真实的 GitHub 仓库。现在想确认的是“检索到的 JSONL 是否真的与当前 Godot 代码 chunk 相关，LLM 能否正确判断”。于是让 GPT 生成用于演示的 Godot chunk、相关 JSONL、以及无关 JSONL，先进行测试会更快。

于是特意制作了 Godot 3 代码 chunk，并配上对应的 Godot 3 → Godot 4 转换 JSONL 与完全无关的 JSONL 进行测试。

起初我只是这样简单地询问。

这个 JSONL 包含对应于源代码的内容吗？  
只回答是或否。

于是相关的 JSONL 也显示为 是，无关的 JSONL 也显示为 是。

起初可能会觉得有些遗憾，但反而觉得是件好事。如果在现在这个阶段没有显现出这样的问题，等以后接入真实的数据库搜索时，LLM 可能会用自己的知识把不相关的 JSONL 也合理地拼接出来。

于是把提示词改得更强一些。

你是 JSONL 依据匹配判定器。

请判断以下 JSONL 是否直接包含对下面 SOURCE_CODE 的转换依据。

判定标准：
- 必须有 JSONL 的 `source_api`、`source_pattern`、`match_terms`、`required_when_seen_in_code`、`before_code` 中的任意一项与 SOURCE_CODE 中的实际字符串或 API 调用**完全匹配**，才算“是”。
- 仅仅出现 Godot、Godot3、Godot4、migration、2D、physics 等宽泛词汇不算相关。
- JSONL 中出现 “does not describe”、 “not related”、 “unrelated”、 “does not apply” 等否定表述的内容不视为相关依据。
- 若 JSONL 涉及其他 API、其他节点或其他系统，则为“否”。
- 不要使用你已有的 Godot 知识，只依据 JSONL 中的字符串依据进行判断。
- 回答时只能输出 **“是”** 或 **“否”** 中的一个。

这样修改后，相关 JSONL 为 是，无关 JSONL 为 否。

今天在此实验中得到的基准很重要。Retriever 在获取 JSONL 候选后让 LLM 验证时，不能只看宽泛的相似度。必须先检查 JSONL 中的 source_api、source_pattern、match_terms、required_when_seen_in_code、before_code 等字段是否与当前 chunk 的实际字符串/API 调用直接匹配。

明天的工作

明天似乎需要再制作更多的 demo 集。

需要制作多个与 Godot chunk 相关的 JSONL 和无关的 JSONL，并多次测试 Qwen 如何得出答案。仅凭一两次成功就将其作为基准还为时过早。

尤其需要进一步确认以下情况：

  • 当多个相关 JSONL 混在一起时，Qwen 是否能正确挑选实际依据
  • 当无关 JSONL 仅在关键词上相似时，是否能正确判定为 否 并剔除
  • Qwen 是否能基于字符串依据正确区分 api_mapping 与 label_prototypes 的差异
  • 类似 docs_chunks 的说明文档性质的 JSONL 是否也能以相同方式进行验证
  • 当看起来像 Godot 3 代码但没有 JSONL 依据时，是否不会进行随意迁移

今天总体上是把抽象结构转化为实际界面和输入流程的一天。即使在脑中已经认为了解的内容，实际在网页上展开、拆分并通过搜索输入展示后，也变得更加清晰。

接下来的步骤是多次重复实际 DB 检索和 Qwen 验证，确认这一流程是否保持稳定。