web-browser

web-browser スキル

原作者不明 · 凯寓 (KAIYU) が修正・メンテナンス バージョン：v2.1.0

クロスプラットフォーム互換性

項目	macOS / Linux	Windows
環境チェック	bash ${CLAUDE_SKILL_DIR}/scripts/check-deps.sh	Git Bash または WSL で実行する必要があります
一時ファイルパス	/tmp/shot.png	%TEMP%\shot.png
Chrome ユーザーデータ	~/Library/Application Support/Google/Chrome/	%LOCALAPPDATA%\Google\Chrome\User Data\
Node.js インストール	brew install node	winget install OpenJS.NodeJS.LTS

Windows ユーザーの方へ：check-deps.sh は bash スクリプトであり、Git Bash または WSL 経由で実行する必要があります。スクリーンショットのパスには /tmp/shot.png の代わりに %TEMP%\shot.png を使用してください。

事前チェック

ネットワーク操作を開始する前に、まず CDP モードの可用性を確認します：

以下のスクリプトがエラーを報告するか、依存関係が不足している場合は、SETUP.md を読んで初回設定を完了してください。

bash ${CLAUDE_SKILL_DIR}/scripts/check-deps.sh

• Node.js 22+：必須（ネイティブ WebSocket を使用）。バージョンが 22 未満でも使用可能ですが、ws モジュールのインストールが必要です。
• Chrome remote-debugging：Chrome のアドレスバーで chrome://inspect/#remote-debugging を開き、「Allow remote debugging for this browser instance」 にチェックを入れるだけです。ブラウザの再起動が必要になる場合があります。

チェックに合格したら、CDP Proxy を起動して操作を実行します。合格しなかった場合は、ユーザーを設定完了へと導きます。

ブラウジングの哲学

人間のように考え、効率と適応性を両立させながらタスクを完了する。

タスクを実行する際は、固定観念から計画された手順に過度に依存せず、目標を持って臨み、見ながら判断し、障害に遭遇したら解決し、内容が不十分だと分かれば深掘りする——全体を通じて「自分は何を達成したいのか」を軸に意思決定します。このスキルのすべての動作はこのロジックに従うべきです。

① リクエストを受け取る — まずユーザーが何をしたいのかを明確にし、成功基準を定義します：何をもって完了とするのか？どのような情報を取得し、どのような操作を実行し、どのような結果に到達する必要があるのか？これが以降のすべての判断のアンカーとなります。

② 起点を選ぶ — タスクの性質、プラットフォームの特徴、達成条件に基づき、最も直接的に到達できる可能性が高い方法を最初の一手として検証します。一発で成功すればもちろん最善ですが、成功しなければ③で調整します。例えば、ページ操作が必要、ログイン状態が必要、静的取得が不可能と分かっているプラットフォーム（小紅書、WeChat 公式アカウントなど）→ 直接 CDP

③ プロセス検証 — 各ステップの結果は証拠であり、単なる成功・失敗の二値シグナルではありません。結果を①の成功基準と照らし合わせ、目標に対する判断を更新します：道は前進しているか？結果の全体的な姿（品質、関連度、量）は目標の達成可能性を示しているか？方向が間違っていると分かれば即座に調整し、同じ方法で何度もリトライしません——検索がヒットしないことは「まだ正しい方法を見つけていない」ではなく「目標が存在しない」かもしれません；API のエラー、ページに期待される要素が欠けている、リトライしても改善しない、といったことはすべて方向を再評価すべきだというサインです。ポップアップやログインウォールなどの障害に遭遇したら、それが本当に目標を遮っているかを判断します：遮っているなら対処し、遮っていないなら回避します——コンテンツはすでにページの DOM 内にあり、インタラクションは単なる表示手段にすぎないかもしれません。

④ 完了判断 — 定義したタスクの成功基準と照らし合わせ、タスクが完了したことを確認してから停止します。ただし、過度な操作もせず、「完全さ」のためにコストを浪費しません。

ネットワークツールの選択

• 情報の真実性を確保し、一次情報は二次情報に優る：検索エンジンやアグリゲーションプラットフォームは情報発見の入口です。複数回の検索試行の後に質的な改善がない場合、より根本的な取得方式へエスカレートします：一次ソース（公式サイト、公式プラットフォーム、元のページ）を特定します。

