通过 MCP 工具程序化抓取 Amazon 商品/关键词/类目/卖家/榜单/评论数据。
文档
pangolinfo-amazon-product-explorer
试用Use when: user asks "what should I sell" / "find a blue-ocean niche" / "is X category worth entering" / "I want to launch a new product in Y" / "从 0 到 1 选品"...
它能做什么
Use when: user asks "what should I sell" / "find a blue-ocean niche" / "is X category worth entering" / "I want to launch a new product in Y" / "从 0 到 1 选品" / "新品立项". Covers: GTM scouting SOP — external demand → niche filter → benchmark products → review pain mining → IP clearance → final go/no-go report. NOT for: daily monitoring or rank tracking (use amazon-daily-competitor-radar) / writing Listing copy (use amazon-listing-optimization) / single ASIN lookup (call get_amazon_product directly).
技能文档
Amazon GTM 选品 SOP
跑前必读:本文件末尾《核心规则 / Core Rules》章节(已内联,自包含)。 角色:Amazon 增长顾问 + 数据咨询师。用硬数据出 go/no-go 判断,不出凑数 niche。
用户触发与档位识别
Fast 档(默认,≤90s):
- "X 方向能做什么"
- "我想做 Y 类目,先研究一下"
- "看看 wireless earbuds 有没有机会"
Full 档(用户明示,≤5min):
- "深度选品报告"
- "完整 GTM 策略"
- "详细分析 X 类目,包括差评和 IP"
单工具直通(不跑 SOP):
- "查一下 ASIN B0XXX" →
get_amazon_product - "X 类目热销榜" →
list_bestsellers
Fast 档 SOP(5 回合 ≤ 90s)
每回合 ≤ 2 并发(实测 2026-05-28:3 并发会触发后端业务码 9200 "no content")。
回合 1 (5s) search_categories ← 拿 browseNodeId
回合 2 (5s) filter_niches | keyword_trends ← 2 并发
回合 3 (5s) search_amazon | list_new_releases ← 2 并发
回合 4 (5s) get_amazon_product(A1) | get_amazon_product(A2) ← 2 并发
回合 5 (5s) get_amazon_product(A3) ← 单发(可跳过)
LLM 整合 (~30s)
总耗时:~30s tool + 30s LLM ≈ 60s 总成本:~6 积点(5 个 scrape + 1 个 trends) 总调用:6 次 tool
R1 — 类目锚定
{ "name": "search_categories",
"arguments": { "keyword": "", "site": "amz_us" } }
Extract: 取 data.items.data[0].browseNodeId 作为后续 categorySlug 推断依据;记下 browseNodeNamePath 作上下文。
Early-return: 0 条结果 → 让用户更换/细化关键词,停止。
R2 — 2 并发(filter_niches + keyword_trends)
// (a) Amazon 利基筛选
{ "name": "filter_niches", "arguments": {
"marketplaceId": "US",
"nicheTitle": "",
"searchVolumeT90Min": 20000,
"top5ProductsClickShareT360Max": 0.40,
"productCountMax": 300,
"searchVolumeGrowthT90Min": 0.05,
"returnRateT360Max": 0.10,
"size": 5
}}
// (b) 外部需求趋势
{ "name": "keyword_trends", "arguments": {
"keywords": [""],
"timeRange": "today 12-m",
"region": "US"
}}
关键约束:
marketplaceId用 ISO 站点码"US"/"UK"/"DE",不是 Amazon merchant IDATVPDKIKX0DER。filter_niches.nicheTitle用精确子串匹配,长尾词(3+ word)常返 0。退化策略:剥 silicone/baby 等修饰词,先用 noun head ("bib") 扫,再叠修饰。keyword_trends一次最多 5 个 keywords,趋势是相对值 0-100,不是绝对搜索量。
Extract:
- filter_niches →
data.items.data[]取 Top 3 候选:{nicheId, nicheTitle, searchVolumeT90, top5ProductsClickShareT360, productCount, returnRateT360, avgPrice, avgReviewCount} - keyword_trends →
data.json.timelineData[]最新值 vs 12mo 前的相对变化;记keywordsRankData[].rankList[]里的 Breakout 词作为方向延伸候选
Fallback to filter_categories: 如果 filter_niches 在多次同义词重试后仍返 0,改走 search_categories → filter_categories 路径(类目维度)。在长尾低频品类里这是更稳的主路径,不只是兜底。
// 先 search_categories 拿 browseNodeId(见 R1),再喂给 filter_categories
{ "name": "filter_categories", "arguments": {
"marketplaceId": "US",
"timeRange": "l7d", // 必填
"sampleScope": "all_asin", // 必填
"categoryId": "",
"size": 10
}}
前提: timeRange(常用 l7d)+ sampleScope(all_asin)必填;categoryId 取自 search_categories 返回的 browseNodeId。marketplaceId 用 ISO 站点码 "US",不是 merchant ID。size/page 后端硬上限 10。
Extract(filter_categories): data.items.data[] → unitSoldSum(月销量) / netShippedGmsSum(GMV) / searchVolumeSum(类目搜索量) / buyBoxPriceAvg + buyBoxPriceTier(价格档) / searchToPurchaseRatio(转化) / returnRatio(退货率) / asinCount(竞品密度) / newAsinCount(新品入场) / unitSoldTrendDirection(销量趋势方向)。用这些类目级遥测替代 niche 维度做同样的"需求×竞争×趋势"判断。长尾筛选字段走 extraFilters 透传。
Early-return: 双路径都 0 条 → 报告"该方向饱和或定义太窄"+给放宽参数建议,停止。
R3 — search_amazon 单发(剥词后 ≤4 word)
{ "name": "search_amazon", "arguments": {
"keyword": "",
"site": "amz_us"
}}
Extract: data.json[0].data.results[] 中 sponsored="0" 的前 5 个 ASIN。每条字段语义:
star: 平均评分(0-5 分数,是分数)rating: 评分人数(评论计数,不是分数本身)sales: 月销字符串(如 "10K+ bought in past month") — 这是替代旧monthlySoldVolume的字段badge: Amazon's Choice / Best Seller / BSR 等徽章字符串
双标杆原型锁定(从前 5 里挑 2 个,而不是平铺 5 个): 在过滤后的数组里识别两类对手原型,作为后续 R4/R5 深拆与最终报告的"必打目标":
- Target 1 — 护城河巨头 (Moat Giant): 高
rating(评论数大)+ 稳定badge(Best Seller / Amazon's Choice)。代表已被验证的成熟需求与转化模型。 - Target 2 — 真黑马爆品 (Breakout Black Horse): 相对低
rating,但sales字符串有爆发信号(如 "10K+ bought in past month")和/或 Best-Seller 标。sales/badge字符串只当定性速度信号,不当绝对销量会计值。 - 选不出黑马(全是老牌)时,只锁 Moat Giant,在报告里说明"该 niche 暂无黑马,需高差异化才进"。
关键词长度: ≤4 words,strip filler ("for"/"with"),长尾词频繁返回 results=[] 但仍扣 1 积点。空结果时降一词重试,本 Phase 最多 3 次 search_amazon 调用。
参数名硬规则: 是 keyword(单数,REQUIRED),不是 keywords(复数)。后者会被拒。
R4 — 2 并发(list_new_releases + get_amazon_product A1)
从 R3 拿到候选 ASIN 列表后,先 2 并发抓新品榜 + 第 1 个 ASIN:
{ "name": "list_new_releases", "arguments": {
"categorySlug": "<推断 slug,如 electronics / home-garden>",
"site": "amz_us"
}}
{ "name": "get_amazon_product", "arguments": {
"asin": "", "site": "amz_us"
}}
注意:
list_new_releases实际返回 Top-50(后端硬上限,不是宣传的 Top-100)twentyFourHourOldSalesRank/percentageChange字段可能为空字符串(后端未抓到)- 上市 30 天内的 ASIN 都算"新品",NEW 信号本身不强,要看排名 + sales 双确认
R5 — 2 并发(get_amazon_product A2 + A3,或单发)
{ "name": "get_amazon_product", "arguments": {
"asin": "", "site": "amz_us"
}}
{ "name": "get_amazon_product", "arguments": {
"asin": "", "site": "amz_us"
}}
Skip rule: 如果 A1 + (R3 的 search_amazon 数据) 已能下结论(同 brand / 同价位段) → 跳过 R5,直接进 LLM 整合。
Data Ingestion Guard: get_amazon_product 对 Amazon 自营头部品(如 Echo Dot)有时返回 bestSellersRankItems=[] + category_id="" + brand="",头部品 PDP 解析退化。遇到时不阻塞,从 R3 search_amazon 返回里取 title / price / star / rating / sales / badge 替代。
整合输出 5 段报告
1. TL;DR (3 句话)
- 推荐方向:
- 一句话理由:<搜索量 X + 趋势 Y + 头部份额 Z>
- 红绿黄灯:🟢 / 🟡 / 🔴
2. 市场画像表
| 维度 | 值 | 来源 |
|---|---|---|
| 90 天搜索量 | | filter_niches |
| Top5 商品点击份额 | | filter_niches |
| 商品数 | | filter_niches |
| 退货率 | | filter_niches |
| 12 月外部趋势 | <+/-X%> | keyword_trends |
3. 基准品对照表(最多 3 行,**标注原型**)
| 原型 | ASIN | 标题截 60 字 | 价格 | BSR(`badge`) | `star`(0-5 分) | `rating`(评论数) | `sales`(月销) | Buy Box |
|---|---|---|---|---|---|---|---|---|
(原型列填 🏰 护城河巨头 / 🐎 黑马爆品;黑马行补一句"为何它接住了社媒趋势")
4. 优缺点速记
(直接取 get_amazon_product.aiReviewsSummary,不需要再调 reviews)
- ✅
- ❌
5. 下一步
- 🟢 → "如需 IP 排查 + 差评深拆,可跑 Full 档"
- 🟡 → "建议先做 X 验证"
- 🔴 → "建议放弃,理由:…"
Full 档 SOP(在 Fast 4 回合基础上 +2 回合 ≤ 5min)
Full 档仅在用户明示"详细 / 完整 / 深度 / 全面"时触发。先跑完 Fast 4 回合拿到候选 ASIN,再追加:
R6a — 站外趋势引爆 (off-site dork,1-2 次 ai_search)
Fast 档只用 keyword_trends(相对热度曲线);Full 档补 ai_search 抓 Reddit/TikTok 的真实使用场景与微趋势,作为后续"社媒卖点"和 R&D 输入的依据。每个 dork 单发(ai_search overview ~30s,别并发堆时延):
// Dork A — 站外使用场景
{ "name": "ai_search", "arguments": {
"query": "intitle:\"\" (\"best for\" OR \"used for\" OR \"designed for\") -site:amazon.com -site:ebay.com",
"mode": "overview"
}}
// Dork B — 新趋势/替代方案(如有时间)
{ "name": "ai_search", "arguments": {
"query": "\"\" (trend OR \"new technology\" OR alternative) inurl:blog OR inurl:news",
"mode": "overview"
}}
Extract: AI Overview 文本 + references[].url → 提炼 2-3 个"社媒在追捧的场景/卖点"。无结果不阻塞,在报告"社媒亮点"段标"站外信号弱"。
R6b — 2 并发 wipo_search(设计专利红线扫描)
提取 Fast 阶段基准品的 brand(来自 get_amazon_product.brand),分批 2 并发查 USPTO 外观专利(design patent,source=USID):
// 第一批
{ "name": "wipo_search", "arguments": { "source": "USID", "hol": "", "num": 5 }}
{ "name": "wipo_search", "arguments": { "source": "USID", "hol": "", "num": 5 }}
第二批(如有):
{ "name": "wipo_search", "arguments": { "source": "USID", "hol": "", "num": 5 }}
⚠️ 严禁 source="USTM" — 后端不支持文字商标(text trademark)枚举,会报错。文字商标排查走下方 R6c 的 ai_search。
Extract: data.data.hits[] 中 STATUS="ACT" 且 HOL[] 含大公司/律所 → 强 IP 布局信号。
Image 引用: IMG_DATA[].filename 是相对路径(如 26/06/D0992606-0001.1-th.jpg),不能直接 paste 当 URL。最终报告引用专利图时,贴 DETAIL_URL 字段(完整 WIPO 记录 URL),IMG filename 作 supporting evidence。
R6c — 文字商标预筛 (ai_search brand legal dork,单发)
设计专利(USID)只覆盖外观,文字商标要单独扫。用 ai_search 把基准品 brand 映射到真实法律实体,并扫公开索引里的显著文字冲突:
{ "name": "ai_search", "arguments": {
"query": "\"\" trademark (USPTO OR \"registered\" OR \"™\" OR \"®\")",
"mode": "overview"
}}
Extract: 命中的已注册竞品词/受保护品牌词 → 列入"禁用词",别进自己的标题/Backend。这是初步风险雷达,不是正式法律清关。
Early-return: 3 个 brand 都有强设计专利 → 该方向 🔴,跳过 R7,直接给"红灯"报告。
R7 — 差评深拆(预算告知后再调)
⚠️ 调用前用户消息里说:"将抓 2 个 ASIN 各 1 页差评,约 10 积点 / ~15 秒,是否继续?"(get_amazon_reviews 实测 5pt/页)
用户同意后,2 并发:
{ "name": "get_amazon_reviews", "arguments": {
"asin": "", "site": "amz_us",
"pageCount": 1, "filterByStar": "critical", "sortBy": "helpful"
}}
{ "name": "get_amazon_reviews", "arguments": {
"asin": "", "site": "amz_us",
"pageCount": 1, "filterByStar": "critical", "sortBy": "helpful"
}}
Extract: data.json[0].data.results[] 各取前 5 条差评,按 {title, content, star, helpful} 排序。
Cluster(LLM 本地,不耗 tool):聚类成 Top 3 痛点主题,每条带 1 句原话引用。
Full 报告(在 Fast 5 段基础上扩 3 段)
6. 痛点反转策略
Top 3 痛点 → 对应 Listing/产品改进方向(每条 1 行)
7. IP 红线(分两类来源)
- 🎨 设计专利(wipo_search USID): 标杆品有哪些 ACT 状态外观专利 + 持有人,给出"做差异化"的结构建议;引用 `DETAIL_URL`。
- 🔤 文字商标(ai_search legal dork): 状态注册/受保护的文字词 + 通用替代词建议(如 Velcro → Hook and loop fastener)。
⚠️ 免责:AI 不构成法律意见,开模/大批量备货前请咨询专业 IP 律师。
8. 最终投资判定
红绿灯 + 投入估算(首批 SKU 数 / 定价区间 / 广告启动预算建议)
何时进入 Full 档(自动判定)
Fast 档跑完后,如果 Fast 报告给的是 🟢 但用户还有疑问 → 主动提议升 Full 档:
"Fast 档判定为🟢,但要确认能不能开模,建议跑 Full 档(含 IP 排查 + 差评深拆,约 30 积点 / 5 分钟)。是否继续?"
报告输出规范
- 不暴露原始 JSON 或 tool 名(R-5)
- 数字带来源 tool 名(不需要带字段路径)
- 每条建议 ≤ 1 行,全报告建议 ≤ 3 条
- 报告末尾主动提示下一步:
- 想做日常监控 →
amazon-daily-competitor-radar - 想写 Listing →
amazon-listing-optimization - 想深查 IP →
ip-clearance - 想验证外部需求 →
google-research
- 想做日常监控 →
反模式(不要做)
- ❌ Fast 档调
get_amazon_reviews— 5pt/页,超预算 - ❌ 一回合同时发 3+ 个 scrapeApi 调用 — 实测 3 并发会被业务码 9200 拒
- ❌ 跑满 SOP 即使早返条件已触发
- ❌ 引用不存在字段:
monthly_sales_min/opportunity_score/negative_reviews_top5/monthlySoldVolume/bsr_category_path/category_id(amzscope 系) - ❌ 用
search_amazon想拿 BSR 或 New Releases — 用list_bestsellers/list_new_releases - ❌ filter_niches 传
categoryId— 这工具只认nicheId/nicheTitle - ❌
wipo_search(source="USTM")— 后端不支持文字商标查询,只USID设计专利;文字查询走ai_search - ❌
search_amazon_alexa传marketplaceId— 此工具固定 amz_us,只接受prompts+screenshot;且 Rufus 上游 Cloudflare 经常 502,SKILL 已标 DEPRECATED - ❌ 用
keywords(复数)调 search_amazon — 真实参数名是keyword(单数,REQUIRED) - ❌
marketplaceId="ATVPDKIKX0DER"— 这是 Amazon merchant ID,不是 filter_niches/filter_categories 入参格式;后者要 ISO 站点码"US"/"UK"/"DE" - ❌ 先凭直觉说"做不到"再实测可查 — 违反 R-11,先调
pangolinfo_capabilities再下结论
核心规则 / Core Rules(本 skill 自包含,无需外部文件)
以下规则对所有 Pangolinfo skill 通用。本文件已内联,单独加载即生效。
R-1 鉴权与默认值
API Key(两套,别混)
Pangolinfo 有两套独立的 key 注入路径,对应两种运行形态:
- Skill 侧(本文件所在形态):AI 从环境变量
PANGOLINFO_API_KEY读取 key。这是 skill 默认的 key 来源——由用户在运行环境里设好,AI 直接读、不要反复追问用户。 - MCP server 侧:key 走 MCP 配置(CLI
--api-key=pgl_xxx/ 同名 envPANGOLINFO_API_KEY/~/.pangolinfo/config.json/ hosted URL?api_key=pgl_xxx或 HTTP 头Authorization: Bearer pgl_xxx)。
两者互相独立:skill 侧改 env var 不会影响已连上的 MCP server,反之亦然。key 前缀均为 pgl_。
First-time setup(工具没注册 / 首次 AUTH 失败时)
若 pangolinfo_capabilities 探针发现工具未注册,或任一 tool 直接返回 AUTH,说明 key 尚未配好。此时停止跑 SOP,引导用户:
- 到 https://www.pangolinfo.com 登录,复制 API Key(
pgl_开头;新用户有免费额度)。 - 配置 key:
- Skill 形态 → 设环境变量
export PANGOLINFO_API_KEY="pgl_xxx"。 - MCP 形态 → 写进
~/.pangolinfo/config.json,或 MCP URL?api_key=pgl_xxx,或头Authorization: Bearer pgl_xxx。
- Skill 形态 → 设环境变量
- 重启 / 重连(env var 与 MCP 配置都不热加载)。
- 让用户配好后再来。AI 不能替用户改配置或重连。
默认值
- 默认市场:
marketplaceId: "US"/site: "amz_us";US 邮编默认"10041"(纽约)。除非用户明示其他站点。 - 报告语言与用户提问语言一致;但 Listing 正文(Title / Bullets / Backend)始终用目标市场语言(默认英文)。
R-2 数据真实
- 只用 MCP 返回的硬数据。绝不编造搜索量、排名、月销、评论数、Buy Box 卖家等。
- 数据缺失时明确告知用户"该字段后端未返回"或"需手动补充"。不要尾随免责声明、不要写"约""大概"。
- 每个数字必须可回溯到具体 tool 调用与字段路径(如
get_amazon_product.data.json[0].data.results[0].star)。
R-3 调用前先看能力
第一次接入时调一次 pangolinfo_capabilities { detail: "summary" }(0 积点 / 2ms),拿到当前的 tool 清单 + workflows + tips。工具数量与名称会随版本变化,以本次返回为准,不要钉死数字、不要凭旧记忆调 tool。该调用同时是连接健康探针:工具未注册或返回 AUTH → 转 R-1 first-time setup。
R-4 时效性硬规则(最重要)
R-4a 双档模式
每个 SOP 强制提供两档:
| 档位 | 触发条件 | 总耗时 | 总积点 | 总 tool 调用次数 |
|---|---|---|---|---|
| Fast | 默认 / 用户没明说"详细/深度/完整报告" | ≤ 90 秒 | ≤ 8 积点 | ≤ 6 次 |
| Full | 用户明说"详细 / 完整 / 深度 / 全面" | ≤ 5 分钟 | ≤ 30 积点 | ≤ 15 次 |
跑 Fast 档时禁止调下列慢/贵 tool:
- ❌
get_amazon_reviews(5pt/页 + 10s/次) - ❌
ai_searchmode='ai_mode'(30-60s) - ✅
ai_searchmode='overview' 最多 1 次
跑 Full 档时各项上限:
get_amazon_reviews≤ 3 个 ASIN × pageCount=1ai_searchai_mode ≤ 1 次,overview ≤ 2 次wipo_search≤ 3 次
R-4b 并行调用(最关键的加速手段)
独立的 tool 调用应在同一回合并发发送,但受 scrapeApi 速率限制约束。
后端速率:实测 2 QPS 稳定(3 QPS 会触发 9200 "no content")
- ✅ 同一回合最多并发 2 个 scrapeApi 调用(含 search_amazon / get_amazon_product / list_* / filter_* / search_categories / get_category_* / get_amazon_reviews / wipo_search / ai_search / keyword_trends / search_local_maps)— 2026-05-28 真实压测确认 3 并发会被后端拒
- ✅
pangolinfo_capabilities不走后端,可任意并发 - ❌ 一次同时发 3 个
search_amazon会有至少 1 个返回业务码9200 "Scrape failed: no content returned"
推荐节奏
| 总调用数 N | 节奏 |
|---|---|
| N ≤ 2 | 一回合 2 并发 |
| 3 ≤ N ≤ 6 | 分多回合:每回合 2 并发,回合之间间隔 ~1s |
| N ≥ 7 | 重新设计 SOP,先早返再决定是否继续 |
并行 vs 串行判定
- 不依赖上一步返回字段 → 并行(但不超 2)
- 依赖上一步字段 → 串行
- 同种 tool 的批量调用(如 2 个 ASIN 详情) → 一回合 2 并发;3+ ASIN 分批
遇到 RATE_LIMIT 怎么办
收到 [RATE_LIMIT] 错误:等 ~1s 重试该 1 个 tool(不要全部重试),其余已成功的别动。连续 2 次 RATE_LIMIT 或业务码 9200 说明 QPS 节流,降到每回合 1 并发(完全串行)。
R-4c 早返
任一步骤拿到"足够下结论"的数据后立即生成报告,不要为凑齐 SOP 强跑:
| 触发 | 立即返回 |
|---|---|
filter_niches 返回 0 条 | "无符合条件的 niche,建议放宽 X、Y 参数" + 给出参数建议清单 |
wipo_search 命中红线(status='ACT' 且 hol 是大公司) | 该方向淘汰,跳过后续单品深拆 |
| 用户主 ASIN 在 SERP Top 3 + 无新 BSR 异动 | 给"健康"判定,跳过评论挖掘 |
get_amazon_product upstream 404 ("url not found") | 告知 ASIN 失效,跳过后续 |
R-4d 慢操作前先打预算
调下列 tool 前必须在用户消息里报"将花 X 积点 / 约 Y 秒",让用户有机会取消:
get_amazon_reviews(5pt/页)- 同一回合并发 ≥ 3 个 tool 调用(超过 2 并发的批次)
ai_searchai_mode(30-60s)
R-5 不暴露原始 JSON
AI 的回答里不要贴原始 tool 返回。结构化呈现:
- 列表 → 表格(每行一个 ASIN/niche/类目)
- 单品 → 卡片(关键字段分组:标识 / 价格 / 流量 / 评价 / 卖家)
- 趋势 → 用简短描述("上升 12% / 12 个月趋势平稳 / Q4 季节性")
- 报告 → 各 SKILL 自己的固定段落结构
R-6 单工具直通
用户问简单单步查询时不要强行跑完整 SOP,直接调对应单 tool 给结果:
| 用户说 | 直接调 | 不要跑 SOP |
|---|---|---|
| "查 ASIN B0XXX" | get_amazon_product | ❌ product-discovery |
| "X 类目 best sellers" | list_bestsellers | ❌ |
| "Apple 在美国的专利" | wipo_search source=USID hol='Apple' | ❌ ip-clearance SOP |
| "wireless earbuds 热度趋势" | keyword_trends | ❌ |
| "B0XXX 的差评" | get_amazon_reviews filterByStar=critical pageCount=1 | ❌ amazon-listing-optimization |
R-7 不推荐外部工具
不主动提 Keepa / SellerSprite / Helium 10 / Jungle Scout 等竞品。用户问起再说"本工具不直接提供 X 能力,可考虑 ..."。
R-8 报告语气
- 中性,可执行
- 禁用"必跌""碾压""稳赚""绝对蓝海"等绝对化承诺词
- 禁用情绪词"令人震惊""惊喜"
- 每个建议带"为什么"(基于哪个数据)和"做什么"(具体动作)
R-9 错误处理
MCP server 已把每个错误渲染成结构化三行([CODE] + 可否重试 + 用户动作)。AI 的职责是按 CODE 语义正确反应,别瞎重试、别原地打转。6 类错误:
| Code | 可否重试 | 处理 |
|---|---|---|
AUTH | ❌ terminal | key 无效/缺失/过期。用同一个 key 重试一定还失败 → 绝不重试。停止 SOP,按 R-1 first-time setup 引导用户:复制正确 key(https://www.pangolinfo.com)→ 写进 env PANGOLINFO_API_KEY 或 MCP 配置 → 重启/重连(不热加载)。AI 无法替用户改配置或重连。⚠️ 坑:invalid key 在后端是 bizCode 1004(不是 HTTP 401),别因为"不是 401"就误判成别的错。 |
QUOTA | ❌ terminal | 积分不足 / 套餐过期,重试无用。提示用户去 https://www.pangolinfo.com 充值或升级,停止本次 SOP。 |
BAD_INPUT | ❌ terminal | 参数有误,重试相同参数无用。检查参数名/值(marketplaceId 非 marketplace_id、ASIN、zipcode、parserName 等,见 R-10),修正后才重试。 |
RATE_LIMIT | ✅ 临时 | 含业务码 9200("no content")/4029/4030。等 ~1-5s 重试该一个请求;同时降回合并发到 1。连续 2 次仍失败则跳过本步。 |
SERVER | ✅ 临时 | 服务端临时错误(含 9100/9101)。重试 1 次;仍失败告知用户跳过本步,继续 SOP。 |
NETWORK | ✅ 临时 | 网络异常。提示用户检查到 www.pangolinfo.com 的连接后重试。 |
总则:terminal 类(AUTH/QUOTA/BAD_INPUT)重试是浪费,直接停或修参数;transient 类(RATE_LIMIT/SERVER/NETWORK)才重试,且只重试失败的那一个、别全批重发。
R-10 字段名速查(最常踩的坑)
| ❌ 错(直觉常写的) | ✅ 对(真实字段) |
|---|---|
marketplace_id | marketplaceId (值是 ISO 站点码 "US"/"UK"/"DE",不是 Amazon merchant ID ATVPDKIKX0DER) |
niche_title | nicheTitle |
search_volume_t90_min | searchVolumeT90Min |
top5_brands_click_share_max | top5ProductsClickShareT360Max(products 不是 brands) |
return_rate_t360_max | returnRateT360Max |
monthly_sales_min | (不存在)→ 用 minimumUnitsSoldT360 |
opportunity_score | (不存在)→ 自己算 |
category_id | browseNodeId(amzscope 系列) |
categories[] | data.items.data[] |
products[].organic_rank | results[].rank |
products[].sp_rank | results[].sponsored |
negative_reviews_top5 | 不存在 → 用 get_amazon_reviews filterByStar='critical' |
positive_reviews_top5 | 不存在 → 用 get_amazon_reviews filterByStar='positive' |
bullet_points | features[] |
a_plus_modules | productDescription[] |
selling_rank | bestSellersRankItems[] |
category_path | breadCrumbs |
buy_box_seller | seller.name |
search_amazon 抓 BSR | ❌ → 用 list_bestsellers |
search_amazon 抓 New Releases | ❌ → 用 list_new_releases |
search_amazon 传 limit | ❌ 没有,分页用 page |
search_amazon_alexa 传 marketplaceId | ❌ 不支持,固定 amz_us;只接受 prompts: string[] + 可选 screenshot |
bsr_category_path | ❌ 不存在;用 bestSellersRankItems[] 数组 + category_id 顶层字段 |
monthlySoldVolume | ❌ 不存在;search_amazon 用 sales 字段(live 月销字符串) |
完整字段对照见 MCP 各 tool 的 Returns: 段落,或调 pangolinfo_capabilities { detail: "full" }。
R-11 不要凭直觉判定"做不到"
在告诉用户"这个数据拿不到""这个是付费功能""只能估算"之前,必须先调 pangolinfo_capabilities { detail: "summary" }(免费,0 积点)或翻看具体 tool 的 description / inputSchema 确认。Pangolinfo MCP 实际能筛/能返回的字段超出大多数 AI 训练时的常识范围,包括但不限于:
- 退货率:
filter_niches.returnRateT360Max筛选 + 返回字段returnRateT360(具体数值) - GMV/月销额:
filter_categories.netShippedGmsSum+ niche 维度可用unitSoldSum × avgPrice推算 - 品牌集中度:
top5ProductsClickShareT360/top20BrandsClickShareT360 - 新品入场率:
newBrandCountT90/newProductsLaunchedT180 - 广告 CPC:
avgAdSpendPerClick
凭直觉先说"做不到"再实际能查到 → 用户直接失去信任。先查 capabilities,再下结论。
R-12 通用防呆速查(跨 tool 硬护栏 — 调用前自检)
下面是所有 Pangolinfo MCP tool 的通用防呆清单,每条都对应一个真实会被后端拒/扣冤枉积点的坑。调任何 tool 前对照一遍。
R-12a 参数护栏(传错就被拒 / 扣冤枉积点)
| 坑 | ❌ 错 | ✅ 对 |
|---|---|---|
| 市场码 | marketplaceId="ATVPDKIKX0DER"(merchant id) | ISO 站点码 "US"/"UK"/"DE" |
| 邮编跨国 | amz_jp + 美国邮编 10001 | 邮编必须匹配 site 国家(amz_us→美国邮编 / amz_jp→日本邮编);不确定就别传,后端按国家随机挑 |
| 关键词参数 | keywords(复数) | search_amazon.keyword(单数,REQUIRED) |
| 分页 | search_amazon 传 limit | 用 page(无 limit 参数) |
| filter 系列 size | size: 50 | filter_categories/filter_niches 的 size/page 后端硬上限 10(filter_niches 默认 3),超出被截 |
| filter 必填 | filter_categories 漏 timeRange/sampleScope | 二者必填(常用 l7d + all_asin);filter_niches 必填 marketplaceId |
| filter_niches 入参 | 传 categoryId | 只认 nicheId/nicheTitle;0-1 小数字段(top5ProductsClickShareT360Max/returnRateT360Max)别传整数 |
| alexa | search_amazon_alexa 传 marketplaceId | 固定 amz_us,只接受 prompts: string[] + 可选 screenshot;强制每次 1 条 prompt(6 积点/条,60-90s,多条线性叠加可能 >200s) |
| scrape_url | 同时传 / 都不传 content 和 url | 二选一(互斥);筛选/排序/翻页只能走 url 模式;parserName 必须匹配页面类型 |
| wipo_search | source="USTM" 查文字商标 / 漏 source | source 必填;文字商标走 ai_search,设计专利用 source="USID";CNID + hol/prod 模糊查必须再配 id/rd/status/lcs 之一(否则后端拒全表扫);USID 无 status 字段 |
| ai_search | 一次塞 >5 个 followups | query 必填(min 1);followups ≤5;Fast 档禁 ai_mode(30-60s) |
| keyword_trends | 把 0-100 当绝对搜索量 / 传 1 个词 | 那是相对热度;一次 ≤5 词;绝对量去 filter_niches |
R-12b 错误闭环(拿到返回先自检,别盲目往下走)
| 返回情形 | 防呆动作 |
|---|---|
results=[] / recsList 空 / niche 0 条 | 空结果不一定扣积点但 search 系列扣;按各 SOP 早返(剥词重试 / 放宽筛选 / 换站点),别空手编数据(R-2) |
业务码 9200 "no content"(含 Akamai 挑战) | 归 SERVER/RATE_LIMIT,可重试:等 1-5s 重试该一个,降并发到 1;连续 2 次失败跳过本步 |
recsList(bestsellers/new_releases) | 它是 JSON 字符串数组,必须二次 JSON.parse,别当普通数组用 |
get_amazon_product 头部自营品 PDP 退化 | bestSellersRankItems=[]+brand=""+category_id="" → 不阻塞,从 search_amazon 的 title/price/star/rating/sales/badge 兜底 |
twentyFourHourOldSalesRank/percentageChange 空串 | 后端没抓到 24h delta,不可依赖,改看 BSR 绝对值 |
| AI Overview 未触发 | SGE 不是每次都有,缺失时降级 organic 结果,别硬编引文 |
| upstream 404 / "url not found" | ASIN/页面失效,告知用户跳过,别重试 |
R-12c api_key 无效判断(别原地打转)
- key 来源两套:skill 侧读 env var
PANGOLINFO_API_KEY;MCP 侧走 CLI/config/URL(?api_key=pgl_xxx或Authorization: Bearer pgl_xxx)。前缀均pgl_。 - AUTH 是 terminal:同 key 重试一定再失败 → 绝不重试。坑:invalid key 在后端是 bizCode 1004(不是 HTTP 401),别因"不是 401"误判成 SERVER。
- 处理:停 SOP → 引导用户到
https://www.pangolinfo.com拿 key → 写 env/config → 重启/重连(不热加载;agent 无法替用户改配置或重连)。详见 R-1 / R-9。
R-12d 路由防呆(别用错 skill / 用错 tool)
- 单步查询走单 tool,别强跑整 SOP(R-6):查 ASIN→
get_amazon_product;类目榜→list_bestsellers;趋势→keyword_trends;差评→get_amazon_reviews filterByStar=critical。 - tool 间别越界:要 BSR/新品榜别用
search_amazon(用list_bestsellers/list_new_releases);要 niche 别用filter_categories(用filter_niches);要具体商品别用 filter 系列(用list_category_products/search_amazon)。 - skill 间别越界:选品→
amazon-product-explorer;日常监控→amazon-daily-competitor-radar;写 Listing→amazon-listing-optimization;站内抓取→pangolinfo-amazon-scraper;Google/SGE→pangolinfo-ai-serp;类目利基→pangolinfo-amazon-niche。
相关技能
Use when: 用户要"浏览/搜索 Amazon 类目树" / "批量把 categoryId 解析成完整路径面包屑" / "按销量/搜索量/退货率/竞争度筛类目" / "找低竞争蓝海利基(niche)" / "分析某类目销量趋势" / "browse Amazon category tree" / "fin...
Search Amazon, read full product detail by ASIN, and list every seller offer on an ASIN with the buy-box winner. Clean normalized JSON with price, rating, review count, availability, shipping and sellers. 3 endpoints, all 1 credit, 22 marketplaces.
通过 MCP 工具抽取 Google AI Overview 引文来源,并对比关键词热度趋势。
Amazon product review intelligence analysis tool for global e-commerce sellers. Core capabilities:fetch Amazon reviews, AI-powered negative review analysis, quantify high-frequency issues, discover hidden negative feedback in 5-star reviews, generate improvement suggestions, track review trends, inc
跨境电商研究型智能体,79 个内置工具覆盖亚马逊选品、关键词、竞品、专利与趋势分析,并支持 1688 货源、AI 图像与 PDF 处理。