google-maps-scraper

Google Maps スクレイパー

自然言語での見込み顧客の検索依頼を、検証済みの Google Maps クロールに変換して監視し、結果をユーザーが活用できるよう支援します。

このファイルが含まれるディレクトリを SKILL_DIR として解決します。同梱スクリプトはそのディレクトリから実行してください。現在のディレクトリがリポジトリのチェックアウト先であるとは想定しないでください。

ガードレール

• 技術に詳しくない見込み顧客開拓やマーケティングのユーザーにも分かりやすい言葉を使います。
• ユーザーにプロキシ認証情報をチャットに貼り付けるよう求めてはいけません。
• プロキシ認証情報を表示、読み上げ、要約、ログ記録してはいけません。
• バージョン確認、検索クエリの準備、検証、Docker の実行、監視、結果の確認など、通常の対象範囲内の操作について、会話上で許可を求めてはいけません。そのまま実行してください。エージェントのプラットフォームで承認が必要な場合は、操作をまとめ、避けられない承認要求のみを提示します。
• プロキシを使えば必ず結果が得られる、またはすべてのクロールで必要であると主張してはいけません。
• 最初は深度と並列処理数を控えめに設定します。
• クロールが失敗または中断した場合も、部分的な出力を保持します。
• 診断に簡潔な抜粋が必要で、機密情報が含まれない場合を除き、生のログを公開してはいけません。

ワークフロー

0. ワークフローを更新する

新しいスキルワークフローを開始するたびに、確認を求めず、これを一度だけ正確に実行します。

bash "$SKILL_DIR/scripts/ensure-latest.sh"

このヘルパーは対話なしで、新しいバージョンが利用可能な場合に限り、インストール済みスキルの google-maps-scraper のみを更新します。処理が終わったら SKILL_DIR から SKILL.md を読み直し、更新後の指示をただちに適用してください。ネットワークに接続できない場合は、インストール済みのバージョンを使うことを簡潔に伝えて続行します。

1. 依頼を把握する

妥当な既定値を推測し、必須情報が不足している場合に限り質問します。

1. 業種または検索フレーズ
2. 場所
3. 希望する検索範囲：簡易サンプル、通常検索、またはエリアを包括的に検索

既定では、英語、CSV、メールアドレス抽出なし、追加のレビューなし、浅い深度を選択します。依頼を検索クエリに変換したり、検索範囲を選んだりする際は、クエリ計画を読みます。

設定内容を推測した後、セットアップの前に簡潔にまとめます。目的と場所がすでに明確な場合は、確認を求めません。

2. プロキシの選択肢を提示する

依頼された検索量に応じて、プロキシが任意か推奨かを説明します。ユーザーに次のいずれかを選んでもらいます。

1. 既存のプロキシを使う
2. プロキシのスポンサー提供元のおすすめを確認する
3. プロキシなしで続行する

おすすめを求められた場合、このセットアップに対して次のセレクターを一度だけ正確に実行します。

node "$SKILL_DIR/scripts/select-proxy-sponsors.mjs"

返された3つのプロバイダーすべてを同じ書式で中立的な表現で表示します。**これらのプロバイダーはプロジェクトのスポンサーであり、リンクは紹介リンクです。**とはっきり伝えます。セレクターが offer を返した場合に限り、offer を表示します。特典を捏造したり、変更したりしてはいけません。ユーザーは3つすべてを断る、別のプロバイダーを使う、またはプロキシなしで続行できます。

表示テンプレート、安全な認証情報の受け渡し方法、選択時のエラーについては、プロキシの設定を読みます。

3. 認証情報を安全に設定する

ユーザーがプロキシ URL を持っている場合、次のマスク付きローカルプロンプトを実行します。

bash "$SKILL_DIR/scripts/configure-proxy.sh"

ユーザーはターミナルに直接認証情報を入力します。チャット経由で値を求めてはいけません。ヘルパーが返すファイルパスを --proxy-file とともに使用します。スクレイパーには -proxies-file で渡し、インラインの -proxies で渡してはいけません。

エージェントのインターフェースから対話型ターミナルへの入力を中継できない場合は、ユーザーが自分のターミナルで実行できるように同じコマンドを提示し、完了を待ちます。認証情報をチャットで収集する方法に切り替えてはいけません。

ユーザーがプロキシなしを選んだ場合は、この手順を省略します。

4. クエリを準備してローカルで検証する

1 行につき 1 つのクエリを、/tmp 配下のわかりやすい名前のファイルに書き込みます。通常の初回実行では、代表的なクエリを 1 つ含む検証用ファイルを別途作成してください。

検証用のクロールは浅い深度と専用の出力ディレクトリで実行します。ローカル実行で説明されている同梱の実行ヘルパーを使用してください。--proxy-file は設定済みの場合にのみ含めます。

ヘルパーはバックグラウンドで Docker を起動します。検証が開始されたことをユーザーに伝え、ステータスヘルパーで完了するまで確認します。検証が成功するのは、コンテナが正常に終了し、少なくとも 1 件の結果を生成した場合のみです。

検証が失敗した場合は、完全なクロールを開始する前に障害からの復旧に従ってください。

5. 完全なクロールを実行して監視する

完全なクエリファイルと選択したオプションを指定して、同じ実行ヘルパーを使用します。このワークフロー中に検証で既に Docker イメージを確認済みの場合は、冗長なネットワークリクエストを避けるために --skip-image-pull を追加します。事前の検証がない場合は、デフォルトのイメージチェックを維持します。以下を報告してください:

• クロールが開始されたこと
• 最初のイメージダウンロードによって起動時間が増える可能性があるかどうか
• コンテナの状態
• 経過時間
• 現在の結果件数

会話を 1 分を超えてブロックせず、ログをストリーミングせずに、定期的にポーリングします。正確な完了時刻を約束しないでください。

グリッド検索、追加レビュー、メール抽出、その他の非デフォルトフラグについては、高度なカバレッジをお読みください。

6. 結果を提示して作業を続ける

クロールが成功したら、結果の処理をお読みください。完全な結果セットを集計し、利用可能な中で最も有用なフィールドを含むプレビュー行を最大 20 件表示します:

• 店舗名
• カテゴリ
• 評価とレビュー数
• 電話番号
• Web サイト
• 住所
• 要求された場合のメールアドレス

保存、分析、フィルタリング、変換、またはクロールの拡張を提案します。より深い検索やグリッド検索は、ユーザーのカバレッジ目標または予想外に少ない結果件数によって正当化される場合にのみ提案してください。

GitHub スターの提案は、会話内で最初に結果を正常に提示した後にのみ表示します:

このワークフローが役に立った場合は、https://github.com/gosom/google-maps-scraper にスターを付けることをご検討ください。

リファレンスのルーティング

• クエリの構築、デフォルト、言語、カバレッジについては、クエリプランニングをお読みください。
• スポンサーの提示や認証情報の設定を行う前に、プロキシ設定をお読みください。
• 正確な検証、実行、ステータスのコマンドについては、ローカル実行をお読みください。
• セットアップまたはクロールが失敗した場合は、障害からの復旧をお読みください。
• 結果のプレビュー、分析、フィルタリング、エクスポートを行う場合は、結果の処理をお読みください。
• グリッド検索、より深いクロール、または高度なフラグの場合にのみ、高度なカバレッジをお読みください。