computer-automation

デスクトップのコンピューター操作

重要なルール — 違反するとワークフローが破綻します：

1. midscene コマンドをバックグラウンドで実行しないでください。 各コマンドは同期的に実行し、次のアクションを決める前に出力（特にスクリーンショット）を確認してください。バックグラウンド実行では、スクリーンショットを確認・分析して操作するループが破綻します。
2. midscene コマンドは一度に 1 つだけ実行してください。 前のコマンドが完了するまで待ち、スクリーンショットを確認してから次のアクションを決めてください。複数のコマンドを連結して実行しないでください。
3. 各コマンドの完了に十分な時間を確保してください。 Midscene のコマンドは AI 推論と画面操作を伴うため、一般的なシェルコマンドより時間がかかることがあります。通常、コマンドには約 1 分かかります。複雑な act コマンドでは、さらに長くかかる場合があります。
4. 終了前に必ずタスクの結果を報告してください。 自動化タスクが完了したら、見つかった重要なデータ、完了した操作、撮影したスクリーンショット、関連する調査結果などを含めて、結果をユーザーに積極的に要約してください。最後の自動化ステップの後、何も報告せずに終了しないでください。ユーザーは 1 回のやり取りで完全な回答を期待しています。
5. ウィンドウは最小化のみ行い、明示的に指示された場合を除き閉じないでください。 ウィンドウを閉じたり、邪魔にならないようにしたりする必要がある場合は、閉じるのではなく最小化してください。ユーザーから明示的に指示されない限り、アプリやウィンドウを閉じないでください。

npx -y @midscene/computer@1 を使用して、デスクトップ（macOS、Windows、Linux）を操作します。各 CLI コマンドは MCP ツールに直接対応しています。AI エージェントであるあなたが、スクリーンショットに基づいて実行する操作を決定します。

act でできること

デスクトップ上の 1 回の 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"
# If using OpenRouter, set:
# 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>

RDP 経由で接続する

ローカルマシンではなく、リモートの Windows デスクトップを操作するには、RDP モードを使用します。--host を指定すると connect が RDP モードに切り替わり、その後のすべてのコマンド（act、tap、take_screenshot、assert、disconnect）は、@midscene/computer にバンドルされた RDP ヘルパーバイナリを経由して実行されます。ローカルのマウスやキーボードは操作されません。

最小限の例：

npx -y @midscene/computer@1 connect \
  --host rdp.example.com \
  --username Administrator \
  --password "$RDP_PASSWORD"

connect で使用できるすべての RDP オプション（--host を設定すると RDP モードが有効になります。他のフラグは省略可能です）：

• --host <fqdn-or-ip> — RDP ホストです。RDP モードに入るには必須です。
• --port <number> — RDP ポートです（デフォルトは 3389）。
• --username <user> — RDP ユーザーアカウントです。
• --password <secret> — RDP パスワードです。環境変数、シークレットマネージャー、または対話型プロンプトから読み込むことを推奨します。共有トランスクリプトには絶対に貼り付けないでください。
• --domain <domain> — Active Directory / NTLM ドメインです。
• --security-protocol <auto|tls|nla|rdp> — セキュリティプロトコルのネゴシエーション方法です。デフォルトは auto です。
• --ignore-certificate — TLS 証明書の検証をスキップします。自己署名証明書を使用している信頼できる開発用ホストでのみ使用してください。
• --admin-session — 管理者／コンソールセッションに接続します（mstsc /admin と同等です）。
• --desktop-width <px> と --desktop-height <px> — 特定のリモートデスクトップ解像度を要求します。実際のサイズは、RDP サーバーがネゴシエーションで返す値です。たとえば、1024x768 を要求しても、ホストが 1280x720 に固定している場合は 1280x720 になります。接続後に listdisplays --host ... --username ... --password ... を実行して、ネゴシエーションされたサイズを確認してください。

RDP モード固有の注意事項：

