Qwen 测试用 JSONL 架构与用途

编写日期：2026年 6月 28日

目的

使用 Qwen 创建 Godot 代码块，并在该代码块上附加正确的 JSONL 与错误的 JSONL，以进行 “是”/“否” 验证时，整理参考的 JSONL 格式以及每个 JSONL 的用途。

本文档不是提供示例数据的文档。它是用于在测试时确认哪些 JSONL 执行何种角色、哪些字段用于直接依据判定的架构参考文档。

公共标准

JSONL 在每一行写入一个 JSON 对象。

{...}
{...}
{...}

测试中不使用包装表名的 wrapper，而是将对应目标表列的字段放在顶层。

好:
{"chunk_id":"...","content":"...","code_blocks":[...]}

避免:
{"table":"docs_chunks","payload":{"chunk_id":"..."}}

DB中自动生成或写入搜索索引的字段，即使在测试 JSONL 中也不需要手动填充。

DB 运营字段	测试 JSONL 标准
`id`	排除
`embedding`	排除或 null
`search_tsv`	排除
`created_at`	排除

在 Qwen 直接依据验证中，重要的是“JSONL 中的哪个字段与 SOURCE_CODE 的实际字符串/API/模式直接匹配”。

docs_chunks

用途

docs_chunks 是将官方文档说明、教程、class reference 正文以 chunk 为单位保存的 JSONL。

用于代码说明请求、通用 API 用法确认、Godot 3/4 通用语法说明确认。它不是用于迁移规则本身，而是用于确认“这段代码直接关联到哪篇官方文档说明”。

JSONL 格式

{
  "chunk_id": "text, required",
  "doc_version": "text, required",
  "source_url": "text, required",
  "source_file": "text, required",
  "source_sha256": "text, required",
  "doc_type": "text, required",
  "symbol": "text or null",
  "section_path": "array, required",
  "heading": "text or null",
  "content": "text, required",
  "code_blocks": "array, required",
  "language_tags": "array<string>",
  "godot_version_tags": "array<string>",
  "api_symbols": "array<string>",
  "token_count": "integer or null",
  "metadata": "object"
}

直接依据的字段

字段	直接依据标准
`content`	必须说明 SOURCE_CODE 中的 API、函数名、节点名、代码模式
`code_blocks`	必须包含与 SOURCE_CODE 相同的代码字符串或调用模式
`api_symbols`	必须与 SOURCE_CODE 中的 API/符号直接匹配
`heading`	辅助依据。仅标题相同且没有正文/代码依据时较弱
`godot_version_tags`	仅作版本参考。仅凭此判断为 `是` 不可

在测试中的作用

案例	期望
SOURCE_CODE 使用 `get_viewport_rect().size`，且 `content` 或 `code_blocks` 中也有相同表达	`是`
仅共享与 SOURCE_CODE 相同的宽泛主题，实际字符串/API 不存在	`否`
说明 Godot 3/4 通用语法且代码字符串直接匹配	`是`
仅版本标签匹配且无代码依据	`否`

api_mapping

用途

api_mapping 是一个 JSONL，用于记录 Godot 3 到 Godot 4 中名称、类名、函数名、符号名的变化。

用于判断简单的名称更改、重命名、替换、已弃用/已移除的 API。函数使用方式整体变化的例子更适合放在 label_prototypes 那里。

JSONL 格式

{
  "mapping_id": "text, required",
  "source_api": "text, required",
  "target_api": "text or null",
  "change_type": "text, required",
  "godot_from": "text, required",
  "godot_to": "text, required",
  "confidence": "text, required",
  "evidence_chunk_ids": "array<string>",
  "match_terms": "array<string>",
  "notes": "text",
  "negative_patterns": "array<string>"
}

直接依据的字段

字段	直接依据标准
`source_api`	必须在 SOURCE_CODE 中实际出现
`target_api`	用于验证转换后代码或迁移说明
`match_terms`	必须与 SOURCE_CODE 中的实际字符串/API 完全匹配
`notes`	辅助说明。相比单独依据，更倾向于与 source_api/match_terms 一起查看
`negative_patterns`	如果 SOURCE_CODE 符合此模式，则反而成为 `否` 的依据

