conversation-json-to-md

会話 JSON から MD へ

概要

ユーザーが提供したチャットエクスポート JSON を、統一された Q&A 形式の複数の Markdown ファイルに変換します。このワークフローでは、ユーザーとアシスタントのやり取りのみを残し、会話ごとに 1 つの Markdown ファイルを作成し、回答の Markdown を保持したうえで、ファイル名と見出し構成を正規化する 2 回目の処理を実行します。

使用する場面

以下をユーザーから依頼された場合に、このスキルを使用します。

• 1 つの JSON チャットエクスポートを複数の .md ファイルに分割する
• 会話ごとに Markdown ファイルを 1 つ作成する
• ユーザーとアシスタントの質問／回答の内容のみを残す
• 回答セクション名を Answer に変更する
• 2 回目の書式設定処理でエクスポート済みファイルを正規化する

使用しない場面

以下の場合は、このスキルを使用しないでください。

• JSON チャットエクスポートを扱わない単純なテキスト変換
• 会話以外の JSON 処理タスク
• 構造変換ではなく、意味的な要約が必要な依頼

手順

1. ユーザーが指定した入力ファイルのパスを読み取ります。デフォルトのファイル名を想定しないでください。
2. 会話／メッセージの構造を自動的に検出します。
3. 会話ごとに Markdown ファイルを 1 つエクスポートします。
4. ユーザーとアシスタントの Q&A の内容のみを残します。
5. 各 Q&A ブロックを次の形式にします。
   • ## <question text>
   • ### Answer
6. 回答の Markdown を保持し、回答内の見出しレベルを 1 つ下げます。
7. 最終的に納品する前に、独立した 2 回目の書式チェックを実行し、ファイル名とタイトル構成を修正します。

対応している入力構造

同梱のスクリプトは、次のような一般的なエクスポート形式に対応しています。

• DeepSeek／ChatGPT に似たマッピングツリー（mapping/root/children/fragments）
• Qwen に似たエクスポート（data[].chat.messages[]、phase=answer を含む content_list）
• Claude Web エクスポート形式（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

出力形式

各出力ファイルは次の構成になります。

# <conversation title>

## <user question 1>
### Answer
<assistant answer markdown>

## <user question 2>
### Answer
<assistant answer markdown>

2 回目の書式設定（必須）

エクスポート後、出力ファイルに対して 2 回目のチェックと修正を実行します。

1. ファイル名の正規化：

• タイトルのみのファイル名にします
• ファイル名に使用できない文字を削除します
• 重複するファイル名には (2)、 (3)…を付けて解決します

2. 見出しの正規化：

• H1 は 1 つだけにします：# <conversation title>
• 質問を H2 にします
• 回答を必ず ### Answer にします

3. 本文の正規化：

• 回答本文の Markdown を保持します
• 回答内の見出しレベルを下げた状態に保ちます

4. 最終確認：

• ファイル名や見出しのルールに違反するファイルが残っていないことを確認します

検証チェックリスト

• ファイル数が検出された会話数と一致している
• ファイル名にランダムな接尾辞がない
• 出力に ## REQUEST や ## RESPONSE の見出しがない
• 回答ブロックが ### Answer になっている
• Markdown が正しくレンダリングされる状態で出力されている