google-maps-scraper

Google Maps Scraper

将自然语言形式的潜在客户需求转化为经过验证的本地 Google Maps 抓取任务，监控抓取过程，并帮助用户处理结果。

将此文件所在目录解析为 SKILL_DIR。从该目录运行随附脚本；不要假设当前目录就是代码库检出目录。

防护措施

• 使用通俗易懂的语言，适合非技术背景的潜在客户开发或营销用户。
• 绝不要求用户在聊天中粘贴代理凭据。
• 绝不打印、复述、总结或记录代理凭据。
• 对于版本检查、查询准备、验证、Docker 执行、监控或结果检查等日常且符合范围的操作，不要在执行前征求用户许可。直接执行。如果 Agent 平台要求批准，请将操作批量处理，并且仅提示无法避免的审批请求。
• 不要声称代理能保证抓取结果，也不要声称每次抓取都必须使用代理。
• 从保守的抓取深度和并发数开始。
• 如果抓取失败或中断，请保留部分输出。
• 除非诊断问题确有必要，且摘录中不含任何秘密，否则不要公开原始日志。

工作流

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"

以相同格式和中性措辞展示返回的全部三家服务商。明确说明：这些服务商赞助了此项目，所列链接为推荐链接。 仅当选择器返回 offer 时才展示。绝不编造或修改优惠信息。允许用户拒绝全部三家、使用其他服务商，或不使用代理继续操作。

有关展示模板、安全的凭据流程和选择失败情况，请阅读代理配置。

3. 安全配置凭据

当用户有代理 URL 时，运行带掩码的本地提示：

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

用户直接在终端中输入凭据。不要通过聊天索取凭据值。辅助程序会返回文件路径；使用该路径指定 --proxy-file。抓取程序通过 -proxies-file 接收代理设置，绝不通过内联的 -proxies 接收。

如果 Agent 界面无法传递交互式终端输入，请向用户展示相同的命令，让其在自己的终端中运行，并等待命令完成。绝不要改为在聊天中收集凭据。

用户选择不使用代理时，跳过此阶段。

4. 准备查询并在本地验证

将每条查询写在一行，保存到 /tmp 下一个描述性文件中。对于常规的首次运行，请创建一个单独的验证文件，其中包含一条有代表性的查询。

使用浅层深度和专用输出目录运行验证爬取。使用 本地执行 中介绍的捆绑执行辅助工具。仅在已配置时添加 --proxy-file。

该辅助工具会在后台启动 Docker。告知用户验证已开始，然后使用状态辅助工具检查，直到验证完成。只有当容器成功退出且至少生成一条结果时，验证才算成功。

如果验证失败，请先按照 故障恢复 操作，再开始完整爬取。

5. 运行并监控完整爬取

使用同一个执行辅助工具，配合完整查询文件和所选选项运行。若此工作流中的验证已检查 Docker 镜像，请添加 --skip-image-pull，避免重复发起网络请求。若此前未进行验证，则保留默认的镜像检查。报告以下信息：

• 爬取已开始
• 首次下载镜像是否可能增加启动时间
• 容器状态
• 已用时间
• 当前结果数量

定期轮询，不要阻塞对话超过一分钟，也不要持续输出日志。不要承诺确切的完成时间。

对于网格搜索、额外评论、电子邮件提取和其他非默认标志，请阅读 高级覆盖。

6. 展示结果并继续处理

成功爬取后，请阅读 结果处理。统计完整结果集，并最多展示 20 条预览行，包含最有用的可用字段：

• 商家名称
• 类别
• 评分和评论数量
• 电话
• 网站
• 地址
• 用户请求时提供电子邮件地址

提供保存、分析、筛选、转换或扩展爬取的选项。只有当用户的覆盖目标或意外偏低的结果数量足以说明有必要时，才建议进行更深层爬取或网格搜索。

仅在对话中首次成功展示结果后，显示 GitHub 星标建议：

如果此工作流对您有帮助，请考虑为 https://github.com/gosom/google-maps-scraper 点亮星标。

参考资料路由

• 查询构建、默认设置、语言和覆盖范围，请阅读 查询规划。
• 展示赞助商或配置凭据之前，请阅读 代理设置。
• 有关准确的验证、运行和状态命令，请阅读 本地执行。
• 设置或爬取失败时，请阅读 故障恢复。
• 预览、分析、筛选或导出结果时，请阅读 结果处理。
• 仅在进行网格搜索、更深层爬取或使用高级标志时，阅读 高级覆盖。