シナリオ	ツール
検索要約やキーワード結果、情報源の発見	WebSearch
URL が既知で、ページから特定の情報をピンポイントで抽出する必要がある	WebFetch（Web ページの内容を取得し、小規模モデルがプロンプトに基づいて抽出し、処理後の結果を返します）
URL が既知で、生の HTML ソース（meta、JSON-LD などの構造化フィールド）が必要	curl
非公開コンテンツ、または静的層が無効と分かっているプラットフォーム（小紅書、WeChat 公式アカウントなどの公開コンテンツもスクレイピング対策で制限されている）	ブラウザ CDP（直接、静的層をスキップ）
ログイン状態、インタラクティブ操作が必要、または人間のようにブラウザ内を自由にナビゲートして探索する必要がある	ブラウザ CDP

ブラウザ CDP は URL が既知であることを要求しません——任意の入口から出発し、ページ内検索、クリック、ジャンプなどによって目標コンテンツを見つけられます。WebSearch、WebFetch、curl はいずれもログイン状態を扱いません。

Jina（オプションの前処理層で、WebFetch/curl と組み合わせて使用可能。その特性により tokens 消費を節約できるため、タスクに適した場面では積極的に組み合わせて使用してください）：サードパーティのネットワークサービスで、Web ページを Markdown に変換し、token を大幅に節約できますが、情報の欠落がある可能性があります。呼び出し方法は r.jina.ai/example.com（URL の前にプレフィックスを付け、元の URL の http プレフィックスは保持しない）、制限は 20 RPM。記事、ブログ、ドキュメント、PDF など本文を核とするページに適しています；データパネル、商品ページなど非記事構造のページでは誤ったブロックを抽出する可能性があります。

ブラウザ層に入ると、/eval があなたの目と手になります：

• 見る：/eval で DOM をクエリし、ページ上のリンク、ボタン、フォーム、テキストコンテンツを発見する——「このページに何があるか見てみる」に相当します
• する：/click で要素をクリック、/scroll でスクロール読み込み、/eval でフォーム入力・送信——人間のようにページ内を自然にナビゲートします
• 読む：/eval でテキストコンテンツを抽出し、画像/動画が核心的な情報を担っているかを判断する——担っている場合はメディア URL を抽出してピンポイントで読み取るか /screenshot で視覚認識します

ページ内を閲覧する際は、まず eval でページ構造を把握し、それから次の動作を決めます——リストがあれば詳細にクリックして入り、ページネーションがあればめくり、コンテンツがあれば抽出します。すべてのステップを事前に計画する必要はありません。

プログラム的操作と GUI インタラクション

ブラウザ内でページを操作する方法は二つあります：

• プログラム的方式（URL を構築して直接ナビゲート、eval で DOM 操作）：成功すれば高速で正確ですが、ウェブサイトにとっては正常なユーザー行動ではなく、スクレイピング対策を引き起こしやすくなります。
• GUI インタラクション（ボタンをクリック、入力欄に記入、スクロール閲覧）：GUI は人間のために設計されており、ウェブサイトは正常な UI 操作を制限しないため、確実性が最も高いですが、ステップが多く遅いです。

対象プラットフォームへの理解に基づいて判断します。プログラム的方式が妨げられた場合、GUI インタラクションは信頼できるフォールバックです。注意：記憶に頼ってパラメータ付きの URL を構築しないでください——内部パラメータ（都市コード、カテゴリ ID など）はいつでも変わり得るため、不確かな場合はページのインタラクションを通じて、または DOM から実際のリンクを抽出してください。

ブラウザ CDP モード

CDP Proxy を通じてユーザーの日常的な Chrome に直結し、自然にログイン状態を引き継ぎ、独立したブラウザを起動する必要がありません。 ユーザーの明示的な要求がない限り、ユーザーの既存のタブを自発的に操作せず、すべての操作は自分で作成したバックグラウンドタブ内で行い、ユーザー環境への侵入を最小限に保ちます。ユーザーのタブを閉じない前提で、タスク完了後に自分で作成したタブを閉じ、環境を清潔に保ちます。

起動

bash ${CLAUDE_SKILL_DIR}/scripts/check-deps.sh

