デスクトップコンピュータ自動化

重大なルール — 違反はワークフローを破壊します:

1. midsceneコマンドをバックグラウンドで実行しないでください。 各コマンドは同期実行し、次のアクションを決める前に出力(特にスクリーンショット)を読む必要があります。バックグラウンド実行はスクリーンショット-分析-実行ループを破壊します。
2. 一度に1つのmidsceneコマンドのみを実行してください。 前のコマンドが完了するのを待ち、スクリーンショットを読んでから次のアクションを決めてください。複数のコマンドを連鎖させないでください。
3. 各コマンドが完了するのに十分な時間を確保してください。 Midsceneコマンドにはインテリジェンス推論と画面対話が含まれるため、典型的なシェルコマンドより長くかかる場合があります。通常のコマンドは約1分必要で、複雑なactコマンドはさらに長くかかる場合があります。
4. 終了前に必ずタスク結果をレポートしてください。 自動化タスク完了後、ユーザーに結果を主体的に要約する必要があります。見つかった重要データ、完了したアクション、撮影されたスクリーンショット、関連する発見を含めてください。最後の自動化ステップ後に黙って終わらないでください。ユーザーは単一のやり取りで完全な応答を期待しています。
5. ウィンドウは明示的に指示されない限り、最小化のみで閉じないでください。 ウィンドウを却下するか邪魔を避ける必要がある場合は、閉じるのではなく最小化してください。ユーザーが明示的に指示しない限り、アプリやウィンドウを閉じないでください。

npx -y @midscene/computer@1を使用してデスクトップ(macOS、Windows、Linux)を制御してください。各CLIコマンドはMCPツールに直接マップされます。あなた(AIエージェント)は脳として機能し、スクリーンショットに基づいて実行するアクションを決定します。

actでできること

デスクトップ上の単一のact呼び出し内で、Midsceneはマウスを移動、クリック、ダブルクリック、右クリック、アイテムのドラッグ、テキストの入力またはクリア、スクロール、単一キーまたはキーボードショートカットの押下、選択されたディスプレイ上に表示されているものに対する多段階の対話を実行できます。

前提条件

Midsceneは強力なビジュアルグラウンディング機能を持つモデルが必要です。以下の環境変数を設定する必要があります。システム環境変数またはカレントワーキングディレクトリの.envファイルのいずれかとして(Midsceneは.envを自動的にロードします):

MIDSCENE_MODEL_API_KEY="your-api-key"
MIDSCENE_MODEL_NAME="model-name"
MIDSCENE_MODEL_BASE_URL="https://..."
MIDSCENE_MODEL_FAMILY="family-identifier"

例: Gemini(Gemini-3-Flash)

MIDSCENE_MODEL_API_KEY="your-google-api-key"
MIDSCENE_MODEL_NAME="gemini-3-flash"
MIDSCENE_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
MIDSCENE_MODEL_FAMILY="gemini"

例: Qwen 3.5

MIDSCENE_MODEL_API_KEY="your-aliyun-api-key"
MIDSCENE_MODEL_NAME="qwen3.5-plus"
MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
MIDSCENE_MODEL_FAMILY="qwen3.5"
MIDSCENE_MODEL_REASONING_ENABLED="false"
# OpenRouterを使用する場合は以下を設定:
# MIDSCENE_MODEL_API_KEY="your-openrouter-api-key"
# MIDSCENE_MODEL_NAME="qwen/qwen3.5-plus"
# MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"

例: Doubao Seed 2.0 Lite

MIDSCENE_MODEL_API_KEY="your-doubao-api-key"
MIDSCENE_MODEL_NAME="doubao-seed-2-0-lite"
MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_FAMILY="doubao-seed"

よく使用されるモデル: Doubao Seed 2.0 Lite、Qwen 3.5、Zhipu GLM-4.6V、Gemini-3-Pro、Gemini-3-Flash。

モデルが設定されていない場合は、ユーザーに設定を依頼してください。モデル設定でサポートされるプロバイダーを確認してください。

