セマンティックセレクターの概要

このガイドでは、akaBot Studioでの**セマンティックセレクター（Semantic Selector）**の使用方法について説明します。セマンティックセレクターは、厳密なHTML属性やウィンドウプロパティに依存するのではなく、高度なAI（コンピュータービジョン）を使用して、視覚的な意味とテキストに基づいて画面上のUI要素を特定します。

---

1. 概要

従来のセレクター（StrictまたはFuzzy）は、技術的な内部プロパティ（ID、CSSクラス、タグなど）に依存しています。Webサイトやアプリケーションの設計が更新されたり、内部コードが変更されたりすると、これらの従来のセレクターは機能しなくなり、自動化が失敗する原因となります。

セマンティックセレクターは、人間と同じように要素を見つけることでこの問題を解決します。要素をわかりやすい英語で記述するだけです（例: "Button Save", "InputBox Email"）。 セマンティックセレクターを使用することで、ワークフローはUIの変更、動的なID、およびシステムの更新に対して非常に高い復元力（レジリエンス）を持つようになります。

---

2. 前提条件

セマンティックセレクターを使用する前に、環境が以下の要件を満たしていることを確認してください：

システム管理者向け (ITセットアップ)

セマンティックセレクターには、AIグラウンディングモデルがロードされたCV（コンピュータービジョン）サーバーへの接続が必要です。プロジェクトフォルダー内の cvsettings.json ファイルにサーバーURLが正しく設定されていることを確認してください。

{
  "serverUrl": "http://localhost:8000/cv",
  "apiKey": "*",
  "ocr": true,
  "table": false,
  "background": false,
  "semantic": {
    "url": "http://localhost:8000"
  }
}

（注：ヘルスチェック、グラウンディング、およびOCRエンドポイントはアクティビティパッケージによって内部的に処理されます。CVサーバーのベースURLに semantic.url を設定するだけです）。

RPA開発者向け (Studioセットアップ)

セマンティックセレクターはアプリケーションの現在の視覚的状態を分析するため、アクティビティは「アプリケーションを開く/アタッチ（Open/Attach Application）」または「ブラウザーを開く/アタッチ（Open/Attach Browser）」スコープ内に配置する必要があります。これらのスコープの外で単独のアクティビティとして使用することはできません。

---

3. ステップバイステップガイド

以下の手順に従って、サポートされているUIアクティビティ（Click、Hover、Type Into、Select Item、Get Text、Find Elementなど）にセマンティックセレクターを設定します。

ステップ 1: サポートされているアクティビティを追加する

目的のUIアクティビティを「アプリケーションを開く/アタッチ」または「ブラウザーを開く/アタッチ」スコープにドラッグアンドドロップします。

ステップ 2: ターゲットを指定する

アクティビティ内の「画面上で指定（Indicate on screen）」をクリックし、通常通りターゲット要素を選択します。「選択オプション（Selection Options）」ウィンドウが表示されます。

ステップ 3: セマンティックセレクターを有効にする

「選択オプション」ウィンドウで、「Semantic selector」チェックボックスをオンにして、AIによるターゲット指定を有効にします。

ステップ 4: ターゲットを説明する

操作したい要素を明確かつ簡潔に説明します。標準の構文（フォーマット）である [Element Role] + [Visible Text] を使用します。 例：Button Save、InputBox Email、Icon Search、CheckBox Remember me

ステップ 5: 選択の検証

**「Validate（検証）」**ボタンをクリックします。AIが画面を分析し、入力された説明に一致すると判断した要素をハイライト表示します。

ハイライトされた結果が正しい場合は、**「Confirm（確認）」**をクリックしてターゲットを保存します。 （注：セマンティックセレクターを唯一のターゲット指定方法として使用することも可能ですが、説明フィールドを空白のままにすることはできません）。

---

4. セマンティック記述のベストプラクティス

AIモデルから最高の精度を引き出すために、説明（プロンプト）を記述する際は以下のガイドラインに従ってください：

推奨（Do This）	非推奨（Don't Do This）	理由
Button Login	Login	"Login" という単語は、段落、ヘッダー、またはボタンに表示される可能性があります。"Button" を追加することで、AIに探すべき要素のタイプを正確に指示できます。
InputBox First Name	First Name	"InputBox" を追加することで、AIは "First Name" というテキストラベルと、実際に入力したいテキストフィールドを区別しやすくなります。
Icon Search	Magnifying glass	視覚的な文字通りの説明ではなく、標準的なUIコンポーネント名（Icon、Button、Checkbox、Dropdown、InputBox）を使用してください。

---

5. トラブルシューティング（検証結果）

**「Validate（検証）」**をクリックすると、システムからステータスが返されます。問題のトラブルシューティングには、以下の表を使用してください：

ステータスメッセージ	意味と解決策
(空) + ハイライト	成功: AIが説明に一致する要素を正常に見つけ、ハイライト表示しました。
ターゲット要素と一致しません	警告: AIが要素を見つけましたが、最初にクリックした元の要素とは異なる場所にあります。 解決策: 説明が一般的すぎないか（例：画面に2つの「Submit」ボタンがあるなど）を確認します。説明をより具体的にしてください。
要素が見つかりません	エラー: 画面上で説明に一致する要素をAIが見つけられませんでした。 解決策: スペルを確認するか、別の役割（Role）を使用してください（例：Button を Icon に変更する）。
セマンティックサーバーが設定されていません	エラー: cvsettings.json ファイルがないか、semantic.url が空白です。 解決策: IT管理者に連絡してCVサーバーのURLを設定してください。
サーバーを利用できません	エラー: 設定されたCVサーバーがダウンしているか、到達不可能です。 解決策: ネットワーク接続を確認するか、サーバーが稼働しているかを確認してください。
セマンティックセレクターはアプリケーション/ブラウザースコープ内でのみ利用可能です。	エラー: アタッチ/開くスコープの外にアクティビティを配置しました。 解決策: アクティビティをブラウザーまたはアプリケーションスコープ内に移動してください。