microsim-generator

MicroSim ジェネレーター

バージョン： 1.0

概要

このメタスキルは、可視化の要件に基づいて、MicroSim の作成リクエストを適切な専門ジェネレーターに振り分けます。個別の MicroSim ジェネレーター 17 個のスキルを、特定の実装ガイドを必要に応じて読み込む単一のエントリーポイントに統合します。

src/microsim-utils/ 内の 6 つの Python バッチユーティリティが、MicroSim 生成の反復作業（仕様の解析、ファイルの雛形作成、iframe の挿入、iframe の高さの修正、品質の検証、ナビゲーションの更新）を自動化し、バッチ実行ごとに約 430K トークンを節約します。エージェントの創造的な作業は .js ファイルの作成に集中します。

デフォルトの逐次実行

microsim generator スキルを章のすべての #### 図要素に使用する場合、ユーザーが明示的に「execute in parallel」というフレーズを使わない限り、microsim generator のタスクは必ず逐次実行してください。

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

次のようなリクエストがあった場合に、このスキルを使用してください。

• 対話型の教育用可視化
• データの可視化（チャート、グラフ、プロット）
• タイムラインまたは時系列表示
• 地理情報／地図の可視化
• ネットワーク図または概念マップ
• フローチャートまたはワークフロー図
• 数学関数のプロット
• 集合図（ベン図）
• 優先度マトリクスまたはバブルチャート
• カスタムシミュレーションまたはアニメーション
• 評価付き比較表
• セルの詳細を展開できるマトリクス比較
• すべての統計情報が出典まで追跡できる、事実確認済みのインフォグラフィックポスター
• 章向け MicroSim の一括生成

---

Step 0: 環境設定

生成作業を始める前に、パスを設定し、対象範囲を確認してください。

0.1 パスの設定

# Python utilities live in the ibook-skills repo
UTILS="$HOME/Documents/ws/ibook-skills/src/microsim-utils"

