用途：把“业务类型 + 地点”转成干净的地方商户线索表，用于获客。引擎 gosom/google-maps-scraper 以本地 Docker 容器运行，REST API 位于 http://localhost:8080，无鉴权，仅绑定 localhost。
主要能力：一次任务可含多个关键词，每个结果最多 34 个原始字段。默认只输出 8 个线索字段：title、phone、emails、website、category、address、review_rating、review_count；其余字段（经纬度、link、place_id、营业时间、图片、菜单等）默认丢弃，仅在用户明确要求时展示。邮箱默认开启（email:true），会访问商户网站查找，速度较慢；社交主页（Instagram、Facebook、LinkedIn）为可选增强，需先询问用户，由脚本用 HTTP 与正则提取，不消耗 LLM token，覆盖率约 40%–70%。
使用方式：先检查引擎是否运行：curl -s http://localhost:8080/api/v1/jobs >/dev/null 2>&1 && echo UP || echo DOWN；若 DOWN，在套件根目录执行 docker compose up -d。创建任务 POST /api/v1/jobs，必填 keywords（把地点写进词里，如 "plumbers in Denver CO"）、lat、lon（字符串）、max_time（秒）；推荐 depth（默认 10，建议从 5 起）、lang、zoom、radius、fast_mode、email。返回 {"id":"<uuid>"}。轮询 GET /api/v1/jobs/{id}，字段为 "Status"，从 working 变为 ok 或 failed；Bash 工具禁止前台 sleep，需后台轮询。完成后 GET /api/v1/jobs/{id}/download 下载 CSV。脚本 scripts/scrape.py 默认返回 8 个线索字段，--full 保留全部列，--fields 自选，--json 输出 JSON；scripts/scrape.sh 可一步完成创建、轮询、下载；--city 可自动地理编码，--grid 3 用于整城采集（3x3 分块、按 place_id 去重）。
适用场景：本地商户线索收集、按城市或关键词批量采集、需要邮箱与社交主页的获客名单。
限制与注意：抓取 Google Maps 违反其服务条款，上游仅有免责声明，无公开封禁阈值；过快或过多可能被临时限流，表现为任务失败、结果为空或行数骤降，可降低 depth、暂停或配置 proxies 数组（socks5/http/https，支持认证，引擎自动轮换）。本地建议一次只跑一个任务。抓到的邮箱和电话属个人数据，存储或联系需遵守 GDPR、CCPA、CAN-SPAM。不要把 API 暴露到 localhost 之外，不要向聊天中倾倒大 CSV，按 place_id/cid 去重，定期删除旧任务释放磁盘。拒绝用于监视个人、垃圾信息或骚扰。其他端点：GET /api/v1/jobs 列出任务，DELETE /api/v1/jobs/{id} 删除任务；浏览器界面与 OpenAPI 文档见 http://localhost:8080 与 http://localhost:8080/api/docs。