在测试中的作用

案例	期望
SOURCE_CODE 中有 `KinematicBody2D` 且 JSONL `source_api` 也是 `KinematicBody2D`	`是`
SOURCE_CODE 中有 `yield(` 且 JSONL `match_terms` 中有 `yield(`	`是`
JSONL 为 `Camera -> Camera3D` 但 SOURCE_CODE 是 `KinematicBody2D`	`否`
仅出现 Godot 3/4、migration 等宽泛词汇	`否`

label_prototypes

用途

label_prototypes 是保存函数使用方式、参数构成、调用模式整体变化示例的 JSONL，而不是单纯的名称更改。

如果 api_mapping 是“哪个名字变成了什么”，那么 label_prototypes 更接近于“代码应如何模式化编写”。

{
  "prototype_id": "text, required",
  "label": "text, required",
  "task_type": "text, required",
  "input_pattern": "text, required",
  "expected_finding": "text, required",
  "recommended_action": "text, required",
  "evidence_mapping_ids": "array<string>",
  "evidence_chunk_ids": "array<string>",
  "severity": "text",
  "validator_rules": "object"
}

validator_rules可以具有以下子字段。

{
  "required_when_seen_in_code": "array<string>",
  "before_code": "text",
  "after_code": "text",
  "reject_when_seen_in_code": "array<string>"
}

直接依据的字段

字段	直接依据标准
`input_pattern`	必须与 SOURCE_CODE 的调用模式直接匹配
`expected_finding`	说明需要寻找什么问题/模式
`recommended_action`	转换或说明方向
`validator_rules.required_when_seen_in_code`	必须在 SOURCE_CODE 中实际出现才算 “是” 依据
`validator_rules.before_code`	若与 SOURCE_CODE 完全相同的前置代码模式，则为强 “是” 依据
`validator_rules.reject_when_seen_in_code`	若 SOURCE_CODE 中出现该模式，则该原型为 “否”

在测试中的作用

案例	期待
SOURCE_CODE 中有 `yield(get_tree().create_timer(...), "timeout")` 且 `before_code` 也是相同模式	`是`
SOURCE_CODE 中有 `move_and_slide(velocity)` 且原型说明了该调用方式的更改	`是`
SOURCE_CODE 是 `yield` 但原型是 `Color8` 转换	`否`
与 SOURCE_CODE 共享相同标签但实际没有模式	`否`

三个 JSONL 的边界

JSONL	核心问题	主要需要匹配的内容
`docs_chunks`	这段代码是否直接关联某官方文档说明/教程	`content`, `code_blocks`, `api_symbols`
`api_mapping`	代码中包含的 API/符号在 Godot 3 → 4 中是否改名或目标变更	`source_api`, `target_api`, `match_terms`
`label_prototypes`	这段代码的使用方式/参数/调用模式是否属于整体更改的示例	`input_pattern`, `validator_rules`, `before_code`

公共语法处理

Godot 3 与 Godot 4 中相同的语法不视为版本差异。

情况	使用的 JSONL	判定标准
`_ready()`, `_process(delta)`, `print()` 等通用代码	对应代码/函数的 JSONL 1 个 + 完全不同函数的 JSONL 1 个	若同一代码块有直接依据则为 `是`，完全不同函数则为 `否`
将与通用语法无关的 migration JSONL 关联	`api_mapping` 或 `label_prototypes` 错误答案	若实际没有 API/模式则为 `否`
出现 Godot 3 特有 API	Godot 3 专用 JSONL + Godot 4 专用 JSONL	与 SOURCE_CODE 中的 Godot 3 字符串/模式直接匹配的 JSONL 为 `是`
出现 Godot 4 特有 API	Godot 4 专用 JSONL + Godot 3 专用 JSONL	与 SOURCE_CODE 中的 Godot 4 字符串/模式直接匹配的 JSONL 为 `是`