@youtyan/browser-pilot 0.7.1

package/skills/bp-testing/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: bp-testing
+description: Use when testing web applications interactively using browser-pilot MCP tools. Triggers on "テスト", "動作確認", "E2Eテスト", "verify", "check functionality", "test scenario", "ブラウザテスト", "画面確認".
+---
+
+# Browser Testing — エージェント駆動Webアプリテスト
+
+webapp-testingの代替。Playwrightスクリプトを書く代わりに、browser-pilot MCPツールで直接テストする。
+
+## Authoritative Test Spec
+
+`apps/test-sandbox/CHECKLIST.md` が全ツールのE2Eテスト仕様書。ツール追加・変更時はそちらを参照。
+
+## Decision Tree
+
+```dot
+digraph {
+  "テスト対象?" [shape=diamond];
+  "サーバー起動済み?" [shape=diamond];
+  "browser_tab create" [shape=box];
+  "browser_tab list+connect" [shape=box];
+  "シナリオ実行" [shape=box];
+  "結果判定" [shape=box];
+
+  "テスト対象?" -> "サーバー起動済み?" [label="URL既知"];
+  "サーバー起動済み?" -> "browser_tab create" [label="yes"];
+  "サーバー起動済み?" -> "サーバー起動 → tab create" [label="no"];
+  "browser_tab create" -> "シナリオ実行";
+  "テスト対象?" -> "browser_tab list+connect" [label="既にタブで開いてる"];
+  "browser_tab list+connect" -> "シナリオ実行";
+  "シナリオ実行" -> "結果判定";
+}
+```
+
+## Tool Quick Reference
+
+### Navigation & Page Content
+| Tool | Purpose |
+|------|---------|
+| `browser_tab` | list / connect / create / close タブ管理 |
+| `browser_get_page` | ページ取得（html / markdown / text / accessibility） |
+| `browser_navigation` | back / forward / reload |
+| `browser_screenshot` | スクリーンショット |
+| `browser_pdf` | ページをPDFに保存 |
+
+### Interaction
+| Tool | Purpose |
+|------|---------|
+| `browser_click` | テキスト or セレクタでクリック（all, waitSelector対応） |
+| `browser_action` | hover / dblclick / contextmenu / drag / focus / blur + 座標モード |
+| `browser_set_values` | input / textarea / select / contenteditable に値設定（fields配列で一括） |
+| `browser_select_option` | native select + カスタムドロップダウン選択 |
+| `browser_keyboard` | キー入力（modifier, repeat対応） |
+| `browser_scroll` | direction / scrollTo / intoView / container scroll |
+| `browser_handle_dialog` | alert / confirm / prompt 制御 |
+| `browser_paste_file` | ドロップゾーンにファイルペースト |
+| `browser_upload_file` | input[type=file] にファイルアップロード |
+| `browser_batch` | 複数アクションを1回のラウンドトリップで実行 |
+
+### Query & Inspection
+| Tool | Purpose |
+|------|---------|
+| `browser_find_elements` | tag / text / role / attribute / nearText で要素検索 |
+| `browser_get_attributes` | 要素の属性値取得 |
+| `browser_get_bounds` | 要素の座標・サイズ取得 |
+| `browser_wait_for` | appear / disappear / count_change 待機 |
+| `browser_execute_javascript` | 任意JS実行（BP_ALLOW_EXECUTE_JS=1 必須） |
+| `browser_extract` | セマンティック構造化データ抽出（決定的アルゴリズム、LLM不使用） |
+
+### Debugging & Diagnostics
+| Tool | Purpose |
+|------|---------|
+| `browser_console` | コンソールログ取得（level / textPattern フィルタ） |
+| `browser_network` | ネットワークリクエスト取得（method / status / URL フィルタ） |
+| `browser_performance` | メトリクス + diagnose_layout / diagnose_network / diagnose_runtime / diagnose_accessibility / diagnose_memory |
+| `browser_css_inspect` | 要素のcomputed style + 競合CSSルール分析 |
+| `browser_diagnose_interaction` | クリック/入力が効かない原因を診断（overlay, pointer-events, disabled等） |
+| `browser_health` | ページ全体のヘルスチェック（console errors, failed requests, CWV概要） |
+| `browser_storage` | localStorage / sessionStorage の読み書き |
+| `browser_cookie` | Cookie の取得・設定・削除 |
+
+### Annotation & Recording
+| Tool | Purpose |
+|------|---------|
+| `browser_annotate` | rect / arrow / text / mosaic / badge アノテーション |
+| `browser_record` | 操作をWebM動画に録画 |
+
+### Assertion
+| Tool | Purpose |
+|------|---------|
+| `browser_assert` | プログラマティックなページアサーション（テキスト存在、要素数、属性値等） |
+
+## テストシナリオの実行パターン
+
+### 1. Navigate & Assert
+
+```
+browser_get_page { url: "http://localhost:3000", mode: "markdown" }
+# → Markdownに "ダッシュボード" が含まれることを確認
+```
+
+### 2. Interact & Verify
+
+```
+browser_set_values { selector: "#email", value: "test@example.com" }
+browser_set_values { selector: "#password", value: "password123" }
+browser_click { text: "ログイン" }
+browser_wait_for { selector: ".dashboard", condition: "appear", timeout: 10000 }
+browser_get_page { scope: ".dashboard", mode: "markdown" }
+# → "ようこそ" が含まれることを確認
+```
+
+### 3. Programmatic Assertion
+
+```
+browser_assert { selector: ".dashboard", condition: "contains_text", text: "ようこそ" }
+# → pass/fail を自動判定。condition: exists/visible/contains_text/count
+```
+
+### 4. Visual Verification
+
+```
+browser_screenshot {}
+# → レイアウト崩れがないことを目視確認
+```
+
+### 5. Batch Execution (ラウンドトリップ削減)
+
+```
+browser_batch { actions: [
+  { type: "setValue", selector: "#email", value: "test@example.com" },
+  { type: "setValue", selector: "#password", value: "password123" },
+  { type: "click", text: "ログイン" }
+] }
+```
+
+### 6. Diagnostic Flow
+
+```
+# ページ全体のヘルスチェック
+browser_health {}
+
+# 特定要素のインタラクション問題を診断
+browser_diagnose_interaction { selector: "#broken-button" }
+
+# CSS問題の調査
+browser_css_inspect { selector: "#misaligned-element" }
+
+# レイアウト診断
+browser_performance { action: "diagnose_layout", selector: "#overflowing-child" }
+```
+
+## アサーション方法
+
+| 確認内容 | ツール | 判定方法 |
+|---------|--------|---------|
+| テキスト存在 | `browser_assert` | condition: "contains_text" で自動判定 |
+| テキスト存在（手動） | `browser_get_page` | 返却Markdownに文字列が含まれるか |
+| 要素存在 | `browser_find_elements` | マッチ件数 > 0 |
+| 要素非存在 | `browser_find_elements` | マッチ件数 === 0 |
+| 要素出現待ち | `browser_wait_for(condition: "appear")` | タイムアウトしなければOK |
+| 要素消滅待ち | `browser_wait_for(condition: "disappear")` | タイムアウトしなければOK |
+| 属性値 | `browser_get_attributes` | 期待値と一致 |
+| CSS状態 | `browser_css_inspect` | computed style が期待値と一致 |
+| レイアウト | `browser_screenshot` | 目視確認 |
+| ページ健全性 | `browser_health` | console errors / failed requests / CWV |
+
+## テスト結果の報告
+
+各シナリオの結果を以下のフォーマットで報告:
+
+```
+## テスト結果
+
+| # | シナリオ | 結果 | 備考 |
+|---|---------|------|------|
+| 1 | ログインフォーム表示 | PASS | |
+| 2 | 正常ログイン | PASS | |
+| 3 | 不正パスワード | FAIL | エラーメッセージが表示されない |
+```
+
+## Common Mistakes
+
+| 間違い | 正しい対応 |
+|--------|-----------|
+| スクショだけでテスト完了 | `browser_assert` or テキスト取得で内容を確認してからスクショ |
+| SPA操作後すぐにget_page | `browser_wait_for` で遷移完了を待つ |
+| エラーケースをテストしない | 正常系の後に異常系も必ず実行 |
+| 前のテストの状態に依存 | 各シナリオ開始時にページリロード or 初期状態に戻す |
+| 個別ツール呼び出しが多すぎる | `browser_batch` でラウンドトリップ削減（MCP往復は約2秒） |
+| クリックが効かない原因不明 | `browser_diagnose_interaction` で原因特定 |
+| レイアウト崩れの原因不明 | `browser_css_inspect` + `browser_performance(action: "diagnose_layout")` |
+| ページ全体の問題を個別に調査 | まず `browser_health` で全体像を把握 |

