idea_world_labDEV JOURNAL
2026年7月13日星期一

Qwen Validation Debugger 提示应用结构

创建日期:2026年7月13日

文档目的

本文档整理了实际应用于 tools/qwen-validation-debugger 的 Prompt。

仅记录代码在何处生成 Prompt、向哪个 API 发送、以及期望的响应格式,不添加解释。

目标文件

文件 本文档中展示的内容
tools/qwen-validation-debugger/core.js 实际 Qwen 请求中使用的 Prompt 生成函数
tools/qwen-validation-debugger/server.js 接收 Prompt 并发送至 Qwen/OpenAI 兼容 API 的路由
tools/qwen-validation-debugger/public/app.js 哪个按钮/操作调用哪个 API 与 Prompt

API 调用通用结构

server.js 中的 callQwen() 以相同方式发送所有 Prompt。

{
  model,
  messages: [{ role: 'user', content: prompt }],
  temperature: 0
}
来源
endpoint 浏览器输入值 qwenEndpoint
model 浏览器输入值 qwenModel
apiKey 浏览器输入值 qwenApiKey
prompt core.js的提示生成函数返回值

API key 在浏览器中作为请求 body 发送到服务器,但不会存入 localStorage

提示调用路径

屏幕操作 浏览器函数 服务器 API core.js 提示函数 响应整理函数
项目标注 classifyItem() POST /api/classify-item buildClassificationPrompt() extractJsonObject(), normalizeClassification()
代码生成 generateCode() POST /api/generate-code buildCodePrompt() extractJsonObject(), normalizeGeneratedCode()
JSONL 生成 generateJsonl() POST /api/generate-jsonl buildJsonlPrompt() extractJsonObject()
JSONL 验证 verifyJsonl() POST /api/verify-jsonl buildVerificationPrompt() normalizeYesNo()
JSONL 提示预览 renderSlot() 无 API 调用 buildJsonlPromptPreview() 仅用于屏幕显示

表定义

提示中使用的表定义位于 core.jsTABLE_DEFINITIONS 中。

docs_chunks

项目
label docs_chunks
purpose 用于确认官方文档说明性依据是否直接匹配代码块。
directFields content, code_blocks, api_symbols, heading, symbol

schema:

chunk_id
doc_version
source_url
source_file
source_sha256
doc_type
symbol
section_path
heading
content
code_blocks
language_tags
godot_version_tags
api_symbols
token_count
metadata

api_mapping

项目
label api_mapping
purpose 确认 Godot 3 到 Godot 4 的名称、类、函数、符号如何更改的依据是否直接对应代码块。
directFields source_api, target_api, match_terms, notes

schema:

mapping_id
source_api
target_api
change_type
godot_from
godot_to
confidence
evidence_chunk_ids
match_terms
notes
negative_patterns

label_prototypes

项目
label label_prototypes
purpose 确认不是简单的名称更改,而是函数使用方式、参数构成、调用模式整体改变的示例依据是否直接对应代码块。
directFields input_pattern, expected_finding, recommended_action, validator_rules.required_when_seen_in_code, validator_rules.before_code, validator_rules.after_code

schema:

prototype_id
label
task_type
input_pattern
expected_finding
recommended_action
evidence_mapping_ids
evidence_chunk_ids
severity
validator_rules

插槽案例定义

getSlotCase({ tableName, versionKey, expectation })决定 JSONL 生成提示中要放入的 goalgenerationRuleexpectedAnswer

