agent-browser-automate

タスクの自動化 — 実行プロトコル

内部テンプレート。 エントリーポイント：agent-browser スキル。

---

禁止事項

NEVER use `fill` when you want to append — it clears first; use `type` to append
NEVER upload a file with `click` then `fill` — use dedicated `upload <sel> <path>` command
NEVER submit a form without showing field values first — judgment gate required

---

認証の設定（優先順位に従って1つ選択）

# Option 1 (recommended): Auth Vault — encrypted, reusable
agent-browser auth login <vault-name>
agent-browser open <url>

# Option 2: Persistent profile (local only)
agent-browser --profile ~/.myapp open <url>

# Option 3: Token injection
agent-browser open <url>
agent-browser storage local set authToken "<token>"
agent-browser reload

# Option 4: HTTP Basic Auth
agent-browser open <url>
agent-browser set credentials <user> <pass>

# Option 5: Bearer header
agent-browser --headers '{"Authorization":"Bearer <token>"}' open <url>

---

フォーム自動化の手順

agent-browser snapshot -i                                    # get refs
agent-browser find label "Email" fill "[email protected]"
agent-browser find label "Password" fill "<password>"
agent-browser find role button click --name "Submit"
agent-browser wait --load networkidle
agent-browser screenshot --full step-complete.png           # evidence

---

ファイル操作

# Upload
agent-browser find label "Attachment" upload ./file.pdf

# Download (triggers on button click, waits for completion)
agent-browser find role button click --name "Export CSV"
agent-browser wait --download ~/report.csv

# Generate PDF
agent-browser pdf ./report.pdf

---

複数タブの操作

agent-browser tab new
agent-browser open <second-url>
agent-browser tab 0       # switch back to first tab (0-based index)
agent-browser tab list    # see all tabs with URLs

---

クリップボード

# Read clipboard
agent-browser clipboard read

# Write to clipboard
agent-browser clipboard write "text to copy"

# Copy element text to clipboard
agent-browser clipboard copy @e3

# Paste clipboard into element
agent-browser clipboard paste @e5

# macOS: paste system clipboard into focused element
agent-browser keyboard inserttext "$(pbpaste)"

---

マウスの細かな操作（キャンバス／カンバン／描画アプリ）

agent-browser mouse move <x> <y>
agent-browser mouse down
agent-browser mouse move <x2> <y2>   # drag
agent-browser mouse up

---

待機パターン

# Page load
agent-browser wait --load networkidle

# Wait for element to appear
agent-browser wait "#success-toast"

# Wait for element to disappear (loading spinner)
agent-browser wait "#spinner" --state hidden

# Wait for URL to change (after form submit / redirect)
agent-browser wait --url "**/dashboard"

# Wait for text to appear
agent-browser wait --text "Upload complete"

# Wait for download to finish
agent-browser wait --download ./report.xlsx

---

復旧パターン

失敗	復旧方法
認証の有効期限切れ	auth login <name> で再認証します
Auth Vault のパスワードが変更された	auth delete <name> を実行してから auth save <name> を実行します
予期しないポップアップ／ダイアログ	dialog status で確認してから、dialog dismiss を実行します
fill が既存の内容を上書きする	追記するには type を使用します
モーダルをスクロールできない	scroll down --selector ".modal-body"

---

判断が必要な場面

次の場合は一時停止します：

• フォームを送信する直前（フィールドの値を表示して、確認を求めます）
• ダウンロード／削除／支払いを実行する直前
• 再試行後も認証に失敗した場合（新しい認証情報が必要です）

---

注意点

間違い	対処法
Auth Vault のパスワードが変更された	auth delete を実行してから、再度 auth save を実行します。既存の設定を直接更新することはできません
fill が意図せず内容を消去する	追記するには type を使用します
ファイルのアップロードに失敗する	click してから fill するのではなく、find label "..." upload <path> を使用します
モーダル内をスクロールできない	scroll down --selector ".modal-body"
ダウンロードが取得されない	ダウンロードボタンをクリックした後、wait --download <path> を使用します
JavaScript ダイアログがデーモン全体をブロックする	Playwright は CDP レベルで割り込みます。eval "window.confirm = () => true" は機能しません（JavaScript レイヤーのオーバーライドでは CDP に到達できません）。確実な対処法は、click がブロックされている間に、2つ目の並行プロセスから dialog accept を呼び出すことだけです
読み取り専用の DOM ノード（ARIA ロールのない <p>、<span>、<div>）がスナップショットに含まれない	snapshot で公開されるのはアクセシビリティツリー（操作可能な要素のみ）です。操作できないノードの内容は、eval "document.querySelector('#id').textContent" または eval "document.querySelector('.class').innerText" で読み取ります