2026-06-25 源代码分析与 Markdown 分类回顾

今天重新整理了将官方文档 Markdown 划分为三个 JSONL 表的标准。

最初考虑将 Godot 官方文档 Markdown 分为 docs_chunks、api_mapping、label_prototypes 三个表。但 docs_chunks 和 api_mapping 的作用明确，而 label_prototypes 的使用边界却模糊不清。

一开始这三个表的边界不清。随后在重新审视流程图时，我自行确定了这三表都是以相同方式将官方文档 Markdown 分类为 JSONL 并保存的对象。

整理后的结论如下。

docs_chunks 是 Godot 4 官方文档的依据。
api_mapping 是保存 Godot 3 → Godot 4 中函数名、类名、符号名如何变化的 JSONL 对象。
label_prototypes 是保存函数使用方式、参数构成、调用模式整体改变时该如何编写的 JSONL 对象。

以后将按文件系统单元分析 Godot 项目。把 .gd、.tscn、.tres、project.godot 等文件拆分为 AST/代码片段单元，并使用所需的官方文档 JSONL 依据。随后按需调用 Qwen 3.6，判断该片段是 Godot 3 还是 Godot 4，是否需要迁移，是否可用作代码说明数据。

将判断结果存入 score DB，并按项目将 Godot 3/Godot 4/mixed/unknown 文件系统分类。之后基于已分类的文件系统设计 SFT 与 DPO 的源码。

Markdown 分类初始化

今天废弃了 Markdown → JSONL 的分类结果。

原因是分类阶段并未将整个 Markdown 传递给 LLM，而只传了前 3000 字。用户的意图和需求是从头到尾查看官方文档后再进行分类。但 LLM 生成的代码将传递范围任意限制在前部，且未能及时发现这一点。官方文档仅凭前部有时无法体现文档性质，尤其是 api_mapping 与 label_prototypes 的边界，需要判断是函数名/符号变更，还是函数使用方式/参数/调用模式变更。

整理的标准：

Markdown 分类时要传递文件名和整个 Markdown 正文。
不仅凭前部 excerpt 来选择表。
之前的 JSONL 输出和已写入 PostgreSQL 的数据因标准偏差全部作废。
清空 DB 与 JSONL 后重新开始分类。

初始化结果：

godot_rag.docs_chunks：0 条
godot_rag.api_mapping：0 条
godot_rag.label_prototypes：0 条
godot_rag.ingest_reports：0 条
本地 JSONL 输出删除
重启 Streamlit 应用

本次工作中类似的错误再次出现。

这并非用户从一开始就设计错误，而是 LLM 生成的代码和文档偏离了用户意图，且未能及时发现。问题不只是一次遗漏，而是在整理表边界和数据流的过程中，多次出现相同的确认缺失。错误的重复正如“失误是能力的一部分”，这部分需要更加注意。

尤其是在未准确确认实现前就对文档下结论，或把尚未确定的 schema 与流程写成已确定的内容，导致 docs_chunks、api_mapping、label_prototypes 本应同级时，却把某个表写成特殊流程，破坏了文档的一致性。

以后在推进工作时，几乎必须把文档编写作为必需步骤。文档化的目的不是为了展示，而是确认当前依据何种标准在判断。代码或数据有任何改动，都要记录该改动来源的标准，防止同样的错误再次出现。

如果这次仍未对当前代码结构进行文档化就继续下去，可能会更晚发现问题。编写 LLM 分类方式文档时，发现实际代码只传递了前 3000 字而非完整 Markdown，随后按原需求改为传递完整 Markdown。于是这件事成为了“文档化不仅是整理，更是验证代码实际行为是否符合用户意图”的案例。

RunPod 中断与转换重启观察

在 Markdown → JSONL 转换过程中，RunPod 服务器意外停止，导致本地网页应用中进行的转换被中断。随后重新启动 Streamlit 应用，检查状态是保持原样还是从头开始。

观察依据是 state.json 中保存的各文件状态以及网页应用的 Latest Processing Log。重启前后核对的关键证据如下。

重启前状态为 done 47、deferred 7、converting 1、pending 1515。
当时正在处理的文件是 pages/classes__class_astar3d__23ef6ac2.md。
应用重启后日志记录了 앱 재시작 후 자동 이어하기를 일시정지함（应用重启后自动续传被暂停）。
随后出现 처리 중이던 파일을 pending으로 되돌림（将正在处理的文件恢复为 pending）日志，目标文件仍为同一 pages/classes__class_astar3d__23ef6ac2.md。
再次启动时，该文件出现 기존 분류 재사용（复用已有分类）日志，完成后继续处理下一个文件。
随后依次处理 pages/classes__class_astargrid2d__51463855.md、pages/classes__class_atlastexture__336f837e.md、pages/classes__class_audiobuslayout__a2e0df1f.md，done 计数逐步增加。

通过这些观察确认了以下几点。

转换结果整体未被重置。
正在处理的文件安全地回到了 pending 状态。
已完成的文件不会再次处理。
若已有分类结果，则会被复用。
重启后会从上次中断的点继续执行。

然而，RunPod 服务器意外停止时，转换流程可能长时间等待或中断。对于长时间的转换任务，需要设置能够快速感知 RunPod 服务器状态、API 响应失败、以及本地应用重启的通知。仅凭网页应用界面难以判断是服务器宕机、在等待 API 响应，还是本地应用已退出。

若继续沿用此流程，至少应显著提示以下状态。

RunPod 服务器不可响应
API 超时或 5xx 响应重复出现
Streamlit 应用进程退出
处理中的文件在同一表阶段停留超过一定时间
应用重启导致自动续传被暂停