条件 label expectedAnswer goal generationRule
docs_chunks + positive 说明依据 JSONL 创建直接说明 SOURCE_CODE 的官方文档式 JSONL。 JSONL 的说明/代码/符号字段中至少有一个必须与 SOURCE_CODE 中的实际字符串/API 调用直接匹配。
docs_chunks + negative 其他代码说明 JSONL 虽然与 SOURCE_CODE 的部分 API/主题重叠,看起来像搜索候选,但实际是说明其他代码行为的官方文档式 JSONL。 即使 JSONL 与搜索候选在部分 API 或主题上重叠也可以,但不得直接说明 SOURCE_CODE 的核心目的、目标对象、最终行为/结果。
expectation === negative + versionKey === migration 无关转换 JSONL 创建既不适用于 Godot 3 代码也不适用于 Godot 4 代码的无关 3→4 转换/模式 JSONL。 JSONL 采用 3→4 转换格式,但不能直接涉及 GODOT3_SOURCE_CODE 的变更前依据,也不能直接涉及 GODOT4_TARGET_CODE 的变更后依据。
expectation === negative + 除 migration 之外 无关转换 JSONL 创建不应应用于 SOURCE_CODE 的无关转换/模式 JSONL。 JSONL 必须涉及其他 API、其他节点、其他调用模式,且不能成为 SOURCE_CODE 的转换来源依据。
versionKey === migration + positive 3→4 转换依据 JSONL Godot 3 示例 / Godot 4 否 创建将 Godot 3 代码的变更前模式转换为 Godot 4 代码的变更后形式的 3→4 转换依据 JSONL。 JSONL 的 source_api、source_pattern、match_terms、input_pattern、before_code、required_when_seen_in_code 必须与 GODOT3_SOURCE_CODE 的实际变更前字符串/API 调用直接匹配;target_api、after_code、recommended_action 必须说明 GODOT4_TARGET_CODE 的变更后形式。
versionKey === godot3 + positive 需要转换 JSONL 创建展示必须将 SOURCE_CODE 中的 Godot 3/源端 API 或调用模式转换为 Godot 4 的 JSONL。 JSONL 中的 source_api、source_pattern、match_terms、input_pattern、before_code、required_when_seen_in_code 中至少有一项必须与 SOURCE_CODE 中的实际转换源字符串/API 调用直接匹配。
versionKey === godot4 + positive 已经应用 JSONL 创建如果 SOURCE_CODE 已经是 Godot 4 目标形式,则不应被判定为额外迁移依据的 JSONL。 JSONL 必须包含 target_api、after_code、signature_stable、no_change、common syntax 等已应用或无需转换的方向,并且不能让 SOURCE_CODE 被判定为转换来源。
其他 positive 通用/不必要 JSONL 创建如果 SOURCE_CODE 属于通用语法,则不应被判定为 api_mapping 或 label_prototypes 迁移依据的 JSONL。 JSONL 必须包含 target_api、after_code、signature_stable、no_change、common syntax 等已应用或无需转换的方向,并且不能让 SOURCE_CODE 被判定为转换来源。

1. 标注提示

调用位置

项目
浏览器函数 classifyItem(itemId)
服务器 API POST /api/classify-item
core 函数 buildClassificationPrompt({ itemTitle })
输入值 itemTitle
响应 JSON syntax_scope, label, reason, godot3_focus, godot4_focus

提示原文

你是 Godot 代码测试项目分类器。

判断下面的 TEST_ITEM 是否可以在 Godot 3 和 Godot 4 中使用相同的语法/相同的代码块进行测试,还是需要分别为 Godot 3 和 Godot 4 编写代码。

判断标准:
- 如果是使用相同的 GDScript 语法和相同的 API 调用,在 Godot 3/4 中都能自然解释的项目,则为 “common”。
- 类名、函数名、签名、节点名、调用方式等在不同版本中有意义的差异的 API/语法,则为 “separate”。
- 若不明确则归为 “separate”。更安全地生成更多测试更好。
- 必须仅输出一个 JSON 对象。

JSON 格式:
{
  "syntax_scope": "common 或 separate",
  "label": "简短的中文标签",
  "reason": "为什么这样判断的一两句话",
  "godot3_focus": "生成 Godot 3 代码时的关注点",
  "godot4_focus": "生成 Godot 4 代码时的关注点"
}

TEST_ITEM:
${itemTitle}

