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が存在するか確認
  → 存在しない場合は manabi-ingest を先に実行するよう案内して停止

1. manifest.json を読み込み、チャプター一覧とスクリーンショットディレクトリを取得
2. 各チャプターのスクリーンショットディレクトリの存在を確認
3. 全フレーム数をカウントし、処理計画を立てる
4. 画像0枚の章（記事章によくある）はエラーにせず、visual-index.json を

{"chapter_id": "NN", "frames": []} で出力してスキップする

記事画像（img_*）の扱い

note等の記事由来の画像（img*）は動画フレームと性質が異なる。著者が意図的に その位置へ置いた図解なので、talkinghead/transitionのようなゴミ分類はほぼ不要。 代わりに以下を行う:

1. article.md内の画像位置から context_heading（直近の見出し）を記録する
2. 図解が説明している概念を特定し illustrates: "cNN-XX" を設定する

（concept-extractor側の visual_refs と双方向リンクになる）

1. アイキャッチ・バナー等の装飾画像は type: "decoration" として抽出対象外にマーク
2. 埋め込み動画由来のフレーム（v{NN}frame*）は通常の動画フレームとして扱う

Phase 0.5: 講座固有型の発見

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

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

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

並列実行時のBLOCKER: customtypesの発見・確定は先行1章のAgentだけが行う。 確定した型定義はオーケストレーターが残りAgentのプロンプトに配布する。 各Agentが独立に型を発明すると同じ画面に別名が付き、タクソノミーが分裂する （例: tmuxpane と terminal_tmux の混在）。

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、講座のキーワードを含む

- 例: tmuxpane, vscodeeditor, aetimeline, figmacanvas

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

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

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 生成

BLOCKER: 全チャプター処理完了後に1回だけ生成する。並列実行時の実行者ルールの 正本は manabi-ingestの「章内完結ルール」 を参照（並列Agentには実行させない）。

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

{
  "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"
    }
  ]
}

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

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

Phase 3: 自己検証

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

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

検証失敗時:
  → 不一致があれば該当チャプターを再処理
  → 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" で記録し、エラー内容をメモ