idea_world_labDEV JOURNAL
2026年6月27日星期六

基于 JSONL 收集现状的测试仓库选择观察日志

编写日期：2026 年 6 月 27 日

目的

根据迄今为止生成的 JSONL，判断先克隆哪种性质的 Godot 仓库进行测试更为合适。

这里的目标并不是“随便挑选一个著名的仓库”。首先要看当前数据库中累积的依据在什么领域较强，哪些领域仍然薄弱，然后选择 Retriever 实际能够找到依据的仓库性质。

分析依据如下两个文件。

/Users/joyeongjin/make_md/work/web_jsonl/docs_chunks/docs_chunks.jsonl
/Users/joyeongjin/make_md/work/web_jsonl/api_mapping/api_mapping.jsonl

state.json中包含转换状态、分类提示、原始响应调试，但可能会混入运行时设置值，因此在公开文档中不搬移原文。此观察日志仅保留 JSONL 统计和判断。

快照状态

基于观察时点的转换仍在进行中。

docs_chunks.jsonl: 153 records
api_mapping.jsonl: 117 records
label_prototypes.jsonl: 尚未生成文件

网页转换状态大致如下流程。

done: 132 files
pending: 1425 files
deferred: 11 files
converting: 2 files
classified: 144 files

因此本文档不是最终结论，而是“截至目前收集的 JSONL 基准的第一轮报告选择标准”。

docs_chunks 观察

docs_chunks 已生成 153 条记录。

其构成大致如下。

class_reference: 127
about: 26

在95个 Markdown 原始文件中生成了 chunk，129 条记录中包含了 API 符号。包含 code block 的记录有 36 条。

截至目前，docs_chunks 中显著的区域如下：

Animation 系列  
Audio 系列  
Camera 系列  
Canvas/CanvasItem 系列  
Array/Callable/GlobalScope 类似的基础 API  
AnimatedSprite2D 部分  
AStar/AStarGrid2D 部分

相反，仍然显得薄弱的区域如下。

KinematicBody / CharacterBody migration
move_and_slide 调用方式
yield -> await 转换
Color8 -> Color.from_rgba8 转换
TileMap migration
RigidBody / physics body migration
HTTPRequest / networking

即使在当前时点，docs_chunks 作为 “Godot 4 官方文档说明依据” 可以在一定程度上使用，但仍难以认为已经积累了足够的典型 Godot 3 → Godot 4 2D 动作游戏迁移依据。

api_mapping 观察

api_mapping 已生成 117 条记录。

更改类型如下所示。

rename_or_replacement: 82
behavior_change: 24
deprecated: 11

所有记录的 confidence 都在 verified_from_docs 中。

截至目前，明显的映射区域如下。

Array 方法及其行为差异  
AnimationPlayer / AnimationMixer / AnimationTree / AnimationNode 系列  
AudioStream / AudioEffect / AudioEffectSpectrumAnalyzer 系列  
Camera / Camera3D / CameraAttributes 系列  
CanvasItem draw/modulate 系列  
GlobalScope 部分函数和已弃用的常量  
AStarGrid2D 部分

例如，目前的 JSONL 中包含以下性质的依据。

Camera -> Camera3D  
Camera.get_transform -> Camera3D.get_camera_transform  
WorldEnvironment 曝光 设置 -> CameraAttributes 系列  
AnimationPlayer 的部分功能 -> AnimationMixer 分离  
AnimationNode._process -> AnimationNodeExtension._process_animation_node  
AudioEffectLimiter -> AudioEffectHardLimiter  
Array.sort 行为 变化  
Array.has 的 C# 名称 差异  
CanvasItem.modulate 行为 变化  
CanvasItem.draw_string / draw_rect 行为 变化

这句话的意思是，如果现在立刻进行 migration 测试的话，2D platformer 的 KinematicBody2D 或 move_and_slide 比起 Camera、Animation、Audio、CanvasItem、Array 相关的代码更有可能被卡住。

观察 label_prototypes

在当前快照中没有 label_prototypes.jsonl 文件。

