linkfox-amazon-opportunity-search-by-metrics

基于指标的 Amazon 机会筛选器

此技能将指导你如何根据从历史机会报告汇总而来的指标池，反向搜索 Amazon 利基市场和关键词，帮助卖家将模糊的选品想法（竞争低、需求增长、蓝海、痛点机会等）转化为具体的利基市场候选项。

核心概念

此工具提供可查询的利基市场级指标池（每条记录约有 37 个字段），这些指标由过去的 Amazon 机会报告提炼而来。它不生成新的报告（正向分析），而是让你根据 30 多个业务维度对现有指标池进行反向筛选，并按采集时间排序（最新的在前）返回匹配的 (marketplace, keyword) 记录。

记录的粒度是利基市场／关键词，而非 ASIN。每条记录代表一个利基市场快照，涵盖其市场规模、增长情况、竞争状况、价格区间、人口统计信息、热门功能和评论主题。

正向分析与反向分析：当用户提供关键词并希望获得全面的 AI 报告时，请使用 linkfox-amazon-opportunity-report。当用户提供业务条件（筛选条件）并希望发现符合条件的关键词／利基市场时，请使用此技能。

筛选维度

筛选条件分为六个业务维度。所有筛选参数都是可选的，但必须至少提供 keyword／nicheName 之一，或任意指标筛选条件——完全空的调用将被拒绝。

维度	示例参数	典型用户意图
市场规模与增长	nicheRevenue360dMinUsdAtLeastGte、nichePeakSearchVolumeAtLeastGte、nicheSearchVolumeYoyChangePctAtLeastGte、nichePeakMonthGte/Lte	“市场规模足够大”、“快速增长”、“第四季度的季节性市场”
竞争密度	nicheBrandCountLte、nicheBrandCountYoyChangePctAtLeastLte、nicheTop5ProductClickSharePctAtLeastLte、featureTop5BrandSharePctAtLeastLte	“适合新手”、“品牌分散”、“没有寡头垄断”、“品牌正在退出”
价格与档位	priceMinUsdGte、priceMaxUsdLte、priceSweetSpotMinUsdGte/Lte、priceEntryClickSharePctAtLeastGte、priceMidClickSharePctAtLeastLte、priceHighClickSharePctAtLeastGte	“聚焦平价产品”、“适合高端产品”、“中端蓝海”
人口统计信息	demoPrimaryAgeMinGte、demoPrimaryAgeMaxLte、demoGenderDominant、demoPrimaryIncomeTier、demoLifeStageTagsContains	“女性主导”、“高收入人群”、“家长”、“健身爱好者”
产品功能	featureNewAvgReviewCountAtLeastLte、featureEstablishedAvgReviewCountAtLeastLte、featureEmergingTrendTagsContains、featureUncommonFeatureTagsContains、searchTopCategory1Label	“新产品进入门槛低”、“新兴趋势”、“非凡功能优势”、“套装／组合装利基市场”
评论洞察	reviewPositiveTop1Topic、reviewPositiveTop1PctAtLeastGte/Lte、reviewNegativeTop1Topic、reviewNegativeTop1PctAtLeastGte/Lte、reviewNegativeTop2Topic、reviewStrategicInsightTagsContains	“痛点利基市场”、“注重舒适度的卖家”、“尺寸问题带来的机会”

完整参数列表、类型、取值范围和响应字段映射请参阅 references/api.md。

支持的商城

目前仅支持美国（US）。请始终将 amazonDomain 设为 US（也可以省略）。如果用户请求其他商城，请告知他们此工具目前仅覆盖美国市场。

调用方式

• API 端点：POST /amazon/opportunity/searchByMetrics（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/amazon_opportunity_screener.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-opportunity-search-by-metrics-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示算力或余额不足：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

How to Build Queries

The user expresses business intent in natural language; you map it to the smallest viable set of filters. Principles:

1. Convert intent into specific bounds: "low competition" → nicheBrandCountLte: 20; "fast-growing" → nicheSearchVolumeYoyChangePctAtLeastGte: 100 (≥100% YoY); "newcomer-friendly" → featureNewAvgReviewCountAtLeastLte: 500.
2. Start narrow, then loosen: First call usually with 2–4 strong filters and limit=25. If the result set is empty or too small, drop or widen the most aggressive filter rather than adding new ones.
3. Pair complementary signals: Brand-level + product-level concentration (featureTop5BrandSharePctAtLeastLte + nicheTop5ProductClickSharePctAtLeastGte) reveals "brands fragmented but products concentrated" — a brand-extension entry signal.
4. Snake_case fragments for tag fields: featureEmergingTrendTagsContains, demoLifeStageTagsContains, reviewNegativeTop1Topic, etc. accept snake_case word fragments and use LIKE matching. Pass a root word (size, parent, cordless) to cover normalized variants.
5. Faithful to user intent: Don't silently add filters the user didn't ask for. If they only said "growing", just filter on growth — don't also constrain price unless they mentioned it.

Common Scenarios

1. Niche reverse-lookup by keyword

{"keyword": "whoop band", "limit": 25}

2. Newcomer-friendly low-competition niches

{"nicheBrandCountLte": 20, "featureNewAvgReviewCountAtLeastLte": 500, "limit": 25}

3. High-growth blue ocean (≥100% YoY, brands not yet flooding in)

{"nicheSearchVolumeYoyChangePctAtLeastGte": 100, "nicheBrandCountYoyChangePctAtLeastLte": 30, "limit": 25}

