actionbook

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

ユーザーが以下を求める場合に有効にしてください。

• ウェブサイト上で何かを行う（「LinkedInでメッセージを送信して」「Airbnbを予約して」「Googleで検索して」など）
• サイトの操作方法を尋ねる（「ツイートを投稿するには？」「LinkedInで応募するには？」など）
• 特定のサイトでフォームへの入力、ボタンのクリック、移動、検索、絞り込み、閲覧を行う
• ウェブページのスクリーンショットを撮影する、または変更を監視する
• 外部ウェブサイト向けのブラウザベースのAIエージェント、ウェブスクレイパー、E2Eテストを構築する
• 繰り返し発生するウェブ作業（データ入力、フォーム送信、コンテンツ投稿）を自動化する
• 複数のウェブサイトやタブを同時に操作する

仕組み

Actionbookは、最新のウェブ向けのアクションマニュアルを提供します。アクションマニュアルは、ページ上で何をすべきかをエージェントに正確に伝えます。解析も推測も不要です。

これが重要な理由：

• 10倍高速 — アクションマニュアルは、セレクターとページ構造を事前に提供します。手順ごとにスナップショットを取得するループは不要です。
• 高精度 — SPA、ストリーミングコンポーネント、ドロップダウン、日付ピッカー、動的コンテンツを確実に処理します。
• 同時実行可能 — 明示的な --session／--tab を使用するステートレスアーキテクチャです。多数のタブを並行して操作できます。

ワークフロー：

1. ブラウザーセッションを開始します
2. 対象ページに移動します
3. スナップショットを取得して、要素の参照情報を含むページ構造を取得します
4. スナップショットの参照情報を使って自動化します

任意のコマンドの詳しい使い方や使用例を確認するには、actionbook <command> --help を実行してください。

ブラウザー自動化

すべてのブラウザーコマンドはステートレスです。--session と --tab を明示的に渡してください。「現在のタブ」はありません。任意のセッション／タブに対してコマンドを並行して実行できます。

セッションを開始する

actionbook browser start --set-session-id s1

--session と --set-session-id はどちらも取得または作成の動作をします。指定されたIDの実行中セッションがあればそれを再利用し、見つからない場合は新たに作成します。--profile が渡され、そのプロファイルがセッションに紐付けられたプロファイルと一致しない場合、コマンドは SESSION_PROFILE_MISMATCH で失敗します。

基本のワークフロー：スナップショット、操作、待機

actionbook browser goto <url> --session s1 --tab t1
actionbook browser snapshot --session s1 --tab t1          # Get page structure with refs
actionbook browser fill @e3 "text" --session s1 --tab t1   # Use refs from snapshot
actionbook browser click @e7 --session s1 --tab t1
actionbook browser wait navigation --session s1 --tab t1   # Wait for page load

スナップショットの参照情報

snapshot は、すべての要素に参照情報（例：@e3、@e7）を付けます。これらの参照情報を任意のコマンドのセレクターとして使用してください。要素を指定する際に推奨される方法です。

参照情報はスナップショット間で安定しています。要素が同じであれば、参照情報も変わりません。そのため、手順のたびにスナップショットを再取得することなく、複数のコマンドを連続して実行できます。

コマンドのカテゴリ

すべてのコマンドで、使用方法と例を確認するために --help を利用できます。

カテゴリ	主なコマンド	ヘルプ
検索	search	actionbook search --help
マニュアル	manual（エイリアス：man）	actionbook manual --help
セッション	start、close、restart、list-sessions、status	actionbook browser start --help
タブ	new-tab、close-tab、list-tabs	actionbook browser new-tab --help
ナビゲーション	goto、back、forward、reload	actionbook browser goto --help
状態の確認	snapshot、text、html、value、title、url、viewport、attr、attrs、box、styles、describe、state、inspect-point、screenshot、pdf	actionbook browser snapshot --help
操作	click、fill、type、press、select、hover、focus、scroll、drag、upload、eval、mouse-move、cursor-position	actionbook browser click --help
待機	wait element、wait navigation、wait network-idle、wait condition	actionbook browser wait element --help
Cookie	cookies list、cookies get、cookies set、cookies delete、cookies clear	actionbook browser cookies list --help
ストレージ	local-storage list|get|set|delete|clear、session-storage ...	actionbook browser local-storage get --help
ログ	logs console、logs errors	actionbook browser logs console --help
ネットワーク	network requests、network request <id>、network har start、network har stop	actionbook browser network requests --help
クエリ	query one|all|nth|count	actionbook browser query --help
バッチ	batch-new-tab、batch-snapshot、batch-click	actionbook browser batch-new-tab --help
拡張機能	extension status、extension ping、extension install、extension uninstall、extension path	actionbook extension status --help
デーモン	daemon restart	actionbook daemon restart --help

コマンドの全リファレンス：command-reference.md

クラウドプロバイダー

ローカルの Chrome を起動する代わりに、リモートブラウザーでセッションを実行するには、browser start で -p／--provider を使用します。対応プロバイダーは driver、hyperbrowser、browseruse です。それぞれ、シェル環境変数から独自の <PROVIDER>_API_KEY を読み込みます。

export HYPERBROWSER_API_KEY="your-key"
actionbook browser start -p hyperbrowser --session s1
actionbook browser goto "https://example.com" --session s1 --tab t1
actionbook browser snapshot --session s1 --tab t1

モードにかかわらず、すべてのブラウザーコマンドは同じように動作します。browser restart --session <id> を実行すると、session_id を維持したまま、新しいリモートセッションが発行されます。

例：エンドツーエンド

