Visual Indexer

visual-indexer

course-bundleの全スクリーンショットをカタログ化し、分類・OCR・メタデータ付与を行うスキル。

---

推奨実行モデル & 並列化

モデル: sonnet 必須（opusはコスト3-5倍。精度差は小さい）

1回の実行で全フレームをReadするためコスト最大。sonnet並列を厳守。

並列化: 章をN分割してN Agent並列起動

Agent起動テンプレート:

Agent(
  model: "sonnet",
  mode: "bypassPermissions",
  run_in_background: true,
  prompt: "Process chapters NN-NN of [bundle_path]..."
)

注意: visual-indexerは画像を全Read するため最もコスト重い。必ずsonnet+並列。opusで全章順次は禁じ手。

---

WHAT — 何をするか

コースの全チャプターに含まれるスクリーンショット画像を1枚ずつ読み取り、以下を行う:

1. フレーム分類 — コア型7種 + 講座固有型（custom_types）で画像を分類 2. OCR抽出 — 画像内のテキストをすべて抽出 3. ビジュアル要素の特定 — 図形、矢印、ボックス等の視覚要素を記録 4. キーワード付与 — ダウンストリームのスキルが検索しやすいようにタグ付け 5. インデックス生成 — チャプター別 visual-index.json + 全体 visual-catalog.json

---

WHY — なぜ必要か

• procedure-extractorが手順画像を紐付けるのにOCR情報とフレーム分類が必要
• concept-extractorがスライド画像を補強材料として使う
• talking_headやtransitionを除外することで後段の処理コストを削減
• コース全体の画像資産を俯瞰できるカタログが必要

---

HOW — 実行手順

Phase 0: 準備・検証

BLOCKER: manifest.jsonが存在するか確認
  → 存在しない場合は course-ingest を先に実行するよう案内して停止

1. manifest.json を読み込み、チャプター一覧とスクリーンショットディレクトリを取得 2. 各チャプターのスクリーンショットディレクトリの存在を確認 3. 全フレーム数をカウントし、処理計画を立てる

Phase 0.5: 講座固有型の発見

各章の最初の5フレームをサンプル読みし:

1. コア型に当てはまるか判定 2. 当てはまらない画面が2枚以上ある → 講座固有型を提案 3. ユーザーまたはメインセッションに型定義を提示（章の最初だけ） 4. 確定したら visual-index.json の custom_types に登録 5. 以降のフレームはコア型 + 講座固有型から選択

注: 完全自動化する場合は、Phase 0.5でAgent自身が判断して登録する。

Phase 1: チャプター別フレーム処理

各チャプターについて以下を実行:

Step 1.1: フレーム一覧取得

ls chapters/{chapter_id}/screenshots/

Step 1.2: バッチ処理（5-10枚ずつ）

BLOCKER: 各画像は必ずReadツールで読み取ってから分類する
  → ファイル名からの推測は NG

各フレームについて:

1. Readツールで画像を読み取る 2. フレーム分類 — 以下のタクソノミーで分類:

コア型（全講座共通）:

コア型に当てはまらない繰り返し画面は 講座固有型（custom_types） として登録する（後述）。

講座固有型（custom_types）

コア型に当てはまらないが、講座内で繰り返し出現する画面は講座固有型として動的に作成する。

作成ルール

1. 最初の3-5フレームを見て型候補を検討 2. 「コア型に当てはまらない」かつ「2枚以上出る」 → 講座固有型として登録 3. 命名は snake_case、講座のキーワードを含む

• 例: tmux_pane, vscode_editor, ae_timeline, figma_canvas

4. 1講座あたり最大5型まで（無限増殖防止） 5. 1枚しか出ない型は作らず、コア型のうち最も近いものに割り当て

3. OCR抽出 — 画像内の全テキストを text_content 配列に格納 4. ビジュアル要素特定 — visual_elements 配列に記録 5. キーワード付与 — 内容を表すキーワードを keywords 配列に格納 6. 信頼度判定 — confidence を high / medium / low で設定 7. UI操作判定 — ブラウザ/ターミナル画面の場合 is_ui_walkthrough を設定

Step 1.3: visual-index.json 生成

チャプターの全フレーム処理が完了したら visual-index.json を生成:

{
  "chapter_id": "03",
  "custom_types": {
    "tmux_pane": "tmuxで複数paneに分割されたClaude Code画面（タイトルバーにtmux表記、画面分割あり）"
  },
  "frames": [
    {
      "filename": "frame_005.jpg",
      "type": "content_slide",
      "text_content": ["AIマインド", "壁打ち", "アイデア", "専門知識"],
      "visual_elements": ["equation_diagram", "four_boxes", "arrow"],
      "keywords": ["4原則", "マインド"],
      "confidence": "high"
    }
  ]
}

出力先: chapters/{chapter_id}/visual-index.json

スキーマ: schemas/visual-index.schema.json に準拠すること。

