Review Sentinel

面向本地企业的自动化 Google 评论监控、分析与回复草稿生成工具。

功能说明

• 获取 当前 Google 评论与评分（通过 Google Places API）
• 追踪 评分/评论数量随时间的变化（使用本地状态文件）
• 分析 评论中的情感倾向、主题分布与趋势变化
• 生成 匹配评论语气及业务类型的经营者回复草稿
• 生成 声誉报告，并支持与竞品对比
• 告警 新出现的负面评论（需配合 cron 任务实现每日监控）

前置条件

• Python 3.8+（仅依赖标准库，无需 pip 安装任何第三方包）
• Google Places API 密钥（必需）——可通过以下任一方式提供：
  1. GOOGLE_PLACES_API_KEY 环境变量（推荐）
  2. credentials/google-places-api-key 文件（相对于工作目录）
  • 需在 Google Cloud Console 中启用 “Places API (New)”
  • 免费额度：每月 $200 信用额度（约支持 5,000 次请求）
• 备用方案：内置网页抓取脚本，但稳定性较差

限制说明

• Places API 单次请求最多返回 5 条最相关评论（Google API 限制）
• 网页抓取备用方案可能因 Google 页面结构变更而失效
• 未配置 cron 任务时，无法实现实时告警
• 评论回复发布需手动复制粘贴（无 API 写入权限）

初始化设置

首次使用时，请向用户索取以下信息：

1. 商家名称 与 所在地（城市或完整地址）
2. Google Maps Place ID（可选；若未提供则自动搜索）

将配置保存至技能目录下的 review-sentinel/config.json：

{
  "businesses": [
    {
      "name": "Business Name",
      "placeId": "ChIJ...",
      "location": "City, State",
      "searchQuery": "Business Name City",
      "lastChecked": null,
      "reviewCount": 0,
      "rating": 0
    }
  ]
}

核心工作流

1. 检查评论

触发词示例：“检查评论”、“我们的评论情况如何”、“有新评论吗”

1. 运行 scripts/fetch_reviews_places.py ，通过 Google Places API 获取当前评论数据（首选方式）
   • 备用方式：scripts/fetch_reviews.py （网页抓取，稳定性差）
2. 与 review-sentinel/state/.json 中存储的状态进行比对
3. 输出报告：自上次检查以来的新评论、评分变动、评论总数变动
4. 更新状态文件

2. 分析评论

触发词示例：“分析评论”、“评论趋势”、“顾客都在说什么”

1. 调用抓取脚本获取最新评论
2. 解析评论文本、评分与日期
3. 按情感倾向与主题分类（服务、等候时间、员工、价格、质量等）
4. 识别模式：高频投诉点、季节性趋势、评分走势
5. 如已配置竞品信息，则同步开展竞品对比分析

3. 起草回复

触发词示例：“回复评论”、“起草回复”、“回复所有评论”

针对每条尚未回复的评论：

• 5 星评论： 具体感谢客户所表扬的内容，并诚挚邀请其再次光临
• 4 星评论： 温暖致谢，并温和回应其中轻微顾虑
• 3 星评论： 表示感谢，明确指出并回应具体问题，主动提供解决方案
• 1–2 星评论： 表达共情，致歉但不承认责任归属，建议线下沟通解决，保持专业得体

撰写指南：

• 每条回复控制在 100 字以内
• 切勿表现出防御性或争辩态度
• 须引用评论中的具体细节（体现人工审阅）
• 自然嵌入商家名称
• 避免模板化——不得重复使用完全相同的回复内容

4. 声誉报告

触发词示例：“声誉报告”、“评论报告”、“月度报告”

生成结构化报告，包含以下内容：

• 整体评分及趋势（上升 / 下降 / 稳定）
• 评论增速（每周 / 每月新增评论数）
• 情感倾向分布
• 最受好评的方面
• 最常被投诉的问题
• 竞品对比分析（如已配置）
• 改进建议与行动项

报告保存路径：review-sentinel/reports/YYYY-MM-DD-report.md。

5. 评论告警（cron 自动化）

为实现自动化监控，建议用户配置 cron 任务：

Schedule: daily at 9 AM
Task: Check for new reviews, alert on any 1-2 star reviews immediately

回复语气指南

根据商家类型调整回复语气：

• 医疗/专业类机构： 正式、富有同理心、注重隐私保护（严禁提及具体治疗项目或健康状况）
• 零售/餐饮类商家： 温暖、友好、口语化
• 服务型业务： 专业、以解决问题为导向

竞品追踪

当配置了竞品商家后，分析流程将额外包含以下内容：

• 评分并排对比
• 评论增速对比
• 情感倾向差距分析
• 竞争格局简要总结

状态管理

所有状态均存于 review-sentinel/state/ 目录下：

• .json —— 最新评论快照及历史记录
• config.json —— 商家配置信息

完整状态文件结构请参阅 references/state-schema.md。

快速上手示例

User: "Check reviews for my clinic"
Agent: Runs fetch_reviews_places.py "My Clinic Seattle"
Agent: Compares with stored state, reports:
  - Rating: 4.6★ (stable)
  - 3 new reviews since last check (2 positive, 1 negative)
  - Alert: 1-star review from "Jane D." needs response
  - Drafts response for approval

重要注意事项

• Google 评论抓取受频率限制。请勿对同一商家每日执行超过数次抓取操作。
• 所有评论回复草稿必须经用户审核批准后方可发布。
• 严禁自动发布回复——必须确保“人在环中（human-in-the-loop）”。
• 对于涉及健康隐私合规要求的商家（如 HIPAA / PIPEDA），回复中严禁提及患者病情或诊疗细节。