ユーザーのリクエスト：「来週、SFでAirbnbの部屋を探して」

actionbook browser start --set-session-id s1
actionbook browser goto "https://airbnb.com" --session s1 --tab t1
actionbook browser snapshot --session s1 --tab t1
actionbook browser fill @e3 "San Francisco" --session s1 --tab t1
actionbook browser click @e7 --session s1 --tab t1
actionbook browser wait navigation --session s1 --tab t1

eval の入力ソース

browser eval は、相互に排他的な次の3つのソースから式を受け取ります。

• 位置引数：actionbook browser eval "expr" ...
• --file：actionbook browser eval --file script.js ...
• 標準入力：echo 'expr' | actionbook browser eval - ...

eval のエラー処理

browser eval は失敗時に構造化されたエラーコードを返します。メッセージを解析するのではなく、error.code に応じて処理してください。

• EVAL_RUNTIME_ERROR — JS の例外です。再試行する前に式を確認してください。
• EVAL_CROSS_ORIGIN — クロスオリジンの fetch または CSP によるブロックです。リクエストをサーバー側でプロキシしてください。
• EVAL_RESPONSE_NOT_JSON／EVAL_RESPONSE_NOT_OK — error.details.body_head（レスポンス本文の先頭最大256文字）を読み取り、403、チャレンジページ、CORS エラーを区別してください。むやみに再試行しないでください。
• EVAL_TIMEOUT — 式の実行が --timeout を超過しました。処理量を減らすか、タイムアウトを延長してください。
• EVAL_ARGS_CONFLICT — 複数の入力ソースが指定されているか、どれも指定されていません。必ず1つだけ指定してください。
• EVAL_FILE_NOT_FOUND — --file のパスを読み取れません。パスを確認してください。
• EVAL_STDIN_TTY — - が指定されていますが、標準入力がターミナルです。式をパイプで渡してください。
• EVAL_STDIN_EMPTY — 標準入力が空でした。上流のパイプラインを確認してください。

CDP エラー処理

要素の操作、ナビゲーション、CDP 経由の通信を行うブラウザーコマンドは、構造化されたエラーコードを返します。error.code に応じて処理を分岐してください。

• CDP_NODE_NOT_FOUND — DOM ノードが古くなっています。snapshot を呼び出して参照を更新してから、再試行してください。
• CDP_NOT_INTERACTABLE — 要素は存在しますが、操作できません。表示範囲にスクロールする、表示されるまで待つ、またはオーバーレイを閉じてください。
• CDP_NAV_TIMEOUT — ナビゲーションがタイムアウトしました。--timeout を増やすか、URL に到達できることを確認してください。再試行可能です。
• CDP_TARGET_CLOSED — コマンドの実行中にタブが移動したか、セッションが終了しました。新しいセッションを開始してください。再試行可能です。
• CDP_PROTOCOL_ERROR — CDP の応答が不正な形式です。details.reason と details.cdp_code を確認してください。
• CDP_GENERIC — 分類されていない CDP エラーです（通信または解析）。固有の対処方法はありません。

CDP_NAV_TIMEOUT と CDP_TARGET_CLOSED は再試行可能です（error.retryable == true）。ほかの CDP コードは、再試行の前に呼び出し元での対処が必要です。error.code が CDP_* コードの場合、取得可能であれば error.details に reason と cdp_code が含まれます。

セレクター

セレクターは、以前の知識や記憶ではなく、actionbook browser snapshot から取得してください。必ず最初に snapshot を実行して現在の参照を取得してから、その参照を使ってページを操作してください。

ログインページの処理

ログイン／認証の壁（サインインページ、パスワードプロンプト、MFA／OTP、CAPTCHA、アカウント選択画面）に遭遇した場合：

1. 自動化を一時停止し、現在のブラウザーセッションを開いたままにします（同じタブ／プロファイル／Cookie を使用）。
2. 同じブラウザーウィンドウで、ユーザーに手動でログインを完了するよう依頼します。
3. ユーザーがログイン完了を確認したら、同じセッションで続行します。
4. ログイン後のページが異なる場合は、続行する前に actionbook browser snapshot を実行して、新しいページ構造を取得します。

ログインページが表示されたという理由だけで、別のツールに切り替えないでください。

セッションのクリーンアップ

browser close は冪等です。不明なセッション、またはすでに閉じられたセッションを閉じると、致命的なエラーではなく、meta.warnings に警告が含まれた ok: true が返されます。セッション ID の入力ミスや、すでに終了したセッションは、もはやエラー条件ではありません。

• クリーンアップ中は、セッションの存在を事前に確認せずに browser close を無条件で呼び出しても安全です。
• meta.warnings を読み取り、新たに閉じた場合と、すでに存在しないセッションの場合を区別してください。ok: true の応答に含まれる警告を、セッションがまだ有効であることを示すものとして扱わないでください。
• 同じセッションに対する別の close がすでに進行中の場合、コマンドは SESSION_CLOSING（致命的）を返します。

HAR 記録

network har start は --max-entries N を受け付け、リングバッファの上限を設定します（デフォルト：10000）。har stop がドロップされたエントリーを検出した場合（data.dropped > 0）、エンベロープに meta.truncated = true と meta.warnings 内の HAR_TRUNCATED 警告が含まれます。設定された上限を確認するには data.max_entries を読み取ってください。トレース全体を保持するには、--max-entries を増やすか、より早く記録を停止してください。

参照

参照	説明
command-reference.md	すべてのフラグとオプションを含む、コマンドの完全なリファレンス
authentication.md	ログインフロー、OAuth、2FA の処理、セッションの永続化