--- name: amazon-listing-optimization description: | Use when: user says "写/优化 Listing" / "改我的标题" / "我的五点不行" / "Search Terms 怎么写" / "竞品文案怎么抄" / "rewrite my listing" / "我的转化率差" / "VOC 分析". Covers: 5-step Listing optimization — VOC 痛点挖掘 (来自 reviews) → 标题/五点/Backend 写作 → IP 合规自动筛查 → 文案可直接复制上架。 NOT for: 选品 (use amazon-product-explorer) / 日常监控 (use amazon-daily-competitor-radar) / 单纯 ASIN 详情 (call get_amazon_product directly). version: 3.1.0 mcp_tools_used: - pangolinfo_capabilities - search_amazon - get_amazon_product - get_amazon_reviews - ai_search - wipo_search - get_category_paths - search_amazon_alexa applies_to: [claude-code, cursor, cline, windsurf, hermes, codex, openclaw] budget: fast: { duration: "≤ 90s", cost: "≤ 10 积点", calls: "≤ 5" } full: { duration: "≤ 4min", cost: "≤ 40 积点", calls: "≤ 12" } --- # 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 ```jsonc { "name": "search_amazon", "arguments": { "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) ```jsonc { "name": "get_amazon_product", "arguments": { "asin": "", "site": "amz_us" }} { "name": "get_amazon_product", "arguments": { "asin": "", "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=[], site="amz_us")` 验证类目路径。 ```jsonc { "name": "get_category_paths", "arguments": { "categoryIds": [""], "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): ```jsonc { "name": "get_amazon_product", "arguments": { "asin": "", "site": "amz_us" }} { "name": "get_amazon_reviews", "arguments": { "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. 标题（直接可复制） + <核心词1> + <型号/规格> + <主卖点1> + <适配场景> + <核心词2> + 实例: 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 秒,是否继续?" ```jsonc { "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): ```jsonc { "name": "get_amazon_reviews", "arguments": { "asin": "", "pageCount": 1, "filterByStar": "critical", "sortBy": "helpful" }} { "name": "get_amazon_reviews", "arguments": { "asin": "", "pageCount": 1, "filterByStar": "critical", "sortBy": "helpful" }} ``` 回合 2 (单发): ```jsonc { "name": "ai_search", "arguments": { "query": "what do people complain about ", "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 并发**: ```jsonc // 第一批 { "name": "wipo_search", "arguments": { "source": "USID", "prod": "", "num": 5 }} { "name": "wipo_search", "arguments": { "source": "USID", "prod": "", "num": 5 }} ``` 第二批(如有): ```jsonc { "name": "wipo_search", "arguments": { "source": "USID", "prod": "", "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 单独扫,把拟用词映射到真实法律实体并查公开注册冲突: ```jsonc { "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=` / 同名 env `PANGOLINFO_API_KEY` / `~/.pangolinfo/config.json` / hosted URL `?api_key=` 或 HTTP 头 `Authorization: Bearer `）。 两者**互相独立**：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 并发,回合之间间隔 ~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=` 或 `Authorization: Bearer `)。**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`。