/product-research

name: product-research
description: 基于Sorftime MCP的深度选品调研。通过LLM Agent执行多维度分析：数据采集→属性标注→交叉分析→竞品VOC→壁垒评估→选品决策评估。交互式执行，输出Markdown报告和Dashboard看板。
argument-hint: "[产品/类目关键词] [站点]"
user-invocable: true

选品分析器 (Product Research - LLM Agent 驱动版)

定位

基于 **Sorftime MCP + LLM Agent** 的深度选品调研。LLM 直接执行分析逻辑，脚本仅负责数据采集和报告渲染。

**核心特点**：

• **LLM 驱动**：分析、洞察、决策全部由 LLM 完成
• **交互式执行**：逐步推进，用户可中途干预
• **轻量脚本**：仅用于 API 调用和 Dashboard 渲染

---

Script Directory

| 脚本 | 用途 | 何时调用 | |------|------|---------| | `run_analysis.py` | **主入口脚本**：整合数据采集、分析、报告生成 | 推荐使用 | | `collect_data.py` | Sorftime 数据采集（类目、Top100、关键词、趋势） | Step 1 | | `get_reviews.py` | 竞品差评数据采集 | Step 4 | | `api_client.py` | Sorftime API 调用 + SSE 解析 + 编码修复 | 每次 API 调用 | | `render_dashboard.py` | 生成 Dashboard 可视化看板（v3.1 修复版） | 报告生成阶段 | | `fix_data_json.py` | **数据验证和修复脚本**：校验并自动修复 data.json | Dashboard 生成前 | | `validate_data.py` | **数据验证脚本**：校验 data.json 字段命名和数据一致性 | 报告生成前 |

**脚本职责**：

• **不做分析判断**：所有分析由 LLM 完成
• **不做复杂计算**：交叉分析让 LLM 从数据中发现
• **仅做数据搬运**：API → 结构化数据

**推荐使用方式**：

# 阶段1：数据采集（基础版 Dashboard）
python scripts/run_analysis.py "earbuds" US

# 阶段2：LLM 分析完成后，生成最终版报告
python scripts/run_analysis.py "earbuds" US --final

# 其他选项
python scripts/run_analysis.py "earbuds" US --collect-only  # 仅数据采集
python scripts/run_analysis.py "earbuds" US --no-reviews     # 跳过差评采集

---

执行流程（两阶段）

**重要**：选品分析分为两个阶段，数据采集由脚本自动完成，LLM 分析需要人工参与。

阶段1：数据采集（脚本自动）

python scripts/run_analysis.py "keyword" US

**输出**：

• `data.json` - 基础数据结构（不含分析结论）
• `dashboard.html` - 基础版看板（不含决策评分、VOC 等）
• `raw/` - 原始数据文件

**脚本自动完成**： 1. 类目搜索 → 获取 nodeId 2. Top100 产品数据采集 3. 关键词数据采集 4. 类目趋势数据采集 5. 竞品差评采集 6. 市场分析（价格区间、品牌分布）

阶段2：LLM 分析（交互式）

**必须完成的 LLM 分析任务**：

| 步骤 | 任务 | 输出到 data.json | |------|------|------------------| | 1 | 属性标注 | `product_types`、`dimensions_analysis` | | 2 | 交叉分析 | `cross_analysis` | | 3 | VOC 分析 | `voc_analysis.dimensions` | | 4 | 壁垒评估 | `barriers` | | 5 | 决策评估 | `decision` (overall_score, verdict) |

**完成后运行**：

python scripts/run_analysis.py "keyword" US --final

`--final` 参数会： 1. ✅ 验证分析数据完整性 2. ✅ 更新 data.json 3. ✅ 生成完整版 Dashboard（含决策评分、VOC 等） 4. ✅ 如果数据不完整，会提示缺失的字段

数据完整性检查

也可以单独检查数据完整性：

python scripts/render_dashboard.py data.json --check

输出示例：

✓ 数据完整，可以渲染完整版 Dashboard
  包含: decision.overall_score, voc_analysis.dimensions, barriers, cross_analysis

或

⚠️ 数据不完整，缺少以下字段:
  - decision.overall_score
  - voc_analysis.dimensions

ℹ️ 请先完成 LLM 分析，然后重新运行渲染

---

执行流程（交互式）

Step 0: 信息收集

📋 选品分析 - 信息确认

1. 产品/类目关键词：[用户提供]
2. 目标站点：[US/GB/DE/FR/IT/ES/CA/JP，默认US]
3. 选品场景：[新手入门/蓝海发现/季节性/品牌打造/定向品类]
4. 约束条件（可选）：
   - 价格区间：如 $10-40
   - 月销量：如 > 1000
   - 预算：如 10万人民币

Step 1: 数据采集（增强版 v3.0）

**API 调用顺序**：