コマンド

デスクトップに接続

npx -y @midscene/computer@1 connect
npx -y @midscene/computer@1 connect --displayId <id>

ディスプレイのリスト表示

npx -y @midscene/computer@1 list_displays

スクリーンショットを撮る

npx -y @midscene/computer@1 take_screenshot

スクリーンショットを撮った後、保存された画像ファイルを読んで、次のアクションを決める前に現在の画面状態を理解してください。

アクションを実行

actを使用してコンピュータと対話して結果を取得します。UIの対話をすべて内部で自律的に処理します。クリック、入力、スクロール、待機、ナビゲーションなどです。複雑で高レベルなタスクを全体として提供してください。小さなステップに分割しないでください。自然言語で実行したい内容と望ましい効果を説明してください:

# 具体的な指示
npx -y @midscene/computer@1 act --prompt "検索フィールドにhello worldを入力してEnterキーを押す"
npx -y @midscene/computer@1 act --prompt "ファイルアイコンをゴミ箱にドラッグする"

# またはターゲット駆動型の指示
npx -y @midscene/computer@1 act --prompt "Chromeブラウザを使用して上海の天気を検索し、結果を教えてください"

現在の画面状態をアサート

assertを使用して、現在の画面が自然言語条件を満たすことを確認します。UIアクションは実行せず、表示される画面状態をチェックし、アサーションが真の場合のみ成功します。検証、QAチェック、act後の最終状態確認に使用します。

npx -y @midscene/computer@1 assert --prompt "ログインボタンが表示されている"
npx -y @midscene/computer@1 assert --prompt "アクティブウィンドウに保存確認メッセージが表示されている"
npx -y @midscene/computer@1 assert --displayId 1 --prompt "ファイルピッカーが開いている"

参照画像を使用した正確なターゲット設定

ユーザーがスクリーンショット、アイコン、ロゴ、または参照画像を提供し、正確なビジュアルマッチを望む場合は、汎用的なact --promptの代わりにtap --locateを使用してください。--locateをJSONとして渡してください。promptはターゲットを説明し、imagesは名前付き参照画像を提供し、convertHttpImage2Base64: trueは画像URLが直接モデルからアクセスできない場合に便利です。

npx -y @midscene/computer@1 tap --locate '{
  "prompt": "画像を含む領域をタップ",
  "images": [
    {
      "name": "target image",
      "url": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"
    }
  ],
  "convertHttpImage2Base64": true
}'

同じlocate JSONシェイプはlocateパラメータを受け入れる他のコマンドにも機能します。

切断

npx -y @midscene/computer@1 disconnect

レポートファイルを使用

生成されたHTMLレポートは人間が読むことをお勧めします。ステップバイステップの実行詳細と各操作の再生ビデオが含まれており、何が起こったかを理解し、問題をトラブルシューティングするのが容易になります。

別のスキルまたはツールがレポートを使用する必要がある場合は、同じプラットフォームCLIパッケージからreport-toolで最初に変換してください。LLMベースのワークフローではMarkdownを推奨します。レポートをプログラムで処理する必要がある場合はJSONを使用してください。

npx -y @midscene/computer@1 report-tool --action to-markdown --htmlPath ./midscene_run/report/.../index.html --outputDir ./output-markdown
npx -y @midscene/computer@1 report-tool --action split --htmlPath ./midscene_run/report/.../index.html --outputDir ./output-data

ワークフローパターン

CLIコマンドは呼び出し間でステートレスであるため、このパターンに従ってください:

1. 接続してセッションを確立
2. ヘルスチェック — connectコマンドの出力を確認してください。connectがすでにヘルスチェック(スクリーンショットとマウス移動テスト)を実行している場合、追加のチェックは不要です。実行していない場合は、手動で1つ実行してください。スクリーンショットを撮り、成功することを確認してから、マウスをランダムな位置に移動し(act --prompt "マウスをランダムな位置に移動する")、成功することを確認してください。どちらかのステップが失敗した場合は、停止してトラブルシューティングしてから続行してください。両方のチェックがエラーなしで成功した後のみ、次のステップに進みます。
3. ターゲットアプリを起動してスクリーンショットを撮ることで現在の状態を確認し、アプリが起動して画面に表示されていることを確認してください。
4. actを使用してアクションを実行して希望するアクションまたはターゲット駆動型の指示を実行し、結果の画面状態を確認する必要がある場合はassertを使用します。
5. 切断して完了
6. 結果をレポート — 達成されたことを要約し、タスク中に抽出された重要な発見とデータを提示し、生成されたファイル(スクリーンショット、ログなど)とそのパスをリストアップしてください

ベストプラクティス

1. 常に最初にヘルスチェックを実行します: 接続後、connectコマンドの出力を確認してください。connectがすでにヘルスチェック(スクリーンショットとマウス移動テスト)を実行している場合、追加のチェックは不要です。実行していない場合は、手動で1つ実行してください。スクリーンショットを撮り、マウスをランダムな位置に移動してください。両方ともエラーなしで成功する必要があります。これにより環境の問題を早期に発見できます。
2. このスキルを使用する前にターゲットアプリをフォアグラウンドに持ってきてください: 最高の効率のため、他の手段を使用してアプリをフォアグラウンドに持ってきてください(例えば、macOSではopen -a <AppName>、Windowsではstart <AppName>)。その後、midsceneコマンドを呼び出します。スクリーンショットを撮ってアプリが実際にフォアグラウンドにあることを確認してください。ビジュアル確認の後のみ、このスキルを使用してUI自動化を進めてください。Spotlight、Startメニュー検索、またはmidsceneを通じた他のランチャーベースのアプローチは避けてください。これらは一時的なUI、複数のインテリジェンス推論ステップを含み、著しく遅くなります。
3. UI要素について具体的にしてください: 曖昧な説明ではなく、明確で具体的な詳細を提供してください。「ボタン」ではなく、「SafariウィンドウのSafariウィンドウの左上隅の黄色い最小化ボタン」と言ってください。
4. 可能な限り場所を説明してください: 要素のターゲット設定を支援するため、位置を説明してください(例えば、「メニューバーの右上隅のアイコン」、「左のサイドバーの3番目のアイテム」)。
5. バックグラウンドで実行しないでください: すべてのmidsceneコマンドは同期実行する必要があります。バックグラウンド実行はスクリーンショット-分析-実行ループを破壊します。
6. 複数のディスプレイを確認してください: アプリを起動しましたがスクリーンショットに表示されない場合、アプリウィンドウが別のディスプレイで開いた可能性があります。list_displaysを使用して利用可能なディスプレイを確認してください。2つのオプションがあります。アプリウィンドウを現在のディスプレイに移動するか、connect --displayId <id>を使用してアプリがあるディスプレイに切り替えてください。
7. 同じアプリ内の関連する操作を単一のactコマンドにまとめてください: 同じアプリ内で連続する操作を実行する場合、それらを3つの個別コマンドに分割するのではなく、1つのactプロンプトにまとめてください。例えば、「Xを検索し、最初の結果をクリックし、スクロールして詳細を確認する」は、3つではなく単一のact呼び出しにする必要があります。これにより往復を削減し、不要なスクリーンショット-分析サイクルを避け、著しく高速化します。
8. 実行前にPATHをセットアップしてください(macOS): macOSでは、PATHが不完全な場合、一部のコマンド(例えばsystem_profiler)が見つからない可能性があります。midsceneコマンドを実行する前に、PATHに標準システムディレクトリが含まれていることを確認してください:

   export PATH="/usr/sbin:/usr/bin:/bin:/sbin:$PATH"
   

   これにより、システムユーティリティが欠落しているためのスクリーンショット失敗を防止します。
