Zach Listing Health Checker

前置建议

本公开版 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】→ 发现问题 → 人工修复 → 复检

上下游

2. 输入参数

支持站点配置

3. 检查项详细定义

3.1 页面可访问性

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

常见异常场景：

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

3.2 价格与优惠

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

记录字段：

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

3.3 卖家信息（Buy Box）

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

记录字段：

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

3.4 购物车状态

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

3.5 配送信息

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

记录字段：

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

3.6 类目与节点

检查内容：

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

记录字段：

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

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

3.7 BSR 排名

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

记录字段：

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

3.8 差评监控

检查内容：首页评论中的差评（1-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：首页所有结果列表（含 ASIN、标题、位置、类型）
• captcha：是否被验证码拦截

根据第 3.9 节的判断标准标记搜索可见性状态。

注意：多个 ASIN 搜索同一关键词时，只需抓取一次搜索结果页，在结果中查找所有目标 ASIN。

Step 5：生成健康检查报告

按照第 5 节的报告模板，将所有检查结果整理为 Markdown 报告。

总体评估逻辑：

• 🟢 全部通过：所有 9 项均为 ✅
• 🟡 需关注：有 ⚠️ 但无 ❌
• 🔴 有异常：有任何一项 ❌

Step 6：保存报告

将报告保存到：

outputs/listing-health-check/{品牌名或ASIN}/{YYYY-MM-DD}_{ASIN}_健康检查报告.md

如果无法从页面确定品牌名，使用卖家名称或 ASIN 作为目录名。

Step 7：输出摘要

在终端向用户输出：

1. 总体评估状态（🟢/🟡/🔴）
2. 异常项和需关注项的简要列表
3. 报告文件的保存路径

5. 输出报告模板

---
created: YYYY-MM-DD HH:MM
topic: {ASIN} Listing 健康检查
type: 健康检查报告
data_sources: 亚马逊官网页面抓取（curl + BeautifulSoup）
---

# {ASIN} Listing 健康检查报告

> 检查时间：YYYY-MM-DD HH:MM
> 站点：{站点代码} ({域名}) | 邮编：{邮编}
> 商品标题：{完整标题}

## 总体评估

| 状态 | 说明 |
|------|------|
| 🟢 / 🟡 / 🔴 | {一句话总结，如"链接健康，所有指标正常"} |

通过：X/9 | 需关注：X | 异常：X

---

## 逐项检查结果

### 1. ✅/❌ 页面可访问性
- **状态**：正常 / 异常
- **详情**：{具体描述}

### 2. ✅/⚠️/❌ 价格与优惠
- **当前售价**：${XX.XX}
- **划线价**：${XX.XX} / 无
- **折扣**：{X% off} / 无
- **优惠券**：{金额或百分比} / 无
- **Subscribe & Save**：{折扣} / 无

### 3. ✅/❌ 卖家信息（Buy Box）
- **Sold by**：{卖家名}
- **Ships from**：{发货方}
- **期望卖家**：{用户指定} → ✅ 匹配 / ❌ 不匹配 / 未指定

### 4. ✅/⚠️/❌ 购物车状态
- **Add to Cart**：有 / 无
- **Buy Now**：有 / 无
- **Buy Box 持有**：是 / 否

### 5. ✅/⚠️/❌ 配送信息
- **预计送达**：{日期}
- **Prime**：是 / 否
- **配送费**：{免费 / 金额}
- **判断**：正常（≤7天）/ 偏慢（7-14天）/ 异常（>14天）

### 6. ✅/⚠️ 类目与节点
- **搜索栏大类**：{大类名称}
- **面包屑路径**：{完整路径}
- **提示**：请人工确认节点是否为期望类目

### 7. ✅/⚠️/❌ BSR 排名

| 层级 | 类目 | 排名 |
|------|------|------|
| 大类 | {类目名} | #{排名} |
| 子类1 | {类目名} | #{排名} |
| 子类2 | {类目名} | #{排名} |

