OpenCLI Browser — ブラウザ自動化ツール

CLI 経由で Chrome を段階的に制御します。既存ログインセッションを再利用 — パスワード不要です。

前提条件

opencli doctor    # 拡張機能 + デーモン接続を確認

必須: Chrome 実行中 + OpenCLI Browser Bridge 拡張機能インストール済み

重要ルール

1. 必ず state を使ってページを検査する、screenshot は使わない — state は [N] 要素インデックス付きの構造化 DOM を返し、即座で 0 トークンコストです。screenshot はビジョン処理が必要で遅いです。ユーザーが明示的にビジュアルの保存をリクエストした場合のみ screenshot を使用してください。
2. 必ず click/type/select を使用して対話する、eval でクリックやタイプをしない — eval "el.click()" は scrollIntoView と CDP クリックパイプラインをバイパスし、画面外要素での失敗を引き起こします。state で [N] インデックスを見つけてから click <N> を使用してください。
3. スクリーンショットではなく get value で入力を検証 — type 後、get value <index> を実行して確認してください。
4. ページが変わるたびに state を実行 — open、click（リンク上）、scroll 後、常に state を実行して新しい要素とそのインデックスを確認してください。インデックスを推測しないでください。
5. && で積極的にコマンドをチェーンする — open + state、複数の type 呼び出し、type + get value を単一の && チェーンに組み合わせてください。各ツール呼び出しにはオーバーヘッドがあり、チェーンはそれを減らします。
6. eval は読み取り専用 — eval は データ抽出専用 (JSON.stringify(...)) です。クリック、タイプ、ナビゲーション には使わないでください。常に IIFE でラップして変数競合を回避: eval "(function(){ const x = ...; return JSON.stringify(x); })()".
7. 総ツール呼び出しを最小化 — 実行前にシーケンスを計画してください。良いタスク完了は 15-20 ではなく 3-5 ツール呼び出しです。open + state を 1 呼び出しに組み合わせてください。type + type + click を 1 呼び出しに組み合わせてください。新しいインデックスを発見する必要があるときのみ別に state を実行してください。
8. API 発見には network を優先 — ほとんどのサイトは JSON API を持っています。API ベースのアダプターは DOM スクレイピングより信頼性があります。

コマンドコストガイド

コスト	コマンド	いつ使うか
無料で即座	state, get *, eval, network, scroll, keys	デフォルト — これらを使用
無料だがページ変更	open, click, type, select, back	対話 — 後で state を実行
高コスト（ビジョントークン）	screenshot	ユーザーが保存画像を必要とするときのみ

アクションチェーンルール

コマンドは && でチェーンできます。ブラウザはデーモン経由で永続するため、チェーンは安全です。

可能な限り常にチェーンする — ツール呼び出しが少ない = 完了が速い:

# 良い: open + inspect を 1 呼び出しで (1 ラウンドトリップ節約)
opencli browser open https://example.com && opencli browser state

# 良い: フォーム入力を 1 呼び出しで (2 ラウンドトリップ節約)
opencli browser type 3 "hello" && opencli browser type 4 "world" && opencli browser click 7

# 良い: type + verify を 1 呼び出しで
opencli browser type 5 "test@example.com" && opencli browser get value 5

# 良い: click + wait + state を 1 呼び出しで (ページ変更クリック用)
opencli browser click 12 && opencli browser wait time 1 && opencli browser state

# 悪い: 各アクションを別呼び出しで (無駄)
opencli browser type 3 "hello"    # これをするな
opencli browser type 4 "world"    # 3 つすべてを
opencli browser click 7            # 一緒にチェーンできるのに

ページ変更 — チェーン内で常に最後に配置 (その後のコマンドは古いインデックスを見る):

• open <url>, back, click <ナビゲートするリンク/ボタン>

ルール: インデックスが既にわかっている場合はチェーンする。インデックスを発見する必要がある場合は state を別に実行してください。

コアワークフロー

1. ナビゲート: opencli browser open <url>
2. 検査: opencli browser state → [N] インデックス付きの要素
3. 対話: インデックスを使用 — click, type, select, keys
4. 待機（必要な場合）: opencli browser wait selector ".loaded" または wait text "Success"
5. 検証: opencli browser state または opencli browser get value <N>
6. 繰り返す: ブラウザはコマンド間で開いたままです
7. 保存: ~/.opencli/clis/<site>/<command>.ts に TS アダプターを書く

コマンド

ナビゲーション

