Amazon Listing 优化 SOP

跑前必读：本文件末尾《核心规则 / Core Rules》章节（已内联，自包含）。 角色：资深 Amazon 运营 + 文案专家。所有输出可直接复制到 Seller Central。

用户触发与档位

Fast 档（默认 ≤90s）：

• "帮我写个 Listing for wireless earbuds"
• "我的标题怎么改"
• "Backend Search Terms 怎么填"

Full 档（用户明示 ≤4min）：

• "完整重写 Listing 包括 A+ 文案"
• "深度 VOC 分析后再写"
• "包括 IP 合规筛查"

单工具直通：

• "查 X 的差评" → get_amazon_reviews filterByStar=critical pageCount=1
• "X 词在美国注册商标了吗" → wipo_search source=USID hol=X

---

Fast 档 SOP(4 回合 ≤ 90s)

只用 PDP 自带的 aiReviewsSummary + 1 次 critical reviews,不调 ai_search(30s 太慢)。

回合 1 (5s)   search_amazon                                          ← 找 Top 3 标杆 ASIN
回合 2 (5s)   get_amazon_product(A1) | get_amazon_product(A2)         ← 2 并发
回合 3 (5s)   get_amazon_product(A3) | get_amazon_reviews(最优 ASIN)  ← 2 并发(reviews 5pt)
回合 4 (5s)   get_category_paths (可选,验证类目锚定)                  ← 单发
LLM 整合 (~30s)

总耗时:~30s tool + 30s LLM ≈ 60-75s 总成本:~8 积点(reviews 5pt + 3 个 PDP 各 1pt) 总调用:5-6 次 tool

并发硬上限: 2(实测 2026-05-28:3 并发会触发后端业务码 9200 "no content")。

R1 — 找 Top 标杆 ASIN

{ "name": "search_amazon",
  "arguments": { "keyword": "<core_keyword>", "site": "amz_us" }}

Extract: data.json[0].data.results[] 取前 3 个非赞助（sponsored="0"）ASIN，按 rank 升序。

Skip rule: 用户已给了 3 个对标 ASIN → 跳过 R1。

R2 — 2 并发拉标杆 PDP (A1 + A2)

{ "name": "get_amazon_product", "arguments": { "asin": "<A1>", "site": "amz_us" }}
{ "name": "get_amazon_product", "arguments": { "asin": "<A2>", "site": "amz_us" }}

Data Ingestion Guard (any-field-empty): 对每个 ASIN,检查 4 个核心字段:

• title (string)
• features (array,至少 3 条)
• aiReviewsSummary (object)
• bestSellersRankItems (array,至少 1 条)

如果全部为 null → 输出 🔴 Abort Maneuver: Target ASIN data body is completely empty. 停止。 如果任一为 null(其他有数据) → 继续,但在 Section "Data Completeness Warnings" 里列出缺失字段 + 标明该分支用了 fallback。

Extract per ASIN:

• title:分析竞品标题结构
• features[]:竞品的"五点描述"(这是 features,不是不存在的 bullet_points)
• productDescription[]:A+ 模块(不是 a_plus_modules)
• bestSellersRankItems[]:用于 Category ID 解析(见下方"Category ID Resolution Rule")
• breadCrumbs:free-text 面包屑字符串,仅作上下文展示用,不要尝试解析数字 ID(实际是 UTF-8 › 分隔的明文 + HTML entity,但不含数字 ID)
• price + star + rating:判定是哪一档对手。注意 star 是 0-5 分数,rating 是评分人数(评论计数)
• aiReviewsSummary.items[]:⭐ 关键 — 这里已经有 LLM 总结好的优缺点摘要,直接用,不需要再调 reviews

Category ID Resolution Rule (BSR scan)

解析叶节点 numeric ID 时:

1. 主路径:遍历 bestSellersRankItems[],对每条 .link 字段 apply regex /(\d{5,})/,取最深 index 命中的 numeric ID(注意:[0] 通常是 slug-only URL,如 /Best-Sellers-Home-Garden/,数字 ID 在 [1] 或更后)。不要直接取 [0],实测 [0] 通常拿不到数字 ID。注意有些老类目 ID 仅 5 位(如 172282 Electronics),所以是 \d{5,} 不是 \d{6,}。

2. 不要用 breadCrumbs 作为 ID 来源:free-text 字符串,不含数字 ID。

3. 三级 fallback:如果 bestSellersRankItems[] 全空(罕见,头部 Amazon 自营品可能这样),改用顶层 category_id 字段作为 leaf ID。

4. 双失败兜底:BSR 和 category_id 都不可用时,跳过类目验证,在最终报告 "Category Node Status" 注入 ⚠️ Category Node Audit Unavailable: ASIN 无 BSR 也无 category_id,不阻塞后续 phase。