因此在此阶段若要用 Retriever 测试“函数使用方式整体改变的示例”，证据不足。虽然 api_mapping 中也包含了 behavior_change，但那更像是从文档中提取的 API 变更依据，而不是完整的使用模式示例。

所以现在挑选仓库时，宁可先验证已经拥有的 docs_chunks 和 api_mapping 覆盖的领域，而不是主动测试 label_prototypes 的仓库。

现在就适合克隆的仓库特性

按照 JSONL 的标准，最先适合克隆的仓库是“体积小、Godot 版本信息明确、并且使用了当前已有的 mapping 且与之重叠的 API 的实际代码仓库”。

优先级如下：

第一优先级：基于 Godot 3 的小型 Camera/WorldEnvironment/Animation 示例

最好的首个测试候选是 Godot 3 项目中实际使用 Camera、WorldEnvironment、AnimationPlayer、AnimationTree、CanvasItem 绘制、AudioEffect 等功能的小型示例仓库。

原因是当前 api_mapping 已经包含了相应的依据。

Camera -> Camera3D
Camera.get_transform -> Camera3D.get_camera_transform
WorldEnvironment 曝光 设置 -> CameraAttributes
AnimationPlayer -> AnimationMixer 相关变化
AnimationNode / AnimationTree 系列变化
CanvasItem draw/modulate 行为变化
AudioEffect / AudioStream 系列变化

如果克隆这样的仓库，在 AST 片段中会出现 Camera、WorldEnvironment、AnimationPlayer、CanvasItem、AudioEffect 等线索，Retriever 在当前 JSONL 中找到依据的可能性很高。

测试目的也很明确。

Godot 3 代码片段
-> AST 片段
-> api_mapping 搜索
-> docs_chunks 辅助搜索
-> LLM 判断提示预览

即可以直接通过当前数据确认“这段代码是否使用了 Godot 3 API，或者在 Godot 4 中应基于何种依据进行更改”。

二级优先：基于 Godot 4 的小型 Animation/Audio/Camera 示例

第二个候选是用 Godot 4 编写的小示例仓库。

这个仓库更适合用于确认“正常的 Godot 4 代码说明”和“Retriever 是否没有带来错误的 Godot 3 迁移”，而不是用于迁移验证。

当前 docs_chunks 中已经包含了 Animation、Audio、Camera、CanvasItem、Array 等官方文档的说明。因此，当插入 Godot 4 代码片段时，能够很好地查看说明是否以 docs_chunks 为中心进行支撑。

该仓库最好具备以下特性。

带有 project.godot 的完整小项目  
.gd 文件大约 5~30 个  
包含 .tscn 文件  
使用 AnimationPlayer 或 AnimationTree  
使用 AudioStreamPlayer 或 AudioEffect  
使用 Camera2D/Camera3D  
使用 Array、Callable 等基础 API  
大容量资源不多

3顺位：Godot 3和 Godot 4 版本分开的相同主题示例

如果可能，提供将相同主题分为 Godot 3 版本和 Godot 4 版本的示例是最好的。

例如，如果相同的摄像机/动画/音频示例分别位于 Godot 3 分支和 Godot 4 分支，那么比较 Retriever 与 LLM 的判断就很容易。

这种仓库很适合检查以下内容。

Godot 3 片段中 api_mapping 是否正常工作  
Godot 4 片段中 docs_chunks 说明依据是否正常  
如何在 LLM 提示中展示相同功能的不同版本代码差异  
如何在项目层面累计对 godot3/godot4/mixed 的判断

现在立即克隆的仓库类型尚不明确

仅从当前的 JSONL 来看，以下特性的仓库仍然不适合作为首次测试。

典型的 Godot 3 2D 平台游戏

KinematicBody2D、move_and_slide、yield、TileMap、Color8 等线索众多的 Godot 3 2D 平台游戏，后期必然会需要。

但在当前快照中，这些线索在 JSONL 中几乎不存在。若现在就加入此类仓库，Retriever 可能找不到依据，或会拉取与 Animation/Audio/Camera 无关的依据。

因此，这类仓库是“优秀的最终测试候选”，但不是“当前使用 JSONL 直接验证的首选”。

