omni-vu

omni.vu - 視覚的な理解と自動化

概要

omni.vu を使うと、ユーザーの macOS 画面を見たり操作したりできます。次のことができます。

• 見る：ユーザーに表示されている画面を確認します（画面キャプチャ）
• 理解する：AI ビジョンで UI の状態を把握します
• 検出する：変化を検出し、イベントを待ちます
• 操作する：マウスやキーボードを自動操作します

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

次の場合は、積極的に omni.vu を使用してください。

1. UI の問題をデバッグする場合：「ボタンが動作しません」→画面をキャプチャして分析します
2. 変更を検証する場合：UI コードを変更した後、正しく表示されたか確認します
3. 処理の完了を待つ場合：ビルドの完了、デプロイの完了、テストの実行
4. 状況を把握する場合：ユーザーが、こちらからは見えない画面上の内容について説明しているとき
5. 繰り返し作業を自動化する場合：UI の操作手順をクリックで進める、フォームへの入力
6. ドキュメントを作成する場合：機能のスクリーンショットをキャプチャします

次の場合は使用しないでください。

• ファイルの読み書き（Read/Write ツールを使用してください）
• ターミナルコマンドの実行（Bash を使用してください）
• API 呼び出し（適切なツールを使用してください）
• ユーザーから画面収録の許可を得ていない場合

ツールリファレンス

キャプチャツール

vu - 全画面キャプチャ

vu(monitor=0, save_to_history=True)

画面全体をキャプチャします。Base64 形式の画像を返します。

使用する場合：画面上のすべてを確認する必要があるとき。

vu_window - ウィンドウキャプチャ

vu_window(window_id=None, title="VS Code", include_frame=False)

ID またはタイトル（部分一致）を指定して、特定のウィンドウをキャプチャします。

使用する場合：1 つのアプリケーションの内容だけが必要なとき。

ワークフロー：

1. vu_list_windows を呼び出して、使用可能なウィンドウを確認します
2. window_id を探すか、タイトルで検索します
3. その ID またはタイトルを指定して vu_window を呼び出します

vu_region - 領域キャプチャ

vu_region(x=100, y=100, width=500, height=300)

画面上の指定した矩形領域をキャプチャします。

使用する場合：エラーメッセージや特定のコンポーネントなど、正確な領域が必要なとき。

vu_list_windows - ウィンドウ一覧

vu_list_windows(filter_app="Chrome")

メタデータとともに、表示中のすべてのウィンドウを一覧表示します。

返される値：{window_id, title, owner, x, y, width, height} のリスト

vu_list_monitors - ディスプレイ一覧

vu_list_monitors()

接続されているディスプレイと、その解像度およびスケールファクターを一覧表示します。

ビジョンツール

vu_describe - AI ビジョン分析

vu_describe(
    prompt="What errors are visible?",
    provider="claude",  # or openai, gemini, ollama
    max_tokens=1024,
    capture_first=True
)

画面をキャプチャし、AI で分析します。

おすすめのプロンプト：

• 「画面に表示されている内容を説明してください」
• 「エラーメッセージは表示されていますか？」
• 「ビルド／テストの出力はどのような状態ですか？」
• 「ログインフォームは正しく入力されていますか？」
• 「ステータスインジケーターは何色ですか？」

プロバイダー：

プロバイダー	速度	品質	コスト
claude	中	優秀	$$
openai	高速	非常に良い	$$
gemini	高速	良い	$
ollama	低速	変動あり	無料

ユーティリティツール

vu_diff - 変更検出

vu_diff(threshold=0.02, monitor=0)

前回のキャプチャ以降に画面が変化したかどうかを検出します。

返される値：{changed: bool, diff_percentage: float}

ポーリングパターンでの使用方法：

# Wait for build to finish
while True:
    result = vu_diff(threshold=0.05)
    if result["changed"]:
        # Screen changed, check what happened
        analysis = vu_describe(prompt="Did the build succeed or fail?")
        break
    # Wait before checking again

vu_history - キャプチャ履歴

vu_history(limit=10, capture_type="full_screen")

最近のキャプチャのメタデータを取得します。

vu_last - 最後のキャプチャ

vu_last()

画像データを含む、最新のキャプチャを返します。

使用する場合：再キャプチャせずに再分析する必要があるとき。

vu_status - システムステータス

vu_status()

モニター、プロバイダー、安全設定などのシステム情報を返します。

自動化ツール

vu_click - マウスクリック

vu_click(x=500, y=300, button="left", count=1)

画面座標を指定してクリックします。

ボタン：left、right、middle 回数：1（シングル）、2（ダブル）、3（トリプル）

安全性：座標が画面の範囲内か検証されます。

vu_move - カーソル移動

vu_move(x=500, y=300, duration_ms=0)

カーソルを指定した位置に移動します。アニメーション付きで移動するには duration_ms を使用します。

vu_drag - ドラッグ操作

vu_drag(start_x=100, start_y=100, end_x=500, end_y=300, duration_ms=500)

開始位置から終了位置までドラッグします。