| 步骤 | API | 输出 | 说明 | 优先级 | |------|-----|------|------|----------| | 0.5 | `search_categories_broadly` | blue_ocean_categories.json | **【新增】蓝海市场发现** | 📋 按需 | | 1.1 | `category_name_search` | category_info.json | 按产品名搜索类目（使用 searchName 参数） | ⛔ 必调 | | 1.2 | `category_report` | top100.json | Top100 产品数据 | ⛔ 必调 | | 1.3 | `keyword_detail` × 3+ | keywords.json | 多维度关键词对比 | ⛔ 必调 | | 1.4 | `category_trend` | trend.json | 新品占比趋势 | ⛔ 必调 | | 1.5 | `keyword_extends` | keyword_extends.json | **【新增】关键词延伸词（维度发现）** | 📋 推荐 | | 1.6 | `potential_product` | potential_products.json | **【新增】潜力产品发现** | 📋 推荐 | | 1.7 | `product_detail` × 6-10 | products.json | 竞品详情（按需） | 📋 按需 | | 1.8 | `product_reviews` × 6-10 | reviews.json | 竞品差评（按需） | 📋 按需 |

**⚠️ 重要：API 参数说明（v3.0）**

• `category_name_search` 参数：`{"amzSite": "US", "searchName": "bluetooth speaker"}`
• **正确的类目搜索 API，参数名是 searchName**
• `search_categories_broadly` 参数（蓝海发现）：`{"amzSite": "US", "top3Product_sales_share": 0.4}`
• `potential_product` 参数（潜力产品）：`{"amzSite": "US", "monthlySales_min": 500}`
• `keyword_extends` 参数（延伸词）：`{"amzSite": "US", "keyword": "bluetooth speaker"}`
• `category_report` 参数：`{"amzSite": "US", "nodeId": "7073956011"}`
• **nodeId 是字符串类型**

**脚本调用方式**：

# 方法1: 使用 collect_data.py (推荐)
from scripts.collect_data import collect_data
result = collect_data("bluetooth speaker", "US")

# 方法2: 使用 api_client.py
from scripts.api_client import SorftimeClient

client = SorftimeClient()

# 获取类目ID（正确的方式）
category = client.search_category_by_product_name("US", "bluetooth speaker")
node_id = category[0]['nodeId']

# 获取Top100
top100 = client.get_category_report("US", node_id)

# 获取关键词详情
keywords = client.get_keyword_detail("US", "bluetooth speaker")

Step 2: 属性标注（LLM 驱动）

**LLM 任务**：从 Top100 标题中提取关键差异化维度

## 属性标注任务

基于以下 Top100 产品标题，提取 3-6 个关键差异化维度：

### 标题样本
[提供 Top20-30 标题作为样本]

### 提取要求
1. 识别差异化维度（如：功率、防水、续航、形态等）
2. 为每个产品标注维度值
3. 标注置信度（高/中/低）

### 输出格式
| ASIN | 功率 | 防水 | 续航 | ... | 置信度 |

**对低置信度产品**：调用 `product_detail` 补充验证

Step 3: 交叉分析（LLM 直接发现）

**LLM 任务**：从标注数据中发现供需缺口

## 交叉分析任务

基于以下已标注的 Top100 产品数据，执行交叉分析：

### 数据
[提供标注后的产品数据]

### 分析要求
1. 选择 2-3 对有意义的维度组合（如：功率×价格、防水×场景）
2. 识别：空白点（0产品）、薄供给（≤2产品）、高需求低供给
3. 分析每个缺口的原因（技术限制？需求不存在？被忽视？）
4. 按机会价值排序

### 输出格式
| 维度组合 | 状态 | 产品数 | 月销量 | 原因分析 | 机会评级 |

**关键点**：让 LLM 直接从数据中发现规律，而不是用 Python 脚本计算

Step 4: 竞品与 VOC 分析

**竞品选择逻辑表**（LLM 按细分段选择）：

| ASIN | 品牌 | 选择理由 | 类型 | 覆盖维度 | |------|------|----------|------|----------| | [LLM 选择 6-10 个代表性竞品] |

**⛔ 差评维度归类（关键步骤）**

**必须按维度归类，禁止按 ASIN 组织**

**LLM 任务**：将竞品差评按属性维度归类，并映射到品牌能力和产品方案

**输入**：`competitor_reviews.json`（按 ASIN 组织的原始差评） **输出**：`data.json` 中的 `voc_analysis` 字段（按维度归类）

**归类要求**： 1. **识别主要维度**（3-6 个）- 基于差评内容提取痛点类别 2. **每个维度包含**：

• `dimension`: 维度名称（如：音质/音量、舒适度、续航）
• `pain_point`: 痛点描述
• `frequency`: 提及频次
• `percentage`: 占比（如 "32%"）
• `affected_brands`: 涉及品牌列表
• `brand_opportunity`: 品牌/供应链能力如何解决
• `product_solution`: 具体产品改进方向

**输出格式示例**：

{
  "voc_analysis": {
    "dimensions": [
      {
        "dimension": "音质/音量",
        "pain_point": "音量太小，户外听不清",
        "frequency": 45,
        "percentage": "32%",
        "affected_brands": ["SHOKZ", "JL