大型完整游戏仓库

资产众多且包含数百个 .gd 文件的大型游戏仓库仍为时过早。

现在需要的不是把大型项目直接交给模型，而是追踪代码片段到底检索了哪些 JSONL 依据。大型仓库的调试范围过大，难以看清哪些依据为何被检索。

首次测试最好使用小且功能明确的示例。

以 C# 为主的仓库

当前 JSONL 中虽有 C# 的提及和部分 C# 名称差异，但整体流程是基于 GDScript AST 和 .gd 片段设计的。

因此，以 C# 为主的 Godot 仓库目前不适合作为首次测试对象。

以 GDExtension / 原生插件为主的仓库

以 GDExtension、C++、Rust 绑定、原生插件为主的仓库同样为时过早。

当前目标是将 Godot 项目的 .gd、.tscn、project.godot 拆分为片段，并观察 Retriever 如何查找官方文档依据。以原生扩展为主的仓库分析方向会不同。

仓库选择标准

根据目前的标准，克隆候选应满足以下条件。

Godot 版本必须能够在 README 或 project.godot 中查看  
必须有 project.godot 文件  
必须有 .gd 文件  
如果有 .tscn 文件会更好  
大容量资产应尽量少  
功能范围应小且明确  
必须包含与当前 JSONL 中的 API 重叠的代码

当前与 JSONL 匹配良好的关键词如下。

Camera
Camera3D
WorldEnvironment
CameraAttributes
AnimationPlayer
AnimationTree
AnimationNode
AnimationMixer
AudioStream
AudioEffect
CanvasItem
draw_string
draw_rect
modulate
Array.sort
Array.has
AnimatedSprite2D
AStar2D
AStarGrid2D

相反，在目前的第一次测试中，作为核心标准还为时过早的关键词如下。

KinematicBody2D
CharacterBody2D
move_and_slide
yield
await
Color8
TileMap
RigidBody2D
HTTPRequest
multiplayer
GDExtension

判断

根据目前收集的 JSONL，如果要选择第一个克隆目标，“小型 Godot 3 迁移候选仓库”是不错的。不过，与其选择常见的 2D platformer，不如选择实际使用 Camera/WorldEnvironment/Animation/Audio/CanvasItem 系列的项目更为合适。

原因很简单。

现在的 api_mapping 已经拥有 Camera、Animation、Audio、CanvasItem、Array 等方面的依据。相反，作为 Godot 3 2D 物理迁移代表线索的 KinematicBody2D、move_and_slide、yield、TileMap 在当前的 JSONL 中几乎不存在。

因此，第一次测试最现实的流程如下。

# 小型 Godot 3 摄像机/动画/音频 示例克隆
- → .gd 和 .tscn 片段化
- → 当前使用 JSONL 进行 Retriever 检索
- → 检查 api_mapping 命中是否与实际代码相关
- → 查看将要输入 LLM 的提示预览

接下来，最好克隆一个用 Godot 4 编写的小型 Animation/Audio/Camera 示例，以确认基于 docs_chunks 的说明生成流程。

最终，当 label_prototypes 生成且 KinematicBody2D、move_and_slide、yield、Color8、TileMap 系列的依据累积后，那时克隆典型的 Godot 3 2D 平台游戏或动作游戏仓库来测试迁移判断更为合适。

结论

现在立即要克隆的仓库性质如下。

第一候选：
  小且版本明确的 Godot 3 示例
  实际使用 Camera / WorldEnvironment / AnimationPlayer / AnimationTree / Audio / CanvasItem 中的部分
  包括 .gd、.tscn、project.godot
  资产不过大

二次候选：
  使用相同领域的 Godot 4 示例
  用于比 migration 更好的代码说明和 docs_chunks 检索质量验证

待处理:
  KinematicBody2D / move_and_slide / yield / 基于 TileMap 的 Godot 3 2D 平台游戏
  在与 label_prototypes 相关的迁移依据进一步累积后进行测试

这一步骤似乎是对当前收集的 JSONL 进行最不浪费的验证方法。