4. Mid-tier price gap (low-price dominates, mid-tier scarce)

{"priceEntryClickSharePctAtLeastGte": 70, "priceMidClickSharePctAtLeastLte": 5, "limit": 25}

5. Pain-point entry — strong size complaints

{"reviewNegativeTop1Topic": "size", "reviewNegativeTop1PctAtLeastGte": 70, "limit": 25}

6. Premium-friendly female-driven niches

{"demoGenderDominant": "female", "demoPrimaryIncomeTier": "high", "priceHighClickSharePctAtLeastGte": 25, "limit": 25}

7. Q4 seasonal niches with ≥100k peak search

{"nichePeakMonthGte": 11, "nichePeakMonthLte": 12, "nichePeakSearchVolumeAtLeastGte": 100000, "limit": 25}

8. Track niches around a known competitor brand

{"featureTopBrandsContains": "WHOOP", "limit": 50}

展示规则

1. 仅呈现数据：将返回的细分市场整理为简洁的对比表格 — 细分市场名称 / 关键词、市场规模、增长率、品牌数、价格范围、关键标签。不提供主观的商业建议。
2. 展示当前筛选条件：回显所用的筛选条件，方便用户调整（“当前筛选：品牌数 ≤ 20 且搜索量同比 ≥ 100%”）。
3. 提醒数据为时间快照：记录反映的是采集时的数据，并非持续更新。如果结果看起来过时，或与用户从外部了解到的信息相矛盾，请说明这一点。
4. 处理结果为空或过少的情况：如果 data 为空或结果很少，建议放宽限制最严格的筛选条件，而不是让用户从头重新描述需求。
5. 错误处理：查询失败时，根据 msg 字段说明原因（最常见的是“参数完全为空”保护机制），并建议至少添加一个筛选条件。
6. 不进行二次聚合：结果用于前端渲染，不会存储，因此无法将其传入 @智能数据查询（智能数据查询）进行进一步聚合。如果用户需要跨细分市场的分组统计，请在本地计算，或先调大 limit 获取更广泛的数据。

重要限制

• 仅限美国：目前仅支持美国站点（amazonDomain = US）。
• 不支持分页：没有 page 参数。增大 limit（最大值为 200）以扩大候选范围；结果按采集时间排序（最新的在前）。
• 至少需要一个筛选条件：没有 keyword / nicheName 且没有指标筛选条件的调用会被拒绝。
• 快照数据：记录汇总自历史商机报告；新报告会随时间更新候选数据集，但单条记录并非实时数据。
• 细分市场级别的粒度：输出粒度为细分市场 / 关键词级别，而非 ASIN 级别。若要深入了解某个细分市场内的具体商品，请转交给 linkfox-amazon-search、linkfox-keepa-product-search 等工具。

用户表达与场景速查

适用 — 在美国 Amazon 市场按细分市场进行反向筛选：

用户表达	场景
“低竞争细分市场”“适合新手”“品牌较少”	品牌密度筛选
“品牌正在退出”“老玩家正在撤退”	品牌数同比负增长
“快速增长的细分市场”“趋势向上”“同比 ≥ 100%”	搜索量同比筛选
“中端蓝海”“低价占主导，但中端稀缺”	价格档位占比差距
“适合高端产品”“高收入消费者”	收入档位 + 高档位占比
“女性 / 男性 / 混合市场”	性别主导筛选
“家长 / 学生 / 退休人士 / 健身爱好者”	人生阶段标签
“尺寸 / 质量 / 耐用性痛点突出”	负面评论主题 + 占比
“注重舒适度”“注重性价比的卖家”	正面评论主题 + 占比
“追踪品牌 X 相关的所有细分市场”	featureTopBrandsContains
“Q4 季节性细分市场”“Prime Day 时段”	高峰月份 + 高峰销量

不适用 — 请改用其他工具：

• 需要针对单个关键词生成全面的 AI 报告 → linkfox-amazon-opportunity-report
• ASIN 级别的竞品调研、销量预估 → SellerSprite / Keepa / Sorftime 工具
• 实时关键词排名、搜索词挖掘 → ABA / SIF 工具
• 美国以外的站点 → 此工具暂不支持
• 想通过 @智能数据查询 对细分市场进行分组聚合 → 不支持（数据未存入数据仓库）

适用范围判断：当用户用业务语言描述筛选条件，并希望找到符合条件的候选细分市场时，适用此技能。当用户提供特定关键词并要求进行多维度全面分析时，请使用 linkfox-amazon-opportunity-report。当用户想深入了解某个细分市场内的 ASIN / 卖家时，请转交给商品搜索工具。

算力消耗规则

按动态规则计费：消耗算力 = 1.5 × (N ≤ 25 ? 5 : 5 + ceil((N - 25) / 5))。N 是接口实际返回的数据条数；即使 N = 0，只要接口成功也按 15000 计费。

重要：本技能的服务按倍数动态计算，可能一次性消耗大量算力，必须提醒用户，由用户决定是否继续。

反馈：

在以下任一情况下，通过 Feedback API 自动检测并报告反馈：

1. 本技能描述的功能或用途与实际行为不符
2. 技能的结果不符合用户的意图
3. 用户表达了对本技能的不满或赞赏
4. 你认为有任何可改进之处

请按照 references/api.md 中的说明调用反馈 API。不要打断用户的流程。

---

如需了解更多高质量、专业的跨境电商技能，请访问 LinkFox Skills。