product-research

选品分析器 (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", "JLab"],
        "brand_opportunity": "有14.2mm大动圈供应链",
        "product_solution": "14.2mm动圈+音量增强模式"
      }
    ],
    "summary": "主要痛点集中在音质(32%)、舒适度(28%)、续航(18%)"
  }
}

禁止的输出方式：

• ❌ 按 ASIN 组织：{"B0XXX": {"reviews": [...]}}
• ❌ 缺少频次/占比数据
• ❌ 缺少品牌机会和产品方案映射

Step 5: 評価と意思決定

参入障壁の評価：

障壁の種類	レベル	データの根拠	推定コスト	緩和策
レビューの障壁	中/高	Top10 の平均 XXX 件のレビュー	$XXX	Vine + PPC
資金の障壁	中/高	初回在庫 + 広告	¥XX	初回 MOQ を管理
...	...	...	...	...

商品選定の意思決定評価（5つの評価軸）：

評価軸	重み	評価（1-10）	加重スコア	根拠
市場規模	20%	[LLM による評価]	X.X	[データの根拠]
競争環境	25%	[LLM による評価]	X.X	[データの根拠]
...	...	...	...	...
合計スコア	100%	-	X.XX	意思決定の結論

意思決定の結論とスコアの対応：

• 7.5-10点 → 参入を推奨（優先的に推進）
• 6.0-7.4点 → 慎重な参入を推奨（正確なポジショニングと明確な参入条件が必要）
• 4.0-5.9点 → 当面は見送り（さらなるデータ検証が必要）
• 0-3.9点 → 参入を推奨しない（機会よりもリスクが大きい）

商品マトリックス（Tier 1 は具体的な仕様の記載が必須）：

### Tier 1: [产品定位]

**目标市场**：[维度组合空白/机会]
**决策理由**：[数据依据]

| 维度 | 规格 | 决策依据 |
|------|------|----------|
| [维度1] | [具体值] | [为什么] |
| [维度2] | [具体值] | [为什么] |

**目标定价**：$XX.XX
**差异化主张**：[一句话]
**对标竞品**：[ASIN] — [我们的优势]
**预估月销潜力**：XX-XX 件

Step 6: レポートの出力

出力ファイル：

product-research-reports/
└── {category}_{site}_{YYYYMMDD}/
    ├── report.md              # Markdown 完整报告（LLM 直接输出）
    ├── data.json              # 结构化数据（供 Dashboard 使用）
    ├── dashboard.html         # 可视化看板（脚本渲染）
    └── raw/                   # 数据文件
        ├── category_info.json # 类目信息
        ├── top100.json        # Top100 产品数据
        ├── trend.json         # 趋势数据
        └── keywords.json      # 关键词数据

data.json の構造（簡易版）：

{
  "metadata": {
    "category": "bluetooth speaker",
    "site": "US",
    "date": "20260319"
  },
  "market_overview": {
    "top100_monthly_sales": 55000,
    "top100_monthly_revenue": 5200000,
    "avg_price": 95,
    "top3_product_concentration": 0.2578,
    "top3_brand_concentration": 0.5058,
    "top10_brand_concentration": 0.8234
  },
  "dimensions": [...],
  "cross_analysis": [...],
  "competitors": [...],
  "voc_analysis": {
    "dimensions": [
      {
        "dimension": "音质/音量",
        "pain_point": "音量太小，户外听不清",
        "frequency": 45,
        "percentage": "32%",
        "affected_brands": ["SHOKZ", "JLab"],
        "brand_opportunity": "采用更大驱动单元",
        "product_solution": "14.2mm动圈+音量增强模式"
      }
    ],
    "summary": "主要痛点集中在音质(32%)、舒适度(28%)、续航(18%)"
  },
  "barriers": [...],
  "go_nogo": {...}
}

⛔ 重要：データフィールドの命名規則

フィールド名	説明	例
top3_product_concentration	Top3 商品の販売数が Top100 の総販売数に占める割合	0.2578 = 25.78%
top3_brand_concentration	Top3 ブランドの販売数が Top100 の総販売数に占める割合	0.5058 = 50.58%
top10_brand_concentration	Top10 ブランドの販売数が Top100 の総販売数に占める割合	0.8234 = 82.34%
new_product_share	新商品の販売数の割合（販売開始から6か月未満）	0.26 = 26%

曖昧な命名は禁止：

• ❌ top3_concentration（商品かブランドか不明確）
• ✅ top3_product_concentration または top3_brand_concentration

