zach-listing-health-checker

事前の推奨事項

この公開版 Skill は自己完結型であり、プライベートなワークスペースファイル、内部リファレンスライブラリ、ブランド専用プロトコルには依存しません。

実行を開始する前に、まずこの Skill 自体の方法論のセクションに目を通すことをおすすめします。特に、以下の点を確認してください。

• ページのアクセス可否の判定
• Buy Box／Add to Cart／配送状況の異常基準
• 検索での表示確認ロジック

独自の Listing 診断フレームワークがある場合は、補足情報として利用できます。ただし、この Skill の実行に外部のプライベート資料は必要ありません。

Listing ヘルスチェッカー — 完全な方法論

1. スキルの位置付け

中核となる考え方

curl + BeautifulSoup を使って、Amazon のサーバー側でレンダリングされた HTML を取得します。API やサードパーティのデータツールは使用しません。

理由：確認したいのは「消費者が Amazon を開いたときに何が見えるか」です。API が返すデータは、フロントエンドのページと一致しない場合があります（キャッシュ、地域差、権限の違いなど）。このスキルの価値は、見たままの情報を取得できることにあります。

Amazon 商品ページの主要データ（タイトル、価格、販売者、BSR、レビューなど）はすべてサーバー側でレンダリングされた HTML に含まれており、JavaScript を実行する必要はありません。curl に適切なブラウザー Headers を組み合わせれば、完全なページ（約 2.4 MB の HTML）を安定して取得できます。

スクリプトディレクトリ

スクリプトは 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	出品チェックリストの実行工程の 1 つです
下流	手動での修正	問題が見つかった場合、手動での対応が必要です
下流	再チェック（このスキルを再度実行）	修正後に再検証します

---

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」、CAPTCHA ページが表示される

よくある異常ケース：

• 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 検索での表示状況

確認内容：主要キーワードで検索したとき、商品が検索結果の1ページ目に表示されるかを確認します。

状態	判定条件
✅ 正常	1ページ目の自然検索結果で見つかる
⚠️ 要確認	広告枠でのみ見つかり、自然検索結果では見つからない
❌ 異常	1ページ目にまったく見つからない（抑制されているか、検索で表示されない可能性があります）

重要な操作：

• 検索時に「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：1ページ目のレビュー詳細（星評価、タイトル、日付、内容、低評価かどうか）
• 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 が1ページ目にあるかどうか
• target_position：掲載位置番号
• target_type：organic（自然検索結果）または sponsored（広告枠）
• search_department：検索対象範囲
• first_page_results：1ページ目のすべての検索結果一覧（ASIN、タイトル、位置、種類を含む）
• captcha：CAPTCHA によるブロックの有無

第 3.9 節の判定基準に従って、検索での表示状況を判定します。

注意：複数の ASIN を同じキーワードで検索する場合、検索結果ページの取得は1回だけで十分です。結果から対象の ASIN をすべて確認します。

Step 5：ヘルスチェックレポートの作成

第 5 節のレポートテンプレートに従い、すべての確認結果を Markdown レポートにまとめます。

全体評価の判定基準：

• 🟢 すべて合格：9 項目すべてが ✅
• 🟡 要確認：⚠️ があり、❌ がない
• 🔴 異常あり：❌ が1つ以上ある

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. データソースは1つのみ：すべての情報は Amazon 公式サイトのページ取得（curl + BeautifulSoup）から取得し、Sorftime MCP やその他のサードパーティ製データツールは使用しません。
2. 取得できなかった情報は推測しない：スクリプトで抽出できなかったフィールドは「⚠️ 取得できませんでした」と記載し、決して捏造しません。
3. データの時点を明記する：レポートに確認時刻を明記し、「結果は確認時点のページスナップショットのみを表します」と説明します。
4. 事実と判断を区別する：
   • ページから取得した元の情報 ＝ 📊 データ上の事実
   • 確認結果に基づく提案 ＝ 💡 分析による推論
5. 低評価レビューの傾向は過去のデータと比較する：初回の確認ではスナップショットを記録するのみとし、「低評価レビューが新たに追加されたか」は判断しません。過去のレポートがある場合にのみ比較します。

---

7. 制限事項と対処方法

制限事項	説明	対処方法
JS による動的コンテンツ	curl はサーバー側でレンダリングされた HTML を取得するため、JS で動的に読み込まれるコンテンツが欠落する場合があります	重要な情報が欠落している場合は「⚠️ 動的読み込みが原因で取得できなかった可能性があります」と記載します
クローラー対策	Amazon が CAPTCHA または簡略化されたページを返す場合があります	スクリプトが CAPTCHA を自動検出し、レポートに「❌ Amazon にブロックされました。手動で確認することをおすすめします」と記載します
地域差	郵便番号を実際に設定していないため、価格や配送の表示に影響する可能性があります	レポートに使用した郵便番号とサイトを記載します
検索のパーソナライズ	検索結果はアルゴリズムの影響を受けます	「検索結果は特定時点のスナップショットであり、ユーザープロファイルによって異なる場合があります」と明記します
1回限りのスナップショット	「低評価レビューが突然追加された」など、時系列での変化は検出できません	定期的に実行し、過去のレポートと比較することをおすすめします

---

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 が提供された場合は、1つずつ完全な確認手順を実行し、最後に集計表を出力します。

---

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