• RDP モードでは --displayId と --headless は無視されます。接続された RDP セッションで公開される仮想ディスプレイは常に 1 つで、そのサイズはサーバーがネゴシエーションで返した値になります。
• ディスプレイ一覧を表示するコマンドは 2 つあり、動作が異なります。適切な方を選んでください。
  • list_displays（アンダースコアあり、プラットフォームツール）—ローカルの物理ディスプレイのみを列挙します。RDP フラグは受け付けません。RDP 接続後に実行しても役に立ちません。
  • listdisplays（アンダースコアなし、アクションツール）— connect／take_screenshot などと同じ RDP フラグを受け付けます。RDP モードでは、ネゴシエーションされた仮想ディスプレイを返します。例：[{ "id": "...", "name": "RDP 10.70.86.26:3389 (1280x720)", "primary": true }]。これを使って実際の解像度を確認してください。
• RDP トランスポートでは、@midscene/computer に同梱されているネイティブヘルパーバイナリを使用します。RDP helper binary not found エラーが表示される場合は、オプションの bin/<platform>/rdp-helper がインストールから除外されています。パッケージを再インストールするか、新しい tarball を展開してください。
• RDP 認証情報はシークレットとして扱ってください。--password を含む .env ファイルをリポジトリにコミットしないでください。代わりに現在のシェルで export RDP_PASSWORD=... を実行し、--password "$RDP_PASSWORD" のように参照してください。
• レイテンシの目安：CLI を実行するたびに新しい node プロセスが起動するため、コマンドごとに RDP セッションを再確立します。おおよその所要時間は次のとおりです。
  • connect／take_screenshot／keyboardpress／scroll：約 5 秒（node の起動 + RDP TLS+NLA ハンドシェイク + 最初のフレーム）。
  • act／assert／tap --locate：約 5 秒 + AI 推論 + 計画されたサブアクション。一般的な操作では、エンドツーエンドで 8～20 秒かかると見込んでください。
  • RDP ハンドシェイク自体は約 700 ミリ秒です。残りは CLI の仕組み上避けられないコールドスタートのコストです。
• 接続失敗時の診断：connect が失敗した場合、stderr の最初の行に対処に必要なエラーが表示されます（例：connect_failed: Failed to connect to RDP server: ERRCONNECT_LOGON_FAILURE: Logon failed.）。続くスタックトレースは診断上のノイズです。最初の行を読み、認証情報やネットワークを確認してください。よくある ERRCONNECT_* の原因は次のとおりです。
  • LOGON_FAILURE — ユーザー名／パスワード／ドメインが正しくありません。
  • CONNECT_TRANSPORT_FAILED — ホストに到達できないか、RDP ポートがブロックされています。nc -zv <host> 3389 で確認してください。
  • TLS_CONNECT_FAILED — TLS ハンドシェイクが拒否されました。自己署名証明書を使用している開発用ホストでは --ignore-certificate を試すか、--security-protocol nla を指定してください。

connect --host ... が成功した後は、以降のワークフロー（act、tap --locate、assert、take_screenshot、listdisplays、report-tool、disconnect）はローカルモードと同じです。ただし、CLI の各実行はステートレスで再接続するため、以降の各コマンドにも同じ --host／--username／--password／--ignore-certificate フラグを渡してください。

ディスプレイ一覧

npx -y @midscene/computer@1 list_displays

スクリーンショットの撮影

npx -y @midscene/computer@1 take_screenshot

スクリーンショットを撮影したら、次のアクションを決める前に保存された画像ファイルを読み取り、現在の画面の状態を把握してください。

アクションの実行

act を使ってコンピューターを操作し、結果を取得します。クリック、入力、スクロール、待機、移動など、すべての UI 操作を自律的に処理するため、作業を細かな手順に分けるのではなく、複雑なタスクをまとめて指示してください。自然言語で、何をしたいか、どのような結果を得たいかを説明します。

# specific instructions
npx -y @midscene/computer@1 act --prompt "type hello world in the search field and press Enter"
npx -y @midscene/computer@1 act --prompt "drag the file icon to the Trash"

# or target-driven instructions
npx -y @midscene/computer@1 act --prompt "search for the weather in Shanghai using the Chrome browser, tell me the result"

現在の画面状態を確認する

assert を使って、現在の画面が自然言語で指定した条件を満たしているか確認します。UI 操作は行わず、画面に表示されている状態を検査し、条件が真の場合にのみ成功します。検証、QA チェック、act 実行後の最終状態の確認に使います。

