/zach-listing-health-checker

name: zach-listing-health-checker
description: |
  以真实消费者视角检查亚马逊Listing健康状态。通过网页抓取模拟消费者浏览体验，
  检查页面可见性、价格、卖家信息、购物车、配送、类目节点、排名、差评等关键指标，
  并验证关键词搜索可见性。使用时机：新品上架后验收、日常巡检、排查Listing异常。
  触发词：/zach-listing-health-checker
benefits-from: []
user-invocable: true
allowed-tools: Read, Glob, Bash, Write, Edit, Grep
risk-level: low

前置建议

本公开版 Skill 是自包含的，不依赖任何私有工作区文件、内部参考库或品牌专属协议。

开始执行前，建议先通读本 Skill 自身的方法论部分，重点关注：

• 页面可访问性判断
• Buy Box / Add to Cart / 配送状态的异常标准
• 搜索可见性验证逻辑

如果你已经有自己的 Listing 诊断框架，可以作为补充背景使用；但本 Skill 的执行不依赖外部私有资料。

Listing 健康检查器 — 完整方法论

1. 技能定位

核心理念

**通过 curl + BeautifulSoup 抓取亚马逊服务端渲染的 HTML，不借助任何 API 或第三方数据工具。**

原因：我们要验证的是"消费者打开亚马逊能看到什么"。任何 API 返回的数据都可能与前台页面不一致（缓存、区域差异、权限差异）。这个技能的价值就在于**所见即所得**。

亚马逊商品页面的核心数据（标题、价格、卖家、BSR、评论等）全部在服务端渲染的 HTML 中，无需 JavaScript 执行。curl 配合正确的浏览器 Headers 可稳定获取完整页面（~2.4MB HTML）。

Script Directory

脚本位于 `skills/zach-listing-health-checker/scripts/`：

• **browser_utils.py** — 通用网页抓取模块（curl 封装、站点配置、反爬检测），其他 Skill 可复用
• **fetch_amazon_page.py** — 商品页面抓取，提取 9 项检查数据，输出 JSON
• **fetch_amazon_search.py** — 搜索结果页抓取，检查 ASIN 搜索可见性，输出 JSON

工作流位置

新品上架流程：
  zach-new-product-listing-writer → zach-launch-checklist-generator
      → 【zach-listing-health-checker：上架验收】
      → zach-ad-campaign-builder → 广告投放

日常运营：
  定期巡检 → 【zach-listing-health-checker】→ 发现问题 → 人工修复 → 复检

上下游

| 方向 | 技能 | 关系 | |------|------|------| | 上游 | zach-new-product-listing-writer | Listing 创建完成后需要验收 | | 上游 | zach-launch-checklist-generator | 上架检查清单的执行环节之一 | | 下游 | 人工修复 | 检查出问题后需要人工介入 | | 下游 | 复检（再次调用本技能） | 修复后重新验证 |

---

2. 输入参数

| 参数 | 必需 | 默认值 | 说明 | |------|------|--------|------| | ASIN | ✅ 是 | — | 10 位字母数字，通常以 B0 开头 | | 站点代码 | 否 | US | 支持的站点见下方列表 | | 卖家名称 | 否 | — | 用于校验 Sold By 是否正确 | | 核心关键词 | 否 | — | 逗号分隔，用于搜索可见性验证 |

支持站点配置

| 站点代码 | 域名 | 默认邮编 | 货币 | |----------|------|----------|------| | US | amazon.com | 90001 | USD | | UK / GB | amazon.co.uk | SW1A 1AA | GBP | | DE | amazon.de | 10115 | EUR | | FR | amazon.fr | 75001 | EUR | | IT | amazon.it | 00100 | EUR | | ES | amazon.es | 28001 | EUR | | CA | amazon.ca | M5V 2T6 | CAD | | JP | amazon.co.jp | 100-0001 | JPY | | MX | amazon.com.mx | 06600 | MXN | | AU | amazon.com.au | 2000 | AUD |

---

3. 检查项详细定义

3.1 页面可访问性

**检查内容**：页面是否正常渲染商品信息。

| 状态 | 判断条件 | |------|----------| | ✅ 正常 | 页面包含商品标题、图片、价格等核心元素 | | ❌ 异常 | 出现狗狗页面（Dog page）、404、"Looking for something?"、"Currently unavailable"、验证码页面 |

**常见异常场景**：

• ASIN 被下架 → 狗狗页面或 "Currently unavailable"
• ASIN 被合并到其他变体 → 自动跳转
• 区域限制 → "This item does not ship to your location"

3.2 价格与优惠

**检查内容**：当前售价、划线价、折扣、优惠券。

| 状态 | 判断条件 | |------|----------| | ✅ 正常 | 有明确售价显示 | | ⚠️ 需关注 | 价格与预期差异较大（需用户判断） | | ❌ 异常 | 无价格显示、显示 "See price in cart"、或价格为 $0 |

**记录字段**：

• 当前售价
• 划线价（List Price / Was Price）
• 折扣百分比
• 优惠券（Coupon）金额或百分比
• 是否有"Subscribe & Save"折扣

3.3 卖家信息（Buy Box）

**检查内容**：Sold by 和 Ships from 信息。

| 状态 | 判断条件 | |------|----------| | ✅ 正常 | Sold by 显示为用户指定的卖家名称 | | ❌ 异常 | Sold by 不是指定卖家（Buy Box 被抢） | | ⚠️ 需关注 | 用户未指定卖家，仅记录当前信息 |

**记录字段**：

