卖家精灵亚马逊调研

它解决什么问题

亚马逊选品调研的痛点不是没有数据，而是数据散落在不同工具里，字段命名不统一，刻度混乱，而且很多工具的实际行为与文档描述不一致。

卖家精灵（SellerSprite）的网页版提供市场容量、品牌集中度、价格分布、关键词趋势、竞品流量、评论、Keepa 价格/BSR 历史等维度。当你试图把这些能力接入自动化流程或 Agent 工作流时，会遇到几个具体问题：

1. 响应需要二次解析 — MCP 返回的 result.content[0].text 是 JSON 字符串，不是对象，需要再 json.loads() 一次
2. 字段映射变化 — 网页 API 的 totalUnits 在 MCP 响应里叫 units，bsrRank 变成 bsr，reviews 变成 ratings（评分数，不是评分）
3. 参数模式混淆 — 有些工具要扁平参数 {marketplace, asin}，大部分要 request 嵌套对象 {request:{marketplace, asin}}，判断依据是 required 字段
4. 刻度混乱 — 集中度字段是 0~1 小数（展示需 ×100），returnRatio 已经是 0~100 百分数，supplyDemandRatio 是真实比值（如 78.88），三者不能混用
5. 实际响应与文档不一致 — keyword_research_trends 的趋势字段实际是 time/search，不是文档写的 month/searches；keepa_info 返回的是 buyBox/bsr 数组，没有 currentPrice/bsrHistory；traffic_source 需要扁平参数 +q，用 request 嵌套会返回 q is required
6. review 采样限制 — 无论 size 传多大，每次最多返回 20 条评论，评分分布只是样本
7. HTML 实体未解码 — 标题里的 &、" 会直接显示在报告里
8. 报告只打印到控制台 — 用户看不到，等于没做调研
9. 缺少可视化 — 只有 Markdown 表格，没有价格趋势图、BSR 折线、对比柱状图

技能如何工作

MCP 连接配置

密钥通过 header 传递，不是 URL 参数。正确配置：

{
  "url": "https://mcp.sellersprite.com/mcp",
  "headers": {
    "secret-key": "your_secret_key"
  }
}

错误做法：把密钥放在 URL 查询参数，或用 Authorization header，会触发 secret_invalid。

参数模式判断

调用工具前查看 required 字段：

• required=["marketplace","asin"] → 扁平参数
• required=["request"] → request 嵌套对象

工作流与命令

通过 /命令 触发多步骤调研：

• /product-research — 选品，组合 product_research + product_node
• /market-analysis — 市场全景，组合 market_research + 12 个分布工具
• /competitor-analysis — 竞品拆解，组合 asin_detail + traffic_keyword
• /keyword-research — 关键词选品，组合 keyword_research + keyword_miner
• /traffic-analysis — 流量结构，组合 traffic_source + traffic_keyword_stat
• /opportunity-finder — 蓝海机会，组合 aba_research_trend + google_trend
• /review-insights — 评论洞察，组合 review + NLP 分析
• /pricing-strategy — 定价分析，基于 market_price_distribution
• /ad-optimizer — 广告优化，组合 keyword_order + traffic_keyword

战术策略卡

对话中引用策略名称即可触发，例如：

• 新品爆发型：上架 ≤2 月 + 月销 ≥300 + Review ≤100
• 隐形爆款：上架 ≤3 月 + 月销 ≥500 + Review ≤50
• 流量分散关键词：搜索 ≥5000 + 集中度 5% + 新品仍出单
• 自然流量反查：自然流量占比 >60%
• 低质量 Listing 高销量：LQS ≤60 + 月销 ≥400

报告输出

调研完成后必须保存三份文件到 {类别名}/ 目录：

• market_report.md — 结构化 Markdown 报告
• research_data.json — API 原始返回数据
• market_report.html — HTML 可视化报告，基于 MD 数据自动生成，含 Canvas 图表

HTML 报告覆盖概览、销量、流量、关键词、竞争、市场、评论、价格、SWOT、行动建议等维度，深色主题，响应式布局，单文件纯 HTML+CSS+JS，无需额外 API 调用。

数据清洗流程

1. 解码 HTML 实体
2. 按实际响应字段提取数据
3. 处理 0~1 与 0~100 的刻度换算
4. 过滤父节点汇总行
5. 使用 nodeLabelPath 英文路径而非 nodeLabelLocale 中文翻译
6. 标注 ⚠️ 数据质量问题

适用边界与注意点

工具可靠性差异

不同工具的数据可信度不同：

• 可信：product_research、market_research、keyword_miner、traffic_keyword、traffic_listing、market_price_distribution、market_brand_concentration
• 有缺陷但可用：review（仅 20 条样本）、keepa_info（需正确提取数组最后一个值）、aba_research_trend（字段少）
• 可信度低：traffic_source（可能返回无关产品流量，建议用 traffic_keyword + traffic_keyword_stat 替代）
• 不可靠：keyword_research（忽略 keyword 参数，返回全局热词，相关性无法保证）

类目节点陷阱

必须使用叶子节点 nodeIdPath，父节点返回全 0 数据。

product_node 返回的 nodeLabelLocale 中文翻译经常出错：Microphones → 显微镜、Microphone Accessories → 辅料、Stands → 摊位。始终以 nodeLabelPath 英文完整路径为准。

混合类目问题

某些子类目混合了不同类型的商品（如 Electric Guitar Electronics 下既有 $5-15 电子元件，也有 $40+ 无线吉他系统），会导致价格分布两极分化、品牌集中度失真。需要手动标注真实竞品，单独圈定可比价格区间。

报告质量检查

保存前逐项检查：

• 标题和描述已解码 HTML 实体
• 至少调用 3 个以上工具交叉验证
• traffic_source 失败时有 fallback 方案
• keepa_info 调用后必须在报告中展示
• review 部分注明"仅 20 条样本"
• 高价值关键词列表排除品牌词和泛词
• 多变体销量汇总加 ⚠️ 注解
• ASIN 自身数据与搜索市场数据区分标注

多值参数处理

brands、sellers、fulfillment 等多值参数传逗号字符串，不是数组："brands": "Sony,Bose,JBL"

批量调用优化

市场全景分析需要调用 13 个工具（market_research + 12 分布工具），这些工具之间没有数据依赖，可以全部并行调用。

连接稳定性

• SSE 方案不可用：/sse 端点会因 CDN session affinity 导致 302/504 错误
• 必须使用 HTTP POST 到 /mcp
• Accept header 必须包含 application/json, text/event-stream