# Google Map Voices

> 評論聲音專案 — Google Maps 評論抓取 + 分析。輸入店家名稱或 URL，自動抓評論、統計星等、提取金句、歸類負評。產出結構化分析報告，任何需要「客人真實聲音」的下游 Skill 都能接（FB 貼文、Blog/SGE 文章、品牌健診）。

- Skill: `helloruru/google-map-voices` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add helloruru/google-map-voices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/helloruru/google-map-voices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: HelloRuru (https://skillmd.com/u/helloruru)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/helloruru/google-map-voices

---


# 評論聲音專案（google-map-voices）— 評論抓取 + 分析

從 Google Maps 抓取店家評論，分析成可直接使用的情報。
**獨立積木** — FB 貼文要客人金句？接。Blog 要 EEAT 社會證明？接。品牌健診要負評分析？接。

## 適用範圍

- **用途**：新客戶接案前評論偵察、FB 貼文素材、Blog/SGE 的 EEAT 社會證明、品牌健診
- **不適用**：寫文案（交給 client-fb-copywriter）、寫文章（交給 sge-article-pipeline）、存客戶資料（讓使用者確認再存）

## 觸發詞

「開評論」「抓評論」「抓 Google 評論」「評論分析」「查評價」「Map Voice」

## 安裝（第一次用要做）

```bash
pip install -r requirements.txt
```

如果跑腳本掛在 `No module named 'websockets.protocol'`，把 websockets 升級到 13+：

```bash
pip install --upgrade "websockets>=13"
```

## 工作流（Phase 1-3）

### Phase 1：抓取

**輸入**（擇一）：

- 店家名稱 + 地區（例：「美龍食品行 頭份」）
- Google Maps URL

**執行**：

```bash
python scraper.py "店家名稱 地區" --sort all --max 60 -o reviews.json
```

關鍵參數：

- `--sort all`：四種排序合併去重（推薦，最大化評論數）
- `--max 60`：每種排序最多抓 60 則
- `--show`：顯示瀏覽器（除錯用，預設無頭）

**輸出**：JSON 檔（評論者、星等、時間、全文、review ID）+ 終端的星等分布摘要

### Phase 2：分析

讀取 Phase 1 的 JSON，依照分析模板產出報告。

> **詳細分析指南**：[references/analysis-guide.md](references/analysis-guide.md)（金句提取四條件、六大分類表、EEAT 馬賽克格式、負面三種歸類、產業特殊處理）

**概覽**：

1. **基本統計** — 總評論數、星等分布
2. **正面金句** — 從 4-5 星挑出有畫面/情緒/細節/故事的，按六大分類歸類
3. **EEAT 格式** — 金句轉成馬賽克名 + 日期 + 引用格式，Blog 直接貼
4. **負面歸類** — 真痛點（要避開）+ 反轉金句（表面抱怨其實是有力證據）+ 無效抱怨（忽略）
5. **重要發現** — 一句話點出最關鍵的洞察

### Phase 3：存檔（雙資料庫）

- **已是客戶**（clients-database.md 有段落）→ 自動存入對應段落
- **偵察中**（找不到段落）→ 存入 `memory/reviews-inquiries.md`（僅 HelloRuru 內部使用）

## 跟其他 Skill 的接口

| 下游 Skill | 怎麼接 |
| ---------- | ------ |
| client-fb-copywriter | 金句速查表（按分類）→ 建人設 + 嵌入金句 |
| sge-article-pipeline | 顧客實證表（馬賽克名 + 日期 + 金句）→ EEAT 社會證明直接貼 |
| clients-database.md | Phase 3 自動存檔 |

## 限制與已知問題

- Google Maps 每種排序約 20 則，`--sort all` 合併最多 60-80 則
- 無法抓到全部評論（345 則店家最多抓 50-60 則）
- 抓取時間：單一排序約 1 分鐘，`--sort all` 約 3-4 分鐘
- 第一次跑會自動下載 chromedriver（30 秒，正常現象）