• Sold by：卖家名称
• Ships from：发货方（Amazon / 卖家名 / 第三方）
• 是否为 FBA（Ships from Amazon）

3.4 购物车状态

**检查内容**：是否有 Add to Cart / Buy Now 按钮。

| 状态 | 判断条件 | |------|----------| | ✅ 正常 | 同时显示 Add to Cart 和 Buy Now | | ⚠️ 需关注 | 只有 Add to Cart 没有 Buy Now，或显示 "See All Buying Options" | | ❌ 异常 | 无购买按钮，或显示 "Currently unavailable" |

3.5 配送信息

**检查内容**：预计送达时间和 Prime 状态。

| 状态 | 判断条件 | |------|----------| | ✅ 正常 | 有明确的预计送达日期，且在 7 天以内 | | ⚠️ 需关注 | 配送时间 7-14 天 | | ❌ 异常 | 配送时间超过 14 天、或无配送信息 |

**记录字段**：

• 预计送达日期
• 是否有 Prime 标识
• 配送费用（免费/具体金额）

3.6 类目与节点

**检查内容**： 1. 搜索栏旁的大类（department selector） 2. 面包屑导航中的销售节点路径（通常在主图上方）

| 状态 | 判断条件 | |------|----------| | ✅ 正常 | 能正常显示类目信息 | | ⚠️ 需人工确认 | 类目信息显示正常，但需人工确认是否为期望的节点 |

**记录字段**：

• 搜索栏大类名称
• 面包屑完整路径（如 `Musical Instruments › Electronic Music, DJ & Karaoke › Karaoke Equipment › Systems › Portable Systems`）

> 注意：类目节点的"正确性"需要人工判断，技能只负责抓取和展示，不做自动判断。

3.7 BSR 排名

**检查内容**：Best Sellers Rank 在各层级类目中的排名。

| 状态 | 判断条件 | |------|----------| | ✅ 正常 | 有 BSR 排名数据 | | ⚠️ 需关注 | 排名显著下跌（需历史对比） | | ❌ 异常 | 无 BSR 排名（可能表示商品未正常入库或类目异常） |

**记录字段**：

• 每个层级的类目名称 + 排名数字
• 示例：`#152 in Musical Instruments` → `#3 in Portable Karaoke Systems`

3.8 差评监控

**检查内容**：首页评论中的差评（1-3 星）数量和内容。

| 状态 | 判断条件 | |------|----------| | ✅ 正常 | 首页 0 条差评 | | ⚠️ 需关注 | 首页 1-2 条差评 | | ❌ 异常 | 首页 3 条及以上差评 |

**记录字段**：

• 总评分（星级）
• 总评论数
• 首页差评条数
• 每条差评的：星级、标题、简要内容、日期
• 差评趋势判断：首次检查标注「首次检查，无历史对比基线」；有历史报告时对比差评数变化

3.9 搜索可见性

**检查内容**：用核心关键词搜索后，商品是否出现在搜索结果首页。

| 状态 | 判断条件 | |------|----------| | ✅ 正常 | 在首页自然位找到 | | ⚠️ 需关注 | 仅在广告位找到，自然位未找到 | | ❌ 异常 | 首页完全未找到（可能被压制或搜索不可见） |

**关键操作**：

• 搜索时确保选择 "All Departments"，不要被限定在某个子类目
• 区分自然位（Organic）和广告位（Sponsored）
• 记录具体位置编号

---

4. 执行步骤（详细）

Step 1：参数解析与准备

1. 从用户输入中提取 ASIN、站点代码、卖家名称、核心关键词 2. 验证 ASIN 格式（10 位字母数字） 3. 根据站点代码查找域名和默认邮编 4. 如果用户未提供站点代码，默认使用 US 5. 构建商品页面 URL：`https://{domain}/dp/{ASIN}`

Step 2：抓取商品页面

运行 `fetch_amazon_page.py` 脚本抓取商品页面并提取结构化数据：

python3 skills/zach-listing-health-checker/scripts/fetch_amazon_page.py {ASIN} --site {站点代码}

脚本输出 JSON，包含以下字段：

• `page_status`：页面状态（ok / dog_page / unavailable / captcha / fetch_failed）
• `title`：商品标题
• `price`：当前售价、划线价、折扣、优惠券
• `seller`：sold_by、ships_from
• `cart`：add_to_cart、buy_now、see_all_buying_options
• `delivery`：配送文本、Prime 标识
• `category`：搜索栏大类、面包屑路径
• `bsr`：各层级排名和类目
• `ratings`：评分星级、评论总数
• `reviews_on_page`：首页评论详情（星级、标题、日期、内容、是否差评）
• `variants`：变体信息
• `stock`：库存状态
• `anomalies`：异常提示列表

Step 3：解析检查结果

将脚本返回的 JSON 数据逐项对照第 3 节的判断标准，为每个检查项标记状态：

• ✅ 正常
• ⚠️ 需关注
• ❌ 异常

对于脚本未能提取的字段（值为空或缺失），标注为「⚠️ 未能获取」，不做推测。

Step 4：搜索可见性检查

⛔ **仅在用户提供了核心关键词时执行本步骤。**

对每个核心关键词，运行 `fetch_amazon_search.py` 脚本：

python3 skills/zach-listing-health-checker/scripts/fetch_amazon_search.py "{keyword}" {ASIN} --site {站点代码}

脚本输出 JSON，包含：

• `target_found`：目标 ASIN 是否在首页
• `target_position`：位置编号
• `target_type`：organic（自然位）或 sponsored（广告位）
• `search_department`：搜索范围
• `first_page_results`：首页所有结果列表（含