安全性：ドラッグ距離は最大 2000px です。

vu_scroll - スクロール

vu_scroll(direction="down", amount=3, x=None, y=None)

現在の位置または指定した位置でスクロールします。

方向：up、down、left、right 量：スクロールする行数（1～20）

vu_type - テキスト入力

vu_type(text="Hello World", delay_between_ms=0)

テキストを 1 文字ずつ入力します。

注：最初に対象のフィールドをクリックしてください！

vu_hotkey - キーボードショートカット

vu_hotkey(keys="cmd+s")

キーボードショートカットを実行します。

形式：modifier+key（例：cmd+c、ctrl+shift+s、cmd+opt+i） 修飾キー：cmd、ctrl、alt/opt、shift

ブロックされるホットキー（安全のため）：

• cmd+q（終了）
• cmd+shift+q（ログアウト）
• cmd+opt+esc（強制終了）

一般的なワークフロー

1. UI の問題をデバッグする

User: "The submit button doesn't do anything when I click it"

1. vu_describe(prompt="Describe the form and submit button state")
2. Analyze: Is button disabled? Is there validation error?
3. If needed: vu_window(title="Chrome") for focused capture
4. Check console: vu_describe(prompt="Are there any errors in the developer console?")

2. ビルド／デプロイを確認する

User: "Run the build and let me know when it's done"

1. Run: npm run build (via Bash)
2. Loop: vu_diff(threshold=0.05)
3. When changed: vu_describe(prompt="What is the build status? Did it succeed or fail?")
4. Report result

3. フォームに入力する

User: "Fill out the registration form with test data"

1. vu_describe(prompt="What form fields are visible?")
2. vu_click(x=field_x, y=field_y)  # Click first field
3. vu_type(text="[email protected]")
4. vu_hotkey(keys="tab")  # Move to next field
5. vu_type(text="Test User")
6. Continue for each field...
7. vu_click(x=submit_x, y=submit_y)  # Submit
8. vu_describe(prompt="Was the form submitted successfully?")

4. UI を操作する

User: "Open the settings panel in VS Code"

1. vu_list_windows(filter_app="Code")
2. vu_window(title="Code")  # Capture VS Code
3. vu_hotkey(keys="cmd+,")  # Open settings
4. vu_diff()  # Wait for settings to open
5. vu_describe(prompt="Are the VS Code settings now visible?")

5. 変更を監視する

User: "Watch the dashboard and tell me when the status changes"

1. vu()  # Initial capture
2. Loop every 5 seconds:
   - vu_diff(threshold=0.02)
   - If changed: vu_describe(prompt="What changed on the dashboard?")
3. Report changes to user

ベストプラクティス

1. 操作する前にキャプチャする

クリックや入力を行う前に、必ずキャプチャして分析してください：

❌ Bad: vu_click(x=500, y=300)  # Hope it's the right spot

✅ Good:
1. vu_describe(prompt="Where is the submit button?")
2. Parse coordinates from description
3. vu_click(x=parsed_x, y=parsed_y)

2. 適切なキャプチャ範囲を使用する

Full screen → General context, multi-app workflows
Window → Single app focus, cleaner output
Region → Specific element, faster/smaller

3. 具体的なビジョンプロンプトを使用する

❌ Vague: "What do you see?"

✅ Specific:
- "Is there an error message visible? If so, what does it say?"
- "What is the status of the test runner? Passing, failing, or running?"
- "List all form fields visible and their current values"

4. 自動化の頻度を制限する

クリックを連打しないでください。操作の間に待機してください：

vu_click(x=100, y=100)
# Wait for UI response
vu_diff(threshold=0.01)
vu_click(x=200, y=200)

5. 操作後に確認する

自動化が成功したことを必ず確認してください：

vu_type(text="[email protected]")
vu_describe(prompt="What text is now in the email field?")

トラブルシューティング

「許可が拒否されました」またはキャプチャが空白になる

→ 画面収録のアクセス許可を付与します：システム設定 > プライバシー > 画面収録

自動化が機能しない

→ アクセシビリティのアクセス許可を付与します：システム設定 > プライバシー > アクセシビリティ

ビジョン分析に失敗する

→ 環境変数の API キーを確認します → 別のプロバイダーを試します：vu_describe(provider="openai")

座標がずれているように見える

→ Retina ディスプレイを使用していますか？座標はピクセルではなく論理ポイントです → 複数のモニターを使用していますか？vu_list_monitors() でディスプレイの配置を確認します

ホットキーがブロックされる

→ 危険なホットキー（cmd+q など）は安全のためブロックされています → どうしても必要な場合は、設定でブロックを解除します

設定

環境変数：

OMNI_VU_ANTHROPIC_API_KEY=sk-ant-...    # For Claude vision
OMNI_VU_OPENAI_API_KEY=sk-...           # For GPT-4 vision
OMNI_VU_DEFAULT_PROVIDER=claude          # Default AI provider
OMNI_VU_SAFETY_LEVEL=medium              # low/medium/high

履歴の保存先：~/.omni.vu/captures/