macos-automation

macos-automation

目的

このスキルは、AppleScript、JXA、Shortcuts、Automator、osascript、System Events、アクセシビリティ API などのツールを使用して macOS のタスクを自動化し、スクリプトによるアプリやシステム機能の制御を可能にします。

使用する場面

• ファイル管理やアプリ操作など、繰り返し行うワークフローを自動化します。
• キーボードショートカットによるアクションの実行など、カスタム動作のために macOS アプリと連携します。
• Shortcuts だけでは不十分な場合など、複数のアプリを含む複雑な処理をスクリプト化します。
• アプリが直接 API を公開していない場合に、UI 要素の操作などのアクセシビリティタスクを処理します。
• シェルスクリプトや IDE などの環境で、自動化のプロトタイピングをすばやく行います。

主な機能

• osascript を介して AppleScript を実行し、Finder や Safari の操作などを行います。
• JXA（JavaScript for Automation）を実行して macOS API と連携し、最新の JavaScript 構文を使用できます。
• Shortcuts をプログラムで作成して実行し、ファイルの共有などのクイックアクションを行います。
• Automator のワークフローをスクリプトとして使用し、アプリケーションやサービスに変換できます。
• System Events を活用した UI 自動化により、アクセシビリティ API を介してキーボードやマウスの操作をシミュレートします。
• Objective-C／Swift コードへの組み込みに NSAppleScript などの macOS 専用 API を利用できます。

使用パターン

• osascript を使用してコマンドラインからスクリプトを実行します。たとえば、AppleScript コードを直接パイプで渡します。
• JXA モジュールを読み込み、Application('Finder').activate() を実行して、Node.js 環境に JXA を組み込みます。
• Shortcuts を URL として書き出し、open コマンドで呼び出すことで、ほかのツールと連携させます。
• Automator でワークフローを作成してから、.applescript ファイルとして保存し、osascript で実行します。
• アクセシビリティ機能を使用するには、「システム設定」>「プライバシーとセキュリティ」で「アクセシビリティ」を有効にしてから、System Events を使って tell application "System Events" to click button "OK" of window "Main" のように UI 要素を指定します。
• ファイルにアクセスするスクリプトを実行する前に、フルディスクアクセスなど、必要な権限を必ず確認してください。

主なコマンド／API

• osascript CLI：osascript -e 'tell application "Finder" to make new folder at desktop' を使ってフォルダーを作成します。終了コードを確認してエラーを処理してください。
• JXA の例：JavaScript ファイルで const app = Application('Safari'); app.activate(); app.documents[0].url = 'https://example.com'; を使うと、URL を開いて移動できます。
• Shortcuts との連携：shortcuts run "My Shortcut" -i '{"input": "text"}' を使ってショートカットを実行します。パラメーター付きで実行する場合は、入力を JSON として渡します。
• Automator API：tell application "Automator" to run workflow "path/to/workflow" を使って、ワークフローを AppleScript から実行します。
• System Events API：UI 自動化では、osascript -e 'tell application "System Events" to keystroke "a" using {command down}' を使って Command+A をシミュレートします。
• 設定形式：スクリプトをプレーンテキストファイル（.applescript）に保存し、osascript path/to/script.applescript で実行します。JXA では .js ファイルで ES6 モジュールを使用します。

連携に関する注意事項

• osascript の呼び出しをシェルスクリプトでラップして、ほかのツールと連携します。例：$ export APPLESCRIPT_PATH='/path/to/script' を使用し、osascript $APPLESCRIPT_PATH で実行します。
• JXA では、Node.js で OSA モジュールを読み込みます：npm install osa を実行し、const OSA = require('osa'); OSA.runAppleScript('...') を使用します。
• アクセシビリティ機能が必要な場合は、「システム設定」で権限を付与してから、環境変数 $ACCESSIBILITY_ENABLED=1 を設定します。
• 認証情報／キー：保護されたリソースにアクセスするスクリプトでは、$osascript_API_KEY などの環境変数を使用します（ただし、まれです）。多くの場合は、tccutil CLI で macOS の権限を処理します。例：tccutil reset AppleEvents com.example.app を実行してアクセス権をリセットします。
• AppleScript をバンドルにコンパイルするか、Electron アプリで JXA を使用して、より大きなアプリに組み込み、ツール間の連携を実現します。

エラー処理

• osascript の終了コードを確認します。スクリプトが失敗した場合は、osascript -e 'script' 2>&1 でエラーを取得し、stderr を解析して「Execution error: ...」などのメッセージを確認します。
• JXA ではコードを try-catch で囲みます。アプリが見つからないエラーを処理するには、try { Application('Finder').activate(); } catch (e) { console.error(e.message); } のようにします。
• Shortcuts では、shortcuts run "Name" --wait-for-result で実行し、出力に失敗がないか確認します。
• ワークフロー設定で Automator の組み込みログを有効にし、Console アプリでログを確認します。
• 一般的なパターンとして、必要に応じて sudo osascript -e '...' などを使い、常に昇格した権限でスクリプトを実行します。権限エラーが発生した場合は、設定を変更するようユーザーに促します。

具体的な使用例

1. アプリの起動と操作を自動化する：osascript を使って Safari を開き、ページを読み込みます。osascript -e 'tell application "Safari" to open location "https://example.com"' followed by 'tell application "Safari" to activate' を実行します。これは日常的なワークフローに便利です。エラーチェックを追加して拡張できます。
2. Shortcuts で UI を自動化する：ウィンドウのサイズを変更する Shortcut を作成し、CLI から実行します。shortcuts run "Resize Window" -i '{"app": "Finder", "width": 800}' を実行します。JXA と組み合わせて動的な入力を指定することもできます。たとえば、スクリプト内で Application('Shortcuts').run('Resize Window', {input: JSON.stringify({app: 'Finder'})}) のようにします。

グラフの関係

• 関連項目：macos クラスター（直接の親）、applescript スキル（スクリプト作成用のサブスキル）、shortcuts スキル（統合ツール）、automation クラスター（より広範なカテゴリ）。
• 依存関係：macos-os（基本システム）が必要です。UI タスクでは accessibility-api スキルと連携します。