响应规范化

normalizeClassification(parsed) 保存以下内容。

内部字段 来源
syntaxScope parsed.syntax_scope
label parsed.label
reason parsed.reason
godot3Focus parsed.godot3_focus
godot4Focus parsed.godot4_focus

syntax_scope 只能是 commonseparate

2. 代码生成提示

调用位置

项目
浏览器函数 generateCode(itemId, versionKey)
服务器 API POST /api/generate-code
core 函数 buildCodePrompt({ itemTitle, syntaxScope, targetVersion })
输入值 itemTitle, syntaxScope, targetVersion
响应 JSON godot_version, syntax_scope, source_code, notes

versionInstruction 分支

targetVersion versionInstruction
common 编写一个在 Godot 3 和 Godot 4 中都通用的 GDScript 代码块。
godot3 编写一个仅在 Godot 3.x 中出现差异的 GDScript 代码块。
godot4 编写一个仅在 Godot 4.x 中出现差异的 GDScript 代码块。

提示原文

你是用于 Godot 测试的代码块生成器。

${versionInstruction}

要求:
- 不是整个项目,而是按函数或小代码块编写。
- 仅编写与测试项目直接相关的代码。
- 代码中必须显式包含用于版本判断的 API/语法。
- 回答必须仅输出一个 JSON 对象。
- 不要使用 Markdown 代码块标记。

JSON 格式:
{
  "godot_version": "${targetVersion}",
  "syntax_scope": "${syntaxScope}",
  "source_code": "GDScript 代码块",
  "notes": "代码中需要确认的关键点"
}

TEST_ITEM:
${itemTitle}

响应规范化

normalizeGeneratedCode(parsed) 保存以下内容。

内部字段 来源
godotVersion parsed.godot_version
syntaxScope parsed.syntax_scope
sourceCode parsed.source_code
notes parsed.notes

如果 source_code 为空,则进行失败处理。

3. JSONL 生成提示

调用位置

项目
浏览器函数 generateJsonl(itemId, slotId)
服务器 API POST /api/generate-jsonl
core 函数 buildJsonlPrompt({ itemTitle, tableName, expectation, versionKey, versionLabel, sourceCode, targetCode })
输入值 itemTitle, tableName, expectation, versionKey, versionLabel, sourceCode, targetCode
响应 JSON 对象

sourceCode / targetCode 选择

app.jsgetJsonlGenerationCodes(detail, slot) 决定放入 JSONL 生成提示的代码。

slot.versionKey SOURCE 输入
migration GODOT3_SOURCE_CODE 使用 detail.codes.godot3.sourceCodeGODOT4_TARGET_CODE 使用 detail.codes.godot4.sourceCode
common SOURCE_CODE 使用 detail.codes.common.sourceCode
godot3 SOURCE_CODE 使用 detail.codes.godot3.sourceCode
godot4 SOURCE_CODE 使用 detail.codes.godot4.sourceCode

提示原文

你是用于 Godot RAG 测试的 JSONL 生成器。

目标:
${slotCase.goal}

目标表:
${table.label}

表用途:
${table.purpose}

字段列表:
${table.schema.map((field) => `- ${field}`).join('\n')}

对直接匹配判断重要的字段:
${table.directFields.map((field) => `- ${field}`).join('\n')}

生成规则:
- 必须仅输出一个 JSON 对象。
- 不使用 Markdown 代码块。
- ${slotCase.generationRule}
- docs_chunks 是说明依据匹配,api_mapping 和 label_prototypes 是迁移源依据匹配。
- 已经以 Godot 4 目标形式应用的代码或通用语法不是 api_mapping/label_prototypes 中的 “需要转换” 依据。
- negative_patterns 和 reject_when_seen_in_code 是拒绝条件。此字段中的字符串应解释为 “否” 依据,而不是 “是” 依据。
- 不要只匹配宽泛的主题词,而是根据实际字符串/API 调用使相关/无关区分开来。
- 不要随意增加表用途之外的字段。
- source_url、source_file、*_id 值请自然地编写用于测试。