スクリプトは順に Node.js、Chrome ポートをチェックし、Proxy が接続済みであることを確認します（実行されていなければ自動で起動して待機します）。Proxy は起動後は継続的に実行されます。

Proxy API

すべての操作は curl で HTTP API を呼び出します：

# 列出用户已打开的 tab
curl -s http://localhost:3456/targets

# 创建新后台 tab（自动等待加载）
curl -s "http://localhost:3456/new?url=https://example.com"

# 页面信息
curl -s "http://localhost:3456/info?target=ID"

# 执行任意 JS：可读写 DOM、提取数据、操控元素、触发状态变更、提交表单、调用内部方法
curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'

# 捕获页面渲染状态（含视频当前帧）
# macOS/Linux: /tmp/shot.png | Windows: %TEMP%\shot.png
curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"

# 导航、后退
curl -s "http://localhost:3456/navigate?target=ID&url=URL"
curl -s "http://localhost:3456/back?target=ID"

# 点击（POST body 为 CSS 选择器）— JS el.click()，简单快速，覆盖大多数场景
curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'

# 真实鼠标点击 — CDP Input.dispatchMouseEvent，算用户手势，能触发文件对话框
curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload'

# 文件上传 — 直接设置 file input 的本地文件路径，绕过文件对话框
curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'

# 滚动（触发懒加载）
curl -s "http://localhost:3456/scroll?target=ID&y=3000"
curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"

# 关闭 tab
curl -s "http://localhost:3456/close?target=ID"

ページ内ナビゲーション

ページ内のリンクを開く方法は二つあります：

• /click：現在のタブ内で直接クリック、シンプルで直接的、逐次処理。同じページ内で連続操作が必要な場面に適しています。例えば、クリックで展開、ページ送り、詳細への進入など。
• /new + 完全な URL：DOM から対象リンクの完全なアドレス（すべてのクエリパラメータを含む）を抽出し、新しいタブで開きます。複数のページに同時にアクセスする必要がある場面に適しています。

多くのウェブサイトのリンクにはセッション関連のパラメータ（token など）が含まれており、これらのパラメータは正常なアクセスに必要です。URL を抽出する際は完全なアドレスを保持し、パラメータを切り詰めたり省略したりしないでください。

メディアリソースの抽出

コンテンツが画像内にあると判断した場合、/eval で DOM から直接画像 URL を取得し、ピンポイントで読み取ります——全ページスクリーンショットよりもはるかに正確です。

技術的事実

• ページ内には読み込まれているが表示されていないコンテンツが大量に存在します——カルーセルの現在のフレーム以外の画像、折りたたまれたブロックのテキスト、遅延読み込みのプレースホルダー要素など、それらは DOM 内に存在しますがユーザーには見えません。データ構造（コンテナ、属性、ノード関係）を単位として考えることで、これらのコンテンツに直接到達できます。
• /scroll で最下部まで行くと遅延読み込みがトリガーされ、ビューポートに入っていない画像の読み込みが完了します。画像 URL を抽出する前にスクロールしていない場合、一部の画像はまだ読み込まれていない可能性があります。
• メディアリソースの URL を取得した後、公開リソースは直接ローカルにダウンロードしてから読み取りに使用できます；ログイン状態が必要なリソースのみ、ブラウザ内で navigate + screenshot する必要があります。
• 短時間に大量のページを集中的に開く（例えばバッチ /new）と、ウェブサイトのスクレイピング対策リスク管理をトリガーする可能性があります。

動画コンテンツの取得

ユーザーの Chrome の実際のレンダリングにより、スクリーンショットは現在の動画フレームをキャプチャできます。核心的な能力：/eval を通じて <video> 要素を操作し（再生時間の取得、任意の時点への seek、再生/一時停止/全画面）、/screenshot と組み合わせてフレームを採取することで、動画コンテンツを離散サンプリング分析できます。

登录判断

用户日常 Chrome 天然携带登录态，大多数常用网站已登录。

登录判断的核心问题只有一个：目标内容拿到了吗？

打开页面后先尝试获取目标内容。只有当确认目标内容无法获取且判断登录能解决时，才告知用户：

"当前页面在未登录状态下无法获取[具体内容]，请在你的 Chrome 中登录 [网站名]，完成后告诉我继续。"

登录完成后无需重启任何东西，直接刷新页面继续。