package/skills/bp-usage/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: bp-usage
+description: Use when interacting with websites, web apps, browsers, or anything involving URLs, pages, forms, buttons, screenshots, scraping, testing web UI, or automating browser tasks. Triggers on "ブラウザ", "サイト", "ページ", "URL", "Web", "フォーム", "クリック", "スクリーンショット".
+---
+
+# Browser Pilot — ブラウザ自動化MCPツール活用ガイド
+
+## Overview
+
+browser-pilot MCPツールを**積極的に**使ってWebサイトを操作する。ファイルを読むようにWebページを読み、CLIコマンドを叩くようにブラウザを操作する。「手動で確認して」ではなく、自分でやる。
+
+## 基本ワークフロー
+
+```dot
+digraph workflow {
+  rankdir=TB;
+  "タブ接続" [shape=box];
+  "ページ取得" [shape=box];
+  "要素探索" [shape=box];
+  "操作実行" [shape=box];
+  "結果確認" [shape=box];
+  "追加操作?" [shape=diamond];
+
+  "タブ接続" -> "ページ取得";
+  "ページ取得" -> "要素探索";
+  "要素探索" -> "操作実行";
+  "操作実行" -> "結果確認";
+  "結果確認" -> "追加操作?";
+  "追加操作?" -> "要素探索" [label="yes"];
+}
+```
+
+### Phase 1: 接続
+
+```
+browser_tab(action: "list")                    # タブ一覧取得
+browser_tab(action: "connect", tabId: 123)     # 操作対象を固定
+# または
+browser_tab(action: "create", url: "https://...")  # 新規タブ作成+自動接続
+```
+
+### Phase 2: ページ理解
+
+```
+browser_get_page(mode: "compact")              # 低トークンでページ概要+操作可能要素（推奨）
+browser_get_page(mode: "smart")                # 本文抽出（広告・ナビ除去）、長文記事向け
+browser_get_page(scope: "main", mode: "markdown") # メインコンテンツのみmarkdown
+browser_screenshot()                             # レイアウト・CSS確認
+```
+
+### Phase 3: 要素探索 → 操作
+
+```
+browser_find_elements(text: "送信", tag: "button")  # 要素を探す（デフォルト: accessibility engine）
+browser_click(text: "送信")                          # クリック
+browser_wait_for(selector: ".success", condition: "appear")  # 結果待ち
+```
+
+## ツール早見表
+
+| 目的 | ツール | 使い分け |
+|------|--------|----------|
+| ページ取得 | `browser_get_page` | compact（推奨）: 低トークン概要+操作要素。smart: 本文抽出。navigate: 操作要素のみ。markdown/text/html/accessibility/tables/forms/links/metadata/items |
+| ナビゲーション | `browser_get_page(url:)` | URL指定でページ遷移+取得を一発 |
+| 戻る/進む/リロード | `browser_navigation` | action: back/forward/reload |
+| クリック | `browser_click` | text/selector/ref/backendNodeId/nearTextで要素特定。cdpClick: CDP信頼イベント。nth: N番目。snapshotMode: クリック後スナップショット自動取得 |
+| 一括クリック | `browser_click(all: true)` | 全マッチ要素を順にクリック |
+| バッチ操作 | `browser_batch` | click/setValue/keyboard/assert/wait/selectOption/scrollを1回で連続実行。フォーム入力の高速化に最適 |
+| マウス操作（セレクタ） | `browser_action` | hover, dblclick, contextmenu, drag等。通常クリックはbrowser_click |
+| マウス操作（座標CDP） | `browser_action(x, y)` | Canvas/SVG/地図等の非DOM要素を座標で操作。click, hover, drag対応 |
+| フォーム入力 | `browser_set_values` | fields配列で複数フィールド一括入力。React互換イベント発火 |
+| ドロップダウン選択 | `browser_select_option` | ネイティブ`<select>`+カスタムドロップダウン対応 |
+| キーボード | `browser_keyboard` | Enter送信, Escapeモーダル閉じ, Tab移動 |
+| 要素検索 | `browser_find_elements` | engine: accessibility（デフォルト、AXツリー、backendNodeId付き）/ dom（CSS/テキスト検索）。テキスト/タグ/属性/ロール/ラベル近傍で検索 |
+| 属性取得 | `browser_get_attributes` | href, src, data-*等の属性値を取得 |
+| 待機 | `browser_wait_for` | 要素の出現/消滅/数量変化を待つ |
+| アサーション | `browser_assert` | exists/visible/contains_text/countを即時チェック。not反転対応。wait_forと違いポーリングなし |
+| 構造化データ抽出 | `browser_extract` | root+fieldsでスキーマ定義→構造化JSON抽出。semantic型（title/price/url等）で自動解決。root:"auto"で繰り返しパターン自動検出 |
+| スクロール | `browser_scroll` | 方向指定, top/bottom, 要素までスクロール |
+| スクショ | `browser_screenshot` | 視覚確認。レイアウト・CSS・操作結果の確認 |
+| PDF保存 | `browser_pdf` | ページをPDFとして保存。savePath必須。landscape/scale/pageRanges対応 |
+| 録画 | `browser_record` | action: start/stop/status。タブ操作をWebM動画で録画。~/Downloadsに保存。ffmpeg必須 |
+| JS実行 | `browser_execute_javascript` | 他ツールで不可能な操作のエスケープハッチ |
+| 座標取得 | `browser_get_bounds` | セレクタで要素の座標・サイズを取得 |
+| アノテーション | `browser_annotate` | 要素にラベル・番号付きアノテーション描画。action: add/clear |
+| ダイアログ処理 | `browser_handle_dialog` | alert/confirm/promptダイアログの応答 |
+| ファイル貼付 | `browser_paste_file` | 画像/PDF等をクリップボード経由で貼付 |
+| ファイルアップロード | `browser_upload_file` | `<input type="file">`にCDP経由でファイル設定。ネイティブファイル入力用 |
+| コンソール | `browser_console` | console.log/warn/error等を取得。level/textPatternでフィルタ可 |
+| ネットワーク | `browser_network` | HTTPリクエスト一覧取得。urlPattern/method/statusCodeでフィルタ可。requestId指定でheaders/body/cookies/timing詳細取得 |
+| ストレージ | `browser_storage` | cookies（HttpOnly含む）、localStorage、sessionStorage読み取り。namePatternフィルタ対応 |
+| Cookie操作 | `browser_cookie` | action: set/delete。Cookie作成・削除。url+name必須。HttpOnly/SameSite/Secure等の属性指定対応 |
+| CSS検査 | `browser_css_inspect` | 要素のCSS詳細調査。inline style/matched rules/computed style/box model/ancestor chain。レイアウト問題のデバッグに |
+| パフォーマンス | `browser_performance` | DOMノード数、JSヒープ、レイアウト時間等。action: metrics/start_trace/stop_trace/diagnose_load/diagnose_layout |
+| 操作性診断 | `browser_diagnose_interaction` | 要素がクリック/入力可能か事前診断。not_found/invisible/disabled/coveredの原因特定。操作失敗の調査に |
+| ヘルスチェック | `browser_health` | bridge/tab/lockの接続状態を1回で確認。ツール失敗時の初手診断 |
+| タブ管理 | `browser_tab` | action: list/connect/create/close |
+| 画像生成 | `gemini_generate_image` | Gemini Web UIで画像生成 |
+
+## 頻出パターン
+
+### SPA操作（React/Next.js等）
+
+```
+browser_click(text: "次へ")
+browser_wait_for(selector: ".step-2", condition: "appear")  # 画面遷移待ち
+browser_get_page(scope: ".step-2")                           # 新しい内容を取得
+```
+
+**sleepは絶対使わない。** 必ず`browser_wait_for`で条件待ちする。
+
+### ドロップダウン（React Select等）
+
+`browser_select_option`で統一的に選択可能（ネイティブ`<select>`もカスタムも対応）：
+
+```
+browser_select_option(selector: "#category", value: "tech")           # ネイティブselect
+browser_select_option(selector: ".react-select__control", text: "選択肢")  # カスタム
+```
+
+### フォーム送信
+
+```
+browser_set_values(fields: [
+  {selector: "#email", value: "user@example.com"},
+  {selector: "#password", value: "pass"}
+])
+browser_click(text: "ログイン")
+browser_wait_for(selector: ".dashboard", condition: "appear", timeout: 15000)
+```
+
+### フォーム一括操作（browser_batch）
+
+```
+browser_batch(actions: [
+  {type: "setValue", selector: "#email", value: "user@example.com"},
+  {type: "setValue", selector: "#password", value: "pass"},
+  {type: "click", text: "ログイン"},
+  {type: "wait", selector: ".dashboard", condition: "appear", timeout: 15000}
+], snapshotMode: "compact")
+```
+
+### ページ内検索
+
+```
+browser_find_elements(text: "エラー", tag: "div", visibleOnly: true)
+browser_find_elements(role: "button", nearText: "保存")
+browser_find_elements(attribute: "data-testid", attributeValue: "submit-btn")
+```
+
+### 構造化データ抽出
+
+```
+browser_extract(root: ".product", fields: {
+  title: {semantic: "title"},
+  price: {semantic: "price"},
+  url: {semantic: "url"}
+})
+browser_extract()                                # 全自動: パターン検出+セマンティック推論
+browser_extract(root: "auto")                    # 繰り返し要素を自動検出
+```
+
+### ファイルアップロード
+
+```
+browser_upload_file(filePath: "/path/to/doc.pdf")              # input[type="file"]に直接設定
+browser_paste_file(filePath: "/path/to/image.png", selector: ".upload-area")  # クリップボード経由で貼付
+browser_wait_for(selector: ".preview img", condition: "appear")  # アップロード確認
+```
+
+### デバッグ: 要素が見つからない時
+
+```
+browser_get_page(mode: "html", scope: "body")       # 生HTMLを確認
+browser_find_elements(tag: "button", limit: 50)      # ボタンを全列挙
+browser_diagnose_interaction(selector: ".target")     # 操作可否を事前診断
+browser_annotate(annotations: [{selector: ".target", label: "これ"}])  # 視覚的に確認
+browser_screenshot()                                  # 画面状態を確認
+```
+
+### デバッグ: エラー・パフォーマンス調査
+
+```
+browser_console(level: "error")                      # コンソールエラーを確認
+browser_network(statusCode: 500)                     # 500エラーのリクエストを抽出
+browser_network(urlPattern: "api/", method: "POST")  # API呼び出しを確認
+browser_network(requestId: "12345.6")                # リクエスト詳細（headers/body/cookies/timing）
+browser_storage(type: "cookies")                     # 全cookies取得（HttpOnly含む）
+browser_storage(type: "cookies", namePattern: "auth") # authトークン検索
+browser_storage(type: "localStorage")                # localStorage全エントリ取得
+browser_performance()                                           # DOMノード数、JSヒープ等を確認
+browser_performance(action: "diagnose_load")                    # ページ読み込み診断（LCP/CLS/INP原因特定）
+browser_performance(action: "diagnose_layout", selector: ".btn") # CSS レイアウト診断（overflow/stacking/flex等）
+browser_css_inspect(selector: ".misaligned-btn")                # CSS詳細調査（inline/matched rules/computed/box model/ancestor chain）
+browser_health()                                                # 接続状態の確認（ツール失敗時の初手）
+```
+
+### 操作結果の検証
+
+```
+browser_assert(selector: ".success", condition: "visible")            # 成功メッセージが表示されているか
+browser_assert(selector: ".error", condition: "exists", not: true)    # エラーが存在しないことを確認
+browser_assert(selector: ".item", condition: "count", expectedCount: 5) # アイテム数が正しいか
+```
+
+## Common Mistakes
+
+| 間違い | 正しい対応 |
+|--------|-----------|
+| `sleep`で待機 | `browser_wait_for`で条件待ち |
+| ドロップダウンに`browser_set_values` | `browser_select_option`を使う |
+| 操作後に確認しない | `browser_wait_for`または`browser_get_page`で結果確認 |
+| 接続せずに操作 | まず`browser_tab(action: "list")` → `browser_tab(action: "connect")` |
+| スクショだけで判断 | `browser_get_page(mode: "compact")`でテキスト取得が基本 |
+| `browser_click`後すぐ`browser_get_page` | SPAはクリック後に`browser_wait_for`を挟む。または`snapshotMode`で自動取得 |
+| Extension再起動後に操作 | `browser_tab(action: "list")` → `browser_tab(action: "connect")`で再接続 |
+| `browser_execute_javascript`を多用 | 専用ツールがあるならそちらを使う。JSは最終手段 |
+| フォーム入力を1つずつ呼ぶ | `browser_batch`で一括実行（ラウンドトリップ削減） |
+| ツール失敗時にリトライ | `browser_health`で接続状態を確認してから対処 |