Amazon GTM 选品 SOP#

跑前必读：本文件末尾《核心规则 / Core Rules》章节（已内联，自包含）。 来源标记硬规则：本 Skill 发起的每次 MCP tool 调用，都必须在 arguments 顶层加入 "clientSource":"skill"，不得省略。 角色：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")。

text

回合 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 — 类目锚定#

jsonc

{ "name": "search_categories",
  "arguments": { "keyword": "<user_seed_keyword>", "site": "amz_us" } }

Extract: 取 data.items.data[0].browseNodeId 作为后续 categorySlug 推断依据；记下 browseNodeNamePath 作上下文。

Early-return: 0 条结果 → 让用户更换/细化关键词，停止。

R2 — 2 并发(filter_niches + keyword_trends)#

jsonc

// (a) Amazon 利基筛选
{ "name": "filter_niches", "arguments": {
  "marketplaceId": "US",
  "nicheTitle": "<seed_keyword>",
  "searchVolumeT90Min": 20000,
  "top5ProductsClickShareT360Max": 0.40,
  "productCountMax": 300,
  "searchVolumeGrowthT90Min": 0.05,
  "returnRateT360Max": 0.10,
  "size": 5
}}

// (b) 外部需求趋势
{ "name": "keyword_trends", "arguments": {
  "keywords": ["<seed_keyword>"],
  "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 路径(类目维度)。在长尾低频品类里这是 更稳的主路径,不只是兜底。

jsonc

// 先 search_categories 拿 browseNodeId(见 R1),再喂给 filter_categories
{ "name": "filter_categories", "arguments": {
  "marketplaceId": "US",
  "timeRange": "l7d",            // 必填
  "sampleScope": "all_asin",     // 必填
  "categoryId": "<browseNodeId from search_categories>",
  "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)#

jsonc

{ "name": "search_amazon", "arguments": {
  "keyword": "<seed_keyword,strip filler 至 ≤4 word>",
  "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:

jsonc

{ "name": "list_new_releases", "arguments": {
  "categorySlug": "<推断 slug,如 electronics / home-garden>",
  "site": "amz_us"
}}
{ "name": "get_amazon_product", "arguments": {
  "asin": "<A1 from search_amazon>", "site": "amz_us"
}}

注意:

• list_new_releases 实际返回 Top-50(后端硬上限,不是宣传的 Top-100)
• twentyFourHourOldSalesRank / percentageChange 字段可能为空字符串(后端未抓到)
• 上市 30 天内的 ASIN 都算"新品",NEW 信号本身不强,要看排名 + sales 双确认

R5 — 2 并发(get_amazon_product A2 + A3,或单发)#

jsonc

{ "name": "get_amazon_product", "arguments": {
  "asin": "<A2>", "site": "amz_us"
}}
{ "name": "get_amazon_product", "arguments": {
  "asin": "<A3>", "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 段报告#

text

1. TL;DR (3 句话)
   - 推荐方向：<niche_title>
   - 一句话理由：<搜索量 X + 趋势 Y + 头部份额 Z>
   - 红绿黄灯：🟢 / 🟡 / 🔴

2. 市场画像表
| 维度 | 值 | 来源 |
|---|---|---|
| 90 天搜索量 | <searchVolumeT90> | filter_niches |
| Top5 商品点击份额 | <top5ProductsClickShareT360> | filter_niches |
| 商品数 | <productCount> | filter_niches |
| 退货率 | <returnRateT360> | 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）
- ✅ <positive aspect 1>
- ❌ <negative aspect 1>

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,别并发堆时延):

jsonc

// Dork A — 站外使用场景
{ "name": "ai_search", "arguments": {
  "query": "intitle:\"<seed_keyword>\" (\"best for\" OR \"used for\" OR \"designed for\") -site:amazon.com -site:ebay.com",
  "mode": "overview"
}}
// Dork B — 新趋势/替代方案(如有时间)
{ "name": "ai_search", "arguments": {
  "query": "\"<seed_keyword>\" (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):

jsonc

// 第一批
{ "name": "wipo_search", "arguments": { "source": "USID", "hol": "<brand1>", "num": 5 }}
{ "name": "wipo_search", "arguments": { "source": "USID", "hol": "<brand2>", "num": 5 }}

第二批(如有):

jsonc

{ "name": "wipo_search", "arguments": { "source": "USID", "hol": "<brand3>", "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 映射到真实法律实体,并扫公开索引里的显著文字冲突:

jsonc

{ "name": "ai_search", "arguments": {
  "query": "\"<brand_or_proposed_word>\" 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 并发:

jsonc

{ "name": "get_amazon_reviews", "arguments": {
  "asin": "<A1>", "site": "amz_us",
  "pageCount": 1, "filterByStar": "critical", "sortBy": "helpful"
}}
{ "name": "get_amazon_reviews", "arguments": {
  "asin": "<A2>", "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 段）#

text

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=<key> / 同名 env PANGOLINFO_API_KEY / ~/.pangolinfo/config.json / hosted URL ?api_key=<key> 或 HTTP 头 Authorization: Bearer <key>）。

两者 互相独立：skill 侧改 env var 不会影响已连上的 MCP server，反之亦然。 key 是 JWT 格式（ eyJhbGci... 三段式、点分隔），不是 pgl_ 前缀——从官网控制台复制出来长什么样就照原样用，别因为不是 pgl_ 开头就判成无效。

First-time setup（工具没注册 / 首次 AUTH 失败时）#

若 pangolinfo_capabilities 探针发现工具 未注册，或任一 tool 直接返回 AUTH，说明 key 尚未配好。此时 停止跑 SOP，引导用户：

1. 到 https://www.pangolinfo.com 登录，复制 API Key（JWT 格式， eyJhbGci... 开头；新用户有免费额度）。
2. 配置 key：
   • Skill 形态 → 设环境变量 export PANGOLINFO_API_KEY="eyJhbGci..."。
   • MCP 形态 → 写进 ~/.pangolinfo/config.json，或 MCP URL ?api_key=eyJhbGci...，或头 Authorization: Bearer eyJhbGci...。
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 并发,回合之间间隔 ~1sN ≥ 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_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 系列 sizesize: 50``filter_categories/ filter_niches 的 size/ page 后端硬上限 10(filter_niches 默认 3),超出被截filter 必填filter_categories 漏 timeRange/ sampleScope二者 必填(常用 l7d + all_asin); filter_niches 必填 marketplaceIdfilter_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" 查文字商标 / 漏 source``source 必填;文字商标走 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=<key> 或 Authorization: Bearer <key>)。 key 是 JWT( eyJhbGci...),不是 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。