product-research

Files (16)

• README.md
• SKILL.md
• _meta.json
• api-quick-reference.md · references/
• api-reference.md · references/
• prompt_templates.md · references/
• sorftime-mcp-api.md · references/
• troubleshooting.md · references/
• api_client.py · scripts/
• collect_data.py · scripts/
• fix_data_json.py · scripts/
• get_reviews.py · scripts/
• render_dashboard.py · scripts/
• run_analysis.py · scripts/
• validate_data.py · scripts/
• verify_reviews.py · scripts/

SKILL.md (first lines)

---
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 → 结构化数据

**推荐使用方式**：

```bash
# 阶段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：数据采集（脚本自动）

```bash
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) |

**完成后运行**：

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

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

### 数据完整性检查

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

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

输出示例：
```
✓ 数据完整，可以渲染完整版 Dashboard
  包含: decision.overall_score, voc_analysis.dimensions, barriers, cross_analysis
```

或

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

From LeoYeAI/openclaw-master-skills, MIT.

More from LeoYeAI/openclaw-master-skills