opencli browser open <url>              # URL を開く (ページ変更)
opencli browser back                    # 戻る (ページ変更)
opencli browser scroll down             # スクロール (up/down, --amount N)
opencli browser scroll up --amount 1000

検査（無料で即座）

opencli browser state                   # [N] インデックス付き構造化 DOM — プライマリツール
opencli browser screenshot [path.png]   # ビジュアルをファイルに保存 — ユーザー成果物のみ

Get（無料で即座）

opencli browser get title               # ページタイトル
opencli browser get url                 # 現在の URL
opencli browser get text <index>        # 要素テキストコンテンツ
opencli browser get value <index>       # Input/textarea 値 (type 後の検証に使用)
opencli browser get html                # ページ HTML 全体
opencli browser get html --selector "h1" # スコープ付き HTML
opencli browser get attributes <index>  # 要素属性

対話

opencli browser click <index>           # 要素 [N] をクリック
opencli browser type <index> "text"     # 要素 [N] にタイプ
opencli browser select <index> "option" # ドロップダウン選択
opencli browser keys "Enter"            # キー押下 (Enter, Escape, Tab, Control+a)

待機

3 つのバリアント — 状況に合わせて正しいものを使う:

opencli browser wait time 3                       # N 秒待機 (固定遅延)
opencli browser wait selector ".loaded"            # 要素が DOM に表示されるまで待機
opencli browser wait selector ".spinner" --timeout 5000  # タイムアウト付き (デフォルト 30s)
opencli browser wait text "Success"                # テキストがページに表示されるまで待機

待機する時: SPA 上の open 後、非同期読み込みをトリガーする click 後、動的レンダリングコンテンツ上の eval 前。

抽出（無料で即座、読み取り専用）

eval は データ読み取りのみに使用。クリック、タイプ、ナビゲーション には使用しないでください。

opencli browser eval "document.title"
opencli browser eval "JSON.stringify([...document.querySelectorAll('h2')].map(e => e.textContent))"

# 重要: 複雑なロジックを IIFE でラップして "already declared" エラーを回避
opencli browser eval "(function(){ const items = [...document.querySelectorAll('.item')]; return JSON.stringify(items.map(e => e.textContent)); })()"

セレクター安全性: 常にフォールバックセレクターを使用 — querySelector はミス時に null を返す:

# 悪い: セレクターがミスするとクラッシュ
opencli browser eval "document.querySelector('.title').textContent"

# 良い: || または ?. でフォールバック
opencli browser eval "(document.querySelector('.title') || document.querySelector('h1') || {textContent:''}).textContent"
opencli browser eval "document.querySelector('.title')?.textContent ?? 'not found'"

ネットワーク（API 発見）

opencli browser network                  # キャプチャされた API リクエストを表示 (open 以降自動キャプチャ)
opencli browser network --detail 3       # リクエスト #3 の完全応答本文を表示
opencli browser network --all            # 静的リソースを含める

堆積化（CLI として保存）

opencli browser init hn/top              # ~/.opencli/clis/hn/top.ts にアダプタースキャフォルド生成
opencli browser verify hn/top            # アダプターをテスト (limit arg が定義されている場合のみ --limit 3 を追加)

• init はアクティブなブラウザセッションからドメインを自動検出 (指定不要)
• init はファイルを作成し、現在のページから site, name, domain, columns を自動入力
• verify はアダプターをエンドツーエンドで実行して出力を表示; limit arg がアダプターに存在しない場合、--limit 3 は渡されません

セッション

opencli browser close                   # 自動化ウィンドウを閉じる

例: HN ストーリーを抽出

opencli browser open https://news.ycombinator.com
opencli browser state                   # [1] a "Story 1", [2] a "Story 2"... を確認
opencli browser eval "JSON.stringify([...document.querySelectorAll('.titleline a')].slice(0,5).map(a => ({title: a.textContent, url: a.href})))"
opencli browser close

例: フォームを入力

opencli browser open https://httpbin.org/forms/post
opencli browser state                   # [3] input "Customer Name", [4] input "Telephone" を確認
opencli browser type 3 "OpenCLI" && opencli browser type 4 "555-0100"
opencli browser get value 3             # 検証: "OpenCLI"
opencli browser close

再利用可能な CLI として保存 — 完全なワークフロー

ステップバイステップ堆積化フロー:

# 1. ウェブサイトを探索
opencli browser open https://news.ycombinator.com
opencli browser state                          # DOM 構造を理解

# 2. API を発見 (高品質アダプターの重要ステップ)
opencli browser eval "fetch('/api/...').then(r=>r.json())"   # API 呼び出しをトリガー
opencli browser network                        # キャプチャされた API リクエストを確認
opencli browser network --detail 0             # 応答本文を検査

