ReviewRadar Agent｜海外竞品差评猎手

ReviewRadar Agent 是一个面向出海 App、SaaS、独立开发者和小团队的 AI Agent 产品。用户输入自己的产品、目标海外市场、竞品名称，并粘贴或上传 App Store、Google Play、G2、Capterra、Reddit 或 CSV 风格的评论数据后，系统会自动分析海外用户差评、竞品短板、用户痛点，并生成产品路线图、PRD 摘要、用户故事、应用商店回复建议和增长文案。

项目为「头号 Builder」全球挑战赛准备，核心方向固定为 ReviewRadar Agent，不更换赛道。当前支持 MOCK_MODE=true 完整演示；比赛当天填入 GMI Cloud Inference Engine 配置并设置 MOCK_MODE=false 后，即可切换为真实 GMI Cloud API 调用。

面向海外市场的场景价值

出海产品团队经常面临几个问题：

• 海外评论分散在 App Store、Google Play、SaaS 评价站点和社区里，人工整理成本高。
• 竞品差评里有大量可转化为产品机会的信号，但小团队很难持续分析。
• 差评归因之后还要转成 PRD、路线图、回复和增长文案，中间需要多轮 PM 工作。
• 中国出海团队既需要英文产品输出，也需要中文材料辅助内部评审和比赛提交。

ReviewRadar Agent 的定位是“海外竞品差评猎手”：把英文海外评论自动转成可执行的产品决策资产。

为什么它是 Agent，而不是普通聊天机器人

ReviewRadar Agent 不是单轮问答，也不是普通聊天框。它是一个多步骤工作流，每个 Agent 有独立职责、输入上下文、输出结构和调用 trace：

1. ReviewIngestionAgent：标准化评论导入内容，识别来源和竞品覆盖。
2. SentimentAgent：分析评分、正负面情绪和负面信号集中点。
3. PainPointAgent：挖掘用户痛点、根因、影响和证据评论。
4. ClusteringAgent：把相似抱怨聚类成产品机会主题。
5. CompetitorGapAgent：分析竞品短板，输出定位切入点。
6. RoadmapAgent：生成路线图、PRD 摘要和用户故事。
7. GTMAgent：生成应用商店回复、发布文案和增长实验。

所有模型调用都统一经过 src/lib/llm/llmClient.ts，方便切换 mock / GMI Cloud，并为每个 Agent 生成可截图的 trace。

核心功能

• 中英文 UI 切换，默认保留英文产品感，同时支持中文评委阅读。
• 分析报告输出语言选择：English、简体中文。更多语言可作为真实模型模式下的后续扩展。
• UI language 与 Report language 明确分离：前者只控制页面静态文案，后者控制 Agent 生成报告内容。
• 切换 Report language 后，已有结果不会被自动翻译，页面会提示重新运行 Agent 生成对应语言版本。
• Timeline 和 Trace Panel 默认展示可读摘要，原始 JSON 通过折叠按钮查看，适合评委现场阅读和截图。
• Trace JSON 可下载，方便提交材料中说明 GMI 调用链路。
• MOCK_MODE=true 下支持英文和简体中文完整 mock 输出。
• MOCK_MODE=false 下通过 GMI Cloud Inference Engine 生成真实模型报告。
• 内置 36 条英文海外评论样例，覆盖自有产品和 4 个竞品。
• 页面包含 Input Panel、Agent Run Timeline、Insight Dashboard、Roadmap Output、Generated Assets、GMI API Trace Panel。
• 不包含违法爬虫，不绕过平台限制，只处理用户提供或导出的评论数据。

UI language 与 Report language

产品里有两套语言设置：

• UI language：控制按钮、标题、表格表头、状态、提示语等页面文案。切换后立即生效，不清空已有报告。
• Report language：控制 Agent 输出报告的语言。切换后如果已有报告，系统会保留旧报告并提示重新运行，避免误以为旧结果被自动翻译。

样例评论保持英文，是为了模拟真实海外用户评论来源。中文报告模式下会保留 Evidence quote 原始英文评论，并增加中文解读，方便中国评委理解评论背后的产品痛点，同时不丢失海外证据原文。

GMI Cloud Inference Engine 接入方式

调用链路：

UI -> /api/run-agent -> runReviewRadarPipeline -> completeWithLlm -> mockClient 或 gmiClient

真实模式下，src/lib/llm/gmiClient.ts 使用 OpenAI-compatible chat completions 请求：

{
  "model": "GMI_MODEL",
  "messages": [
    { "role": "system", "content": "agent system prompt" },
    { "role": "user", "content": "review data and JSON output contract" }
  ],
  "temperature": 0.2,
  "stream": false
}

API Key 只通过环境变量读取，不会显示在 UI、trace 或日志中。

