opencli-operate

OpenCLI Operate — AI エージェント向けブラウザー自動化

CLI で Chrome をステップごとに操作します。既存のログインセッションを再利用するため、パスワードは不要です。

前提条件

opencli doctor    # Verify extension + daemon connectivity

必要なもの：Chrome が起動していること、OpenCLI Browser Bridge 拡張機能がインストールされていること。

重要なルール

1. ページの確認には必ず state を使用し、screenshot は絶対に使用しないでください — state は [N] の要素インデックスを含む構造化 DOM を返し、即座に実行でき、トークンを消費しません。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 を 1 つの && チェーンにまとめます。ツール呼び出しにはオーバーヘッドがあるため、連結すると削減できます。
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	保存した画像が必要な場合に限り使用

アクションの連結ルール

コマンドは && で連結できます。ブラウザーはデーモン経由で維持されるため、連結しても安全です。

可能な場合は必ず連結してください — ツール呼び出しが少ないほど、完了が速くなります：

# GOOD: open + inspect in one call (saves 1 round trip)
opencli operate open https://example.com && opencli operate state

# GOOD: fill form in one call (saves 2 round trips)
opencli operate type 3 "hello" && opencli operate type 4 "world" && opencli operate click 7

# GOOD: type + verify in one call
opencli operate type 5 "[email protected]" && opencli operate get value 5

# GOOD: click + wait + state in one call (for page-changing clicks)
opencli operate click 12 && opencli operate wait time 1 && opencli operate state

# BAD: separate calls for each action (wasteful)
opencli operate type 3 "hello"    # Don't do this
opencli operate type 4 "world"    # when you can chain
opencli operate click 7            # all three together

ページを変更するコマンドは、必ずチェーンの最後に置いてください（後続のコマンドからは古いインデックスが見えるため）：

• open <url>、back、click <link/button that navigates>

ルール：インデックスがすでに分かっている場合は連結します。先にインデックスを確認する必要がある場合は、state を個別に実行します。

基本的なワークフロー

1. 移動：opencli operate open <url>
2. 確認：opencli operate state → [N] インデックス付きの要素
3. 操作：インデックスを使用 — click、type、select、keys
4. 待機（必要な場合）：opencli operate wait selector ".loaded" または wait text "Success"
5. 確認：opencli operate state または opencli operate get value <N>
6. 繰り返し：コマンド間もブラウザーは開いたままです
7. 保存：TS アダプターを ~/.opencli/clis/<site>/<command>.ts に書き込みます

コマンド

ナビゲーション

opencli operate open <url>              # Open URL (page-changing)
opencli operate back                    # Go back (page-changing)
opencli operate scroll down             # Scroll (up/down, --amount N)
opencli operate scroll up --amount 1000

確認（無料・即時）

opencli operate state                   # Structured DOM with [N] indices — PRIMARY tool
opencli operate screenshot [path.png]   # Save visual to file — ONLY for user deliverables

取得（無料・即時）

opencli operate get title               # Page title
opencli operate get url                 # Current URL
opencli operate get text <index>        # Element text content
opencli operate get value <index>       # Input/textarea value (use to verify after type)
opencli operate get html                # Full page HTML
opencli operate get html --selector "h1" # Scoped HTML
opencli operate get attributes <index>  # Element attributes

操作

opencli operate click <index>           # Click element [N]
opencli operate type <index> "text"     # Type into element [N]
opencli operate select <index> "option" # Select dropdown
opencli operate keys "Enter"            # Press key (Enter, Escape, Tab, Control+a)

待機

3 つの方法があります。状況に合ったものを使用してください：

opencli operate wait time 3                       # Wait N seconds (fixed delay)
opencli operate wait selector ".loaded"            # Wait until element appears in DOM
opencli operate wait selector ".spinner" --timeout 5000  # With timeout (default 30s)
opencli operate wait text "Success"                # Wait until text appears on page

待機するタイミング：SPA での open の後、非同期読み込みを発生させる click の後、動的にレンダリングされたコンテンツに対して eval を実行する前。

抽出（無料・即時、読み取り専用）

データの読み取りにのみ eval を使用してください。クリック、入力、ページ遷移には絶対に使用しないでください。

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

# IMPORTANT: wrap complex logic in IIFE to avoid "already declared" errors
opencli operate eval "(function(){ const items = [...document.querySelectorAll('.item')]; return JSON.stringify(items.map(e => e.textContent)); })()"

セレクターの安全性：必ずフォールバックセレクターを使用してください — 見つからない場合、querySelector は null を返します：

# BAD: crashes if selector misses
opencli operate eval "document.querySelector('.title').textContent"

# GOOD: fallback with || or ?.
opencli operate eval "(document.querySelector('.title') || document.querySelector('h1') || {textContent:''}).textContent"
opencli operate eval "document.querySelector('.title')?.textContent ?? 'not found'"