# Detect project root (directory containing mkdocs.yml)
PROJECT=$(python3 -c "
import os, sys
d = os.path.abspath('.')
while d != os.path.dirname(d):
    if os.path.isfile(os.path.join(d, 'mkdocs.yml')): print(d); sys.exit()
    d = os.path.dirname(d)
print('ERROR: mkdocs.yml not found', file=sys.stderr); sys.exit(1)
")

スクリプトが $UTILS に見つからない場合は、プロジェクト内の src/microsim-utils/ ディレクトリを確認してください。

0.2 対象範囲の確認

ユーザーのリクエスト	実行ルート
「第11章の MicroSim を生成して」	章の一括処理 → Step 1
「内接角の MicroSim を作成して」	単一シミュレーション → Step 1B
「Unix の歴史のタイムラインを作成して」	単一シミュレーション → Step 1B

---

Step 1: 章から仕様を抽出する（一括処理ルート）

章単位で生成する場合は必須です。 章の Markdown を手作業で解析しないでください。

python3 $UTILS/extract-sim-specs.py \
    --project-dir $PROJECT \
    --chapter <chapter-dir-name> \
    --output /tmp/ch-specs.json \
    --status-file /tmp/sim-status.json \
    --verbose

この処理の内容：

• 章の index.md からすべての #### Diagram: および #### Drawing: ヘッダーを解析します
• <details> ブロックの内容、iframe のパス、シミュレーション ID、Bloom レベル、ライブラリのヒントを抽出します
• 仕様オブジェクトの JSON 配列（シミュレーションごとに 1 つ）を生成します
• ライフサイクル状態を含む sim-status.json を生成します：specified → scaffolded → implemented → validated → deployed

出力を確認する：

cat /tmp/ch-specs.json | python3 -m json.tool | head -60

ステータスファイルを確認し、作業が必要なシミュレーションを確認してください。

python3 -c "
import json
with open('/tmp/sim-status.json') as f:
    for e in json.load(f):
        if e['status'] != 'deployed':
            print(f\"  {e['status']:12s}  {e['sim_id']}\")
"

抽出後、Step 2 に進んでください。

---

Step 1B: 単一シミュレーションの簡易手順

単一の MicroSim リクエストの場合（章全体の一括処理ではない場合）：

1. 1 エントリーの仕様 JSON を手動で作成します：

cat > /tmp/ch-specs.json << 'EOF'
[{
    "sim_id": "inscribed-angle-theorem",
    "title": "Central vs Inscribed Angles Interactive",
    "summary": "Demonstrates the inscribed angle theorem",
    "heading_type": "Diagram",
    "chapter": "",
    "element_type": "microsim",
    "bloom_level": "Analyze",
    "library": "p5.js",
    "iframe_src": "",
    "iframe_height": "",
    "spec_text": "",
    "status": ""
}]
EOF

2. そのシミュレーションだけをスキャフォールドします：

python3 $UTILS/generate-sim-scaffold.py \
    --spec-file /tmp/ch-specs.json \
    --sim-id inscribed-angle-theorem \
    --project-dir $PROJECT \
    --verbose

3. Step 3（インストラクショナルデザインのチェックポイント）に進み、次に Step 4（.js の実装）に進みます。

---

Step 2: シミュレーションディレクトリをスキャフォールドする

一括生成では必須です。 main.html、index.md、metadata.json を手動で作成しないでください。

python3 $UTILS/generate-sim-scaffold.py \
    --spec-file /tmp/ch-specs.json \
    --project-dir $PROJECT \
    --verbose

この処理の内容：

• 各仕様について docs/sims/<sim-id>/ ディレクトリを作成します
• 正しい CDN リンク、<main> タグ、スキーマの meta タグを含む main.html を生成します
• frontmatter、iframe 埋め込み、全画面表示リンク、レッスンプランの骨組みを含む index.md を生成します
• Dublin Core フィールドと教育用メタデータを含む metadata.json を生成します
• すでに存在するディレクトリは スキップ します（--force を使用した場合を除く）

一部作成済みのシミュレーションで --force を使用する場合：

シミュレーションディレクトリが存在し（main.html + .js がある）、index.md または metadata.json がない場合、スキャフォールドスクリプトはデフォルトでディレクトリ全体をスキップします。--force を使用すると、スキャフォールドファイルをすべて再生成できます。創作作業は .js ファイル内にあり、スキャフォールドによって上書きされることはないため、安全に実行できます。

python3 $UTILS/generate-sim-scaffold.py \
    --spec-file /tmp/ch-specs.json \
    --project-dir $PROJECT \
    --force \
    --verbose

スキャフォールド後、エージェントは以降 .js ファイルのみを作成します。

ステップ 3：インストラクショナルデザインの確認（必須）

.js ファイルを作成する前に、必ずこの確認を完了してください。

3.1 学習目標の詳細を特定する

仕様から以下の内容を抽出してください：

• ブルームの分類：記憶、理解、応用、分析、評価、または創造
• ブルームの動詞：行動を表す動詞（説明する、実演する、計算するなど）
• 学習目標：学習者ができるようになることを示す、目標の全文

3.2 ブルームの分類に合ったインタラクションパターンを選ぶ

ブルームの分類	適切なパターン	不適切なパターン
記憶（L1）	フラッシュカード、マッチング、ラベル付け	複雑なシミュレーション
理解（L2）	段階的に確認する解答例、具体的なデータの可視化	連続アニメーション、パーティクルエフェクト
応用（L3）	パラメータスライダー、計算ツール、練習問題	受動的な閲覧のみ
分析（L4）	ネットワークエクスプローラー、比較ツール、パターン検出ツール	事前計算された結果
評価（L5）	並べ替え／順位付けのアクティビティ、評価基準ツール	フィードバックの仕組みがないもの
創造（L6）	ビルダー、エディター、キャンバスツール	柔軟性のないテンプレート

3.3 以下の質問に答える

作業を進める前に、以下の質問に答えてください：

1. 学習者が見る必要のある具体的なデータは何ですか？

   • 「アニメーションするパーティクル」ではなく、「トークン化された配列 ['physics', 'ball']」

2. 学習者は観察する前に予測する必要がありますか？

   • はいの場合 → ［次へ］／［前へ］ボタンを備えた段階的な確認方式を使用します
   • はいの場合 → 連続アニメーションは使用しません

3. 静的な矢印ではなく、アニメーションを使うことで何が加わりますか？

   • 明確に答えられない場合 → アニメーションは使用しません

4. このブルームの分類に連続アニメーションは適切ですか？

   • 「説明する」という動詞を使う理解（L2）の場合 → ほとんどの場合、いいえ
   • リアルタイムのフィードバックがある応用（L3）の場合 → 多くの場合、はい

3.4 必要に応じて仕様を修正する

理解レベルの目標に対して仕様でアニメーション／エフェクトが求められている場合：

• インストラクショナルデザイン上の懸念事項となる可能性があることを指摘してください
• 代わりに段階的な確認方式を推奨してください
• ユーザーに尋ねてください：「仕様ではアニメーションが求められていますが、『説明する』という目標には、具体的なデータを可視化する段階的な確認方式のほうが、通常は学習を促進します。代わりに段階的な確認方式で進めますか？」

3.5 判断内容を記録する

回答に以下を追加してください：

Instructional Design Check:
- Bloom Level: [level]
- Bloom Verb: [verb]
- Recommended Pattern: [pattern]
- Specification Alignment: [aligned/modified]
- Rationale: [why this pattern supports the learning objective]

---

ステップ 4：.js ファイルを実装する

ここでエージェントの創造的な作業を行います。実装が必要な各シミュレーションについて、以下を行ってください：

4.1 リクエストを分析し、ジェネレーターを選ぶ

仕様を確認してトリガーとなるキーワードを探し、適切なジェネレーターガイドを選んでください。

クイックリファレンス ルーティングテーブル

トリガーキーワード	ガイドファイル	ライブラリ
タイムライン、日付、時系列、イベント、履歴、スケジュール、マイルストーン	references/timeline-guide.md	vis-timeline
地図、地理、座標、緯度、経度、場所、マーカー	references/map-guide.md	Leaflet.js
関数、f(x)、方程式、プロット、微積分、サイン、コサイン、多項式	references/plotly-guide.md	Plotly.js
ネットワーク、ノード、エッジ、グラフ、依存関係、コンセプトマップ、ナレッジグラフ	references/vis-network-guide.md	vis-network
フローチャート、ワークフロー、プロセス、状態機械、UML、シーケンス図	references/mermaid-guide.md	Mermaid.js
ベン図、集合、重なり、共通部分、和集合、カテゴリ	references/venn-guide.md	Custom
チャート、棒、折れ線、円、ドーナツ、レーダー、統計、データ	references/chartjs-guide.md	Chart.js
バブル、優先度、マトリックス、象限、影響と労力、リスクと価値	references/bubble-guide.md	Chart.js
因果関係、フィードバック、ループ、システム思考、強化、均衡、CLD、システムアーキタイプ	references/causal-loop-guide.md	vis-network
比較、テーブル、評価、星、横並び、機能	references/comparison-table-guide.md	Custom
マトリックス、フレームワーク比較、クリック可能なセル、詳細パネル、展開可能	references/html-table.md	Custom
アニメーション、お祝い、パーティクル、紙吹雪、エフェクト	references/celebration-guide.md	p5.js
分類、分類器、カテゴリ分け、シナリオの仕分け、タイプの識別、パターン認識	references/concept-classifier-guide.md	p5.js
図のオーバーレイ、吹き出しラベル、解剖図、ラベル付きイラスト、インフォグラフィックオーバーレイ、探索／クイズモード	references/infographic-overlay-guide.md	Custom (diagram.js) — インタラクティブシミュレーション。ラベルは data.json にあり、画像にはテキストなし
Python ラボ、コードランナー、実行可能なコードブロック、インタラクティブな Python 演習、Docker	references/docker-python-lab-guide.md	Custom (docker-lab.js)
検証済みインフォグラフィック、統計ポスター、ファクトチェック済みポスター、引用付きデータ、出典付きの主張、エビデンスに基づく比較	references/verified-infographic-guide.md	Custom (text-verify → image) — 静的 PNG。数値はピクセルに埋め込まれ、これ単体を最終成果物にしてはいけません
カスタム、シミュレーション、物理、インタラクティブ、バウンス、動き、p5.js	references/p5-guide.md	p5.js

2 つの infographic ルートの見分け方

どちらのルートにも名前に「infographic」が含まれており、よく混同されます。 言葉がどこにあるかを確認して選んでください。

	infographic-overlay-guide.md	verified-infographic-guide.md
生成物	docs/sims/{sim-id}/ の MicroSim	docs/posters/<slug>/ の静的 PNG ＋監査証跡
解決する問題	画像を探索可能かつ測定可能にすること	画像に埋め込まれた数値の捏造を防ぐこと
画像内のテキスト	なし。タイトルさえありません	テキストと数値がコンテンツそのものです
ラベルの配置場所	data.json にあり、実行時に diagram.js で描画	ピクセル内にあり、描画前に固定
ウェブ検索／引用	使用しません	必須（主張ごとに 2 件以上の検索、要素ごとに source_id）
インタラクションイベントの発生	あり（ホバー、クイズの試行）	なし。静止画像は何も発生させません

目安：誤りの可能性がある数値の主張 → 検証済みガイド。名前を付ける必要がある構造 → オーバーレイガイド。 これらはどちらかを選ぶものではありません。以下の 2 つのポリシーにより、分岐ではなくパイプラインを構成します。

ポリシー：インタラクティブをデフォルトとし、静的画像はデフォルトにしません

ユーザーから明示的に求められない限り、成果物として静的画像を生成してはいけません。 フラットな PNG はレベル 1 の成果物です。インタラクションイベントを一切発生させないため、読者が内容を理解したかどうかを判断する材料になりません。このライブラリが対象とするのはレベル 2 以上（ルートの CLAUDE.md を参照）であり、「インフォグラフィックを作って」という依頼へのデフォルトの回答は、インタラクティブなものです。どちらの方法でも対応できる依頼の場合は、ポスターのルートではなく、オーバーレイガイドに従ってください。

ポリシー：検証済みのポスターには必ずオーバーレイを付ける

検証可能な事実を含む静的ポスターを生成した場合（ユーザーから求められたために生成した場合）は、必ずその後にインタラクティブなオーバーレイを付けてください。 これは任意ではなく、後から提案する追加作業でもありません。ポスターのルートに含まれる必須の第 2 段階です。

理由は測定です。ポスターの価値は検証済みの主張にありますが、PNG だけでは、それらの主張に誰かが関心を持ったかどうかを判断できません。grid-diagram.js のオーバーレイでポスターを囲むと、各領域が計測可能なゾーンになります。ホバー、ゾーンの表示、クイズの回答がインタラクションイベントとなり、読者全体の傾向から、インフォグラフィックが教える概念を読者が習得したかどうかを予測できます。ルートの CLAUDE.md にある「2.99」の目標に従い、すべての読者のイベントを集計して概念の理解度を推定してください。特定可能な読者と結び付いた、学生ごとの成績履歴は決して保持しないでください。

手順：フェーズ 8 の後、references/infographic-overlay-guide.md のグリッドオーバーレイワークフローに従い、data.json.image をレンダリング済みの poster.png に指定し、showLabels: false のままにします（ポスターにはすでに列見出しが印刷されています）。引用を表示したままにするため、各主張の source_id をゾーンの facts[] に引き継いでください。

決定木

Numeric claims that must be verified against sources?
  → YES: run Phases 1–4 of verified-infographic-guide.md to lock a cited claim set, then:
      · user explicitly asked for a static poster/image/PNG?
          → render it (Phases 5–8), THEN always add a grid overlay on top (see Exit Route)
      · otherwise → carry the verified claims into the matched sim guide below.
        Never ship a static image the user did not ask for.

Has dates/timeline/chronological events?
  → YES: timeline-guide.md

Has geographic coordinates/locations?
  → YES: map-guide.md

Mathematical function f(x) or equation?
  → YES: plotly-guide.md

Nodes and edges/network relationships?
  → YES: vis-network-guide.md (or causal-loop-guide.md if systems thinking)

Flowchart/workflow/process diagram?
  → YES: mermaid-guide.md

Sets with overlaps (2-4 categories)?
  → YES: venn-guide.md

Priority matrix/2x2 quadrant/multi-dimensional?
  → YES: bubble-guide.md

Standard chart (bar/line/pie/radar)?
  → YES: chartjs-guide.md

Comparison table with ratings/stars?
  → YES: comparison-table-guide.md

Matrix comparison with clickable cells/detail panels?
  → YES: html-table.md

Celebration/particles/visual feedback?
  → YES: celebration-guide.md

Students classify scenarios into categories (sorting quiz)?
  → YES: concept-classifier-guide.md

Labeled illustration with interactive callout markers or hover zones?
  → YES: infographic-overlay-guide.md

Runnable Python code block executed in Docker?
  → YES: docker-python-lab-guide.md

Custom simulation/animation/physics?
  → YES: p5-guide.md

終了ルート：事実検証済みポスター（MicroSim ではありません）

最初に、このルートを選択する条件を確認してください。 ユーザーが静的な ポスター、画像、または PNG を具体的に求めた場合にのみ、このルートを選択します。「インフォグラフィック」とだけ求められ、静的形式が指定されていない場合は、 ポスターを生成せず、検証済みの主張セットを作成するためにフェーズ 1～4 を実施し、代わりにインタラクティブガイドに引き継ぎます（上記の「方針：インタラクティブをデフォルトにする」を参照）。

references/verified-infographic-guide.md は、このスキルで単独では sim ディレクトリを 生成しない唯一のルートです。このルートでは、検証レポートとソースサイドカーを添えて docs/posters/<slug>/ に静的なポスター PNG を生成します。その後、必ずオーバーレイで ラップします（以下を参照）。リクエストがこの条件に該当する場合：

• このファイルのステップ 0～9 をすべてスキップしてください。 スキャフォールドも、 .js も、CANVAS_HEIGHT も、iframe の挿入も、品質バリデーターも、docs/sims/ の エントリーも不要です。
• ガイドを読み、代わりにその8 フェーズのワークフローに従ってください。フェーズ 1～6 は エージェントがテキストのみで作業し、フェーズ 7 で画像モデルを 1 回だけ呼び出し、 フェーズ 8 でレンダリング結果を監査します。
• このルートを設ける理由となる厳格なルール：検証済みのソースがない主張は、画像に 反映してはいけません。 検証できない主張がある場合、パイプラインを止めるか、 定性的な表現に格下げするか、削除します。推測で描画することは決してありません。

フェーズ 9 は必須です：ポスターをインタラクティブオーバーレイでラップしてください。 レンダリングされたポスターは、最終成果物ではありません。フェーズ 8 に合格したらすぐに、 references/infographic-overlay-guide.md のグリッドオーバーレイワークフローに従って、 その上にグリッドオーバーレイ MicroSim を構築してください。

• data.json.image を、レンダリングされた poster.png に設定します。
• showLabels: false を維持します。ポスターにはすでに列タイトルが印刷されています。
• ポスターの各領域に 1 つずつゾーンを定義し、各主張の source_id をゾーンの facts[] に引き継ぎます。
• オーバーレイで単に見たかどうかではなく、理解度を測れるようにクイズの質問を追加します。

これが必須である理由：ポスターの数値は検証済みですが、静的な PNG ではインタラクションイベントが発生しないため、読者が実際にその主張に関与したかどうかを示す情報は得られません。オーバーレイによって各領域が計測可能なゾーンになり、ホバー、開く操作、クイズへの回答から、ルートの CLAUDE.md にある目標値「2.99」に照らして、すべての読者を集計した場合にインフォグラフィックの概念が習得されているかを予測できます。個人を特定できる読者にひも付く生徒ごとの履歴は、決して保持しないでください。

検証フェーズを実際の MicroSim に再利用する場合。 フェーズ 1～4（主張の計画 → ソースの探索 → 主張ごとの検証 → 検証レポート）は、出力形式に依存しません。出典付きの事実を含む sim が必要な場合（実在する製品の比較表、公表された測定値のグラフ、日付のある出来事のタイムラインなど）は、まずフェーズ 1～4 を実施し、確定した主張セットを該当する sim ガイドに引き継ぎます。各 source_id を sim のデータファイルに引き継ぎ、引用が生徒に見えるようにしてください。フェーズ 5～8 はスキップします。これらはポスターのレンダリング手順です。

4.2 該当するガイドを読み込む

references/ ディレクトリにある対応するガイドファイルを読み、.js ファイルの作成にはそのワークフローに従ってください。

4.3 .js ファイルのみを作成する

スキャフォールド（ステップ 2）によって、すでに main.html、index.md、metadata.json が作成されています。作成する必要があるのは docs/sims/<sim-id>/<sim-id>.js だけです。

各ガイドには以下が含まれます。

1. ライブラリ固有の要件
2. コードのテンプレートとパターン
3. その可視化タイプに関するベストプラクティス

4.4 必須：.js ファイルに CANVAS_HEIGHT コメントを追加する

すべての .js ファイルには、ファイルの先頭付近（最初の10行以内）に、独立した行として // CANVAS_HEIGHT: コメントを含める必要があります。 これは、すべてのライブラリタイプにおける iframe の高さを決定する最も信頼できる情報源です。sync-iframe-heights.py ユーティリティと手動での高さ調整は、このコメントに依存します。

.js がないシミュレーション： シミュレーションが main.html だけで完全に描画され、<id>.js を含まない場合（Mermaid、vis-network、カスタム HTML を使ってこのように作成されているプロジェクトがあります）、コメントを記述する .js ファイルはありません。その場合は、シミュレーションの metadata.json に "canvasHeight": <integer> として高さを保存してください。これは、下流のツールが .js コメントの次に読み取る、一貫性のある構造化フォールバックです。解決順序の全容については、microsim-utils スキルの references/canvas-height-strategy.md を参照してください。このステップのその他の内容（数値の計算方法、+2 の iframe ルール）は同じです。

形式：// CANVAS_HEIGHT: <integer>

値は、切り取られることなく MicroSim 全体（キャンバス、コントロール、凡例、情報パネル、タイトル、余白など）を表示するために iframe に必要な合計ピクセル高さです。

ライブラリタイプ別の CANVAS_HEIGHT の計算方法

ライブラリ	計算式	例
p5.js	drawHeight + controlHeight + graphHeight（canvasHeight 変数）	// CANVAS_HEIGHT: 695
vis-network	コンテナーの高さ + タイトル（約35px）+ 情報パネル（約60px）+ 凡例（約30px）+ コントロール（約40px）	// CANVAS_HEIGHT: 685
Chart.js	チャートコンテナーの高さ + タイトル（約35px）+ コントロール（約40px）+ 凡例（約30px）	// CANVAS_HEIGHT: 505
Plotly.js	プロット div の高さ + タイトル（約35px）+ コントロール（約40px）	// CANVAS_HEIGHT: 475
vis-timeline	タイムラインコンテナーの高さ + タイトル（約35px）+ コントロール（約40px）	// CANVAS_HEIGHT: 475
Leaflet.js	地図コンテナーの高さ + タイトル（約35px）+ コントロール（約40px）+ 凡例（約40px）	// CANVAS_HEIGHT: 515
Mermaid.js	図のコンテナーの高さ + タイトル（約35px）+ コントロール（約40px）	// CANVAS_HEIGHT: 475
カスタム HTML（比較表、html-table、venn）	DOM 要素全体の描画後の高さ	// CANVAS_HEIGHT: 600
インタラクティブなインフォグラフィックオーバーレイ	画像コンテナーの高さ + ツールバー（約40px）+ 情報パネル（約60px）	// CANVAS_HEIGHT: 620

ライブラリタイプ別の例

p5.js：

// Predator-Prey Population Dynamics Simulator
// CANVAS_HEIGHT: 695
let drawHeight = 400;
let graphHeight = 180;
let controlHeight = 115;
let canvasHeight = drawHeight + graphHeight + controlHeight;

vis-network：

// Climate Feedback Loops - vis-network
// CANVAS_HEIGHT: 685
document.addEventListener('DOMContentLoaded', function() {

Chart.js：

// Air Quality Trends Dashboard - Chart.js
// CANVAS_HEIGHT: 505
document.addEventListener('DOMContentLoaded', function () {

Leaflet.js：

// Watershed Map - Leaflet
// CANVAS_HEIGHT: 515
document.addEventListener('DOMContentLoaded', function() {

インタラクティブなインフォグラフィックオーバーレイ：

// Ecosystem Components Overlay
// CANVAS_HEIGHT: 620
document.addEventListener('DOMContentLoaded', function() {

ルール

1. コメントは、解析ツールがすばやく見つけられるよう、.js ファイルの最初の10行以内に記述する必要があります。
2. 値は整数でなければなりません（px の接尾辞や式は使用できません）。
3. iframe の高さ = CANVAS_HEIGHT + 2（2px は iframe の境界線分です）。sync-iframe-heights.py ユーティリティがこれを自動的に加算します。
4. p5.js のシミュレーションでは、CANVAS_HEIGHT の値は drawHeight + controlHeight（graphHeight がある場合はその値も加算）と一致する必要があります。既存の名前付き変数はそのまま残してください。このコメントは、ツール向けの重複するものの正式な宣言です。
5. 既存のシミュレーションを更新する場合、高さに関係する値を変更したら、必ず CANVAS_HEIGHT コメントも更新してください。
6. 高さがわからない場合は、シミュレーションをブラウザーで表示し、コンテンツ全体の高さを測定して、その値を使用してください。迷ったら少し高めに設定してください（コントロールが切り取られるより、余白が少し増えるほうが適切です）。

4.5 曖昧なリクエストへの対応

リクエストが複数のジェネレーターに該当する可能性がある場合：

1. 詳細なスコアリング方法については references/routing-criteria.md を読む
2. 0〜100の尺度で上位3つの候補を採点する
3. 理由を添えてユーザーに選択肢を提示する：

   Based on your request, I recommend:
   1. [Generator A] (Score: 85) - Best for [reason]
   2. [Generator B] (Score: 70) - Alternative if you need [feature]
   3. [Generator C] (Score: 55) - Possible if [condition]
   
   Which would you prefer?
   

4. ユーザーの選択に従って進める

よくある曖昧な用語

曖昧な用語	確認が必要な点
"graph"	チャート（ChartJS）ですか、それともネットワークグラフ（vis-network）ですか？
"diagram"	構造図（Mermaid）、ネットワーク図（vis-network）、それともカスタム図（p5）ですか？
"map"	地理的な地図（Leaflet）ですか、それとも概念マップ（vis-network）ですか？
"table"	星評価（comparison-table）ですか、それとも詳細パネル付きのクリック可能なセル（html-table）ですか？
"visualization"	どの種類のデータですか？どのようなインタラクションが必要ですか？

---

ステップ 5：章の iframe を修正する

バッチ生成では必須です。 章の Markdown に iframe を手動で挿入したり編集したりしないでください。

python3 $UTILS/add-iframes-to-chapter.py \
    --chapter <chapter-dir-name> \
    --project-dir $PROJECT \
    --fix-heights \
    --fix-paths \
    --verbose

この処理の内容：

• iframe の埋め込みがない #### Diagram: ／ #### Drawing: 見出しを検出します
• 正しい相対パスを指定した <iframe> タグを <details> ブロックの前に挿入します
• --fix-heights：.js ファイルを解析して createCanvas() の高さを検出し、iframe の高さをキャンバスの高さ + 2px に設定します
• --fix-paths：絶対パス（/sims/...）を相対パス（../../sims/...）に変換します
• 高さの誤記を修正します（500xp → 500px）

すべての章を一度に処理する場合：

python3 $UTILS/add-iframes-to-chapter.py \
    --all \
    --project-dir $PROJECT \
    --fix-heights \
    --fix-paths \
    --verbose

まずドライランを実行して、変更内容を確認します：

python3 $UTILS/add-iframes-to-chapter.py \
    --chapter <chapter-dir-name> \
    --project-dir $PROJECT \
    --fix-heights --fix-paths \
    --dry-run --verbose

---

ステップ 6：品質を検証する

.js ファイルを実装した後に必ず実行してください。 手動のチェックリストだけに頼らないでください。

python3 $UTILS/validate-sims.py \
    --project-dir $PROJECT \
    --format table \
    --verbose

この処理の内容：

各 MicroSim を 100 点満点の基準で採点します：

カテゴリ	点数	確認項目
main.html	10	ファイルの存在（5）、schema メタタグ（3）、<main> タグ（2）
metadata.json	30	ファイルの存在（10）、必須フィールド（10）、教育的内容（5）、教授法（5）
index.md	35	タイトル（2）、YAML（3）、画像（5）、iframe（10）、全画面表示（5）、例（5）、説明（5）
スクリーンショット	5	PNG ファイルの存在
レッスンプラン	10	index.md 内のセクションの存在
参考文献	5	index.md 内のセクションの存在
p5.js の規約	5	updateCanvasSize、DOM ボタンなし、querySelector による親要素設定、textFont('Segoe UI') なし

評価基準： A（85 点以上）、B（70～84 点）、C（50～69 点）、D（50 点未満）

単一のシミュレーションを検証する場合：

python3 $UTILS/validate-sims.py \
    --project-dir $PROJECT \
    --sim <sim-id> \
    --verbose

見つかった問題を修正し、再検証して改善を確認します：

# After fixing issues...
python3 $UTILS/validate-sims.py \
    --project-dir $PROJECT \
    --min-score 0 \
    --format table \
    --verbose

---

ステップ 6B：iframe の高さを同期する

.js ファイルを実装した後に必ず実行してください。 iframe の高さを手動で計算しないでください。

python3 $UTILS/sync-iframe-heights.py \
    --project-dir $PROJECT \
    --verbose

この処理の内容：

• 各シミュレーションの .js ファイルを解析し、// CANVAS_HEIGHT: <value> コメントを探します（主要な情報源。ステップ 4.4 を参照）
• この順序で代替情報を使用します：metadata.json の "canvasHeight"（.js ファイルのないシミュレーション用）、main.html 内の `` コメント、次に .js から計算した drawHeight + controlHeight
• iframe の高さを CANVAS_HEIGHT + 2（枠線分の 2px）に設定します
• 各シミュレーションの index.md およびシミュレーションを埋め込んでいる docs/ 配下のすべてのページ（章、教師用ガイド、ポスターページ）の <iframe> の height 属性を更新します
• すでに正しい高さのシミュレーションはスキップします

fix-iframe-heights.py ではなく、sync-iframe-heights.py を使用してください。 前者はシミュレーションのページのみを対象とする旧ツールです。シミュレーション自体の index.md は更新しますが、ステップ 5 で挿入した章の埋め込みは古い高さのまま変更されません。そのため、シミュレーション単独のページでは正しく表示されても、章では一部が切れて表示されます。

重要： .js ファイル内の // CANVAS_HEIGHT: コメントは、すべてのライブラリの種類（p5.js、vis-network、Chart.js、Leaflet、Mermaid など）に共通する唯一の信頼できる情報源です。コメントがない場合は、このツールを実行する前に .js ファイルに追加してください。形式と計算ルールについてはステップ 4.4 を参照してください。

単一のシミュレーションを修正する場合：

python3 $UTILS/sync-iframe-heights.py \
    --project-dir $PROJECT \
    --sim <sim-id> \
    --verbose

まずドライランを実行して、変更内容を確認します：

python3 $UTILS/sync-iframe-heights.py \
    --project-dir $PROJECT \
    --dry-run --verbose

---

ステップ 6C：iframe 内でコントロールが表示されていることを確認する（Playwright）

iframe の高さを修正した後、必ず実施してください。 iframe の境界を越えて配置されたコントロールを検出できます。これは、特にレスポンシブレイアウトや狭いビューポートを使用するシミュレーションでは、静的な高さ計算だけでは見落とすことがあります。

TESTER="$BK_HOME/skills/microsim-utils/scripts"

# Single sim (after generating one MicroSim)
python3 $TESTER/test-iframe-heights.py --sims-dir $PROJECT/docs/sims --sim <sim-id>

# All sims in a batch run
python3 $TESTER/test-iframe-heights.py --sims-dir $PROJECT/docs/sims

この処理の内容：

• Playwright を介してヘッドレス Chromium を起動します
• index.md に記載された iframe の高さに合わせたビューポートで、各 MicroSim の main.html を読み込みます
• ライブラリ（p5.js、vis-network、Chart.js）のレンダリングを待ちます
• すべてのインタラクティブなコントロール（ボタン、スライダー、セレクトボックス、チェックボックス）が完全に表示されていることを確認します
• 失敗があった場合、PASS／FAIL と推奨される高さを報告します

前提条件（初回のみのセットアップ）：

pip install playwright
playwright install chromium

シミュレーションが失敗した場合：

1. .js ファイル内の // CANVAS_HEIGHT: コメントを、推奨される高さから 10 を引いた値に更新します
2. そのシミュレーションに対して sync-iframe-heights.py を再実行します
3. Playwright テストを再実行し、合格することを確認します

---

ステップ 7：ナビゲーションを更新する

新しいシミュレーションを作成した後、必ず実施してください。 mkdocs.yml の MicroSims セクションを手動で編集しないでください。

python3 $UTILS/update-mkdocs-nav.py \
    --project-dir $PROJECT \
    --verbose

この処理の内容：

• docs/sims/ をスキャンし、index.md を含むディレクトリを探します
• フロントマターまたは # Heading から表示タイトルを抽出します
• mkdocs.yml の - MicroSims: セクション全体を、アルファベット順に並べたリストに置き換えます
• 冪等性があり、複数回実行しても安全です

まずドライランを実行してください：

python3 $UTILS/update-mkdocs-nav.py \
    --project-dir $PROJECT \
    --dry-run --verbose

---

ステップ 8：MicroSim のスクリーン画像を生成する

教科書内のすべての MicroSim の一覧を掲載する /doc/sims/index.md ファイルには、MicroSim のスクリーン画像が必要です。

MicroSim のスクリーン画像を取得するには、Unix シェルスクリプトを使用します。このシェルスクリプトは Google Chrome をヘッドレスモードで実行し、幅 800px の画像を作成します。スクリーン画像の高さは iframe の高さによって決まります。

スクリーンキャプチャ用シェルスクリプトは ~/.local/bin/bk-capture-screenshot にインストールされており、$BK_HOME/scripts/bk-capture-screenshot プログラムへのシンボリックリンクになっています。

bk-capture-screenshot には 3 つのコマンドラインパラメーターがあります：

$1 MicroSim のディレクトリパス（デフォルト：カレントディレクトリ） $2 JS のレンダリング待機時間（秒）（デフォルト：3） $3 画像の目標高さ（ピクセル）（デフォルト：600）

ヒント：適切な高さにするには、MicroSim の index.md に記載された iframe の高さを使用してください。

使用例：

bk-capture-screenshot /path/to/microsim 3 700    # 3 second delay, 700px height

出力：

MicroSim のディレクトリ内に <microsim-name>.png を作成します。通常、ファイルサイズは約 50K バイトです。

---

ステップ 9：レイアウトを視覚的に確認する（必須）

スクリーンショットを撮影した後、必ず実施してください。 この確認は、Playwright のバウンディングボックス検査を使用する iframe-tester ユーティリティを補完する、視覚的な品質保証です。レイアウトの確認では、クリップされた行ラベル、重なり合うコントロール、残ったストロークを伴うテキスト、パネル内容のはみ出し、コントラストの低いラベル、描画順序の不具合、ライブラリ固有のレンダリング問題など、形状検査では見落とされる不具合を検出します。

ステップ 8 のスクリーンショットを入力として使用してください。再撮影しないでください。

新しく生成した各シミュレーションで、microsim-utils の layout-reviewer ユーティリティを使用してください：

For each sim that was generated in this batch:
  1. Read references/visual-checklist.md from microsim-utils
  2. Read the sim's screenshot PNG (Read tool — Claude Vision sees it)
  3. Walk every checklist item; mark PASS / FAIL / N/A with quoted
     evidence for any FAIL
  4. For each FAIL, consult references/common-fixes.md and apply the
     smallest patch that resolves it (typically a small edit to the
     .js for p5.js / Chart.js / vis-network / Leaflet sims, or to
     main.html for Mermaid sims)
  5. Re-capture, re-read, re-walk the checklist
  6. Stop after 3 review-patch cycles even if issues remain — surface
     residue rather than over-tweak

このユーティリティのワークフロー全体は、$BK_HOME/skills/microsim-utils/references/layout-reviewer.md に記載されています。このジェネレーターでの要件は、「ステップ 8 の後、すべてのシミュレーションがレイアウト確認に合格するか、残っている不具合が明示的に報告されていること」です。

レイアウト確認で行わないこと：

• iframe の高さによるクリッピング（iframe の端を越えるコンテンツ）は修正しません。これはステップ 6B／6C の sync-iframe-heights.py と iframe-tester ユーティリティ（microsim-utils）で対応します。
• 承認済みのシミュレーション（フロントマターが status: approved）は変更しません。このジェネレーターのワークフローでは該当しません。新しく生成したシミュレーションはまだ承認されていないためです。ただし、このルールは引き続き適用されます。

**ジェネレーターで必須とする理由：**生成時点でレイアウトの不具合を検出する価値は、ユーザーがシミュレーションを見る前であれば、後から検出するよりもはるかに高いためです。ステップ 8 の最後に視覚的な確認を行うことで、「埋め込み時に正しく表示されること」が、別途手動で品質確認を行うものではなく、新しい MicroSim の完了条件になります。

---

ワークフローの概要

バッチ（章単位）生成

Step 0: Set UTILS and PROJECT paths
  ↓
Step 1: extract-sim-specs.py → /tmp/ch-specs.json
  ↓
Step 2: generate-sim-scaffold.py → creates main.html, index.md, metadata.json
  ↓
Step 3: Instructional Design Checkpoint (per sim)
  ↓
Step 4: Write .js files (creative work — route to guide, implement)
  ↓
Step 5: add-iframes-to-chapter.py → inserts/fixes iframes
  ↓
Step 6: validate-sims.py → scores quality, fix issues
  ↓
Step 6B: sync-iframe-heights.py → syncs iframe heights (own page + chapter embeds)
  ↓
Step 6C: test-iframe-heights.py → Playwright verifies controls visible in iframe
  ↓
Step 7: update-mkdocs-nav.py → regenerates nav
  ↓
Step 8: bk-capture-screenshot /path/to/microsim 3 {height} → creates screen image
  ↓
Step 9: microsim-utils layout-reviewer → Claude Vision walks the checklist,
        diagnoses + patches FAILs, re-captures to verify (max 3 cycles)

単一シミュレーションの生成

Step 0:  Set UTILS and PROJECT paths
  ↓
Step 1B: Write 1-entry spec JSON + scaffold
  ↓
Step 3:  Instructional Design Checkpoint
  ↓
Step 4:  Write .js file
  ↓
Step 6:  validate-sims.py --sim <name>
  ↓
Step 6B: sync-iframe-heights.py --sim <name>
  ↓
Step 6C: test-iframe-heights.py --sim <name> → Playwright verifies controls visible
  ↓
Step 7:  update-mkdocs-nav.py
  ↓
Step 8:  bk-capture-screenshot /path/to/microsim 3 {height} → creates screen image
  ↓
Step 9:  microsim-utils layout-reviewer → Claude Vision walks the checklist,
         diagnoses + patches FAILs, re-captures to verify (max 3 cycles)

コンテキストウィンドウがいっぱいになった後の再開

バッチ実行中に章の途中でコンテキストウィンドウがいっぱいになった場合：

1. 新しいセッションで sim-status.json を読み、完了した項目を確認します
2. ステータスが implemented 以降のシミュレーションはスキップします
3. ステータスが specified または scaffolded のシミュレーションには、引き続き .js ファイルが必要です

# Check where we left off
python3 $UTILS/extract-sim-specs.py \
    --project-dir $PROJECT \
    --chapter <chapter-dir-name> \
    --status-file /tmp/sim-status.json \
    --verbose

---

利用可能なジェネレーター

主なジェネレーター

ジェネレーター	ライブラリ	最適な用途
p5-guide	p5.js	カスタムシミュレーション、物理、アニメーション
chartjs-guide	Chart.js	棒グラフ、折れ線グラフ、円グラフ、ドーナツグラフ、レーダーチャート
timeline-guide	vis-timeline	時系列イベント、歴史、スケジュール
map-guide	Leaflet.js	地理データ、場所、ルート
vis-network-guide	vis-network	ネットワークグラフ、依存関係、概念マップ
mermaid-guide	Mermaid.js	フローチャート、ワークフロー、UML 図
plotly-guide	Plotly.js	数学関数のグラフ
venn-guide	Custom	集合の関係（2～4 個の集合）
bubble-guide	Chart.js	優先度マトリックス、多次元データ
causal-loop-guide	vis-network	システム思考、フィードバックループ、複数のループを含む CLD 記事
comparison-table-guide	Custom	評価付きの並列比較
html-table	Custom	クリック可能なセルと詳細パネルを備えたマトリックス比較
celebration-guide	p5.js	パーティクル効果、視覚的なフィードバック
concept-classifier-guide	p5.js	分類クイズ — シナリオをカテゴリに分類
infographic-overlay-guide	Custom (diagram.js)	イラスト上にインタラクティブな吹き出し／ゾーンを重ねて表示 — 画像にはテキストを含めません。また、検証済みポスターすべてに必須のラッパーです
docker-python-lab-guide	Custom (docker-lab.js)	Docker コンテナ内で実行可能な Python ラボ
verified-infographic-guide	Custom (text-verify → image)	ファクトチェック済みの統計ポスター — 主張の計画、出典の検証、固定された画像プロンプト（明示的に依頼された場合のみ静的 PNG を作成し、その後は必ずオーバーレイでラップします）

共通規格

すべての MicroSim は、ジェネレーターにかかわらず、以下の規格に従います。

ディレクトリ構造：

docs/sims/<microsim-name>/
├── main.html       # Main visualization file
├── index.md        # Documentation page
├── *.js or *.css   # Supporting files
└── metadata.json   # Dublin Core metadata (optional)

見つけやすさのための URI スキーム：

グローバルに見つけられるよう、すべての MicroSim HTML ファイルにこのスキーマのメタタグを含める必要があります。

<meta name="schema" content="https://dmccreary.github.io/intelligent-textbooks/ns/microsim/v1">

これにより、コード検索を使って GitHub 全体の MicroSim を数え、見つけられるようになります。詳細については、URI Scheme のドキュメントを参照してください。

統合：

• MkDocs ページに iframe で埋め込みます
• 幅に応じたレスポンシブデザイン
• スクロールしない iframe コンテナー
• 標準の高さ：CANVAS_HEIGHT + 2px（CANVAS_HEIGHT は .js ファイルの先頭にある // CANVAS_HEIGHT: <value> コメントで宣言します — Step 4.4 を参照）
• スクロールの乗っ取りを防止します：
  • 章の iframe はスクロールしないようにします：scrolling="no"
  • 明示的に要求されない限り、シミュレーション内でページのホイールスクロールを既定で消費しないでください（たとえば、Leaflet の scrollWheelZoom: false を設定します）
• iframe のパスは必ず相対パスにしてください。絶対パスは使用しないでください：
  • シミュレーション自身の index.md から：<iframe src="main.html" ...>
  • 章ファイル（docs/chapters/*/index.md）から：<iframe src="../../sims/[sim-name]/main.html" ...>
  • /sims/... のような絶対パスは絶対に使用しないでください — GitHub Pages でサイトがサブディレクトリ（例：/geometry-course/）配下に配信される場合、動作しません

品質チェックリスト：

• 最新のブラウザーでエラーなく実行できる
• コンテナーの幅に応じて表示が調整される
• コントロールがすぐに応答する
• iframe に埋め込んだとき、ページのスクロールを乗っ取らない
• 教育目的が明確である
• コードに適切なコメントが付いている
• デザインで特定のフォントが明示的に必要とされない限り、textFont() を呼び出さない — macOS／Linux では利用できない Windows 専用フォントのため、textFont('Segoe UI') は使用しない

例

例 1：タイムラインのリクエスト

ユーザー：「コンピューターの歴史における主要な出来事を示すタイムラインを作成してください」 **ルーティング：**キーワード「タイムライン」「出来事」「歴史」→ references/timeline-guide.md **アクション：**timeline-guide.md を読み、そのワークフローに従います

例 2：グラフのリクエスト

ユーザー：「プログラミング言語の人気を比較する棒グラフを作成してください」 **ルーティング：**キーワード「棒グラフ」「比較」→ references/chartjs-guide.md **アクション：**chartjs-guide.md を読み、そのワークフローに従います

例 3：カスタムシミュレーション

ユーザー：「インタラクティブな跳ねるボールのシミュレーションを作成してください」 **ルーティング：**キーワード「インタラクティブ」「跳ねる」「シミュレーション」→ references/p5-guide.md **アクション：**p5-guide.md を読み、そのワークフローに従います

例 4：曖昧なリクエスト

ユーザー：「プロジェクトの依存関係をグラフで作成してください」 ルーティング：「グラフ」＋「依存関係」はネットワークを示唆します → references/vis-network-guide.md **アクション：**vis-network-guide.md を読みます（ただし、ユーザーがグラフを意味していた場合は確認します）

例 5：章ごとの一括処理

ユーザー：「第 11 章の MicroSim を生成してください」 **アクション：**ステップ 0 → ステップ 1 → ステップ 2 → ステップ 3～4（シミュレーションごとにループ）→ ステップ 5 → ステップ 6 → ステップ 6B → ステップ 6C → ステップ 7

例 6：分類クイズ

ユーザー：「各シナリオがどの認知バイアスを示しているかを学生が特定するクイズを作成してください」 **ルーティング：**キーワード「特定する」「シナリオを分類する」→ references/concept-classifier-guide.md **アクション：**concept-classifier-guide.md を読み、そのワークフローに従います

例 7：因果ループの記事

ユーザー：「サプライチェーンのブルウィップ現象におけるフィードバックループを示してください」 **ルーティング：**キーワード「フィードバックループ」→ references/causal-loop-guide.md **アクション：**causal-loop-guide.md を読みます。記事全体を求められた場合は記事全体を、そうでなければインラインの CLD を 1 つ作成します

例 8：ラベル付き図のオーバーレイ

ユーザー：「構造にラベルを付けた、コケの胞子体のインタラクティブな解剖図を作成してください」 **ルーティング：**キーワード「解剖図」「ラベル付き」→ references/infographic-overlay-guide.md **アクション：**infographic-overlay-guide.md を読み、コールアウトのワークフローに従います

例 9：Python ラボ

ユーザー：「リスト操作に関する実行可能な Python ラボをこのページに追加してください」 **ルーティング：**キーワード「実行可能」「Python ラボ」→ references/docker-python-lab-guide.md **アクション：**docker-python-lab-guide.md を読み、そのワークフローに従います

例 10：事実を検証したポスター

ユーザー：「LED 照明と白熱灯の消費電力を実際の数値で比較するポスターを作成してください」 **ルーティング：**明示的な「ポスター」の指定＋出典が必要な数値の主張 → references/verified-infographic-guide.md **アクション：**このルートに切り替えます。ステップ 0～9 はスキップし、ガイドの 8 つのフェーズを実行します。画像生成を 1 回行う前に、すべての数値を検証してください。その後、必ずフェーズ 9 を実行し、infographic-overlay-guide.md のグリッドオーバーレイで poster.png をラップして、ポスターがインタラクションイベントを出力するようにします。

例 11：形式の指定がないインフォグラフィック

ユーザー：「各食用作物の栽培に必要な水の量を示すインフォグラフィックを作成してください」 **ルーティング：**数値の主張があるものの、静的形式の指定はありません → 検証のフェーズ 1～4 の後、インタラクティブなガイドを使用します **アクション：**静的なポスターは生成しないでください。verified-infographic-guide.md のフェーズ 1～4 を実行して、出典付きの主張のセットを確定します。その後、該当するシミュレーションガイド（ここでは chartjs-guide.md）を使ってビジュアライゼーションを作成し、各 source_id をシミュレーションのデータファイルに引き継ぎます。

例 11：出典付き比較シミュレーション

ユーザー：「検証済みの仕様を使って、これら 5 種類のブレッドボード用電源を比較する表を作成してください」 ルーティング：「比較表」→ references/comparison-table-guide.md。ただし、仕様には出典が必要です アクション：verified-infographic-guide.md のフェーズ 1～4 を実行して、主張を確定し、出典を付けます。その後、comparison-table-guide.md を使ってシミュレーションを作成し、引用が表示されたままになるよう、各 source_id を表に引き継ぎます

参照ファイル

詳細については、以下を参照してください。

• references/routing-criteria.md - すべてのジェネレーターの完全なスコアリング方法
• references/<generator>-guide.md - 各ジェネレーターの具体的な実装ガイド
• assets/templates/ - 共通テンプレートとパターン
• references/infographic-claim-plan-template.yaml、references/infographic-verification-report-template.md、 references/infographic-layout-spec-template.yaml、references/poster-image-prompt.md、 references/infographic-biophilic-case-study.md - 検証済みインフォグラフィックのルート
• scripts/posters/generate-poster-thumbnails.py - ポスターギャラリーのサムネイル（verified-infographic-guide.md の「ギャラリーのサムネイル」を参照）

sim-status.json のライフサイクル

extract-sim-specs.py --status-file フラグは、ライフサイクル追跡ファイルを生成します。状態は次のように進みます。

状態	意味
specified	チャプターに仕様はありますが、sim ディレクトリはまだありません
scaffolded	main.html/index.md を含むディレクトリはありますが、実質的な JS はありません
implemented	JS ファイルが存在し、50 行を超えています
validated	quality_score >= 70
deployed	検証済みで、チャプターに iframe があります