# 3. スキャフォルドを生成
opencli browser init hn/top                    # ~/.opencli/clis/hn/top.ts を作成

# 4. アダプターを編集 (func ロジックを入力)
# - API が見つかった場合: fetch() を直接使用 (Strategy.PUBLIC または COOKIE)
# - API がない場合: page.evaluate() を DOM 抽出に使用 (Strategy.UI)

# 5. 検証
opencli browser verify hn/top                  # アダプターを実行して出力を表示

# 6. 検証が失敗したら編集して再試行
# 7. 完了時に閉じる
opencli browser close

アダプター例:

// ~/.opencli/clis/hn/top.ts
import { cli, Strategy } from '@jackwener/opencli/registry';

cli({
  site: 'hn',
  name: 'top',
  description: 'Top Hacker News stories',
  domain: 'news.ycombinator.com',
  strategy: Strategy.PUBLIC,
  browser: false,
  args: [{ name: 'limit', type: 'int', default: 5 }],
  columns: ['rank', 'title', 'score', 'url'],
  func: async (_page, kwargs) => {
    const limit = Math.min(Math.max(1, kwargs.limit ?? 5), 50);
    const resp = await fetch('https://hacker-news.firebaseio.com/v0/topstories.json');
    const ids = await resp.json();
    return Promise.all(
      ids.slice(0, limit).map(async (id: number, i: number) => {
        const item = await (await fetch(`https://hacker-news.firebaseio.com/v0/item/${id}.json`)).json();
        return { rank: i + 1, title: item.title, score: item.score, url: item.url ?? '' };
      })
    );
  },
});

~/.opencli/clis/<site>/<command>.ts に保存 → すぐに opencli <site> <command> として利用可能。

Strategy ガイド

Strategy	いつ	browser:
Strategy.PUBLIC	パブリック API、認証なし	false
Strategy.COOKIE	ログインクッキーが必要	true
Strategy.UI	直接 DOM 対話	true

常に API を UI より優先 — ブラウジング中に API を発見した場合、fetch() を直接使用してください。

Tips

1. 常に state を最初に — 要素インデックスを推測しない、常に検査する
2. セッションは永続 — ブラウザはコマンド間で開いたまま、再度開く必要なし
3. データ抽出に eval を使用 — eval "JSON.stringify(...)" は複数の get 呼び出しより速い
4. API を見つけるために network を使用 — JSON API は DOM スクレイピングより信頼性がある
5. エイリアス: opencli op は opencli browser の短縮形

一般的な落とし穴

1. form.submit() は自動化で失敗 — フォームを送信するのに form.submit() や eval を使わない。代わりに検索 URL に直接ナビゲート:

   # 悪い: form.submit() はしばしば静かに失敗
   opencli browser eval "document.querySelector('form').submit()"
   # 良い: URL を構築してナビゲート
   opencli browser open "https://github.com/search?q=opencli&type=repositories"
   

2. GitHub DOM は頻繁に変更 — 利用可能な場合は data-testid 属性を優先; クラス名やタグ構造より安定

3. SPA ページは抽出前に wait が必要 — SPA 上の open または click 後、DOM はすぐに準備ができません。常に wait selector または wait text を eval の前に実行

4. クリック前に state を使用 — opencli browser state を実行して利用可能なインタラクティブ要素とそのインデックスを検査。メモリからインデックスを推測しない

5. evaluate はブラウザコンテキストで実行 — アダプター内の page.evaluate() はブラウザ内で実行. Node.js API (fs, path, process) は利用不可. ネットワーク呼び出しに fetch(), ページデータに DOM API を使用

6. page.evaluate 内のバッククォートは JSON ストレージを破壊 — JSON として保存/転送されるアダプターを書く場合、page.evaluate 内のテンプレートリテラルを回避. 文字列連結または関数スタイルの evaluate を使用:

   // 悪い: テンプレートリテラルバッククォートはアダプターが JSON 内にあるときに破壊
   page.evaluate(`document.querySelector("${selector}")`)
   // 良い: 関数スタイルの evaluate
   page.evaluate((sel) => document.querySelector(sel), selector)
   

トラブルシューティング

エラー	修正
"Browser not connected"	opencli doctor を実行
"attach failed: chrome-extension://"	1Password を一時的に無効化
要素が見つからない	opencli browser scroll down && opencli browser state
ページ変更後のインデックスが古い	opencli browser state を再度実行して新しいインデックスを取得