Network（API の特定）

opencli operate network                  # Show captured API requests (auto-captured since open)
opencli operate network --detail 3       # Show full response body of request #3
opencli operate network --all            # Include static resources

Sedimentation（CLI として保存）

opencli operate init hn/top              # Generate adapter scaffold at ~/.opencli/clis/hn/top.ts
opencli operate verify hn/top            # Test the adapter (adds --limit 3 only if `limit` arg is defined)

• init はアクティブなブラウザーセッションからドメインを自動検出します（指定する必要はありません）
• init はファイルを作成し、現在のページから site、name、domain、columns を設定します
• verify はアダプターをエンドツーエンドで実行して出力を表示します。アダプターに limit 引数がない場合は、--limit 3 を渡しません

セッション

opencli operate close                   # Close automation window

例：HN のストーリーを抽出する

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

例：フォームに入力する

opencli operate open https://httpbin.org/forms/post
opencli operate state                   # See [3] input "Customer Name", [4] input "Telephone"
opencli operate type 3 "OpenCLI" && opencli operate type 4 "555-0100"
opencli operate get value 3             # Verify: "OpenCLI"
opencli operate close

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

段階的なセディメンテーションの手順：

# 1. Explore the website
opencli operate open https://news.ycombinator.com
opencli operate state                          # Understand DOM structure

# 2. Discover APIs (crucial for high-quality adapters)
opencli operate eval "fetch('/api/...').then(r=>r.json())"   # Trigger API calls
opencli operate network                        # See captured API requests
opencli operate network --detail 0             # Inspect response body

# 3. Generate scaffold
opencli operate init hn/top                    # Creates ~/.opencli/clis/hn/top.ts

# 4. Edit the adapter (fill in func logic)
# - If API found: use fetch() directly (Strategy.PUBLIC or COOKIE)
# - If no API: use page.evaluate() for DOM extraction (Strategy.UI)

# 5. Verify
opencli operate verify hn/top                  # Runs the adapter and shows output

# 6. If verify fails, edit and retry
# 7. Close when done
opencli operate 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> として利用できます。

戦略ガイド

戦略	使用する場面	browser:
Strategy.PUBLIC	公開 API、認証不要	false
Strategy.COOKIE	ログイン Cookie が必要	true
Strategy.UI	DOM を直接操作	true

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

ヒント

1. 最初に必ず state を実行してください — 要素のインデックスを推測せず、必ず最初に確認してください
2. セッションは保持されます — コマンド間もブラウザーは開いたままなので、再度開く必要はありません
3. データ抽出には eval を使用してください — eval "JSON.stringify(...)" は、複数の get 呼び出しより高速です
4. API の検索には network を使用してください — JSON API は DOM スクレイピングより信頼性が高いです
5. エイリアス：opencli op は opencli operate の短縮形です

よくある落とし穴

1. 自動化では form.submit() が失敗します — フォームの送信に form.submit() や eval を使用しないでください。代わりに、検索 URL に直接移動してください：

   # BAD: form.submit() often silently fails
   opencli operate eval "document.querySelector('form').submit()"
   # GOOD: construct the URL and navigate
   opencli operate open "https://github.com/search?q=opencli&type=repositories"
   

2. GitHub の DOM は頻繁に変更されます — 利用できる場合は data-testid 属性を優先してください。クラス名やタグ構造よりも安定しています。

3. SPA ページでは抽出前に wait が必要です — シングルページアプリで open または click を実行した後、DOM はすぐには準備できません。eval の前に必ず wait selector または wait text を実行してください。

4. クリックする前に state を使用してください — opencli operate state を実行して、利用できるインタラクティブ要素とそのインデックスを確認します。記憶を頼りにインデックスを推測しないでください。

5. evaluate はブラウザーのコンテキストで実行されます — アダプター内の page.evaluate() はブラウザー内で実行されます。Node.js API（fs、path、process）は利用できません。ネットワーク呼び出しには fetch() を、ページデータには DOM API を使用してください。

6. page.evaluate 内のバッククォートは JSON の保存を妨げます — JSON として保存・転送するアダプターを作成する場合は、page.evaluate 内でテンプレートリテラルを使わないでください。文字列連結か関数形式の evaluate を使用してください：

   // BAD: template literal backticks break when adapter is in JSON
   page.evaluate(`document.querySelector("${selector}")`)
   // GOOD: function-style evaluate
   page.evaluate((sel) => document.querySelector(sel), selector)
   

トラブルシューティング

エラー	対処方法
"Browser not connected"	opencli doctor を実行してください
"attach failed: chrome-extension://"	1Password を一時的に無効にしてください
要素が見つからない	opencli operate scroll down && opencli operate state
ページ変更後にインデックスが古くなった	opencli operate state を再度実行して、新しいインデックスを取得してください