amazon-product-research-%26-seller-analytics by serendipityoneinc/amazon-analysis-skill
npx skills add https://github.com/serendipityoneinc/amazon-analysis-skill --skill 'Amazon Product Research & Seller Analytics'人工智能驱动的亚马逊产品研究。从市场发现到日常运营。
语言规则:始终使用用户的语言进行回复。如果用户使用中文提问,则用中文回复。如果使用英文,则用英文回复。此技能文档的语言不影响输出语言。所有 API 调用都通过
scripts/apiclaw.py进行 — 一个脚本,5 个端点,内置错误处理。
必需:APICLAW_API_KEY
作用域:仅用于 https://api.apiclaw.io
设置:引导用户设置环境变量:
export APICLAW_API_KEY='hms_live_xxxxxx'
备用方案:如果未设置环境变量,脚本还会检查技能根目录中的 config.json。
请勿将密钥写入磁盘文件。 始终推荐使用环境变量方法。
新密钥可能需要 3-5 秒才能激活 — 如果首次调用返回 403,请等待 3 秒后重试(最多重试 2 次)。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 文件 | 何时加载 |
|---|---|
SKILL.md (本文件) | 从这里开始 — 涵盖 80% 的任务 |
scripts/apiclaw.py | 执行 所有 API 调用(请勿读入上下文) |
references/reference.md | 需要确切的字段名或筛选参数详情 |
references/scenarios-composite.md | 综合推荐 (2.10) 或中文卖家案例 (3.4) |
references/scenarios-eval.md | 产品评估、风险评估、评论分析 (4.x) |
references/scenarios-pricing.md | 定价策略、利润估算、Listing 参考 (5.x) |
references/scenarios-ops.md | 市场监控、竞品追踪、异常警报 (6.x) |
references/scenarios-expand.md | 产品拓展、趋势、下架决策 (7.x) |
references/scenarios-listing.md | Listing 撰写、优化、内容创作 (8.x) |
不要猜测字段名 — 如果不确定,请先加载 reference.md。
| 任务类型 | 模式 | 行为 |
|---|---|---|
| 单个 ASIN 查询,简单数据查询 | 快速 | 执行命令,返回关键数据。跳过评估标准和输出标准块。 |
| 市场分析、产品筛选、竞品对比、风险评估 | 完整 | 完整流程:命令 → 分析 → 评估标准 → 输出标准块。 |
快速模式触发条件: 用户询问单个特定数据点("B09XXX 的月销量?"、"猫砂有多少个品牌?")— 无需决策分析。
在执行任何完整模式的产品筛选或市场分析之前,请完成此检查清单:
--mode xxx)。当存在预设模式时,请勿手动拼凑筛选条件。常见映射:
--mode low-price--mode beginner--mode long-tail--mode emergingproduct --asin(见下方实时数据补充)。analyze --asins 以获取消费者洞察(特别是 painPoints, improvements, buyingFactors)。📋 数据来源与条件 和 📊 API 使用情况。为何存在此清单: 在测试中,AI 代理反复跳过预设模式、实时数据补充和评论分析 — 尽管下面的说明已清楚描述。此清单强制在执行前暂停并验证。
优先使用脚本执行 API 调用。 脚本包含:
_query 元数据注入(用于查询追溯)备用方案: 如果脚本失败且无法快速修复,则直接使用 curl。在输出中注明"使用 curl 直接调用"。
当 products 或 competitors 在完整模式分析中返回 ASIN 时,为前 3-5 个最相关的 ASIN 调用 product --asin 以获取当前实时数据。对于批量查询(>3 个 ASIN),请在继续之前与用户确认。
| 场景 | 补充? | 补充多少 ASIN |
|---|---|---|
| 单个 ASIN 查询(快速模式) | 已使用实时数据 | — |
| 市场概览(无特定 ASIN) | ❌ 否 | — |
| 产品筛选 / 竞品分析 | ✅ 是 | 按销量前 3 |
| 风险评估 | ✅ 是 | 目标 ASIN + 前 2 竞品 |
| 多产品对比 | ✅ 是 | 所有对比的 ASIN(最多 5 个) |
| Listing 分析 | 已使用实时数据 | — |
处理数据冲突 — products/competitors 有约 T+1 延迟;realtime/product 是实时的:
| 字段 | 使用来源 | 原因 |
|---|---|---|
| 价格 | 实时 (buyboxWinner.price) | 频繁变动 |
| BSR | 实时 (bestsellersRank) | 每小时更新 |
| 评分 / 评分数量 | 实时 | 更及时 |
| 月销量 | products/competitors | 实时数据无此字段 |
| 利润率 / FBA 费用 | products/competitors | 实时数据无此字段 |
当实时数据差异显著时,请注明:例如 "⚡ 价格已更新:数据库 $29.99 → 实时 $24.99 (可能为促销)"
所有命令输出 JSON。进度消息输出到 stderr。
python3 scripts/apiclaw.py categories --keyword "pet supplies"
python3 scripts/apiclaw.py categories --parent "Pet Supplies"
常用字段:categoryName (不是 name), categoryPath, productCount, hasChildren
python3 scripts/apiclaw.py market --category "Pet Supplies,Dogs" --topn 10
关键输出字段:sampleAvgMonthlySales, sampleAvgPrice, topSalesRate (集中度), topBrandSalesRate, sampleNewSkuRate, sampleFbaRate, sampleBrandCount
# 预设模式 (14 种内置)
python3 scripts/apiclaw.py products --keyword "yoga mat" --mode beginner
# 显式筛选条件
python3 scripts/apiclaw.py products --keyword "yoga mat" --sales-min 300 --reviews-max 50
# 模式 + 覆盖 (覆盖项优先)
python3 scripts/apiclaw.py products --keyword "yoga mat" --mode beginner --price-max 30
可用模式:fast-movers, emerging, single-variant, high-demand-low-barrier, long-tail, underserved, new-release, fbm-friendly, low-price, broad-catalog, selective-catalog, speculative, beginner, top-bsr
关键词匹配: 默认为 fuzzy (也匹配品牌名 — 例如 "smart ring" 会匹配 "Smart Color Art" 的笔)。使用 --keyword-match-type exact 或 phrase 获取精确结果。尽可能与 --category 结合使用以减少噪音。
包含逗号的类目路径: 某些类目名称包含逗号 (例如 "Pacifiers, Teethers & Teething Relief")。使用 > 分隔符代替 , 以避免解析错误:
# ❌ 错误 — 名称中的逗号会破坏解析
--category "Baby Products,Baby Care,Pacifiers, Teethers & Teething Relief"
# ✅ 正确 — 使用 ' > ' 分隔符
--category "Baby Products > Baby Care > Pacifiers, Teethers & Teething Relief"
python3 scripts/apiclaw.py competitors --keyword "wireless earbuds"
python3 scripts/apiclaw.py competitors --asin B09V3KXJPB
易混淆字段 (products/competitors 共有) :
| ❌ 错误 | ✅ 正确 | 备注 |
|---|---|---|
reviewCount | ratingCount | 评论数量 |
bsr | bsrRank | BSR 排名 (整数,仅在 products/competitors 中) |
monthlySales / salesMonthly | atLeastMonthlySales | 月销量 (下限估计,不在 realtime/product 中) |
bestsellersRank | bsrRank | bestsellersRank 仅在 realtime/product 中 (数组格式);对于 products/competitors 使用 bsrRank |
price (在 realtime 中) | buyboxWinner.price | realtime/product 将价格嵌套在 buyboxWinner 对象内 |
profitMargin (在 realtime 中) | ❌ 无 | realtime/product 不返回 profitMargin;使用 products/competitors |
完整字段列表:
reference.md→ 共享产品对象
python3 scripts/apiclaw.py product --asin B09V3KXJPB
返回:title, brand, rating, ratingBreakdown, features, topReviews, specifications, variants, bestsellersRank, buyboxWinner
# 单个 ASIN
python3 scripts/apiclaw.py analyze --asin B09V3KXJPB
# 多个 ASIN (竞品评论对比)
python3 scripts/apiclaw.py analyze --asins B09V3KXJPB,B08YYYYY,B07ZZZZZ
# 类目级别洞察
python3 scripts/apiclaw.py analyze --category "Pet Supplies,Dogs,Toys" --period 90d
# 特定洞察维度
python3 scripts/apiclaw.py analyze --asin B09V3KXJPB --label-type painPoints,buyingFactors
返回:totalReviews, avgRating, sentimentDistribution, ratingDistribution, consumerInsights (按 labelType), topKeywords, verifiedRatio
可用 labelType:scenarios, issues, positives, improvements, buyingFactors, painPoints, keywords, userProfiles, usageTimes, usageLocations, behaviors
python3 scripts/apiclaw.py report --keyword "pet supplies"
运行:categories → market → products (前 50) → realtime detail (前 1)。
python3 scripts/apiclaw.py opportunity --keyword "pet supplies" --mode fast-movers
运行:categories → market → products (筛选后) → realtime detail (前 3)。
4 种类型的接口返回不同的字段。请勿假设它们共享相同的结构。
| 数据 | market | products/competitors | realtime/product | reviews/analyze |
|---|---|---|---|---|
| 月销量 | sampleAvgMonthlySales | ✅ atLeastMonthlySales | ❌ | ❌ |
| 收入 | sampleAvgMonthlyRevenue | salesRevenue | ❌ | ❌ |
| 价格 | sampleAvgPrice | price | buyboxWinner.price | ❌ |
| BSR | sampleAvgBsr | bsrRank (整数) | bestsellersRank (数组) | ❌ |
| 评分 | sampleAvgRating | rating | rating | avgRating |
| 评论数量 | sampleAvgReviewCount | ratingCount | ratingCount | totalReviews |
| 评论详情 | ❌ | ❌ | ✅ topReviews + ratingBreakdown | ❌ (无原始评论) |
| 情感分析 | ❌ | ❌ | ❌ | ✅ sentimentDistribution |
| 消费者洞察 | ❌ | ❌ | ❌ | ✅ consumerInsights (11 个维度) |
| 痛点/问题 | ❌ | ❌ | ❌ (从 topReviews 手动提取) | ✅ AI 分析 |
| 关键词 | ❌ | ❌ | ❌ | ✅ topKeywords |
| 卖家 | ❌ | buyboxSeller (字符串) | buyboxWinner (对象) | ❌ |
| 利润率 | ❌ | profitMargin | ❌ | ❌ |
| FBA 费用 | ❌ | fbaFee | ❌ | ❌ |
| 卖家数量 | ❌ | sellerCount | ❌ | ❌ |
| 特性/要点 | ❌ | ❌ | ✅ features | ❌ |
| 变体 | ❌ | variantCount (整数) | variants (完整列表) | ❌ |
使用规则:
products / competitors 获取销量、定价和竞争数据realtime/product 获取评论详情、Listing 内容和卖家信息market 获取类目级别聚合指标reviews/analyze 获取AI 驱动的评论洞察 (情感、痛点、购买因素 — 涵盖所有评论,而不仅仅是 topReviews)products/competitors (定量) + realtime/product (定性) + reviews/analyze (消费者洞察) 作为证据所有接口返回的 .data 都是一个数组。使用 .data[0] 获取第一条记录,不是 .data.fieldName。
| 用户说 | 运行此命令 | 场景文件? |
|---|---|---|
| "哪个类目有机会" | market + categories | 否 |
| "检查 B09XXX" / "分析 ASIN" | product --asin XXX | 否 |
| "中文卖家案例" | competitors --keyword XXX --page-size 50 | scenarios-composite.md → 3.4 |
| "痛点" / "差评" / "消费者洞察" | analyze --asin XXX + product --asin XXX | scenarios-eval.md → 4.2 |
| "类目痛点" / "类目用户画像" | analyze --category XXX | scenarios-eval.md → 4.6 |
| "对比产品" | competitors 或多个 product | scenarios-eval.md → 4.3 |
| "风险评估" / "我能做这个吗" | product + market + competitors | scenarios-eval.md → 4.4 |
| "月销量" / "估算销量" | competitors --asin XXX | scenarios-eval.md → 4.5 |
| "帮我选品" / "找产品" | products --mode XXX (见模式表) | 否 |
| "综合推荐" / "我应该卖什么" | products (多模式) + market | scenarios-composite.md → 2.10 |
| "定价策略" / "定多少价" | market + products | scenarios-pricing.md → 5.1 |
| "利润估算" | competitors | scenarios-pricing.md → 5.2 |
| "Listing 参考" | product --asin XXX | scenarios-pricing.md → 5.3 |
| "市场变化" / "近期变化" | market + products | scenarios-ops.md → 6.1 |
| "竞品更新" | competitors --brand XXX | scenarios-ops.md → 6.2 |
| "异常警报" | market + products | scenarios-ops.md → 6.4 |
| "我还能卖什么" / "相关产品" | categories + market | scenarios-expand.md → 7.1 |
| "趋势" | products --growth-min 0.2 | scenarios-expand.md → 7.3 |
| "我应该下架吗" | competitors --asin XXX + market | scenarios-expand.md → 7.4 |
| "写 Listing" / "生成要点" / "写标题" | product --asin XXX (竞品) | scenarios-listing.md → 8.2 |
| "分析竞品 Listing" / "他们的卖点" | product --asin XXX (多个) | scenarios-listing.md → 8.1 |
| "优化我的 Listing" / "Listing 诊断" | product --asin XXX + competitors | scenarios-listing.md → 8.3 |
| 需要确切的筛选条件或字段名 | — | 加载 reference.md |
产品筛选模式映射 (14 种) :
| 用户意图 | 模式 | 关键筛选条件 |
|---|---|---|
| "适合新手" / "新卖家" | --mode beginner | Sales≥300, growth≥3%, $15-60, FBA, ≤1yr, 自动排除 150+ 红海关键词 |
| "快周转" / "热卖" | --mode fast-movers | Sales≥300, growth≥10% |
| "新兴" / "上升" | --mode emerging | Sales≤600, growth≥10%, ≤180d |
| "单一变体" / "小而美" | --mode single-variant | Growth≥20%, variants=1, ≤180d |
| "高需求低门槛" / "易进入" | --mode high-demand-low-barrier | Sales≥300, reviews≤50, ≤180d |
| "长尾" / "利基" | --mode long-tail | Sales≤300, BSR 10K-50K, ≤$30, sellers≤1 |
| "服务不足" / "有痛点" | --mode underserved | Sales≥300, rating≤3.7, ≤180d |
| "新品" / "新发布" | --mode new-release | Sales≤500, NR 标签, FBA+FBM |
| "FBM" / "自发货" / "低库存" | --mode fbm-friendly | Sales≥300, FBM, ≤180d |
| "低价" / "便宜" | --mode low-price | ≤$10 |
| "宽泛选品" / "广撒网" | --mode broad-catalog | BSR growth≥99%, reviews≤10, ≤90d |
| "精选选品" | --mode selective-catalog | BSR growth≥99%, ≤90d |
| "投机" / "搭便车" | --mode speculative | Sales≥600, sellers≥3, ≤180d |
| "头部卖家" / "畅销品" | --mode top-bsr | 子类目 BSR≤1000 |
market 输出)| 指标 | 良好 | 中等 | 警告 |
|---|---|---|---|
| 市场价值 (avgRevenue × skuCount) | > $10M | $5–10M | < $5M |
| 集中度 (topSalesRate, topN=10) | < 40% | 40–60% | > 60% |
| 新 SKU 率 (sampleNewSkuRate) | > 15% | 5–15% | < 5% |
| FBA 率 (sampleFbaRate) | > 50% | 30–50% | < 30% |
| 品牌数量 (sampleBrandCount) | > 50 | 20–50 | < 20 |
product 输出)| 指标 | 高 | 中等 | 低 |
|---|---|---|---|
| BSR | 前 1000 | 1000–5000 | > 5000 |
| 评论数 | < 200 | 200–1000 | > 1000 |
| 评分 | > 4.3 | 4.0–4.3 | < 4.0 |
| 差评 (1-2★ %) | < 10% | 10–20% | > 20% |
当 atLeastMonthlySales 为 null 时:月销量 ≈ 300,000 / BSR^0.65
每个完整模式分析的末尾必须包含以下两个块:① 数据来源与条件,② API 使用情况。缺少任何一个 = 违反技能契约。
---
📋 **数据来源与条件**
| 项目 | 值 |
|----|-----|
| 数据来源 | APIClaw API |
| 接口 | [使用的接口] |
| 类目 | [类目路径] |
| 时间范围 | [dateRange] |
| 采样 | [sampleType] |
| Top N | [topN 值] |
| 排序 | [sortBy + sortOrder] |
| 筛选条件 | [具体的参数值] |
**数据说明**
- 月销量为**下限估计值** (亚马逊显示"10,000+ bought"),实际可能更高
- 数据库数据有约 T+1 延迟;realtime/product 是当前实时数据
- 集中度指标基于 Top N 样本;不同的 topN → 不同的结果
规则:
📋 **数据来源与条件**,请在回复前添加它此块是强制性的。 每一个响应 — 无论是快速模式还是完整模式 — 必须以此表结尾。没有例外。如果你忘记了,就是违反了技能契约。
📊 **API 使用情况**
| 接口 | 调用次数 |
|-----------|-------|
| categories | 1 |
| markets/search | 1 |
| products/search | 2 |
| realtime/product | 3 |
| reviews/analyze | 1 |
| **总计** | **8** |
| **已消耗积分** | **8** |
| **剩余积分** | **492** |
追踪规则:
apiclaw.py 执行计为对应接口的 1 次调用_credits.consumed 作为总消耗_credits.remaining 作为剩余余额_credits 字段为 null,则显示"N/A"📊 **API 使用情况**,请在回复前添加它realtime/product 的 topReviews 获取特定评论引用)| 场景 | 覆盖情况 | 建议 |
|---|---|---|
| 市场数据:热门关键词 | ✅ 有数据 | 直接使用 --keyword |
| 市场数据:利基/长尾关键词 | ⚠️ 可能为空 | 改用 --category |
| 产品数据:活跃 ASIN | ✅ 有数据 | — |
| 产品数据:已下架/变体 ASIN | ❌ 无数据 | 尝试父 ASIN 或 realtime |
| 实时数据:美国站点 | ✅ 完全支持 | — |
| 实时数据:非美国站点 | ⚠️ 部分支持 | 核心字段 OK,销量可能为 null |
HTTP 错误 (401/402/403/404/429) 由脚本处理并输出结构化的 JSON。自检:python3 scripts/apiclaw.py check
| 错误 | 修复方法 |
|---|---|
Cannot index array with string | 使用 .data[0].fieldName (.data 是数组) |
空 data: [] | 使用 categories 确认类目存在 |
atLeastMonthlySales: null | BSR 估算:300,000 / BSR^0.65 |
每周安装次数
–
仓库
GitHub Stars
27
首次出现
–
AI-powered Amazon product research. From market discovery to daily operations.
Language rule : Always respond in the user's language. If the user asks in Chinese, reply in Chinese. If in English, reply in English. The language of this skill document does not affect output language. All API calls go through
scripts/apiclaw.py— one script, 5 endpoints, built-in error handling.
Required: APICLAW_API_KEY
Scope: used only for https://api.apiclaw.io
Setup: Guide user to set the environment variable:
export APICLAW_API_KEY='hms_live_xxxxxx'
Fallback: The script also checks config.json in the skill root directory if the env var is not set.
Do NOT write keys to disk files. Always recommend the environment variable approach.
New keys may need 3-5 seconds to activate — if first call returns 403, wait 3 seconds and retry (max 2 retries).
| File | When to Load |
|---|---|
SKILL.md (this file) | Start here — covers 80% of tasks |
scripts/apiclaw.py | Execute for all API calls (do NOT read into context) |
references/reference.md | Need exact field names or filter parameter details |
references/scenarios-composite.md | Comprehensive recommendations (2.10) or Chinese seller cases (3.4) |
references/scenarios-eval.md | Product evaluation, risk assessment, review analysis (4.x) |
references/scenarios-pricing.md |
Don't guess field names — if uncertain, load reference.md first.
| Task Type | Mode | Behavior |
|---|---|---|
| Single ASIN lookup, simple data query | Quick | Execute command, return key data. Skip evaluation criteria and output standard block. |
| Market analysis, product selection, competitor comparison, risk assessment | Full | Complete flow: command → analysis → evaluation criteria → output standard block. |
Quick mode trigger: User asks for a single specific data point ("B09XXX monthly sales?", "how many brands in cat litter?") — no decision analysis needed.
Before running any Full-mode product selection or market analysis, complete this checklist :
--mode xxx). Do NOT manually piece together filters when a preset mode exists. Common mappings:
--mode low-price--mode beginner--mode long-tail--mode emergingproduct --asin for the top 3-5 ASINs from results (see Realtime Data Supplementation below).analyze --asins for top ASINs to get consumer insights (especially painPoints, improvements, buyingFactors).Why this exists: In testing, AI agents repeatedly skipped preset modes, realtime supplements, and review analysis — even though the instructions below clearly describe them. This checklist forces a pause-and-verify before execution.
Prioritize script execution for API calls. The script includes:
_query metadata injection (for query traceability)Fallback: If script fails and can't be quickly fixed, use curl directly. Note "using curl direct call" in output.
When products or competitors returns ASINs in Full-mode analysis, call product --asin for the top 3-5 most relevant ASINs to get current real-time data. For bulk lookups (>3 ASINs), confirm with the user before proceeding.
| Scenario | Supplement? | How many ASINs |
|---|---|---|
| Single ASIN lookup (Quick mode) | Already using realtime | — |
| Market overview (no specific ASINs) | ❌ No | — |
| Product selection / competitor analysis | ✅ Yes | Top 3 by sales |
| Risk assessment | ✅ Yes | Target ASIN + top 2 competitors |
| Multi-product comparison | ✅ Yes | All compared ASINs (max 5) |
| Listing analysis | Already using realtime | — |
Handling data conflicts — products/competitors has ~T+1 delay; realtime/product is live:
| Field | Use from | Reason |
|---|---|---|
| Price | realtime (buyboxWinner.price) | Changes frequently |
| BSR | realtime (bestsellersRank) | Updates hourly |
| Rating / ratingCount | realtime | More current |
| Monthly Sales | products/competitors | Realtime doesn't have this |
| Profit Margin / FBA Fee | products/competitors | Realtime doesn't have this |
When realtime data differs significantly, note it: e.g. "⚡ Price updated: database $29.99 → realtime $24.99 (likely promotion)"
All commands output JSON. Progress messages go to stderr.
python3 scripts/apiclaw.py categories --keyword "pet supplies"
python3 scripts/apiclaw.py categories --parent "Pet Supplies"
Common fields: categoryName (not name), categoryPath, productCount, hasChildren
python3 scripts/apiclaw.py market --category "Pet Supplies,Dogs" --topn 10
Key output fields: sampleAvgMonthlySales, sampleAvgPrice, topSalesRate (concentration), topBrandSalesRate, sampleNewSkuRate, sampleFbaRate, sampleBrandCount
# Preset mode (14 built-in)
python3 scripts/apiclaw.py products --keyword "yoga mat" --mode beginner
# Explicit filters
python3 scripts/apiclaw.py products --keyword "yoga mat" --sales-min 300 --reviews-max 50
# Mode + overrides (overrides win)
python3 scripts/apiclaw.py products --keyword "yoga mat" --mode beginner --price-max 30
Available modes: fast-movers, emerging, single-variant, high-demand-low-barrier, long-tail, underserved, new-release, fbm-friendly, low-price, broad-catalog, selective-catalog, speculative, ,
Keyword matching: Default is fuzzy (matches brand names too — e.g. "smart ring" matches "Smart Color Art" pens). Use --keyword-match-type exact or phrase for precise results. Always combine with --category when possible to reduce noise.
Category path with commas: Some category names contain commas (e.g. "Pacifiers, Teethers & Teething Relief"). Use > separator instead of , to avoid parsing errors:
# ❌ Wrong — comma in name breaks parsing
--category "Baby Products,Baby Care,Pacifiers, Teethers & Teething Relief"
# ✅ Correct — use ' > ' separator
--category "Baby Products > Baby Care > Pacifiers, Teethers & Teething Relief"
python3 scripts/apiclaw.py competitors --keyword "wireless earbuds"
python3 scripts/apiclaw.py competitors --asin B09V3KXJPB
Easily confused fields (products/competitors shared) :
| ❌ Wrong | ✅ Correct | Note |
|---|---|---|
reviewCount | ratingCount | Review count |
bsr | bsrRank | BSR ranking (integer, only in products/competitors) |
monthlySales / salesMonthly | atLeastMonthlySales | Monthly sales (lower bound estimate, NOT in realtime/product) |
Complete field list:
reference.md→ Shared Product Object
python3 scripts/apiclaw.py product --asin B09V3KXJPB
Returns: title, brand, rating, ratingBreakdown, features, topReviews, specifications, variants, bestsellersRank, buyboxWinner
# Single ASIN
python3 scripts/apiclaw.py analyze --asin B09V3KXJPB
# Multiple ASINs (competitive review comparison)
python3 scripts/apiclaw.py analyze --asins B09V3KXJPB,B08YYYYY,B07ZZZZZ
# Category-level insights
python3 scripts/apiclaw.py analyze --category "Pet Supplies,Dogs,Toys" --period 90d
# Specific insight dimension
python3 scripts/apiclaw.py analyze --asin B09V3KXJPB --label-type painPoints,buyingFactors
Returns: totalReviews, avgRating, sentimentDistribution, ratingDistribution, consumerInsights (by labelType), topKeywords, verifiedRatio
Available labelType: scenarios, issues, positives, improvements, buyingFactors, painPoints, keywords, userProfiles, usageTimes, usageLocations, behaviors
python3 scripts/apiclaw.py report --keyword "pet supplies"
Runs: categories → market → products (top 50) → realtime detail (top 1).
python3 scripts/apiclaw.py opportunity --keyword "pet supplies" --mode fast-movers
Runs: categories → market → products (filtered) → realtime detail (top 3).
The 4 types of interfaces return different fields. Do NOT assume they share the same structure.
| Data | market | products/competitors | realtime/product | reviews/analyze |
|---|---|---|---|---|
| Monthly Sales | sampleAvgMonthlySales | ✅ atLeastMonthlySales | ❌ | ❌ |
| Revenue |
Usage rule:
products / competitors for sales, pricing, and competition datarealtime/product for review details, listing content, and seller infomarket for category-level aggregate metricsreviews/analyze for AI-powered review insights (sentiment, pain points, buying factors — covers all reviews, not just topReviews)products/competitors (quantitative) + realtime/product (qualitative) + reviews/analyze (consumer insights) as evidenceAll interfaces return .data as an array. Use .data[0] to get the first record, NOT .data.fieldName.
| User Says | Run This | Scenario File? |
|---|---|---|
| "which category has opportunity" | market + categories | No |
| "check B09XXX" / "analyze ASIN" | product --asin XXX | No |
| "Chinese seller cases" | competitors --keyword XXX --page-size 50 | scenarios-composite.md → 3.4 |
| "pain points" / "negative reviews" / "consumer insights" | analyze --asin XXX + |
Product Selection Mode Mapping (14 types) :
| User Intent | Mode | Key Filters |
|---|---|---|
| "beginner friendly" / "new seller" | --mode beginner | Sales≥300, growth≥3%, $15-60, FBA, ≤1yr, auto-excludes 150+ red ocean keywords |
| "fast turnover" / "hot selling" | --mode fast-movers | Sales≥300, growth≥10% |
| "emerging" / "rising" | --mode emerging | Sales≤600, growth≥10%, ≤180d |
| "single variant" / "small but beautiful" | --mode single-variant | Growth≥20%, variants=1, ≤180d |
| "high demand low barrier" / "easy entry" | --mode high-demand-low-barrier |
market output)| Metric | Good | Medium | Warning |
|---|---|---|---|
| Market value (avgRevenue × skuCount) | > $10M | $5–10M | < $5M |
| Concentration (topSalesRate, topN=10) | < 40% | 40–60% | > 60% |
| New SKU rate (sampleNewSkuRate) | > 15% | 5–15% | < 5% |
| FBA rate (sampleFbaRate) | > 50% | 30–50% | < 30% |
| Brand count (sampleBrandCount) | > 50 | 20–50 | < 20 |
product output)| Metric | High | Medium | Low |
|---|---|---|---|
| BSR | Top 1000 | 1000–5000 | > 5000 |
| Reviews | < 200 | 200–1000 | > 1000 |
| Rating | > 4.3 | 4.0–4.3 | < 4.0 |
| Negative reviews (1-2★ %) | < 10% | 10–20% | > 20% |
When atLeastMonthlySales is null: Monthly sales ≈ 300,000 / BSR^0.65
Two blocks are REQUIRED at the end of every Full-mode analysis: ① Data Source & Conditions, ② API Usage. Missing either one = violating the skill contract.
---
📋 **Data Source & Conditions**
| Item | Value |
|----|-----|
| Data Source | APIClaw API |
| Interface | [interfaces used] |
| Category | [category path] |
| Time Range | [dateRange] |
| Sampling | [sampleType] |
| Top N | [topN value] |
| Sort | [sortBy + sortOrder] |
| Filters | [specific parameter values] |
**Data Notes**
- Monthly sales are **lower bound estimates** (Amazon displays "10,000+ bought"), actual may be higher
- Database data has ~T+1 delay; realtime/product is current real-time data
- Concentration metrics based on Top N sample; different topN → different results
Rules :
📋 **Data Source & Conditions**, ADD IT before replyingThis block is NON-NEGOTIABLE. Every single response — Quick or Full mode — MUST end with this table. No exceptions. If you forget, you are violating the skill contract.
📊 **API Usage**
| Interface | Calls |
|-----------|-------|
| categories | 1 |
| markets/search | 1 |
| products/search | 2 |
| realtime/product | 3 |
| reviews/analyze | 1 |
| **Total** | **8** |
| **Credits consumed** | **8** |
| **Credits remaining** | **492** |
Tracking rules:
apiclaw.py execution as 1 call to the corresponding interface_credits.consumed from every API response for total consumed_credits.remaining from the last API response as remaining balance_credits fields are null, show "N/A"📊 **API Usage** at the bottom, ADD IT before replyingrealtime/product topReviews for specific review quotes)| Scenario | Coverage | Suggestion |
|---|---|---|
| Market data: Popular keywords | ✅ Has data | Use --keyword directly |
| Market data: Niche/long-tail keywords | ⚠️ May be empty | Use --category instead |
| Product data: Active ASIN | ✅ Has data | — |
| Product data: Delisted/variant ASIN | ❌ No data | Try parent ASIN or realtime |
| Real-time data: US site | ✅ Full support | — |
| Real-time data: Non-US sites | ⚠️ Partial | Core fields OK, sales may be null |
HTTP errors (401/402/403/404/429) are handled by the script with structured JSON output. Self-check: python3 scripts/apiclaw.py check
| Error | Fix |
|---|---|
Cannot index array with string | Use .data[0].fieldName (.data is array) |
Empty data: [] | Use categories to confirm category exists |
atLeastMonthlySales: null | BSR estimate: 300,000 / BSR^0.65 |
Weekly Installs
–
Repository
GitHub Stars
27
First Seen
–
Python PDF处理教程:合并拆分、提取文本表格、创建PDF文件
59,800 周安装
SQL性能优化助手 - 专业SQL查询调优与索引策略优化工具
8,600 周安装
Vue Router 最佳实践指南:导航守卫、路由生命周期与常见陷阱解决方案
9,200 周安装
后台代理状态通知 - 避免轮询浪费,高效处理AI代理进度更新
205 周安装
网站设计审查工具 - 自动检测并修复HTML/CSS/JS、React、Vue等框架的视觉与布局问题
8,900 周安装
.NET/C# 最佳实践指南:代码规范、设计模式、依赖注入与AI集成
8,900 周安装
Playwright MCP 测试生成工具 - 自动生成 TypeScript 端到端测试代码
9,000 周安装
| Pricing strategy, profit estimation, listing reference (5.x) |
references/scenarios-ops.md | Market monitoring, competitor tracking, anomaly alerts (6.x) |
references/scenarios-expand.md | Product expansion, trends, discontinuation decisions (7.x) |
references/scenarios-listing.md | Listing writing, optimization, content creation (8.x) |
📋 Data Source & Conditions and 📊 API Usage at the end.beginnertop-bsrbestsellersRank | bsrRank | bestsellersRank is realtime/product only (array format); use bsrRank for products/competitors |
price (in realtime) | buyboxWinner.price | realtime/product nests price inside buyboxWinner object |
profitMargin (in realtime) | ❌ N/A | realtime/product does NOT return profitMargin; use products/competitors |
sampleAvgMonthlyRevenuesalesRevenue |
| ❌ |
| ❌ |
| Price | sampleAvgPrice | price | buyboxWinner.price | ❌ |
| BSR | sampleAvgBsr | bsrRank (integer) | bestsellersRank (array) | ❌ |
| Rating | sampleAvgRating | rating | rating | avgRating |
| Review Count | sampleAvgReviewCount | ratingCount | ratingCount | totalReviews |
| Review Details | ❌ | ❌ | ✅ topReviews + ratingBreakdown | ❌ (no raw reviews) |
| Sentiment Analysis | ❌ | ❌ | ❌ | ✅ sentimentDistribution |
| Consumer Insights | ❌ | ❌ | ❌ | ✅ consumerInsights (11 dimensions) |
| Pain Points/Issues | ❌ | ❌ | ❌ (manual from topReviews) | ✅ AI-analyzed |
| Top Keywords | ❌ | ❌ | ❌ | ✅ topKeywords |
| Seller | ❌ | buyboxSeller (string) | buyboxWinner (object) | ❌ |
| Profit Margin | ❌ | profitMargin | ❌ | ❌ |
| FBA Fee | ❌ | fbaFee | ❌ | ❌ |
| Seller Count | ❌ | sellerCount | ❌ | ❌ |
| Features/Bullets | ❌ | ❌ | ✅ features | ❌ |
| Variants | ❌ | variantCount (integer) | variants (full list) | ❌ |
product --asin XXXscenarios-eval.md → 4.2 |
| "category pain points" / "category user portrait" | analyze --category XXX | scenarios-eval.md → 4.6 |
| "compare products" | competitors or multiple product | scenarios-eval.md → 4.3 |
| "risk assessment" / "can I do this" | product + market + competitors | scenarios-eval.md → 4.4 |
| "monthly sales" / "estimate sales" | competitors --asin XXX | scenarios-eval.md → 4.5 |
| "help me select products" / "find products" | products --mode XXX (see mode table) | No |
| "comprehensive recommendations" / "what should I sell" | products (multi-mode) + market | scenarios-composite.md → 2.10 |
| "pricing strategy" / "how much to price" | market + products | scenarios-pricing.md → 5.1 |
| "profit estimation" | competitors | scenarios-pricing.md → 5.2 |
| "listing reference" | product --asin XXX | scenarios-pricing.md → 5.3 |
| "market changes" / "recent changes" | market + products | scenarios-ops.md → 6.1 |
| "competitor updates" | competitors --brand XXX | scenarios-ops.md → 6.2 |
| "anomaly alerts" | market + products | scenarios-ops.md → 6.4 |
| "what else can I sell" / "related products" | categories + market | scenarios-expand.md → 7.1 |
| "trends" | products --growth-min 0.2 | scenarios-expand.md → 7.3 |
| "should I delist" | competitors --asin XXX + market | scenarios-expand.md → 7.4 |
| "write listing" / "generate bullet points" / "write title" | product --asin XXX (competitors) | scenarios-listing.md → 8.2 |
| "analyze competitor listing" / "their selling points" | product --asin XXX (multiple) | scenarios-listing.md → 8.1 |
| "optimize my listing" / "listing diagnosis" | product --asin XXX + competitors | scenarios-listing.md → 8.3 |
| Need exact filters or field names | — | Load reference.md |
| Sales≥300, reviews≤50, ≤180d |
| "long tail" / "niche" | --mode long-tail | Sales≤300, BSR 10K-50K, ≤$30, sellers≤1 |
| "underserved" / "has pain points" | --mode underserved | Sales≥300, rating≤3.7, ≤180d |
| "new products" / "new release" | --mode new-release | Sales≤500, NR tag, FBA+FBM |
| "FBM" / "self-fulfillment" / "low stock" | --mode fbm-friendly | Sales≥300, FBM, ≤180d |
| "low price" / "cheap" | --mode low-price | ≤$10 |
| "broad catalog" / "cast wide net" | --mode broad-catalog | BSR growth≥99%, reviews≤10, ≤90d |
| "selective catalog" | --mode selective-catalog | BSR growth≥99%, ≤90d |
| "speculative" / "piggyback" | --mode speculative | Sales≥600, sellers≥3, ≤180d |
| "top sellers" / "best sellers" | --mode top-bsr | Sub-category BSR≤1000 |