Coding

pangolinfo-amazon-product-explorer

Try it

Get an Amazon go/no-go verdict on a niche in ~60s, with sourced demand, benchmark products, and review pain data.

What it does

Walks you through a structured Amazon GTM scouting workflow: category anchor → demand & trend pull → niche filter → benchmark lock-in → optional IP & review deep dive → traffic-light verdict. Fast tier runs ~60s with ~6 tool credits and produces a 5-section report (TL;DR, market profile, benchmark table, pros/cons, next steps). Full tier adds off-site trend signals, USPTO design-patent scan, text-trademark pre-screen, and clustered critical reviews, then expands the report with a pain-reversal strategy, IP red lines, and a final investment decision with SKU count, pricing band, and ad-launch budget hints. Every number traces back to a specific tool call and field path.

When to use it

  • Pre-R&D go/no-go check on a candidate Amazon category
  • Shortlisting a blue-ocean niche from a vague idea ("should I sell X?")
  • Benchmarking the moat giant + breakout dark horse in a niche
  • Mining 1-star reviews for product improvement direction before tooling up

The skill document

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 ID ATVPDKIKX0DER。
  • 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。

设计专利(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 / 同名 env PANGOLINFO_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,引导用户:

  1. 到 https://www.pangolinfo.com 登录,复制 API Key(pgl_ 开头;新用户有免费额度)。
  2. 配置 key:
    • Skill 形态 → 设环境变量 export PANGOLINFO_API_KEY="pgl_xxx"。
    • MCP 形态 → 写进 ~/.pangolinfo/config.json,或 MCP URL ?api_key=pgl_xxx,或头 Authorization: Bearer pgl_xxx。
  3. 重启 / 重连(env var 与 MCP 配置都不热加载)。
  4. 让用户配好后再来。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_search mode='ai_mode'(30-60s)
  • ✅ ai_search mode='overview' 最多 1 次

跑 Full 档时各项上限:

  • get_amazon_reviews ≤ 3 个 ASIN × pageCount=1
  • ai_search ai_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_search ai_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❌ terminalkey 无效/缺失/过期。用同一个 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_idmarketplaceId (值是 ISO 站点码 "US"/"UK"/"DE",不是 Amazon merchant ID ATVPDKIKX0DER)
niche_titlenicheTitle
search_volume_t90_minsearchVolumeT90Min
top5_brands_click_share_maxtop5ProductsClickShareT360Max(products 不是 brands)
return_rate_t360_maxreturnRateT360Max
monthly_sales_min(不存在)→ 用 minimumUnitsSoldT360
opportunity_score(不存在)→ 自己算
category_idbrowseNodeId(amzscope 系列)
categories[]data.items.data[]
products[].organic_rankresults[].rank
products[].sp_rankresults[].sponsored
negative_reviews_top5不存在 → 用 get_amazon_reviews filterByStar='critical'
positive_reviews_top5不存在 → 用 get_amazon_reviews filterByStar='positive'
bullet_pointsfeatures[]
a_plus_modulesproductDescription[]
selling_rankbestSellersRankItems[]
category_pathbreadCrumbs
buy_box_sellerseller.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 系列 sizesize: 50filter_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)别传整数
alexasearch_amazon_alexa 传 marketplaceId固定 amz_us,只接受 prompts: string[] + 可选 screenshot;强制每次 1 条 prompt(6 积点/条,60-90s,多条线性叠加可能 >200s)
scrape_url同时传 / 都不传 content 和 url二选一(互斥);筛选/排序/翻页只能走 url 模式;parserName 必须匹配页面类型
wipo_searchsource="USTM" 查文字商标 / 漏 sourcesource 必填;文字商标走 ai_search,设计专利用 source="USID";CNID + hol/prod 模糊查必须再配 id/rd/status/lcs 之一(否则后端拒全表扫);USID 无 status 字段
ai_search一次塞 >5 个 followupsquery 必填(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。

Related skills

Fetch raw ad creative, app, ranking, and revenue data from AdMapix as structured JSON.

by fly0pants4.3k installs296 stars

Find why your productivity system keeps failing, then apply the smallest fix — capacity math, bottleneck routing, durable local notes.

by Iván855 installs69 stars

Generate and edit Draw.io, Mermaid, and Excalidraw diagrams from natural language using a structured JSON spec.

by nssa.io1.0k installs47 stars

Join a video meeting as an AI bot with voice, avatar, and screenshare across four operating modes.

by johnpatternai22 installs8 stars

Stores durable facts in a categorized, plain-markdown vault on disk, alongside your agent's built-in memory.

by Iván559 installs18 stars

More from pangolinfo

Browse all skills

Browse Amazon's category tree and filter low-competition niches by sales, search volume, and return-rate metrics.

by pangolinfo23 installs1 stars

Daily Amazon ASIN health check, SERP rank tracking, category-entrant scan, and defensive action recommendations with yesterday-vs-today baseline comparison.

by pangolinfo20 installs