测试项目:
${itemTitle}

代码版本:
${versionLabel}

${isMigrationPair ? `GODOT3_SOURCE_CODE:
${sourceCode}

GODOT4_TARGET_CODE:
${targetCode}` : `SOURCE_CODE:
${sourceCode}`}

服务器响应中一起包含的值

POST /api/generate-jsonl 响应包括以下内容。

响应字段 内容
prompt 实际发送给模型的提示
rawResponse 模型原始响应
jsonl 通过 extractJsonObject() 解析的对象
jsonlText JSON.stringify(parsed) 的结果
expectedAnswer expectedAnswerForSlot() 的结果

4. JSONL 验证提示

调用位置

项目
浏览器函数 verifyJsonl(itemId, slotId, targetVersionKey)
服务器 API POST /api/verify-jsonl
core 函数 buildVerificationPrompt({ tableName, sourceVersionKey, targetVersionKey, sourceCode, jsonlText })
输入值 tableName, sourceVersionKey, targetVersionKey, sourceCode, jsonlText
模型输出

question 分支

tableName question
docs_chunks 判断下面的 JSONL 是否为直接说明 SOURCE_CODE 的官方文档型依据。
api_mapping, label_prototypes 判断是否应根据下面的 JSONL 对当前 SOURCE_CODE 进行迁移。

firstRule 分支

tableName firstRule
docs_chunks 在 docs_chunks 中,仅当 JSONL 直接说明 SOURCE_CODE 的实际字符串、API 调用、代码目的、适用对象、结果时才为 “是”。
api_mapping, label_prototypes 在 api_mapping 和 label_prototypes 中,仅当 JSONL 说明当前 SOURCE_CODE 需要立即应用的更改前模式时才为 “是”。

docs_chunks tableRules

- 在 docs_chunks 中,只有当 JSONL 直接说明 SOURCE_CODE 的核心行为时,才允许 “是”。
- 核心行为不仅是简单的 API 名称,还包括代码计算了什么、应用于哪些对象、最终产生什么状态/结果。
- 即使出现相同的 API 或相同的方法,只要 JSONL 说明的是不同的目的、不同的目标对象、不同的结果,则仅是检索候选而非直接依据,因此为 “否”。
- 如果 JSONL 只提供相同 API 的一般说明,而未说明 SOURCE_CODE 的具体资源、分支、循环、状态变化,则不是直接说明依据,因此为 “否”。
- 根据 SOURCE_CODE 是重复执行、单次执行、状态转换还是资源替换的流程,如果 JSONL 的流程不同,则为 “否”。
- 在同一文件或同一游戏流程中一起出现的功能可以相互成为检索候选。即使如此,只有当 SOURCE_CODE 的最终目的、目标、结果与 JSONL 所说明的最终目的、目标、结果相同时,才为 “是”。
- 即使 api_symbols 或标题中出现了 SOURCE_CODE 的部分调用名称,只要 content/code_blocks 说明的是不同的工作流程,也不是直接说明依据。
- 仅仅符合生命周期函数、公共类型、一般属性名等在多个代码中重复出现的外围线索,并不是直接依据。
- 如果 JSONL 的 code_blocks 说明的是与 SOURCE_CODE 不同的示例代码,即使部分 API 相同,也为 “否”。
- 不要凭自己的知识将意义相似的其他 API 或相似的使用案例推断为等同。JSONL 必须直接呈现当前 SOURCE_CODE 的目的/目标/结果。
- 如果 JSONL_GENERATED_FROM_CODE_VERSION 与 VERIFY_TARGET_CODE_VERSION 不同,需先确认 JSONL 是否说明了当前待验证版本的代码行为。
- 即使版本不同,只要明确说明了公共 API/公共行为,也可能为 “是”,但如果 JSONL 的 code_blocks/api_symbols 与当前 SOURCE_CODE 的实际语法/API 调用不符,即使看起来是相同功能,也为 “否”。