Phase 2: visual-catalog.json 生成

全チャプターの処理完了後、コース全体のカタログを生成:

{
  "course_name": "YouTube Booster",
  "total_frames": 245,
  "course_custom_types": {
    "tmux_pane": {"definition": "tmuxで複数paneに分割されたClaude Code画面", "frame_count": 18},
    "vscode_editor": {"definition": "VS Codeのエディタ画面（ファイルツリー+エディタ+ステータスバー）", "frame_count": 8}
  },
  "type_distribution": {
    "content_slide": 89,
    "browser_screenshot": 45,
    "talking_head": 67,
    "diagram": 23,
    "title_slide": 12,
    "transition": 9
  },
  "chapters": [
    {
      "chapter_id": "03",
      "frame_count": 31,
      "high_value_frames": ["frame_005.jpg", "frame_012.jpg"],
      "visual_index_path": "chapters/03/visual-index.json"
    }
  ]
}

• high_value_frames: content_slide, browser_screenshot, diagram のうち confidence: "high" のもの
• type_distribution: 全チャプターのフレームタイプを集計

出力先: プロジェクトルートの visual-catalog.json

Phase 3: 自己検証

以下のチェックリストを全て通過すること:

• [ ] 全フレームに type が設定されているか
• [ ] text_content が空の content_slide がないか（スライドには必ずテキストがある）
• [ ] talking_head のフレーム数が妥当か（通常20-40%）
• [ ] visual-catalog.json の total_frames が実際のファイル数と一致するか
• [ ] 各 visual-index.json が schemas/visual-index.schema.json に準拠しているか
• [ ] type_distribution の合計が total_frames と一致するか
• [ ] custom_types の数は5以下か
• [ ] 各 custom_type に定義文があるか
• [ ] 各 custom_type を使ったフレームが2枚以上あるか
• [ ] custom_type の命名が snake_case か

検証失敗時:
  → 不一致があれば該当チャプターを再処理
  → text_contentが空のcontent_slideがあれば画像を再読み取り

---

BLOCKER ゲート

---

NG / OK 判定表

---

フレーム分類の判断基準

詳細は references/frame-types.md を参照。概要:

• title_slide: 大きなテキスト、章番号、背景デザイン。テキスト要素が少ない
• content_slide: 箇条書き、図表、概念説明。テキスト量が多い
• browser_screenshot: ブラウザのUI要素（アドレスバー、タブ等）が見える
• terminal_screenshot: 黒背景にモノスペースフォント、コマンドライン
• diagram: 矢印やフロー、接続線。構造化された図形の配置
• talking_head: 人物の映像が画面の大部分を占める。テキスト要素がない/少ない
• transition: 無地の画面、フェード、ぼかし

エッジケース

• スライド上に小さな話者映像がオーバーレイ → content_slide（スライドが主体）
• ブラウザ画面+解説テキストのオーバーレイ → browser_screenshot
• 半分スライド・半分話者 → テキスト量で判断、テキストが多ければ content_slide

---

出力ファイル一覧

---

連携スキル

---

バッチ処理の注意

• Readツールで画像を読み取る際、1回のバッチで5-10枚を処理
• 大量のフレーム（100枚超）がある場合でも全数処理する
• 処理の進捗を章ごとに報告する: Chapter 03: 31/31 frames processed
• エラーが発生したフレームは confidence: "low" で記録し、エラー内容をメモ

フレームタイプ分類ガイド

visual-indexerが画像を分類する際の詳細判定基準。

---

1. title_slide（章タイトル）

視覚的特徴

• 大きなフォントサイズのテキスト（画面の中央に配置されることが多い）
• 章番号やセクション番号が含まれる（例: 「第3章」「Chapter 03」「STEP 3」）
• 装飾的な背景（グラデーション、パターン、ブランドカラー）
• テキスト要素が少ない（タイトル + サブタイトル程度）
• ロゴやコースブランディングが含まれることがある

エッジケース

• タイトル+箇条書きの概要がある場合 → テキスト量で判断。概要が3項目以下なら title_slide、それ以上なら content_slide
• セクション区切りのインタースティシャル → title_slide

ダウンストリーム優先度: 中

マニュアルの見出し画像として使用。必ず1チャプターに1枚以上あるはず。

visual_elements の典型値

logo, icon, subtitle_text, watermark

---

2. content_slide（概念図・スライド）

視覚的特徴

• 箇条書き、番号付きリスト、テーブルなどの構造化テキスト
• 概念の説明図が含まれる
• 背景は単色またはテンプレートデザイン
• テキスト量が多い（3行以上の本文）
• 図とテキストの混在

エッジケース

• スライド上に小さな話者映像（ワイプ）がオーバーレイ → content_slide（スライド内容が主体）
• 半分スライド・半分話者 → テキスト量で判断。テキスト情報が画面の50%以上なら content_slide
• スライドに1つの図だけ → 図がフローチャートなら diagram、概念説明なら content_slide