9. 検証にassertを使用してください: 画面状態が真であることを確認することが目標の場合は、actプロンプトの代わりにassert --prompt "..."を使用してください。アサーションを観察可能で具体的に保ってください。例えば「保存ダイアログが開いている」または「エクスポート完了メッセージが表示されている」など。
10. 完了後は必ず結果をレポートしてください: 自動化タスクを完了した後、ユーザーに尋ねられるのを待つことなく、主体的に結果を提示する必要があります。これには以下が含まれます: (1)ユーザーの元の質問への回答またはリクエストされたタスクの結果、(2)実行中に抽出または観察された重要なデータ、(3)スクリーンショットおよび他の生成されたファイルとそのパス、(4)実行されたステップの簡潔な要約。最後の自動化コマンド後に黙って終わらないでください。ユーザーは単一のやり取りで完全な結果を期待しています。
11. 参照画像が提供される場合はtap --locateを推奨します: ユーザーがスクリーンショット、アイコン、またはロゴを共有し、その正確なビジュアルターゲットを望む場合は、act --promptだけに頼るのではなく、{ "prompt": "...", "images": [...] }などの多モーダルlocate JSONオブジェクトを使用してtap --locateを使用してください。

例 — コンテキストメニューの対話:

npx -y @midscene/computer@1 act --prompt "ファイルアイコンを右クリックし、コンテキストメニューから削除を選択"
npx -y @midscene/computer@1 take_screenshot

例 — ドロップダウンメニュー:

npx -y @midscene/computer@1 act --prompt "ファイルメニューを開き、新規ウィンドウをクリック"
npx -y @midscene/computer@1 take_screenshot

トラブルシューティング

macOS: アクセシビリティ権限拒否

ターミナルアプリにアクセシビリティアクセスがありません:

1. システム設定 > プライバシーとセキュリティ > アクセシビリティを開く
2. ターミナルアプリを追加して有効にする
3. 権限を付与した後、ターミナルアプリを再起動する

macOS: Xcodeコマンドラインツールが見つからない

xcode-select --install

APIキーが設定されていない

.envファイルにMIDSCENE_MODEL_API_KEY=<your-key>が含まれていることを確認してください。

macOS: system_profilerが見つからないエラーでスクリーンショット失敗

take_screenshotがsystem_profiler: command not foundのようなエラーで失敗する場合、PATH環境変数が不完全である可能性があります。以下を実行して修正してください:

export PATH="/usr/sbin:/usr/bin:/bin:/sbin:$PATH"

その後、スクリーンショットコマンドを再度実行してください。

macOS: スクリーンショットが黒い画面を返す

take_screenshotが完全に黒い画像を返す場合、Macはロックされている可能性があります(例えば画面がログイン/ロック画面にある)。これはシステムレベルの制限です。セッションがロックされている間、macOSは画面コンテンツのキャプチャを禁止しているため、アプリケーションレベルに回避策はありません。

推奨される修正: 画面をロックする代わりにスクリーンセーバーを使用してください。スクリーンセーバーはユーザーセッションをアクティブでロック解除の状態に保ち、スクリーンショットが通常にキャプチャできるようにします。

1. システム設定 > ロック画面を開く
2. 「スクリーンセーバーが開始されるか、ディスプレイがオフになった後にパスワードが必要」を長い遅延に設定(または自動化中にオフに)
3. システム設定 > スクリーンセーバーでスクリーンセーバーを設定するオプション(ディスプレイは非アクティビティ後も暗くなりますがロックされません)

AIが要素を見つけられない

1. スクリーンショットを撮って、要素が実際に表示されていることを確認してください
2. より具体的な説明を使用してください(色、位置、周辺テキストを含める)
3. 要素が別のウィンドウの背後に隠れていないことを確認してください

@midscene/*依存関係バージョンが古い

• ローカルバージョンを確認: npm ls @midscene/computer @midscene/core @midscene/shared(またはpnpm why @midscene/computer)。
• 最新バージョンを確認: npm view @midscene/computer version、npm view @midscene/core version、npm view @midscene/shared version。
• 依存関係をアップグレード: npm i @midscene/computer@latest @midscene/core@latest @midscene/shared@latest。