api_mapping / label_prototypes tableRules

api_mapping和 label_prototypes的提问不是“JSONL和代码是否有一点关联”,而是“是否应该根据此 JSONL 更改当前 SOURCE_CODE”。
- 首先根据 JSONL 判定当前 SOURCE_CODE 属于“更改前代码、已更改后代码、无关代码、无需转换代码”中的哪一类。  
- “是”仅在当前 SOURCE_CODE 为更改前代码且需要立即应用 JSONL 所述转换时才允许。  
- 3→4 合并 JSONL 是基于同时查看 Godot 3 更改前代码和 Godot 4 更改后代码而得出的依据。验证时需区分当前 SOURCE_CODE 是更改前代码还是更改后代码。  
- 如果当前 SOURCE_CODE 已是 Godot 4 target 形式,即使 JSONL 看起来与迁移说明相关,也视为“已应用”,答案为“否”。  
- label_prototypes 的“需要转换”判断仅在当前 SOURCE_CODE 实际包含更改前的使用方式、参数构成、调用模式时才为“是”。  
- 与当前 SOURCE_CODE 无关的转换 JSONL,即使验证对象是 Godot 3 代码,只要不适用于当前代码,也返回“否”。  
- source/before/required 系列内容视为更改前代码依据,target/after/recommended 系列内容视为更改后形式,negative/reject 系列内容视为如果在当前代码中应用该转换则不应出现的条件。  
- 即使函数名相同,只有当调用参数、返回值处理、继承节点、周边代码结构等 JSONL 所述的更改前模式直接保留在 SOURCE_CODE 中时,才算“是”。  
- source_api 与 target_api 可能共享相同名称,或 match_terms 中同时出现 source/target 术语。这种情况下,仅函数名或宽泛的 match_terms 匹配并不构成“是”。  
- 同一文件或同一游戏流程中共同出现的功能可以相互成为搜索候选,但如果当前 SOURCE_CODE 中没有直接保留的更改前模式,仍然返回“否”。  
- 若 JSONL_GENERATED_FROM_CODE_VERSION 与 VERIFY_TARGET_CODE_VERSION 不同,需先区分当前 SOURCE_CODE 是 JSONL 的更改前代码还是已更改后代码。  
- 若 JSONL_GENERATED_FROM_CODE_VERSION 不是迁移而是单一版本槽,则仅当当前验证目标代码中直接存在 source/before/required 模式时才为“是”。  
- 若当前 SOURCE_CODE 与 JSONL 的 target/after/recommended 形式相同或更为新颖,则视为已应用代码,答案为“否”。  
- 若验证目标版本为 Godot 4 或 common,而 SOURCE_CODE 已是 target/after 形式,即使 JSONL 是正确的迁移知识,也对当前代码返回“否”。  
- 当 change_type 为 signature_stable、no_change、common 等表示无需转换时,答案为“否”。  
- 即使在 Godot 4 代码或通用语法代码中附带迁移 JSONL,只要不需要额外转换,也返回“否”。

decisionRules

- 在判定之前,用一句话概括 SOURCE_CODE 的核心操作,并用一句话概括 JSONL 所描述的核心依据,然后进行比较。  
- 仅当两者的目标对象、调用目的、输入/参数流向以及最终结果方向一致时,才视为直接依据。  
- 即使看起来像相似的搜索候选,如果它不解释当前的 SOURCE_CODE 或不适用于当前的 SOURCE_CODE,则为“否”。

提示原文

你是 JSONL 依据匹配判定器。

${question}

表格:
${table.label}

表格用途:
${table.purpose}

