| name | market-research |
| description | 电商市场调研工具：爬取产品数据、清洗、生成深度分析报告、跨市场选品机会分析。支持 Amazon US / Amazon BR / Mercado Livre，任意品类关键词。触发：市场调研、竞品分析、选品分析、crawl products、market research、product research、cross-market、选品机会。 |
| metadata | {"openclaw":{"emoji":"📊","requires":{"bins":["python3"]}}} |
Market Research
端到端的电商市场调研与选品工具。支持多平台数据爬取、清洗富化、9 维度深度分析、跨市场选品机会挖掘。
系统架构
crawl.ts (统一入口, --pipeline full 串联全部阶段)
│
├── crawl → amazon-us.json / amazon-br.json / meli.json
├── clean → cleaned.json (30+ 字段/产品)
├── analyze → report.md (9 维度分析)
└── opportunity → opportunity-report.md (选品机会)
支撑模块:
crawlers/ → 平台爬虫 (amazon-us, amazon-br, meli)
brands/ → 品牌识别库 (drills, generic)
cost.ts → 成本估算引擎 (经验公式 + 1688 校准接口)
支持平台
| 平台 ID | 市场 | 爬取方式 | 用途 |
|---|
amazon-us | 美国亚马逊 | curl 搜索 + Camoufox 详情 | 北美热卖品对标 |
amazon-br | 巴西亚马逊 | curl 搜索 + Camoufox 详情 | 巴西市场竞品 |
meli | Mercado Livre | curl 搜索 + curl 详情 | 巴西市场竞品 |
每个爬虫分两阶段：
- 搜索阶段 — curl 请求搜索结果页，提取产品列表（ASIN、名称、价格、评分、评论数）
- 详情阶段 — 逐个访问详情页，提取高清图片、SKU 变体、完整规格
Amazon 详情页需 Camoufox 反检测浏览器；MeLi 详情页无反爬，直接 curl。
快速开始
跨市场选品全流程（推荐）
pnpm tsx {baseDir}/scripts/crawl.ts \
--keyword "cordless drill" \
--platforms amazon-us,amazon-br,meli \
--pipeline full
单市场分析
pnpm tsx {baseDir}/scripts/crawl.ts --keyword "furadeira eletrica" --pipeline full
分步执行
pnpm tsx {baseDir}/scripts/crawl.ts --keyword "fone bluetooth" --platforms amazon-br,meli --max 200
pnpm tsx {baseDir}/scripts/clean.ts --input /tmp/market-research-fone-bluetooth/ --brands auto
pnpm tsx {baseDir}/scripts/analyze.ts --input /tmp/market-research-fone-bluetooth/cleaned.json --output report.md
pnpm tsx {baseDir}/scripts/opportunity.ts \
--us-data /tmp/market-research-cordless-drill/amazon-us.json \
--br-data /tmp/market-research-fone-bluetooth/ \
--output opportunity-report.md
模块 1: crawl.ts — 数据爬取
统一入口，协调多平台爬取并串联后续管道。
pnpm tsx {baseDir}/scripts/crawl.ts --keyword <关键词> [选项]
| 参数 | 说明 | 默认值 |
|---|
--keyword <text> | 搜索关键词（必填） | — |
--platforms <list> | 逗号分隔的平台列表 | amazon-br,meli |
--max <n> | 每个平台最大爬取数量 | 300 |
--output-dir <path> | 输出目录 | /tmp/market-research-<slug>/ |
--pipeline <stage> | 执行阶段 | crawl |
--country <code> | 国家代码 | br |
--proxy <url> | 代理地址（可选） | — |
管道阶段 (--pipeline)
| 阶段 | 说明 | 前置条件 |
|---|
crawl | 仅爬取，输出原始 JSON | — |
clean | 仅清洗 | 需已有爬取数据 |
analyze | 仅分析 | 需已有清洗数据 |
opportunity | 仅跨市场选品分析 | 需已有 US+BR 数据 |
full | 全部串联: crawl → clean → analyze → opportunity | — |
爬虫注册机制：crawlerRegistry 使用动态导入按需加载。新增平台只需实现 CrawlerModule 接口并注册到 registry。
模块 2: clean.ts — 数据清洗
将多平台原始数据统一清洗、去重、富化为标准化格式。
pnpm tsx {baseDir}/scripts/clean.ts --input <目录> [--brands <类目>] [--output <文件>]
| 参数 | 说明 | 默认值 |
|---|
--input <dir> | 含原始 JSON 的目录 | 必填 |
--brands <category> | 品牌库选择 | auto |
--output <file> | 输出路径 | <input>/cleaned.json |
清洗流程
- 数据加载 — 扫描目录所有
*.json，从文件名自动识别来源平台
- 相关性过滤 —
drills 按电钻关键词过滤；auto 过滤名称过短或 UI 伪影
- 去重 — 产品名归一化后去重（前 60 字符，去特殊字符，小写化）
- 品牌识别 — 匹配品牌库模式 → 未命中取首词 → 未知标记 "Unknown"
- 产品分类 — 提取类型、动力源、电压、功率、卡盘尺寸等结构化字段
- 价格解析 — 支持
R$ 1.234,56 / $123.45 多格式，标记异常低价和缺失
- 供应链归类 — 中国品牌/贴牌、疑似中国贴牌、巴西本土、国际品牌、未知来源
- 重量估算 — 按产品类型 + 配件（工具箱 +1kg、大功率 +1kg）
输出字段 (CleanedProduct, 30+ 字段)
name, source, brand, type, power_source, voltage, wattage, chuck_size,
is_professional, has_case, price, price_numeric, price_suspect, price_missing,
original_price, discount_pct, rating, rating_numeric, reviews, sold,
images[], image_count, link, skus[], sku_count, supply_chain, weight_estimate_kg
模块 3: analyze.ts — 9 维度深度分析
基于清洗数据生成深度分析报告（Markdown，含 ASCII 图表和表格）。
pnpm tsx {baseDir}/scripts/analyze.ts --input <文件> [--output <文件>]
| 参数 | 说明 | 默认值 |
|---|
--input <file> | 清洗后的 JSON 文件 | 必填 |
--output <file> | 报告输出路径 | ./market-analysis-report.md |
分析维度
| # | 维度 | 分析内容 |
|---|
| 1 | 市场概览 | 平台对比、价格摘要、产品类型分布、数据质量评估 |
| 2 | 价格分析 | 分布直方图、动态分层 (p25/p50/p75)、平台价差、折扣分布 |
| 3 | 品牌竞争格局 | 市场份额 Top 15、价格x评分四象限矩阵、SKU 丰富度排名 |
| 4 | 产品特征 | 电压/功率/卡盘分布、配件对价格影响（自动检测有意义特征字段） |
| 5 | 图片质量 | 图片数量分布、图片数与评分相关性分析 |
| 6 | 供应链 | 中国/国际/本土占比、OEM 模式识别、来源x价格交叉分析 |
| 7 | FBA 与物流 | 基于重量的成本估算、自配送 vs FBA 对比、重量区间分布 |
| 8 | 季节性 | 巴西市场日历、关键促销节点 (Black Friday、圣诞、母亲节) |
| 9 | 选品矩阵 | 蓝海机会识别、推荐产品画像、入场建议 |
智能特征检测：detectFeatureFields() 自动扫描数据中哪些字段有足够多样性值得分析，避免通用品类输出无意义维度。
模块 4: opportunity.ts — 跨市场选品机会分析
核心选品模块，对比北美热卖品与巴西市场现状，挖掘两类机会。
pnpm tsx {baseDir}/scripts/opportunity.ts --us-data <文件> --br-data <目录> [--output <文件>]
| 参数 | 说明 | 默认值 |
|---|
--us-data <file> | Amazon US 爬取的 JSON 文件 | 必填 |
--br-data <dir> | 含 BR 平台 JSON 的目录 | 必填 |
--output <file> | 选品报告输出路径 | <br-data>/opportunity-report.md |
策略 A: 北美爆品 x 巴西空白
产品在北美已被市场验证（高销量 + 高评分），但巴西还没人做或竞争很弱 → 蓝海机会。
算法：
- US 数据筛选热卖品：评论数 > 500 且评分 >= 4.0
- 对每个热卖品，在 BR 数据中搜索同类竞品：
- 品牌匹配（不区分大小写）
- 关键词重叠 > 40%（去停用词后）
- 按竞争程度分级：
| 等级 | 条件 | 建议动作 |
|---|
| ⭐⭐⭐ | BR 无同类竞品 | 立即切入 |
| ⭐⭐ | BR 有 1-5 个竞品，平均评论 < 50 | 差异化切入 |
| ⭐ | BR 竞争充分 | 转入策略 B |
策略 B: 巴西滞销品 x 降价切入
巴西有人卖但卖不动，如果滞销原因是价格太高，降价后可能有利可图。
算法：
- BR 数据筛选滞销品：评论数 < 20 且价格 > 同平台 p75
- 诊断滞销原因：
- 价格过高（> 中位价 x 1.5）
- 图片不足（< 3 张）
- 缺少 SKU 变体（sku_count = 0 而同类有多 SKU）
- 建议定价 = 畅销品（评论 >= 50）中位价 x 0.85
- 调用 cost.ts 估算建议定价下的成本和利润
- 按利润空间分级：
| 等级 | 条件 | 含义 |
|---|
| ⭐⭐⭐ | 建议定价 > 总成本 x 2 | 利润丰厚 |
| ⭐⭐ | 建议定价 > 总成本 x 1.5 | 有利可图 |
| ⭐ | 建议定价 < 总成本 x 1.5 | 利润空间小 |
模块 5: cost.ts — 成本估算引擎
跨境电商全链路成本估算（中国 → 巴西），供 opportunity.ts 调用。
总成本 = 出厂价 + 海运物流 + 进口关税 + FBA 配送费
利润 = 售价 - 总成本 - 平台佣金
成本项
| 成本项 | 计算方式 |
|---|
| 出厂价 | 售价 x 出厂价系数（按供应链来源） |
| 海运物流 | 重量(kg) x R$8/kg |
| 进口关税 | 出厂价 x 60% (ICMS + II) |
| FBA 费用 | 按重量分级: ≤1kg R$15.9, ≤2kg R$19.9, ≤5kg R$25.9, ≤10kg R$35.9, >10kg R$55.9 |
| 平台佣金 | 售价 x 16% |
出厂价系数
| 供应链来源 | 系数 | 说明 |
|---|
| 中国品牌/贴牌 | 20% | 白牌/OEM 成本最低 |
| 疑似中国贴牌 | 25% | 品牌溢价略高 |
| 巴西本土品牌 | 40% | 本土制造+品牌溢价 |
| 国际品牌 | 50% | 品牌授权+全球定价 |
| 未知来源 | 30% | 保守估算 |
API
estimateCost(product) — 按当前售价估算全链路成本estimateCostAtPrice(targetPrice, product) — "如果卖 X 价，利润多少？"formatCostSummary(estimate) — 格式化为一行可读摘要
1688 校准接口：预留 CostCalibration，未来接入 1688 爬虫可用实际出厂价替代经验公式，置信度从 medium 升级到 high。
品牌识别系统
位于 scripts/brands/，可插拔设计。
| 品牌库 | 说明 | 品牌数 |
|---|
drills | 电钻专用: Bosch, DeWalt, Makita 等 | 40+ |
generic | 通用消费品牌: Samsung, Apple, Xiaomi | 48 |
识别流程：品牌库模式匹配 → 首词提取（排除产品词） → Unknown 兜底。
扩展：创建 scripts/brands/<category>.ts 导出 BrandEntry[]，在 scripts/brands/index.ts 注册。
输出文件
<output-dir>/
├── amazon-us.json # US 原始爬取数据
├── amazon-br.json # BR Amazon 原始爬取数据
├── meli.json # Mercado Livre 原始爬取数据
├── cleaned.json # 清洗后统一格式数据 (30+ 字段/产品)
├── report.md # 9 维度深度分析报告
└── opportunity-report.md # 跨市场选品机会报告 (策略 A + B)
扩展: 添加新平台
- 创建
scripts/crawlers/<platform-id>.ts，实现 CrawlerModule 接口
- 在
scripts/crawl.ts 的 crawlerRegistry 注册
- 在
references/platform-notes.md 记录技术备注
import type { CrawlerModule, CrawlOptions, RawProduct } from "./types.ts";
export const myPlatform: CrawlerModule = {
name: "my-platform",
crawl: async (opts: CrawlOptions): Promise<RawProduct[]> => {
return [];
},
};
环境要求
- Node.js 22+
- Python 3 3.8+ (HTML 解析)
- Camoufox — Amazon 详情页反检测浏览器:
pip install camoufox && python -m camoufox fetch
注意事项
- 反爬限速：搜索页 2s，详情页 1s 延迟
- 带宽：300 产品 x 2 平台约 0.5-1 GB（Camoufox 屏蔽图片/字体/样式/跟踪）
- Amazon 详情页按 50 ASIN 为一批处理，避免浏览器长运行
- 代理成本：住宅代理约 $2-4/次
- 成本估算基于经验公式（confidence: medium），接入 1688 后可提升
- MeLi API 返回 403，只能页面爬取