⛔ 重要：VOC 分析のデータ構造

voc_analysis フィールドには、ASIN ごとではなく、評価軸ごとに分類した低評価レビューの分析を含める必要があります：

フィールド	型	説明
dimension	string	課題の評価軸（例：音質/音量、装着感、バッテリー持続時間など）
pain_point	string	課題の説明
frequency	number	言及頻度
percentage	string	割合（例："32%"）
affected_brands	array	該当するブランドの一覧
brand_opportunity	string	ブランド/サプライチェーンの能力でどのように解決できるか
product_solution	string	具体的な製品の改善案

---

ダッシュボードのレンダリング規則

render_dashboard.py は data.json を可視化ダッシュボードにレンダリングします。主なレンダリング規則：

製品属性の分布

• 必ず表形式を使用し、棒グラフは使用禁止
• 2列レイアウト：左側に価格帯の分布、右側に製品形態の分布
• 各行に表示する項目：評価軸の値、商品数、割合（色付きラベル）
• 割合ラベルの色の規則：≥30%は青、≥20%は緑、≥10%は黄、<10%はグレー

クロス分析（価格帯 × 製品形態）

• 必ずマトリックス形式の表を使用し、グラフは使用禁止
• 行：価格帯（$0-30 から $200+）
• 列：製品形態（骨伝導、イヤーカフ型、オープンイヤー型イヤーフック、カナル型）
• セル：商品数
• 特別なマーク：
  • 競争が激しい（≥15商品）：赤色の「レッドオーシャン」ラベル
  • 市場の空白（0商品）で、かつ機会点となる場合：緑色の「機会」ラベル
• 下部に必ずインサイトのボックスを設け、レッドオーシャンと機会の領域を説明

出力例

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 24px;">
  
  
</div>


<table>
  <thead></thead>
  <tbody></tbody>
</table>
<div class="insight-box">洞察：...</div>

---

LLM プロンプトテンプレート集

詳細なプロンプトテンプレートは references/prompt_templates.md を参照してください。

6つのテンプレートが含まれます：

1. 属性のラベリング - 商品タイトルから差別化要因を抽出
2. クロス分析 - 需要と供給のギャップを発見
3. 競合商品の選定 - 代表的な競合商品を選定
4. 低評価レビューの分類 - 属性の評価軸ごとに課題を分類
5. 商品選定の意思決定評価 - 5つの評価軸による加重評価
6. 商品マトリックスの計画 - Tier 1/2/3 の具体的な仕様

---

必須ルール（⛔ 省略不可）

1. ⛔ Top100 は100件すべてを含めること
2. ⛔ キーワードは少なくとも3つの評価軸で比較すること
3. ⛔ 競合商品を6-10個選び、販売量の基準となる商品/機能の違い/価格帯/課題を網羅すること
4. ⛔ 低評価レビューは評価軸ごとに分類すること（ASIN ごとの分類は禁止）。結果は data.json の voc_analysis フィールドに出力すること
5. ⛔ VOC 分析には、頻度、割合、該当するブランド、ブランドの機会、製品の解決策を含めること
6. ⛔ 商品選定の意思決定評価は、定量的にスコアを付けること
7. ⛔ Tier 1 商品は具体的な仕様まで記載すること（「確認待ち」のプレースホルダーは禁止）
8. ⛔ 各データ表の後に「主なインサイト」の段落を設けること
9. ⛔ 市場の空白/供給の薄さには、原因分析を必ず添えること
10. ⛔ データフィールド名は明確にすること：top3_product_concentration / top3_brand_concentration を使用し、曖昧な top3_concentration は使用禁止
11. ⛔ データの整合性を検証すること：レポート生成前に、data.json 内の数値とレポート本文が一致しているか検証すること

---

よくあるシナリオの戦略

シナリオ1：初心者向け（予算<15万）

• 価格 $10-20
• 小型軽量の商品
• アフターサービスのリスクなし
• 中国の販売者の割合 > 70%

シナリオ2：ブルーオーシャンの発見

• Top3 集中度 < 30%
• 新商品の割合 > 15%
• 検索結果1ページ目のキーワードのレビュー数 < 500

シナリオ3：指定カテゴリーの分析（ユーザーが指定済み）

• カテゴリーのスキャンを省略し、データ収集に直接進む
• ⛔ 属性のラベリングを必ず実施すること
• ⛔ クロス分析を必ず実施すること
• ⛔ 商品選定の意思決定評価（5つの評価軸による評価）を必ず実施すること