ダウンストリーム優先度: 高

concept-extractorの補強材料。text_contentの完全な抽出が必須。

visual_elements の典型値

bullet_list, numbered_list, box, four_boxes, arrow, table, icon, highlight, equation_diagram

---

3. browser_screenshot（ブラウザ画面）

視覚的特徴

• ブラウザのUI要素が見える:
• アドレスバー（URL表示）
• タブバー
• ブックマークバー
• ナビゲーションボタン（戻る/進む）
• Webページのコンテンツが表示されている
• 典型的なWebデザイン要素（ヘッダー、サイドバー、フォーム等）

エッジケース

• ブラウザ全画面モード（UIが隠れている）→ URLやWebデザイン要素から判断
• ブラウザ画面+解説テキストのオーバーレイ → browser_screenshot
• アプリのWebビュー → ブラウザUI要素があれば browser_screenshot
• モバイルブラウザのスクリーンショット → browser_screenshot

ダウンストリーム優先度: 高

procedure-extractorの手順画像として最重要。is_ui_walkthrough: true の設定を忘れずに。

visual_elements の典型値

url_bar, tab_bar, sidebar, form, button, modal, dropdown, cursor, highlight, annotation, circle_emphasis

---

4. terminal_screenshot（コマンドライン）

視覚的特徴

• 黒背景（または暗い背景色）
• モノスペースフォント
• コマンドプロンプト（$, >, # 等）
• コマンド出力テキスト
• ターミナルエミュレータのウィンドウ枠

エッジケース

• IDE内のターミナルパネル → ターミナル部分が主体なら terminal_screenshot、コード編集が主体なら browser_screenshot（IDE系）
• コードエディタ → コマンドラインでなくコードファイルの場合は content_slide に近い。判断に迷えば notes にメモ
• PowerShellの青い背景 → terminal_screenshot

ダウンストリーム優先度: 高

procedure-extractorの手順画像。コマンドの正確なOCR抽出が重要。

visual_elements の典型値

terminal_prompt, code_block, cursor, highlight

---

5. diagram（フローチャート・図解）

視覚的特徴

• 矢印で接続されたノード/ボックス
• フローチャート形式の構造
• マインドマップ
• 組織図、階層図
• プロセスフロー
• テキストよりも図形と接続線が主体

エッジケース

• スライド内の小さな図 → スライドのテキストが主体なら content_slide、図が画面の60%以上なら diagram
• 表（テーブル）→ データ表示が目的なら content_slide、関係性を示すなら diagram
• インフォグラフィック → diagram

ダウンストリーム優先度: 高

概念関係の可視化に使用。ノード間の関係性の抽出が重要。

visual_elements の典型値

flowchart, arrow, box, hierarchy, venn_diagram, matrix, timeline

---

6. talking_head（話者の映像のみ）

視覚的特徴

• 人物の顔/上半身が画面の大部分を占める
• テキスト要素がない、または名前テロップ程度
• 背景は部屋やバーチャル背景
• Webカメラの画質感
• 表情や身振りでの説明

エッジケース

• 話者+小さなスライドのワイプ → スライド内容が読み取れるなら content_slide。読み取れないほど小さければ talking_head
• 話者+テロップ/字幕 → テロップが単なる装飾なら talking_head、内容説明なら content_slide
• 複数人の対談画面 → talking_head

ダウンストリーム優先度: 低

通常スキップ対象。ただし visual-catalog.json の high_value_frames には含めない。

visual_elements の典型値

speaker_thumbnail, subtitle_text, overlay_text, watermark

---

7. transition（空白・遷移フレーム）

視覚的特徴

• 単色の画面（黒、白、ブランドカラー）
• フェードイン/フェードアウトの中間状態
• ぼかし効果
• モーションブラーで内容が判読不能
• ローディング画面

エッジケース

• ロゴのみの画面 → コースロゴで内容がない場合は transition。タイトル文字があれば title_slide
• 画面切り替え中のフレーム → transition
• エンドカード（「ご視聴ありがとうございました」等）→ title_slide（テキストコンテンツがあるため）

ダウンストリーム優先度: なし

完全スキップ対象。text_content は空配列でよい。

visual_elements の典型値

logo, watermark（あれば）

---

判定フローチャート

画像を読み取る
  │
  ├─ テキスト/コンテンツがほぼない
  │   ├─ 人物が映っている → talking_head
  │   └─ 人物もない → transition
  │
  ├─ ブラウザUI要素がある → browser_screenshot
  │
  ├─ ターミナル/コマンドラインである → terminal_screenshot
  │
  ├─ 図形・矢印・フローが主体 → diagram
  │
  ├─ 大きなタイトルテキスト + 少ないテキスト → title_slide
  │
  └─ 構造化テキスト + 説明図 → content_slide

---

confidence の判定基準

---

visual_elements 値の一覧と説明

レイアウト系

図解系

UI要素系

ターミナル系

装飾・強調系