npx -y @midscene/computer@1 assert --prompt "there is a login button visible"
npx -y @midscene/computer@1 assert --prompt "the active window shows a saved confirmation message"
npx -y @midscene/computer@1 assert --displayId 1 --prompt "the file picker is open"

アサーションが失敗すると、デフォルトでは AI が生成した理由をスローします。代わりにカスタムエラーメッセージをスローするには --message を渡します。これは、QA や CI のログに意図した結果を表示する場合に便利です。

npx -y @midscene/computer@1 assert \
  --prompt "the export completed dialog is visible" \
  --message "the export should finish after clicking Save"

アサーションで参照画像（アイコン、ロゴ、スクリーンショット）との比較が必要な場合は、URL またはパスを --image に、表示名を --image-name に渡します。各 --image には、http(s) リンク、data: URI、またはローカルファイルのパスを指定できます。複数の画像を添付する場合は、両方のフラグを対応する順番で繰り返してください。モデルが URL に直接アクセスできない場合は、--convertHttpImage2Base64 true を追加します。@midscene/[email protected]+ が必要です。

npx -y @midscene/computer@1 assert \
  --prompt "the active window matches the supplied reference screenshot" \
  --image "https://example.com/reference.png" \
  --image-name "reference" \
  --convertHttpImage2Base64 true

# or with a local file
npx -y @midscene/computer@1 assert \
  --prompt "the visible icon matches the supplied logo" \
  --image "./fixtures/logo.png" \
  --image-name "logo"

# multiple reference images — pair --image and --image-name by order
npx -y @midscene/computer@1 assert \
  --prompt "the active window matches both the icon and the logo" \
  --image "./fixtures/icon.png" --image-name "icon" \
  --image "./fixtures/logo.png" --image-name "logo"

正確に対象を指定するための参照画像の使用

ユーザーからスクリーンショット、アイコン、ロゴ、参照画像が提供され、見た目を正確に一致させる必要がある場合は、汎用的な act --prompt ではなく tap --locate を優先してください。--locate には JSON を渡します。prompt で対象を説明し、images に名前付きの参照画像を指定します。画像 URL にモデルが直接アクセスできない場合は、convertHttpImage2Base64: true が便利です。

npx -y @midscene/computer@1 tap --locate '{
  "prompt": "tap the area contains the image",
  "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 がすでにヘルスチェック（スクリーンショットとマウス移動テスト）を実行している場合は、追加のチェックは不要です。ヘルスチェックが実行されていない場合は、手動で行います。スクリーンショットを撮影して成功することを確認し、次にマウスをランダムな位置に移動して（act --prompt "move the mouse to a random position"）成功することを確認します。どちらかの手順が失敗した場合は、続行せず、トラブルシューティングを行ってください。両方のチェックがエラーなく成功した場合にのみ、次の手順に進みます。
3. 対象アプリを起動してスクリーンショットを撮影し、現在の状態を確認します。アプリが起動し、画面に表示されていることを確認してください。
4. act を使って目的の操作または対象に基づく指示を実行し、結果の画面状態を確認する必要がある場合は assert を使います。
5. 完了したら切断します
6. 結果を報告 — 完了した内容を要約し、タスク中に得られた主な知見やデータを示し、生成されたファイル（スクリーンショット、ログなど）があればパスとともに一覧にします

ベストプラクティス