---

他の Skills との関係

category-selection (品类筛选五维评分)
        ↓
product-research (深度选品调研) ← 本 Skill
        ↓
amazon-analyse (竞品 Listing 深挖)
        ↓
review-analysis (评论深度分析)

違い：

• category-selection：カテゴリー単位の迅速な絞り込み。5つの評価軸で評価
• product-research：指定カテゴリーの詳細調査。多角的な分析 + 商品選定の意思決定評価
• amazon-analyse：単一の競合商品の Listing を詳細に分析
• review-analysis：レビューに基づく課題の詳細分析

---

対応サイト

US, GB, DE, FR, IT, ES, CA, JP, MX, AE, AU, BR, SA

---

注意事項

1. API Key：.mcp.json から自動的に読み込みます
2. データの鮮度：Sorftime のデータには1-7日程度の遅延が発生する場合があります
3. API のレート制限：1バッチあたりの同時リクエスト数は最大8件です
4. エンコーディングの問題：スクリプトが Unicode-escape と Mojibake を自動的に処理します
5. 生データ：検証用に、すべての API レスポンスが raw/ ディレクトリに保存されます

---

トラブルシューティング

常见错误及解决方案

错误信息	原因	解决方案
HTTP Error 406: Not Acceptable	API参数错误	检查参数名是否为 searchName 而非 productName
An error occurred invoking 'xxx'	API工具不存在	检查 TOOLS 映射表中的工具名称
未查询到对应产品	ASIN无效或站点错误	验证ASIN格式, 确认产品在该站点销售
Authentication required	API Key错误	检查 .mcp.json 中的 key 参数
中文乱码	Mojibake编码	脚本自动修复, 或运行 fix_encoding.py
IndentationError: unexpected indent	Windows 命令行问题	使用脚本文件而非 python -c
输出目录路径错误	相对路径问题	使用 run_analysis.py，自动处理路径
NameError: name 'xxx' is not defined	缺少 datetime 导入	检查脚本 import 语句
Dashboard 渲染问题
Dashboard 显示空白	data.json 结构不匹配	v3.5 已修复：run_analysis.py 自动渲染 Dashboard
Dashboard 未自动生成	旧版本未集成渲染	v3.5 已修复：数据采集完成后自动渲染
PermissionError: [Errno 13]	传递目录路径而非文件路径	使用绝对路径调用：python render_dashboard.py -o output.html data.json
unrecognized arguments	参数顺序错误	正确格式：python render_dashboard.py -o dashboard.html data.json
Dashboard 缺少 VOC 数据	LLM 未生成完整 voc_analysis	确保 LLM 生成包含 voc_analysis.dimensions 的完整 data.json
Dashboard 交叉分析为空	price_type_matrix 数据缺失	确保数据采集包含价格区间分析
KeyError: 'xxx'	字段名不一致	v3.4 已修复：支持新旧字段名兼容
AttributeError: 'str' object has no attribute 'get'	data.json 格式问题	v3.4 已修复：自动转换为列表格式

Dashboard 手动渲染方法

如果自动渲染失败，可以手动调用：

# 从输出目录调用
python .claude/skills/product-research/scripts/render_dashboard.py \
    -o product-research-reports/{keyword}_{site}_{date}/dashboard.html \
    product-research-reports/{keyword}_{site}_{date}/data.json

# 或者使用绝对路径
python "D:\amazon-mcp\.claude\skills\product-research\scripts\render_dashboard.py" \
    -o "D:\amazon-mcp\product-research-reports\{keyword}_{site}_{date}\dashboard.html" \
    "D:\amazon-mcp\product-research-reports\{keyword}_{site}_{date}\data.json"

API 工具名称对照表

功能	工具名称	参数
类目搜索	category_name_search	amzSite, searchName
类目报告	category_report	amzSite, nodeId
类目趋势	category_trend	amzSite, nodeId, trendIndex
关键词详情	keyword_detail	amzSite, keyword
产品详情	product_detail	amzSite, asin
产品评论	product_reviews	amzSite, asin, reviewType

调试技巧

1. 启用详细输出: 在脚本中添加 print() 调试信息
2. 检查原始响应: 查看 SSE 响应的实际内容
3. 分步执行: 使用 Python 交互式环境逐行调试
4. 验证API Key: curl "https://mcp.sorftime.com?key=YOUR_KEY" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

---

版本: v3.6 (两阶段工作流 + 数据验证) | 最后更新: 2026-03-19