diagram-reports-generator

図のレポート生成ツール

概要

このスキルは、章の Markdown ファイルを分析して、幾何学コースに含まれるすべての図と MicroSim の包括的なレポートを自動生成します。レポートファイルは、すばやく参照できる表形式のビューと、章ごとに整理された詳細ビューの 2 つです。

このスキルを使用するタイミング

次のような場合にこのスキルを使用します。

• 幾何学コースのインテリジェント教科書プロジェクトで作業しているとき
• すべての章にわたる図と MicroSim を監査する必要があるとき
• ビジュアル要素の実装状況を追跡するとき
• 複雑さやブルームのタキソノミーの分布を分析するとき
• 新しい図や MicroSim を追加した後にドキュメントを更新するとき
• 講師やコンテンツ作成者向けのレポートを生成するとき

ワークフロー

ステップ 1: 図のレポート生成スクリプトをインストールする

プロジェクトに図のレポート生成スクリプトがまだない場合は、このスキルに付属するリソースからインストールします。

1. プロジェクト内に src/diagram-reports/diagram-report.py があるか確認します
2. 存在しない場合：
   • ディレクトリを作成します：mkdir -p src/diagram-reports
   • このスキルの scripts/diagram-report.py を src/diagram-reports/diagram-report.py にコピーします
3. すでに存在する場合は、最新の状態か確認します（違いがある場合は、必要に応じてユーザーに差分を表示します）

インストール例：

# Create directory if needed
mkdir -p src/diagram-reports

# Copy script from skill (use Read tool to get script content, then Write tool to create file)
# The script is located in this skill's scripts/diagram-report.py

ステップ 2: プロジェクト構成を確認する

レポート生成ツールを実行する前に、プロジェクト構成を確認します。

1. 現在の作業ディレクトリが幾何学コースのルート（または任意のインテリジェント教科書プロジェクト）であることを確認します
2. docs/chapters/ に章のディレクトリが含まれていることを確認します（形式：01-chapter-name、02-chapter-name など）
3. 出力先として docs/learning-graph/ ディレクトリが存在することを確認します

ステップ 3: レポート生成ツールを実行する

Python スクリプトを実行してレポートを生成します。

python src/diagram-reports/diagram-report.py

スクリプトは次の処理を行います。

• docs/chapters/ 内のすべての章ディレクトリをスキャンします
• 各章の index.md ファイルを解析します
• 「#### Diagram:」ヘッダーがある <details> ブロックから図と MicroSim の仕様を抽出します
• 各要素について、次の項目を分析します。
  • 種類（図または MicroSim）
  • 状態（指定されている場合は実装状況）
  • ブルームのタキソノミーのレベル
  • UI 要素の数
  • 推定難易度（簡単、中程度、難しい、非常に難しい）
  • 学習目標

ステップ 4: 生成されたレポートを確認する

スクリプトの実行後、docs/learning-graph/ に次の 2 つのファイルが作成されたことを確認します。

1. diagram-table.md - 次の列を含む、並べ替え可能な表形式のビュー：

   • 章番号
   • 要素のタイトル（章のセクションへのリンク付き）
   • 状態
   • 種類（図／MicroSim）
   • ブルームのタキソノミーのレベル
   • UI 要素の数
   • 難易度

2. diagram-details.md - 章ごとに整理された詳細ビュー。次の内容を含みます。

   • 章ごとの概要
   • 各要素の詳しい説明
   • 学習目標
   • 元の章のセクションへのリンク付きタイトル

ステップ 5: ナビゲーション設定を確認する

生成されたレポートは、すでに MkDocs のナビゲーションにリンクされているはずです。mkdocs.yml ファイルの「Learning Graph」セクションに次の項目があることを確認します。

- Learning Graph:
    - Diagrams Table: learning-graph/diagram-table.md
    - Diagrams Details: learning-graph/diagram-details.md

項目がない場合は、ナビゲーション構成に追加します。

ステップ 6: レポートをプレビューする

生成されたレポートを表示するには、次の手順を実行します。