1. 必ず最初にヘルスチェックを実行してください：接続後、connect コマンドの出力を確認します。connect ですでにヘルスチェック（スクリーンショットの撮影とマウス移動テスト）が実行されている場合、追加のチェックは不要です。実行されていない場合は、手動でチェックしてください。スクリーンショットを撮影し、マウスをランダムな位置に移動します。その後の操作に進む前に、どちらもエラーなく成功する必要があります。これにより、環境の問題を早い段階で検出できます。
2. このスキルを使う前に、対象のアプリを前面に表示してください：最も効率よく作業するために、（macOS の open -a <AppName>、Windows の start <AppName> などで）ほかの方法を使ってアプリを前面に表示してから、midscene コマンドを実行してください。その後、スクリーンショットを撮影し、アプリが実際に前面に表示されていることを確認します。画面で確認してから、このスキルを使った UI 自動化に進んでください。midscene を通じて Spotlight、スタートメニューの検索、その他のランチャーを使う方法は避けてください。一時的な UI が表示され、AI による推論を何度も行う必要があるため、大幅に時間がかかります。
3. UI 要素を具体的に指定してください：曖昧な説明ではなく、明確で具体的な情報を提示してください。「ボタン」ではなく、「Safari ウィンドウの左上にある黄色の最小化ボタン」と指定します。
4. 可能な場合は位置を説明してください：要素を特定しやすくするため、その位置を説明してください（例：「メニューバーの右上にあるアイコン」、「左側のサイドバーにある3番目の項目」）。
5. バックグラウンドで実行しないでください：すべての midscene コマンドは同期的に実行する必要があります。バックグラウンドで実行すると、スクリーンショットの撮影・分析・操作のループが機能しなくなります。
6. 複数のディスプレイを確認してください：アプリを起動してもスクリーンショットに表示されない場合、アプリのウィンドウが別のディスプレイに開いている可能性があります。list_displays を使って、利用可能なディスプレイを確認してください。アプリのウィンドウを現在のディスプレイに移動するか、connect --displayId <id> を使ってアプリが表示されているディスプレイに切り替えてください。
7. 関連する操作は1つの act コマンドにまとめてください：同じアプリ内で連続して操作する場合は、複数のコマンドに分けず、1つの act プロンプトにまとめてください。たとえば、「X を検索し、最初の結果をクリックして、下にスクロールして詳細を確認する」という操作は、3回ではなく1回の 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) 実行した手順の簡単な概要です。最後の自動化コマンドの後に何も報告せずに終了しないでください。ユーザーは、1回のやり取りですべての結果が提示されることを期待しています。
11. 参照画像が提供されている場合は tap --locate を優先してください：ユーザーがスクリーンショット、アイコン、またはロゴを共有し、その画像とまったく同じ対象を指定した場合は、act --prompt だけに頼るのではなく、{ "prompt": "...", "images": [...] } のようなマルチモーダルな locate JSON オブジェクトを指定して tap --locate を使ってください。

例 — コンテキストメニューの操作：

npx -y @midscene/computer@1 act --prompt "right-click the file icon and select Delete from the context menu"
npx -y @midscene/computer@1 take_screenshot

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

npx -y @midscene/computer@1 act --prompt "open the File menu and click New Window"
npx -y @midscene/computer@1 take_screenshot

精度を向上させる（Deep Locate / Deep Think）

Midscene がタスクにうまく対応できない場合に役立つ、任意のグローバルフラグが 2 つあります。コマンド内のどこにでも（サブコマンドの前後どちらでも）指定できます。一度設定すると、該当する操作でデフォルトで使われるため、呼び出しごとにパラメーターを渡す必要はありません。

• --deep-locate — 視覚的な推論をもう 1 回行い、対象の要素を正確に特定します。操作が誤った位置を対象にする場合（位置のずれ／オフセット）に使用してください。tap --locate や act 内で行われる要素の特定など、要素を特定するすべての操作に適用されます。
• --deep-think — より深い推論（豊富なコンテキストとサブゴールへの分解）で act の計画を立てます。複雑な複数ステップの act 命令に使用してください。計画にのみ影響します。

どちらも速度が少し低下する代わりに、結果が向上します。両方を組み合わせて使用することもできます。

# more accurate element location (helps act's internal locating too)
npx -y @midscene/computer@1 act --deep-locate --prompt "click the tiny red close button in the top-left of the window"

# deeper planning for a complex, multi-step act
npx -y @midscene/computer@1 act --deep-think --prompt "open the Export dialog, choose PDF, and save it to the Desktop"

# combine both
npx -y @midscene/computer@1 act --deep-locate --deep-think --prompt "open Preferences and switch to the Advanced tab"

トラブルシューティング

macOS：アクセシビリティの権限が拒否される

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

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

macOS：Xcode Command Line Tools が見つからない

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。