判定标准:
- ${firstRule}
- 要检查的 JSONL 字段: ${table.directFields.join(', ')}
- ${tableRules.join('\n- ')}
- ${decisionRules.join('\n- ')}
- 仅当出现 Godot、Godot3、Godot4、migration、2D、physics 等宽泛词汇时,视为无关。
- JSONL 中出现 “does not describe”、 “not related”、 “unrelated”、 “does not apply” 等否定表述的内容不被视为相关依据。
- 如果 JSONL 内容涉及其他 API、其他节点、其他系统,则为 “否”。
- 不要使用你已知的 Godot 知识,只使用 JSONL 中的字符串依据。
- 回答必须仅输出 “是” 或 “否” 其中之一。

JSONL_GENERATED_FROM_CODE_VERSION:
${sourceVersionKey}

VERIFY_TARGET_CODE_VERSION:
${targetVersionKey}

SOURCE_CODE:
${sourceCode}

JSONL:
${jsonlText}

响应 正规化

normalizeYesNo(text)只接受以下响应作为有效值。

输入 形式 内部 值
yes
아니오 아니오
no 아니오
code fence 上面的值 对应的值
第一行的上方值 对应值
其他 空字符串

5. JSONL 提示 预览

app.jsbuildJsonlPromptPreview()不是发送给模型的函数,而是用于在屏幕上显示的预览。

调用 位置

项目
浏览器 函数 renderSlot()
API 调用
使用 目的 slot 内部的 JSONL 生成 提示 details 区域显示

预览 原文

你是用于 Godot RAG 测试的 JSONL 生成器。

目标: ${slotCase.goal}
目标表格: ${table.label}
表格用途: ${table.purpose}
直接匹配字段: ${table.directFields.join(', ')}

TEST_ITEM: ${itemTitle}
CODE_VERSION: ${versionLabel}

${isMigrationPair ? `GODOT3_SOURCE_CODE:
${sourceCode || '(Godot 3 代码生成后自动填写)'}

GODOT4_TARGET_CODE:
${targetCode || '(Godot 4 代码生成后自动填写)'}` : `SOURCE_CODE:
${sourceCode || '(代码生成后自动填写)'}`}

slot 生成规则

app.jsgetSlotSpecs(detail) 会根据 classification 结果创建 slot。

common

如果 classification 为 common,则创建以下 slot。

versionKey tableName expectation
common docs_chunks positive
common docs_chunks negative
common api_mapping positive
common api_mapping negative
common label_prototypes positive
common label_prototypes negative

separate

如果 classification 为 separate,则创建以下 slot。

versionKey tableName expectation
godot3 docs_chunks positive
godot3 docs_chunks negative
godot4 docs_chunks positive
godot4 docs_chunks negative
migration api_mapping positive
migration api_mapping negative
migration label_prototypes positive
migration label_prototypes negative

expectedAnswer 计算

JSONL 生成响应的 expectedAnswer

expectedAnswerForSlot({ tableName, versionKey, expectation }) 返回 getSlotCase()expectedAnswer

用于验证结果比较的 expectedAnswer

expectedAnswerForVerification({ tableName, sourceVersionKey, targetVersionKey, expectation }) 的规则如下。

条件 expectedAnswer
expectation === negative
tableName === docs_chunkssourceVersionKey === targetVersionKey
tableName === docs_chunkssourceVersionKey !== targetVersionKey
tableNameapi_mappinglabel_prototypes,且 sourceVersionKey === migrationtargetVersionKey === godot3
tableNameapi_mappinglabel_prototypes,且 sourceVersionKey === migrationtargetVersionKey !== godot3
tableNameapi_mappinglabel_prototypes,且 sourceVersionKey === godot3targetVersionKey === godot3
其他情况

提示词更改记录表

以后修改提示词时在下表后继续添加。

日期 函数 更改前的文字/规则 更改后的文字/规则 确认结果
2026-07-13 整体 当前代码基准提示结构 基准线文档化 记录完成
buildClassificationPrompt()
buildCodePrompt()
buildJsonlPrompt()
buildVerificationPrompt()