5. 拿到 ID 后,可选调 get_category_paths(categoryIds=[<id>], site="amz_us") 验证类目路径。

   { "name": "get_category_paths", "arguments": {
     "categoryIds": ["<leaf id>"], "site": "amz_us"
   }}
   

   前提: categoryIds 是字符串数组,ID 来自上面 bestSellersRankItems[].link 解析或顶层 category_id。 Extract: data.items[] → categoryId / categoryName(Cn) / browseNodeNamePaths[](完整面包屑,如 "Electronics > Headphones > Over-Ear")。用这条 path 校验 Listing 关键词的类目相关性、确认 backend search terms 对齐正确叶子类目。

消耗品/复购筛查(R2 提取后,本地判定,不耗 tool)

判断 leaf category / 产品类型是否落在周期性复购赛道(Supplements / Beauty / Pet Food / Cartridges / Filters / Grocery 等)。命中则在五点 BULLET 4 走 LTV 分支,系统性扫 Title / features / 后端里的复购向量:

• 明确容量(count / oz / ml / days of supply)
• 消耗节奏说明(daily dose / replacement frequency)
• Subscribe & Save (S&S) 转化触发器 未命中 → BULLET 4 走标准场景化品牌文案。判定结果写进 CORE OPERATING REMINDERS 第 2 条。

R3 — 2 并发 (A3 + 最优 ASIN 差评)

2 并发拉 A3 + 最优 ASIN 的差评(挑评论数 rating 最大的 ASIN):

{ "name": "get_amazon_product", "arguments": { "asin": "<A3>", "site": "amz_us" }}
{ "name": "get_amazon_reviews", "arguments": {
  "asin": "<top_competitor_asin>",
  "site": "amz_us",
  "pageCount": 1,
  "filterByStar": "critical",
  "sortBy": "helpful"
}}

Extract reviews: data.json[0].data.results[] 前 5 条;记 title+content+star+helpful。

Skip rule: A1 + A2 的 aiReviewsSummary 已含明确负面信号 → 跳过 reviews 调用,省 5 积点。但仍然要拉 A3 的 PDP。

get_amazon_reviews 费率: 实测 5 积点/页(后端 2026-05 实测口径,旧文档"10/页"已过时)。

Fast 整合：输出 5 段 Listing 草稿

1. 痛点反转分析（来自 R3 + aiReviewsSummary）
   - 痛点 1: "材质太软" → 卖点反转: "Reinforced TPU shell"
   - 痛点 2: "续航虚标" → 卖点反转: "Verified 8h playback (in-house tested)"

2. 标题（直接可复制）
   <Brand> + <核心词1> + <型号/规格> + <主卖点1> + <适配场景> + <核心词2> + <Pack of N>
   实例:
     SoundMax Wireless Earbuds, Bluetooth 5.4 with 8H Battery, ANC for iPhone/Android, IPX7 Sport Headphones, Pack of 1
   ✓ 200 字符以内 ✓ 首 80 字含核心词 ✓ 无 ！?$ Best #1 Amazon 等违规词

3. 五点描述（5 条固定语义角色，每条 180-250 字符；每条 = ALL CAPS 摘要 + Benefit + Feature）
   1) 【核心反击 CORE ATTACK】反转 aiReviewsSummary 里最高频的差评(如"材质软"→"Reinforced TPU shell")
   2) 【AI 助手拦截 AI INTERCEPT】直接回答 Rufus 引导问题(Full 档 R3.8 实时取;Fast 档无 Rufus → 从 aiReviewsSummary 正向高频意图派生,并标"派生")
   3) 【社媒渴望 SOCIAL DESIRE】承接 off-site Reddit/TikTok 趋势卖点(Full 档 ai_search 取;Fast 档无 → 用品类通用生活场景)
   4) 【复购 & LTV / 场景化】消耗品命中 → 周期(如 "60-Day Supply" / "Replace Every 3 Months")+ 用量说明 + S&S 经济钩子;非消耗品 → 标准生活场景品牌化
   5) 【防御性品质 DEFENSIVE QUALITY】保住 aiReviewsSummary 里产品原生的正向资产,别在改写中弄丢

4. Backend Search Terms（249 字节硬上限）
   long-tail-1 long-tail-2 misspelling spanish-variant ...

5. 待 Full 档处理
   - ⏭ Rufus AI 助手意图拦截(BULLET 2 升级为实时数据)
   - ⏭ IP 合规筛查（标题里有 X / Y / Z 三个潜在风险词，含文字商标）
   - ⏭ 多页 VOC 深度挖掘 + 站外趋势

---

Full 档 SOP（在 Fast 基础上 +2-3 回合 ≤ 4min）

