6. データ要件と構造定義

本システムで扱うデータ定義です。記録時に各モジュール（YOLO、OCR、Python）が個別に取得する「生データ」の構造を先に行い、それらをコンテキスト理解や自己修復のために集約・紐付けした「統合データ」の構造を後ろに定義します。

6.1. リソースディレクトリ構成と命名規則

JSONファイル自体の肥大化を防ぎ、かつ画像パスを決定論的に特定するため、マクロごとに一意なディレクトリ（workflow_ID）を作成し、リソースをカプセル化します。

macros/
└── wf_12345/             // workflow_IDをルートとする
    ├── integrated.json   // 統合データ（1マクロにつき1つ）
    ├── workflow.json     // ワークフローデータ（1マクロにつき1つ）
    ├── images/           // 画像格納用ディレクトリ
    │   ├── evt_001_pre.png   // 操作直前の全体スクリーンショット（※マウスクリックおよびキー操作の両方で生成）
    │   ├── evt_001_crop.png  // 操作対象UI要素のクロップ画像
    │   ├── evt_002_pre.png
    │   └── ...
    └── temp/             // 一時データ格納ディレクトリ（統合・生成フェーズ完了後に自動破棄）
        ├── input_logs.json   // リアルタイム操作の生ログ（1マクロにつき1つ）
        ├── evt_001_yolo.json // イベントごとのYOLO認識生データ
        └── evt_001_ocr.json  // イベントごとのOCR認識生データ

※操作直後（Post）のスクリーンショットに関する設計変更:
操作の直後に個別のスクリーンショット（post）を撮る仕様は廃止されました。これは、連続する「次の操作の直前（pre）」に撮影される画像が、実質的に前のアクションの直後状態を写していると判断できるためです。これにより、不要なキャプチャ処理のオーバーヘッドとストレージへの二重保存を防止します。

※生データおよび画像リソースのライフサイクルについて:
各モジュールが取得する生データ（YOLO、OCR、入力ログ）は、マクロの生成処理中にのみ temp/ ディレクトリ内へ一時的に保存され、生成完了後に自動破棄されます。また、images/ 内に保存されるスクリーンショットは、マウスクリック時だけでなくキーボード操作時（文字入力等）にも撮影がトリガーされます。ただし、連続したテキスト入力のように「画面の変化率が著しく低い操作」が続いた場合、ストレージ容量の圧迫やデータの冗長化を防ぐため、前回のスクリーンショットとの差分解析を行い、変化率が閾値未満のときは該当する低い画像を自動的に削除・間引きする最適化が実行されます。

6.2. 生データ構造定義（一時データ）

解析モード（録画）中、各認識エンジンおよびフックモジュールが出力するデータ構造です（統合後に破棄）。

6.2.1. UI認識データ（YOLO Engine）

保存先階層: ai-macro-system/macros/wf_{workflow_ID}/temp/evt_{event_id}_yolo.json

6.2.2. テキスト認識データ（OCR Engine）

保存先階層: ai-macro-system/macros/wf_{workflow_ID}/temp/evt_{event_id}_ocr.json

6.2.3. 入力操作データ（Python OS Hook）

保存先階層: ai-macro-system/macros/wf_{workflow_ID}/temp/input_logs.json

6.4. 統合データ構造定義

自律機能やAI生成コアが「コンテキスト理解」を確保するため、一時データをウィンドウ基準の階層型ツリー（DOMライク）に統合したデータモデルです。

※階層ツリー構築と推論誤差の吸収 (IoA判定):
YOLOやOCRが検出した要素の親子関係（包含関係）を構築する際、単なる座標の完全内包ではなく、交差面積率（IoA: Intersection over Area）を計算します。AIの推論による数ピクセルのはみ出しを許容するため、子要素の面積のうち閾値（例: 70%）以上が親要素と重なっていれば内包されていると判定し、堅牢なXMLライクのUIツリーを構築します。

保存先階層: ai-macro-system/macros/wf_{workflow_ID}/integrated.json

6.5. 統合データ JSONフォーマット例

{
  "id": "evt_012",
  "timestamp": 1717654800123,
  "window": {
    "name": "社内システム - Google Chrome",
    "size": { "width": 1920, "height": 1080 },
    "coordinates": { "x": 0, "y": 0 },
    "UIs": [
      {
        "type": "form",
        "relativeBoundingBox": { "x": 1000, "y": 200, "width": 400, "height": 300 },
        "confidence": 0.90,
        "action": null,
        "context": [],
        "children": [
          {
            "type": "button",
            "relativeBoundingBox": { "x": 1220, "y": 280, "width": 60, "height": 40 },
            "confidence": 0.95,
            "action": {
              "inputType": "click_down",
              "inputValue": "left_click",
              "cursorRelativeCoordinates": { "x": 1250, "y": 300 },
              "diffRatio": 0.12
            },
            "context": [
              {
                "type": "text",
                "content": "保存する",
                "relativeBoundingBox": { "x": 1225, "y": 285, "width": 50, "height": 30 },
                "confidence": 0.98,
                "parentRelevance": 0.99
              }
            ],
            "children": []
          }
        ]
      }
    ]
  }
}