1. mkdocs serve を実行して、ローカル開発サーバーを起動します
2. 「Learning Graph」セクションに移動します
3. 「Diagrams Table」または「Diagrams Details」をクリックします
4. すべての図と MicroSim が、正確な情報とともに適切に一覧表示されていることを確認します

レポート出力について

難易度の推定

スクリプトは、次の項目に基づいて難易度を推定します。

• 要素の種類：MicroSim はより高い基本難易度から開始します
• UI の複雑さ：スライダー、ボタン、ドロップダウンなどのコントロールの数
• 機能：アニメーション、回転、3D／アイソメトリック表示、リアルタイム計算
• キャンバスサイズ：キャンバスが大きいほど複雑さが増します

難易度レベル：

• 簡単：静的な図やシンプルな可視化
• 中程度：1～3 個の UI 要素を使った基本的なインタラクティブ機能
• 難しい：4～6 個の UI 要素を使った中程度のインタラクティブ機能、または複雑な機能
• 非常に難しい：多数の UI 要素を使った高度なインタラクティブ機能、または高度な機能

ブルームのタキソノミーの検出

スクリプトは、仕様に記載されたブルームのタキソノミーのレベルを自動的に検出します。

• 記憶
• 理解
• 応用
• 分析
• 評価
• 創造

トラブルシューティング

要素が見つからない

レポートに要素が 0 件と表示される場合：

• チャプターの Markdown ファイルに、#### Diagram: ヘッダーとそれに続く <details> ブロックが含まれていることを確認してください
• <details> ブロックに仕様の内容が含まれていることを確認してください
• 詳細ログフラグを付けて実行してください：python src/diagram-reports/diagram-report.py --verbose

情報が不足している

要素の種類、ステータス、その他のフィールドが欠落している場合：

• チャプターファイル内の <details> ブロックの形式を確認してください
• 仕様に **Type:**、**Status:**、**Learning Objective:** の各フィールドが含まれていることを確認してください
• 種類が明示されていない場合、スクリプトは内容から種類を推定します

レポート内のリンク切れ

チャプターへのリンクが機能しない場合：

• チャプターのディレクトリ名が ##-descriptive-name のパターンに従っていることを確認してください
• MkDocs のアンカー生成が、スクリプトのアンカー作成ロジックと一致していることを確認してください
• 配信中のサイトで移動してリンクをテストしてください

高度な使い方

出力先のカスタマイズ

別の出力ディレクトリを指定します。

python src/diagram-reports/diagram-report.py --output-dir /path/to/output

CSV 形式で生成

スプレッドシートでの分析に使用します。

python src/diagram-reports/diagram-report.py --format csv

HTML 形式で生成

スタンドアロンの HTML レポートを作成します。

python src/diagram-reports/diagram-report.py --format html

デバッグ用の詳細出力

詳細なログ記録を有効にします。

python src/diagram-reports/diagram-report.py --verbose

インテリジェントな教科書作成ワークフローとの連携

このスキルは、より広範なインテリジェントな教科書作成ワークフローと連携します。

1. コンテンツ作成後：チャプターのコンテンツを生成または更新した後に、このスキルを実行します
2. レビューセッションの前：レポートを生成して、不足や不整合を特定します
3. 計画中：難易度の分布を使用して、実装にかかる労力のバランスを取ります
4. ドキュメント作成用：講師向けガイドやプロジェクトのドキュメントにレポートを含めます

同梱リソース

scripts/diagram-report.py

このスキルには、図と MicroSim のレポートを生成するための完全な Python スクリプトが含まれています。このスキルを初めて使用する際に、スクリプトはユーザーのプロジェクト内の src/diagram-reports/diagram-report.py にインストールされます。

スクリプトは次の処理を行います。

• docs/chapters/ 内のすべてのチャプター Markdown ファイルを分析します
• <details> ブロックから図と MicroSim の仕様を抽出します
• UI の複雑さと機能に基づいて難易度を推定します
• 仕様テキストからブルームのタキソノミーのレベルを検出します
• 表形式と詳細形式の両方のレポートを生成します
• 複数の出力形式（Markdown、CSV、HTML）に対応します