### 8. ✅/⚠️/❌ 差评监控
- **总评分**：{X.X} 星（{X,XXX} 条评论）
- **首页差评数**：{X} 条
- **差评趋势**：首次检查，无历史对比基线 / 较上次 {增加/减少} {X} 条

差评详情：

| 星级 | 标题 | 日期 | 内容摘要 |
|------|------|------|----------|
| ⭐{X} | {标题} | {日期} | {内容} |

### 9. ✅/⚠️/❌ 搜索可见性

| 关键词 | 搜索范围 | 是否找到 | 位置 | 类型 |
|--------|----------|----------|------|------|
| {keyword1} | All Departments | 是/否 | #{位置} | 自然/广告 |
| {keyword2} | {范围} | {结果} | {位置} | {类型} |

---

## 问题清单与行动建议

| 优先级 | 问题 | 建议操作 |
|--------|------|----------|
| 🔴 高 | {问题描述} | {具体建议} |
| 🟡 中 | {问题描述} | {具体建议} |

---

## 原始数据快照

> 以下为脚本抓取的原始关键信息，供核对。

{保留核心原始数据，便于日后审计}

6. 数据诚信规则

本技能严格遵守以下数据原则：

1. 数据来源唯一：所有信息来自亚马逊官网页面抓取（curl + BeautifulSoup），不使用 Sorftime MCP 或其他任何第三方数据工具。
2. 不推测未获取信息：脚本无法提取的字段，标注为「⚠️ 未能获取」，绝不编造。
3. 标注数据时效：报告中明确标注检查时间，说明"结果仅代表检查时刻的页面快照"。
4. 区分事实与判断：
   • 页面抓取到的原始信息 = 📊 数据事实
   • 基于检查结果给出的建议 = 💡 分析推断
5. 差评趋势需历史对比：首次检查只记录快照，不做"是否新增差评"的判断；有历史报告时才做对比。

7. 局限性与应对

8. 使用场景

场景 1：新品上架验收

/zach-listing-health-checker B0XXXXXXXXX US MyBrand "main keyword, secondary keyword"

上架 24-48 小时后执行，重点关注：

• 页面是否正常
• Buy Box 是否在自己手上
• 搜索关键词是否可见

场景 2：日常巡检

/zach-listing-health-checker B0XXXXXXXXX

每周例行检查，重点关注：

• 差评数量变化
• Buy Box 是否丢失
• 价格是否正确

场景 3：异常排查

帮我检查 B0XXXXXXXXX，最近销量突然下降，看看链接有没有问题

侧重排查：

• 是否被压制（搜索不可见）
• Buy Box 是否被抢
• 是否有新差评爆发

场景 4：批量检查（多 ASIN）

用户提供多个 ASIN 时，逐个执行完整检查流程，最后输出汇总表。

9. 与其他技能的数据流

本技能不消费其他技能的输出，也不产出供其他技能消费的数据。
它是一个独立的"健康巡检"工具，输出人可读的诊断报告。

唯一的"数据流"是历史报告对比：
  本次报告 ↔ 上次报告（同一 ASIN）→ 差评趋势判断

10. 依赖环境

• Python 3：运行抓取脚本
• beautifulsoup4：HTML 解析（pip install beautifulsoup4）
• curl：系统自带，用于 HTTP 请求
• Bash 工具：用于执行 Python 脚本
• Write 工具：用于保存报告文件
• Read 工具：用于读取历史报告（差评趋势对比）
• Glob 工具：用于查找历史报告文件

无需 Sorftime MCP、无需外部 API。脚本均位于 skills/zach-listing-health-checker/scripts/ 目录。

风险与边界

• risk-level: low — 纯分析/信息收集，只读取公开前台页面，不涉及任何账号操作

上游 / 下游

• 上游：无（直接输入 ASIN 或 URL）
• 下游：zach-listing-rufus-optimizer（内容诊断）、zach-asin-sales-anomaly-analyzer（异常排查）

完成后

报告完成状态：DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT