Godot ソース分析 点数化 アーキテクチャ
作成日: 2026年 6月 25日
目的
Godot 公式ドキュメント RAG を利用して GitHub ソースコードをプロジェクト単位で分類し、その後 SFT/DPO データ生成へとつながるフローを整理する。
今回の整理の核心は docs_chunks、api_mapping、label_prototypes をすべて同じ公式ドキュメント Markdown → JSONL 分類対象とすることです。文書の性質に応じて説明チャンクは docs_chunks、関数名/クラス名/シンボル名の変更は api_mapping、関数の使用方法/引数構成/呼び出しパターンの変更は label_prototypes に送ります。
現在の結論
初期の公式ドキュメント収集段階で準備する主要テーブルは次の 3 つです。
| テーブル | 役割 |
|---|---|
docs_chunks |
公式ドキュメントの説明本文、チュートリアル、class reference チャンク保存対象 |
api_mapping |
Godot 3 → Godot 4 で関数名、クラス名、シンボル名がどのように変わったかを保存する対象 |
label_prototypes |
関数の使用方法、引数構成、呼び出しパターンが丸ごと変わった場合の記述方法を保存する対象 |
| 項目 | 整理 |
|---|---|
| 既存の混乱 | 最初は 3 つのテーブルがそれぞれ別々の動作フローを持つと考えていた。 |
| 新しい境界 | 3 つのテーブルはすべて公式ドキュメント Markdown を JSONL に分類する際に使用する保存対象である。 |
| 現在の優先順位 | 当初の計画通り 3 つのテーブルを維持し、文書の性質に応じて 1 つ以上の JSONL に分類保存する。 |
最終分析単位
入力は GitHub プロジェクトまたはローカルプロジェクトディレクトリです。
分析器はファイルシステムを走査し、Godot 関連ファイルを AST またはコード断片単位に分割します。
初期対象:
| ファイル | 用途 |
|---|---|
.gd |
GDScript AST/行/関数単位分析 |
.tscn, .tres |
シーン/リソース内の class、script、node type 手がかり抽出 |
project.godot |
プロジェクトバージョン、機能、レンダラ、autoload などプロジェクト手がかり抽出 |
| README/文書 | プロジェクト説明と Godot バージョンヒントの補助 |
On-demand LLM 呼び出しフロー
LLM は常時起動させておくのではなく、必要な AST/コード断片ごとにオンデマンドで呼び出します。
各 AST 断片は次の根拠とともに LLM に渡されます。
AST/code chunk
+ 必要な公式ドキュメント JSONL 検索結果
+ 出力 JSONL スキーマ
+ プロジェクト/ファイル 識別情報LLM 応答スキーマと score DB 保存カラムはまだ確定していない。現在の文書では、どのテーブルをどのフローで検索し、その結果がファイルシステムの分類にどのように使われるかだけを記録する。
コード説明生成データフロー
コード説明生成では docs_chunks が核心根拠である。
フロー:
- ユーザーが「これ何の意味？」とソースコードを入力する。
- AST Parser がコードを断片に分割する。
- Retriever が
docs_chunksから関連公式文書を検索する。 - Qwen 3.6 がプロンプト、ソースコード断片、検索根拠が相互に関連しているか検証する。
- 関連のない検索結果は破棄する。
- 関連のある根拠とコード断片を再び Qwen 3.6 に渡し、説明 JSONL を生成する。
- Validator が応答を検証する。
- 検証された結果を score DB に保存する。
- score DB の結果でファイルシステムを分類する。
Godot 3 → Godot 4 関数名変換フロー
マイグレーションでは api_mapping が核心根拠である。
フロー:
- ユーザーが「これ変換が必要？」とソースコードを入力する。
- AST Parser が Godot API 候補シンボルを抽出する。
- Retriever が
api_mappingから source API、target API、change type を検索する。 - Qwen 3.6 が検索結果が該当コード断片と実際に関連しているか検証する。
- 関連のないマッピングは破棄する。
- 関連のあるマッピングだけを利用して Godot 3 → 4 マイグレーション JSONL を生成する。
- Validator が変換応答を検証する。
- 検証された結果を score DB に保存する。
- score DB の結果でファイルシステムを分類する。
Godot 3 → Godot 4 使用パターン変換フロー
使用パターン変換では label_prototypes が核心根拠である。
フロー:
- ユーザーが「これ変換が必要？」とソースコードを入力する。
- AST Parser が関数呼び出し、引数構成、呼び出しパターン候補を抽出する。
- Retriever が
label_prototypesから使用方法/引数/呼び出しパターン変換根拠を検索する。 - Qwen 3.6 が検索結果が該当コード断片と実際に関連しているか検証する。
- 関連のないプロトタイプは破棄する。
- 関連のあるプロトタイプだけを利用して Godot 3 → 4 使用パターン変換 JSONL を生成する。
- Validator が変換応答を検証する。
- 検証された結果を score DB に保存する。
- score DB の結果でファイルシステムを分類する。
Score DB
AST 断片ごとの Retriever 検索結果、LLM 検証結果、Validator 通過結果は最終的に score DB に保存される。
score DB は学習データの原本ではなく、ファイルシステムを分類するための判断結果保存庫である。ソース分析過程で得られた Retriever/LLM/Validator の結果を記録する。
docs_chunks検索結果: コード説明要求において公式文書根拠が実際のコードと関連しているか検証した結果api_mapping検索結果: Godot 3 → Godot 4 関数名/シンボル変換根拠が実際のコードと関連しているか検証した結果label_prototypes検索結果: 関数使用方法、引数構成、呼び出しパターン変換根拠が実際のコードと関連しているか検証した結果
score DB のカラム、集計方式、分類ラベルはまだ決まっていない。この文書では score DB が「分類前の判断結果を集める保存庫」という役割だけを固定する。
最終ファイルシステム分類:
project source
-> AST/code chunks
-> official docs JSONL retrieval
-> on-demand LLM verification
-> score DB
-> classified filesystemSFTと DPO の生成
SFT と DPO の詳細設計はまだ決まっていません。現在確定しているのは、スコア DB 自体が学習データソースではないという点です。まずファイルシステムを分類し、その後、分類されたファイルシステムを基に SFT と DPO を設計するためのソースを作成する予定です。
Git アップロード安全基準
今回の文書化では、Web UI、ローカル変換スクリプト、AST 分析スクリプト、API キー、JSONL 成果物、テストソースコードはアップロードしません。
アップロード許可:
- アーキテクチャ文書
- フローチャート画像
- 公開しても問題ない振り返り／ロードマップテキスト
アップロード禁止:
- Streamlit Web アプリコード
- Markdown → JSONL 変換実験スクリプト
- Retriever／AST 分析実験スクリプト
- API キー、エンドポイント、
.env - 収集した全 Markdown 原本 zip
- AST／コードチャンク分析結果
- JSONL 中間成果物
- テスト用にクローンした外部 Godot プロジェクトソース