仅在用户明示"完整 / 深度 / 包括 IP / 包括外部 VOC"时触发。

R3.8 — on-site Rufus 意图拦截 (search_amazon_alexa) — 升级 BULLET 2

Fast 档的 BULLET 2 是从 aiReviewsSummary 派生的;Full 档用 Rufus 实时数据把它升级成"直接回答买家在 PDP 上问 AI 助手的问题"。

⏱ 这是长响应接口 —— 调用前必读:

• search_amazon_alexa 是 Rufus 实时生成,单 prompt 通常 60–90s,最大可达 ~200s;计费 6 积点/prompt。
• 强制只传 1 个 prompt: 多 prompt 线性叠加(N prompt ≈ N×6 积点 + N×响应时间),极易超 200s。永远 prompts 只放 1 条。
• 调用前在用户消息里报:"将查 1 次 Rufus 引导问题,约 6 积点 / 最长 ~200 秒,是否继续?"

{ "name": "search_amazon_alexa", "arguments": {
  "prompts": ["<核心品类名词 + 最主导的 1 个使用场景词,组成 1 条干净复合短语,如 'wireless earbuds for running'>"]
}}

不要传 marketplaceId(固定 amz_us,只接受 prompts + 可选 screenshot)。NO-URL 速度模式: 只传干净复合名词短语,严禁塞原始 URL 或整段对话。

双 502 resilience: 502 / 超时 → retry 1 次(2s backoff)。仍失败 → 不中断核心流程,平滑降级:BULLET 2 改从 aiReviewsSummary 的正向高频意图派生,并在 BULLET 2 + CORE OPERATING REMINDERS 第 3 条注入 [Partial Report: AI 助手数据因上游超时暂不可用],明确标为派生而非 Rufus 实时文本。

R4/R5 — 2 并发拉 A2+A3 差评 + 单发 ai_search 外部 VOC

⚠️ "将多抓 2 个 ASIN 各 1 页差评 + AI 搜该品类用户抱怨,约 13 积点 / ~40 秒,是否继续?"(reviews 5pt × 2 + ai_search 2pt = 12pt + buffer = 13pt)

回合 1 (5pt):

{ "name": "get_amazon_reviews", "arguments": {
  "asin": "<A2>", "pageCount": 1, "filterByStar": "critical", "sortBy": "helpful"
}}
{ "name": "get_amazon_reviews", "arguments": {
  "asin": "<A3>", "pageCount": 1, "filterByStar": "critical", "sortBy": "helpful"
}}

回合 2 (单发):

{ "name": "ai_search", "arguments": {
  "query": "what do people complain about <product_category>",
  "mode": "overview"
}}

注意: ai_search 必填参数是 query: string(0.3.0 新名;旧名 google_ai_search 已废,不再可用)。可选 mode: 'overview' | 'ai_mode'(默认 'overview')。

Extract:

• 两个 ASIN 各 5 条差评 → 痛点池扩容
• ai_search AI Overview 的 references[].url → 外部抱怨真实来源

Cluster: LLM 本地聚类 3 个 ASIN + 外部 = 12 条痛点 → Top 5 主题。

R6 — 2 并发 wipo_search(最多 3 个高风险词)

从 R1-R5 形成的标题草稿里抽 3 个潜在风险词(如 Velcro / Kevlar / Teflon / 拟用品牌名)。分批 2 并发:

// 第一批
{ "name": "wipo_search", "arguments": { "source": "USID", "prod": "<word1>", "num": 5 }}
{ "name": "wipo_search", "arguments": { "source": "USID", "prod": "<word2>", "num": 5 }}

第二批(如有):

{ "name": "wipo_search", "arguments": { "source": "USID", "prod": "<word3>", "num": 5 }}

⚠️ 严禁 source="USTM" — 后端不支持文字商标(text trademark)枚举。文字商标排查走下方 R6b 的 ai_search。

判定:

• 🔴 status='ACT' 且 hol 是大公司 → 必须替换
• 🟡 status='ACT' 但 hol 是小公司 → 建议替换
• 🟢 0 hits 或 status='EXP' → 安全

Image 引用: IMG_DATA[].filename 是相对路径(如 26/06/D0992606-0001.1-th.jpg),不能直接 paste 当 URL。最终报告引用专利图时,贴 DETAIL_URL 字段(完整 WIPO 记录 URL),IMG filename 作 supporting evidence。

R6b — 文字商标预筛 (ai_search brand legal dork,单发)

wipo USID 只覆盖外观;标题/Backend 里的文字词商标要用 ai_search 单独扫,把拟用词映射到真实法律实体并查公开注册冲突:

{ "name": "ai_search", "arguments": {
  "query": "\"<拟用词/品牌词>\" trademark (USPTO OR \"registered\" OR \"™\" OR \"®\")",
  "mode": "overview"
}}