任务结束

用 /close 关闭自己创建的 tab，必须保留用户原有的 tab 不受影响。

Proxy 持续运行，不建议主动停止——重启后需要在 Chrome 中重新授权 CDP 连接。

并行调研：子 Agent 分治策略

任务包含多个独立调研目标时（如同时调研 N 个项目、N 个来源），鼓励合理分治给子 Agent 并行执行，而非主 Agent 串行处理。

好处：

• 速度：多子 Agent 并行，总耗时约等于单个子任务时长
• 上下文保护：抓取内容不进入主 Agent 上下文，主 Agent 只接收摘要，节省 token

并行 CDP 操作：每个子 Agent 在当前用户浏览器实例中，自行创建所需的后台 tab（/new），自行操作，任务结束自行关闭（/close）。所有子 Agent 共享一个 Chrome、一个 Proxy，通过不同 targetId 操作不同 tab，无竞态风险。

子 Agent Prompt 写法：目标导向，而非步骤指令

• 必须在子 Agent prompt 中写 必须加载 web-browser skill 并遵循指引 ，子 Agent 会自动加载 skill，无需在 prompt 中复制 skill 内容或指定路径。
• 子 Agent 有自主判断能力。主 Agent 的职责是说清楚要什么，仅在必要与确信时限定怎么做。过度指定步骤会剥夺子 Agent 的判断空间，反而引入主 Agent 的假设错误。避免 prompt 用词对子 Agent 行为的暗示：「搜索xx」会把子 Agent 锚定到 WebSearch，而实际上有些反爬站点需要 CDP 直接访问主站才能有效获取内容。主 Agent 写 prompt 时应描述目标（「获取」「调研」「了解」），避免用暗示具体手段的动词（「搜索」「抓取」「爬取」）。

分治判断标准：

适合分治	不适合分治
目标相互独立，结果互不依赖	目标有依赖关系，下一个需要上一个的结果
每个子任务量足够大（多页抓取、多轮搜索）	简单单页查询，分治开销大于收益
需要 CDP 浏览器或长时间运行的任务	几次 WebSearch / Jina 就能完成的轻量查询

信息核实类任务

核实的目标是一手来源，而非更多的二手报道。多个媒体引用同一个错误会造成循环印证假象。

搜索引擎和聚合平台是信息发现入口，是定位信息的工具，不可用于直接证明真伪。找到来源后，直接访问读取原文。同一原则适用于工具能力/用法的调研——官方文档是一手来源，不确定时先查文档或源码，不猜测。

信息类型	一手来源
政策/法规	发布机构官网
企业公告	公司官方新闻页
学术声明	原始论文/机构官网
工具能力/用法	官方文档、源码

找不到官网时：权威媒体的原创报道（非转载）可作为次级依据，但需向用户说明："未找到官方原文，以下核实来自[媒体名]报道，存在转述误差可能。"单一来源时同样向用户声明。

站点经验

操作中积累的特定网站经验，按域名存储在 references/site-patterns/ 下。

已有经验的站点：!ls ${CLAUDE_SKILL_DIR}/references/site-patterns/ 2>/dev/null | sed 's/\.md$//' || echo "暂无"

确定目标网站后，如果上方列表中有匹配的站点，必须读取对应文件获取先验知识（平台特征、有效模式、已知陷阱）。经验内容标注了发现日期，当作可能有效的提示而非保证——如果按经验操作失败，回退通用模式并更新经验文件。

CDP 操作成功完成后，如果发现了有必要记录经验的新站点或新模式（URL 结构、平台特征、操作策略），主动写入对应的站点经验文件。只写经过验证的事实，不写未确认的猜测。

文件格式：

---
domain: example.com
aliases: [示例, Example]
updated: 2026-03-19
---
## 平台特征
架构、反爬行为、登录需求、内容加载方式等事实

## 有效模式
已验证的 URL 模式、操作策略、选择器

## 已知陷阱
什么会失败以及为什么

经验/陷阱内容标注发现日期，当作"可能有效的提示"而非"保证正确的事实"。

References 索引

文件	何时加载
references/cdp-api.md	需要 CDP API 详细参考、JS 提取模式、错误处理时
references/site-patterns/{domain}.md	确定目标网站后，读取对应站点经验