Markdown -> JSONL LLM 分类方式

编写日期：2026年 6月 25日

目的

在 make_md 网页转换器中记录让 LLM 判断将官方文档 Markdown 发送至 docs_chunks、api_mapping、label_prototypes 中哪一个 JSONL 目标的方式。

本文档不存储网页应用代码或 API 密钥。基于当前运行的本地实现，整理向 LLM 提供的输入以及仅允许的输出。

当前执行状态

本地网页 UI 在以下地址运行。

http://localhost:8501/

当前运行进程位于 /Users/joyeongjin/make_md，使用 streamlit run app.py --server.port 8501 启动。

分类调用位置

在当前实现中，表格分类由 classify_tables() 负责。

/Users/joyeongjin/make_md/app.py

分类调用在转换之前执行。

-> classify_tables()
-> 已选择的 table 列表
-> 按 table 调用 call_qwen_api()
-> 生成 JSONL record
-> validate_record()
-> 保存

LLM 输入

在分类阶段传递给 LLM 的输入有以下三项。

输入	说明
system message	强制只返回 JSON。禁止 Markdown、说明、思考文本。
filename	已上传的 Markdown 文件名
full markdown	整个 Markdown 正文

分类阶段必须发送完整的 Markdown 正文。不能只发送前面的 excerpt。仅查看官方文档的前部进行分类时，像 api_mapping 和 label_prototypes 这类在后面的示例或详细说明中才出现边界的文档可能会被错误分类。

LLM 输出格式

LLM 必须仅返回一个 JSON 数组。

允许的值：

["docs_chunks", "api_mapping", "label_prototypes"]

示例：

["docs_chunks"]

["api_mapping", "label_prototypes"]

[]

[]仅在判断为非有用的官方文档内容时使用。

当前提示摘要

分类提示的核心应如下。

Classify this Markdown into zero or more target tables.
Return exactly one JSON array.
Valid values are:
["docs_chunks", "api_mapping", "label_prototypes"]

Table boundaries:
- docs_chunks: official documentation explanations, tutorials, class reference chunks.
- api_mapping: Godot 3 -> Godot 4 function/class/symbol name changes.
- label_prototypes: usage-pattern migrations where arguments, call shape, or usage style changed, not just the name.

Rules:
- Use [] only if the file is not useful documentation content.
- Use one or more valid table names when conversion is needed.
- Do not include explanations, markdown fences, or any text outside JSON.

FILE: <filename>
FULL MARKDOWN:
<entire markdown text>

判别标准

LLM需要一起传递三个表的边界。

表	预期边界
`docs_chunks`	官方文档说明正文、教程、class reference 章节
`api_mapping`	Godot 3 → Godot 4 中函数名、类名、符号名的变化方式
`label_prototypes`	当函数使用方式、参数构成、调用模式整体改变时该如何编写

api_mapping 和 label_prototypes 的边界尤其重要。仅名称改变的属于 api_mapping，而参数构成或调用方式本身改变的属于 label_prototypes。

JSON 校正流程

如果 LLM 未正确返回 JSON 数组，则再次发送校正请求。

校正请求的核心如下。

Your previous classification response was not valid JSON.
Rewrite it as exactly one JSON array using only these strings:
["docs_chunks", "api_mapping", "label_prototypes"].
Use [] only if this file is not useful documentation content.

保正请求仍然失败时，该文件将记录为 classification error。

硬编码 fallback 是否存在

当前的分类阶段基于文件名、路径、正则表达式的硬编码 fallback，不会强制选择表格。

如果没有 API key，则不进行分类。若 Qwen 响应不是有效的 JSON 数组且在校正时也失败，则随机选择的表格不会保存，而是记录为错误。

调试记录

分类结果会以以下形式记录在会话状态中。

{
  "file": "example.md",
  "parsed_result": ["docs_chunks"],
  "matched_tables": ["docs_chunks"],
  "raw_response": "<qwen raw response>"
}

此记录用于在 Qwen 返回非 JSON 响应、返回 [] 或返回无效的表名时确认原因。