Mock 模式与真实 GMI 模式

MOCK_MODE=true：

• 不发起真实 GMI Cloud 请求。
• 使用本地 deterministic mock response 跑通完整流程。
• Trace 面板显示 provider: mock。
• 适合赛前开发、录制 UI 预览、无 Key 演示。

MOCK_MODE=false：

• 每个 Agent 步骤都会调用 GMI Cloud Inference Engine。
• 需要配置 GMI_API_KEY、GMI_BASE_URL、GMI_MODEL。
• Trace 面板显示 provider: gmi。
• 比赛提交时需要配合 GMI Cloud 后台调用记录截图。

如何运行

npm install
npm run dev

打开：

http://localhost:3000

开发模式用于调试，会出现 Next.js 左下角 Dev Overlay，例如 Route / Try Turbopack / Preferences。这不是产品 UI，不需要翻译。

正式截图或录屏请使用生产模式：

npm run build
npm run start -- --port 3001

生产模式访问 http://localhost:3001，不会出现左下角 Dev Overlay。更多说明见 docs/start-guide.md。

生产构建验证：

npm run typecheck
npm run build
npm audit --audit-level=high

环境变量

从 .env.example 创建 .env.local：

MOCK_MODE=true
GMI_API_KEY=
GMI_BASE_URL=https://your-gmi-openai-compatible-base-url/v1
GMI_MODEL=your-gmi-model-name

比赛当天真实调用：

MOCK_MODE=false
GMI_API_KEY=your_real_gmi_key
GMI_BASE_URL=your_gmi_base_url
GMI_MODEL=your_selected_model

不要提交 .env.local，不要提交真实 API Key。

项目结构

src/app/page.tsx                  主界面，中英 UI 切换与报告输出语言选择
src/app/api/run-agent/route.ts    Agent pipeline API endpoint
src/components/                   页面功能面板
src/lib/i18n.ts                   轻量中英 UI 字典
src/lib/agent/pipeline.ts         7 Agent 编排逻辑
src/lib/agent/prompts.ts          Agent prompt 与输出语言约束
src/lib/llm/llmClient.ts          统一 LLM 适配层与 trace 生成
src/lib/llm/gmiClient.ts          GMI Cloud 真实调用 client
src/lib/llm/mockClient.ts         本地 mock 输出
src/lib/data/sampleReviews.ts     英文海外评论样例数据
src/lib/types.ts                  共享类型定义
docs/                             比赛提交材料说明

比赛评分项对齐

• API 调用质量 30 分：7 个 Agent 分步调用，统一 LLM 适配层，真实模式接入 GMI Cloud，每步生成 trace。
• 海外场景价值 25 分：聚焦出海 App / SaaS / 独立开发者，样例数据为英文海外评论，输出直接服务海外产品迭代。
• 产品完成度与可用性 25 分：无数据库、无登录依赖，sample data 可完整跑通，UI 清晰，文档和清单完整。
• 创新性与潜力 15 分：将竞品差评归因、机会识别、PRD、路线图和增长资产连接成一条 Agent 工作流。
• 社区投票 5 分：首屏明确，比赛契合度标签明显，适合截图和视频传播。

提交材料说明

建议提交时包含：

• 产品 Demo 视频：展示输入、运行 7 Agent、Dashboard、Roadmap、Generated Assets、Trace Panel。
• 产品截图：主界面、Agent Timeline、Insight Dashboard、Roadmap、Generated Assets、GMI Trace。
• GMI Cloud 后台截图：必须在 MOCK_MODE=false 后真实调用产生。
• 代码仓库链接：核心 GMI 调用代码可见。
• README 和 docs：中文主版本，保留英文产品摘要。

建议比赛当天分别生成两份报告：

• English 报告：体现面向海外产品团队的真实产品感。
• 简体中文报告：方便中国评委快速理解痛点、路线图和 GMI 调用价值。

生成方式：在 Input Panel 中切换 Output language，每切换一次都重新运行 Agent。切换后旧结果会保留，但页面会提示当前结果仍是旧语言。

安全与诚信说明

• 不提交真实 API Key。
• 不伪造 GMI Cloud 调用记录。
• 不把 mock trace 当作真实 GMI 后台证据。
• 不使用违法爬虫或绕过平台限制。
• 不改变 ReviewRadar Agent / 海外竞品差评猎手的核心方向。

English Summary

ReviewRadar Agent is an overseas competitor review intelligence agent for app, SaaS, and indie product teams. It turns English review exports from App Store, Google Play, G2, Capterra, Reddit, or CSV-like sources into pain points, competitor gaps, product roadmap, PRD brief, user stories, App Store replies, and growth copy. It supports local mock mode before the competition and real GMI Cloud Inference Engine calls on competition day.