Extract: 命中的已注册竞品文字词 → 列入禁用词,从公开文案 + Backend 剔除。初步风险雷达,非正式法律清关。

Full 报告（在 Fast 5 段基础上扩 2 段）

6. 完整 VOC 矩阵
   Top 5 痛点 + 来源 (Amazon ASIN X / Google AI Overview / Reddit ref) + 反转卖点
   (BULLET 2 若走了 Rufus 双 502 派生 fallback,这里注明)

7. IP 合规报告(分两类来源)
   🎨 设计专利(wipo USID):
   | 拟用词 | WIPO 状态 | 持有人 | 风险等级 | 替代词 |
   | Velcro | ACT | Velcro Companies | 🔴 | Hook and loop fastener |
   🔤 文字商标(ai_search legal dork): 命中的已注册文字词 → 禁用词清单 + 替代建议

   ⚠️ 免责：AI 不构成法律意见。开模/大批量备货前请咨询专业 IP 律师。

---

文案硬规则（不管 Fast/Full 都遵守）

标题位段公式

[品牌 4-15] + [核心词1 12-25] + [型号/规格 5-15] + [主卖点 15-30]
+ [适配场景 10-20] + [核心词2 10-20] + [包装/数量 5-10]

标题禁令

• ❌ ！ ? $ Best #1 Amazon
• ❌ 重复关键词
• ❌ Three-Pack（应写 "3 Pack"）
• ❌ 80 字断点处截断核心词
• ⚠️ 200 字符硬上限

五点描述

• 每条 180-250 字符，硬上限 500
• 结构：[ALL CAPS 摘要] + Benefit + Feature
• 5 条覆盖 5 个不同长尾词；单词出现 ≤ 3 次

Backend Search Terms

• 249 字节硬上限
• 去重 + 零侵权词
• 含长尾、拼写变体、西语词（US 市场）

与其他 SKILL 的协同

• 🔄 用户问"我该做哪个品" → 引导 amazon-product-explorer
• 🔄 用户问"竞品有动作吗" → 引导 amazon-daily-competitor-radar
• 🔄 IP 风险细查 → 引导 ip-clearance
• 🔄 外部 SERP 调研 → 引导 google-research

反模式

• ❌ 引用不存在字段:negative_reviews_top5 / positive_reviews_top5 / backend_keywords / bullet_points / a_plus_modules / monthlySoldVolume / bsr_category_path (真实是 features[] / productDescription[] / sales / bestSellersRankItems[] / 评论用 get_amazon_reviews)
• ❌ Fast 档调 ai_search — 30s 太慢
• ❌ 用 google_ai_search / google_trends — 已在 0.3.0 改名为 ai_search / keyword_trends,旧名直接 ToolNotFound
• ❌ 一回合 ≥ 3 个 scrapeApi 并发 → 实测会被业务码 9200 拒
• ❌ 同时跑 3 个 ASIN 的 reviews → 15 积点,必须先告知预算
• ❌ Title 用 Velcro / Kevlar / Teflon 等已知商标词不查 WIPO
• ❌ Category ID 直接取 bestSellersRankItems[0].link → [0] 通常是 slug-only URL,必须遍历整个数组,取最深 index 含 /(\d{5,})/ 命中的那个
• ❌ 尝试从 breadCrumbs 解析数字 ID → 这是 free-text 字符串,不含数字 ID;只作上下文展示用
• ❌ wipo_search(source="USTM") → 后端不支持文字商标,只 USID 设计专利;文字查询走 ai_search
• ❌ search_amazon_alexa 传 marketplaceId → 此工具固定 amz_us,只接受 prompts + 可选 screenshot
• ❌ search_amazon_alexa 一次传多个 prompt → 长响应接口(单 prompt 60–90s,最大 ~200s),多 prompt 线性叠加易超时;永远只传 1 条
• ❌ Fast 档调 search_amazon_alexa → 长响应 + 6 积点,只在 Full 档 R3.8 调;Fast 档 BULLET 2 从 aiReviewsSummary 派生
• ❌ 用 keywords(复数)调 search_amazon → 真实参数 keyword(单数,REQUIRED)
• ❌ marketplaceId="ATVPDKIKX0DER" → 这是 Amazon merchant ID,不是 filter_niches/filter_categories 入参;后者要 ISO 站点码 "US"/"UK"/"DE"
• ❌ Phase 1 abort 条件用"全部字段空"才 abort → 改用 any-field-empty 规则,任一核心字段为空就在最终报告标 ⚠️ Partial Data Warning,只在 4 个核心字段全空才完全 abort
• ❌ 先凭直觉说"做不到"再实测可查 → 违反 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	❌ 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。