conversation-json-to-md

用途

Conversation JSON To MD 用于将用户提供的聊天导出 JSON 转换为多个 Markdown 文件，采用一致的问答格式。适用于把一份 JSON 聊天导出拆分为多个 .md 文件、每个会话一个文件、仅保留用户与助手的问答内容、把回答区块重命名为 Answer，以及通过第二遍格式化规范导出文件等场景。

主要能力

• 自动检测会话/消息结构。
• 每个会话导出一个 Markdown 文件。
• 仅保留 user/assistant 的问答内容。
• 每个问答块格式为：## <问题文本>，下一行 ### Answer，再接助手回答 Markdown。
• 保留回答 Markdown，并将回答内部标题层级整体降一级。
• 交付前执行独立的第二遍格式检查并修正命名/标题结构。

支持的输入结构

内置脚本支持常见导出格式，包括：

• DeepSeek/ChatGPT 式 mapping 树（mapping/root/children/fragments）
• Qwen 式导出（data[].chat.messages[]，content_list 中 phase=answer）
• Claude 网页导出样式（list[{ name, chat_messages: [...] }]）
• 通用消息数组（messages、history、conversations、dialog、turns）
• 成对字段（question-answer、prompt-response、input-output）

如果格式检测失败，应停止并要求用户提供样例片段，再扩展解析规则。

使用方式

读取用户提供的输入文件路径，不要假设默认文件名。运行脚本：

python3 scripts/convert_conversations.py \
  --input /path/to/<user-provided>.json \
  --output-dir /path/to/output_md \
  --clean

输出格式如下：

# <会话标题>

## <用户问题 1>
### Answer
<助手回答 Markdown>

## <用户问题 2>
### Answer
<助手回答 Markdown>

第二遍格式化（必需）

导出后对输出文件执行第二遍检查/修正：

• 文件名规范化：仅保留标题命名；移除非法文件名字符；重名以 (2)、(3)… 区分。
• 标题规范化：仅保留一个 H1（# <会话标题>）；确保问题为 H2；确保回答严格为 ### Answer。
• 正文规范化：保留回答正文 Markdown；保留回答内部标题降级。
• 最终校验：确认没有文件仍违反命名或标题规则。

验证清单

• 文件数量等于检测到的会话数量
• 文件名中无随机后缀
• 输出中无 ## REQUEST 或 ## RESPONSE 标题
• 回答块以 ### Answer 形式存在
• 输出可正确保留 Markdown 渲染

限制

不适用于以下情况：纯文本转换（不涉及 JSON 聊天导出）、非会话类 JSON 处理任务、需要语义摘要而非结构转换的请求。