2026-06-18 Godot RAG 工作重置回顾

今日状态

昨天在咖啡馆喝了大约 1 升咖啡，今天状态非常差。因此没有办法好好编码。即使如此，还是把现在想到的大致内容以及昨天为什么整理工作记录下来。

当前架构中不足的部分

当前 Godot LLM/RAG 架构中不足的部分如下。这些部分需要在后续进行改进。

静态分析层薄弱  
没有基于 GDScript AST/解析器的验证  
Godot 项目依赖图薄弱  
运行/语法验证薄弱  
标签 taxonomy 仍然粗糙  
LLM 生成物与已验证答案的来源区分薄弱  
数据泄漏/重复消除设计薄弱

特别是仅靠 RAG 试图解决的部分是不可行的。Godot 代码判别不仅是文档检索的问题，还必须同时考虑实际的 GDScript 语法、scene/resource 依赖、项目结构以及 Godot 3/4 API 的差异。然而昨天的流程是先对官方文档进行分块（chunking），再把结果交给 LLM 反馈。这种方式表面上看似快速进行，但实际上验证标准一直在动摇。

6 月 17 日工作整理的原因

6 月 17 日，我让 LLM 负责分块，然后把产出再次交给 GPT 进行反馈。但无论怎么看，这种方式都不合适。

之所以爬取官方文档，是为了以整个 Godot 文档为依据。但在工作中途，LLM 在文档尚未被充分分析时，就把 “MVP 核心” 之类的部分判断为重要 API，硬编码特定关键词或过度强化周围语境。这样一来，就不是基于完整官方文档的 RAG，而是变成了只针对少数关键词的搜索引擎。

问题不仅仅是结果不满意。我在未亲自核实的情况下，LLM 自行制定标准，依据该标准生成文件，再根据这些结果进行下一步判断。于是出现了在未查看原始文档结构的情况下产生幻觉（hallucination），后期连 LLM 自己也不知道哪些文件是依据什么标准生成的。

更大层面上，ChatGPT 或 Codex 会在我未指示的方向上随意缩小或改变范围，这种现象非常明显。我本想基于完整官方文档查看结构，而不是让它挑选 “MVP 核心 API” 并硬编码。我并未指示这样做。但 LLM 在中途自行判断 “如果是 MVP，这些就是核心”，甚至在步骤尚未完成时就生成了下一个产出。

特别出现问题的模式如下。

用户希望基于完整官方文档进行结构分析  
-> LLM 任意确定 MVP 范围  
-> 判断部分 API 为核心  
-> 首先进行硬编码/过度强化/目录生成  
-> 在验证之前制作下一阶段产出物  
-> 结果被包装成看似合理的数字  
-> 实际上原始结构和标注标准被污染

这并不是单纯的实现失误，而是工作方式的问题。ChatGPT 或 Codex 在答案尚未出现时，就假设已经有答案，并且在锁定步骤之前倾向于直接进入下一步。表面上看像是在听从指示，实际上却会重新解释指示范围，甚至完全忽视指示，出现先尝试构建“看起来不错的完整形态”的现象。

在本次工作中尤其危险的一点是，LLM 未能正确区分其生成的中间产物的可信度。官方文档中确认的事实、正则意外匹配的词、用户直接批准的规则、LLM 推测的补充信息混在一起。就在这种状态下再次让 LLM 评估结果，结果就变成了 LLM 为自己生成的内容进行似是而非的合理化。

为什么清空 Chunking 产出

今天整理了昨天创建的 RAG Chunking 相关文件。

整理的对象如下。

v1 docs_chunks.jsonl
v2 docs_chunks_v2.jsonl
v3/v3.1 catalog/index/mapping 产出
分块/后处理/验证 草稿脚本
初始 RAG chat/index 草案

最初我只认为 v3/v3.1 有问题，但再仔细看看，v1 和 v2 也需要从根本上重新审视。原本应该从块（chunk）本身开始分析。例如，需要先了解 Godot 类参考实际上是怎样的结构，方法/属性在原始文档中是如何呈现的，Sphinx 转换的结果会以何种方式出现错误。

然而实际情况是，生成块的结果先于原始文档的分析。于是，v1 更像是基于字符数的碎片，v2 则是在其基础上进行后处理的形式。表面上看到了块数量、JSONL 解析成功、doc_type 分布等数字，但真正关键的 “这些块能否作为判断 Godot 3/4 的依据” 并没有得到充分验证。

尤其需要检查 class reference 中 CharacterBody2D.move_and_slide 这类结构是否能够稳定存在，velocity 这类属性是否能够准确分离，以及在迁移文档中如何提取 old/new 关系。如果在未完成这些检查的情况下就给 trusted_api_symbols、syntax_symbols、api_mapping 等起名，得到的只会是看起来合理但实际上被污染的数据。

所以今天我把包括 v1/v2 在内的块产出全部清空。这不是放弃工作，而是为了不再把错误的基准线当作基准线而进行的整理。

今日结论

今日的结论很简单。

需要重新进行分块。  
在此之前，需要先分析 `outputs/godot_docs_full/pages` 原始文档结构。  
不能在没有验证的情况下将 LLM 生成的中间产出作为下一步的依据。

我甚至还没确认，LLM 就自行判断，并且在没有正确查看原始内容的情况下混入了幻觉，结果是 LLM 本身都不知道自己做了什么。在这种状态下继续生成文件，只会增加调试文件，且无法弄清楚标准是什么。

今后不再信任 ChatGPT 或 Codex “自行决定的良好方向”进行扩展实现。尤其是在数据集、标注器、RAG 判别器等标准至关重要的工作中，需要遵循以下原则。

如果 LLM 任意确定 MVP 范围，则中止  
如果包含未经用户批准的硬编码，则中止  
如果在没有原始结构分析的情况下生成产出，则中止  
如果没有验证报告就进入下一阶段，则中止  
如果 LLM 生成物与已验证答案的来源混合，则中止

如果明天再做，第一步不是创建新目录。首先需要分析 godot_docs_full 本身。也就是说，要确认 outputs/godot_docs_full/pages 中的官方文档 Markdown 实际是什么结构，并以此结构重新考虑如何将哪些单元划分为块。

现在需要的问题不是“先放入哪个 API”，而是更接近于下一步。

godot_docs_full 中的 class reference 文档是以什么模式构成的？  
method/property/signal/constant 列表能在原始 Markdown 中可靠地分离吗？  
migration 文档的表格/列表/句子结构是什么形式？  
tutorial 文档不能使用与 class reference 相同的分块标准吗？  
是否需要根据文档类型采用不同的块单元？  
在页面级、章节级、API 成员级中应以哪一种作为默认块？  
在分块之前应先定义什么验证报告？

最终的任务不是“重新制作RAG”，而是分析 godot_docs_full，重新进行符合 Godot 官方文档的块级设计。只有在此之后才需要重新进行分块。

2026-06-18 Godot RAG 工作 重置 回顾