6.6. ワークフローデータと変数データの構造定義 (Omnipotent Workflow)

統合ログからAIによって抽出・生成され、実行エンジンへと引き渡されるマクロシナリオの構造です。本システムでは、あらゆるユーザー操作にスケーラブルに対応するため、「コマンドパターン」と「ユニバーサルセレクタ」を採用した抽象度の高い設計（Omnipotent Workflow）としています。

6.6.1. ワークフロー変数定義 (variables.json)

保存先階層: ai-macro-system/macros/wf_{workflow_ID}/variables.json

6.6.2. ワークフロー実行シナリオ定義 (workflow.json)

保存先階層: ai-macro-system/macros/wf_{workflow_ID}/workflow.json

6.7. データ JSONフォーマット例

コマンドパターンとユニバーサルセレクタを採用した、あらゆる操作に対応可能なマクロの生成例です。

📁 variables.json

{
  "target_file_name": "report_2026.pdf",
  "search_keyword": "ai macro system"
}

📁 workflow.json

{
  "version": "2.0",
  "workflow_ID": "wf_omnipotent_001",
  "metadata": {
    "os": "Windows",
    "resolution": { "width": 1920, "height": 1080 },
    "duration_ms": 15000
  },
  "steps": [
    {
      "step_id": 1,
      "intent": "DRAG_AND_DROP",
      "description": "Drag the specific file to the upload dropzone.",
      "context": {
        "active_window_name": "Explorer"
      },
      "action": {
        "command": "MOUSE_DRAG",
        "parameters": {
          "target": {
            "semantic_role": "listitem",
            "text_contains": "${target_file_name}"
          },
          "destination": {
            "semantic_role": "dropzone",
            "image_template": "upload_area_template.png"
          },
          "button": "left"
        }
      },
      "fallback_raw_events": ["evt_001", "evt_002"]
    },
    {
      "step_id": 2,
      "intent": "COPY_TEXT",
      "description": "Copy the selected text using keyboard shortcuts.",
      "context": {
        "active_window_name": "Browser"
      },
      "action": {
        "command": "KEYBOARD_SHORTCUT",
        "parameters": {
          "modifiers": ["control"],
          "key": "c"
        }
      },
      "fallback_raw_events": ["evt_003"]
    },
    {
      "step_id": 3,
      "intent": "WAIT_FOR_PROCESS",
      "description": "Wait until the loading spinner disappears before proceeding.",
      "context": {},
      "action": {
        "command": "SYSTEM_WAIT",
        "parameters": {
          "condition": "ELEMENT_NOT_VISIBLE",
          "target": {
            "semantic_role": "progressbar"
          },
          "timeout_ms": 10000
        }
      },
      "fallback_raw_events": []
    }
  ]
}

6.8. アプリケーション設定データ（config.json）

ユーザーが画面上の設定エリアから変更した接続先エンドポイントなどの情報を管理・永続化するためのデータ構造です。本ファイルはアプリケーションのルートディレクトリに配置されます。

保存先階層: ai-macro-system/config.json

6.9. アプリケーション設定 JSONフォーマット例

{
  "ai_mode": "local",
  "llm_host": "127.0.0.1",
  "llm_port": "8844",
  "cv_host": "192.168.1.10",
  "cv_port": "8843"
}

6.10. 実行可能マクロデータ（Executable Macro）

実行エンジンが直接解釈可能な、メソッド名と解決済み引数を持つマクロ用JSONです。LLMが workflow.json の意図と integrated.json の座標データを組み合わせて生成した状態を表現し、実行時にそのまま使用されます。

保存先階層: ai-macro-system/macros/wf_{workflow_ID}/executable_macro.json (またはLLMからの直接返却)

📁 実行可能マクロのJSONフォーマット例（事務作業シナリオ）

Webブラウザ上の業務システム（顧客管理システムや経費精算など）で、「新規登録ボタンを押し、フォームに社名とメールアドレスを入力して保存する」といった一般的なデータ入力作業を想定した例です。

{
  "macro_id": "macro_002_customer_registration",
  "target_application": "Google Chrome - 顧客管理システム",
  "commands": [
    {
      "method": "wait",
      "args": {
        "duration": 1.0
      }
    },
    {
      "method": "click",
      "args": {
        "x": 1200,
        "y": 150,
        "button": "left",
        "clicks": 1
      }
    },
    {
      "method": "wait",
      "args": {
        "duration": 0.5
      }
    },
    {
      "method": "click",
      "args": {
        "x": 400,
        "y": 300,
        "button": "left",
        "clicks": 1
      }
    },
    {
      "method": "type_text",
      "args": {
        "text": "株式会社テスト"
      }
    },
    {
      "method": "press_key",
      "args": {
        "key": "tab"
      }
    },
    {
      "method": "type_text",
      "args": {
        "text": "info@example.com"
      }
    },
    {
      "method": "click",
      "args": {
        "x": 400,
        "y": 600,
        "button": "left",
        "clicks": 1
      }
    }
  ]
}