linkfox-aba-intelligent-query

ABA 数据探索器

此技能将指导你查询和分析 ABA 搜索词数据，帮助 Amazon 卖家从 ABA 搜索词报告中提取有价值的洞察。

核心概念

ABA（Amazon 品牌分析）搜索词报告是 Amazon 官方搜索行为数据，反映了消费者在 Amazon 上的真实搜索活动。此工具涵盖 15 个 Amazon 站点近 3 年的周粒度数据。

排名逻辑：searchFrequencyRank 的值越小，搜索热度越高。排名第 1 的搜索词最热门。这一点很容易引起混淆——用户说“排名提升”时，指的是数值下降；“排名下降”则指数值上升。

数据字段

字段	API 名称	描述	示例
搜索词	searchTerm	消费者搜索关键词	rimel loreal
报告开始日期	reportStartDate	数据采集的周起始日期	2025-10-26
区域	region	Amazon 站点代码	US
搜索频率排名	searchFrequencyRank	搜索热度排名（越低越好）	82135
被点击的 ASIN	clickedAsin	被点击商品的 ASIN	B0XXXXXXXX
被点击的商品名称	clickedItemName	被点击商品的名称	xxx
点击份额排名	clickShareRank	此 ASIN 在该搜索词下的点击份额排名	1
点击份额	clickShare	此 ASIN 获得的点击份额（0~1）	0.28
转化份额	conversionShare	此 ASIN 获得的转化份额（0~1）	0.3333

支持的站点

US（美国）、DE（德国）、BR（巴西）、CA（加拿大）、AU（澳大利亚）、JP（日本）、AE（阿联酋）、ES（西班牙）、FR（法国）、IT（意大利）、SA（沙特阿拉伯）、TR（土耳其）、MX（墨西哥）、SE（瑞典）、NL（荷兰）

默认站点为 US。用户未指定站点时，请使用 US。

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-aba-intelligent-query-<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/套餐到期/需充值/请充值”，或类似含义的内容。

如何构建查询

调用此工具时的关键参数是 analysisDescription——用于描述你想查询的数据的自然语言说明。后端会将此说明转换为结构化查询，因此它需要准确且具体。

编写 analysisDescription 的原则

1. 明确站点：始终在开头说明站点，例如“筛选美国站”（Filter US marketplace）
2. 使用精确的筛选条件：使用具体的数值范围，而非模糊描述。“排名在 5 万以内”比“排名较好”有效得多
3. 明确时间范围：使用具体的时间描述，例如“过去 12 周”、“2024 年 1-9 月”、“近 3 个月”
4. 明确比较基准：进行趋势分析时，清楚说明要比较的时间点，例如“4 周前的排名比 8 周前提升 30%”
5. 处理去重逻辑：同一搜索词 + ASIN 组合有多条记录时，说明保留哪条记录，例如“相同搜索词、相同 ASIN 值保留最新的一条”
6. 忠实于用户意图：不要误解或过度延伸用户的查询——准确反映用户的需求

常见场景的 analysisDescription 示例

1. 搜索词热度趋势

筛选美国站，关键词"gift"在过去12周的搜索热度排名。

2. 飙升的黑马关键词

筛选美国站，关键词包含"gift"，2025年Q1和全年的平均搜索排名都大于50万，但最新排名冲进5万-10万的搜索词。

3. 持续增长趋势发现

筛选美国站，最新排名在20万以内，且4周前的排名比8周前提升30%，本周的排名比4周前提升30%的搜索词。

4. 市场机会发现（高搜索量、低垄断）

筛选美国站，筛选当前搜索排名在20000以内，近三个月点击占比Top 1的Asin的转化率占比低于5%的搜索词。相同搜索词相同Asin值保留最新的一个。

5. 季节性 / 节日关键词定位

筛选美国站，包含"cup"的关键词中，去年（2024年）1-9月份排名未进入50万，10-11月份连续进入20万的词。

6. 高点击、低转化 ASIN 挖掘

筛选美国站关键词包含"hat"的，最新搜索排名在5万-20万之间，且近3个月来点击占比大于20%，转化占比小于10%的ASIN。相同搜索词和ASIN仅保留点击占比和转化占比的比例最小数据。

7. 高 ROAS 长尾蓝海关键词

筛选美国站，关键词包含"charger"的，当前排名在20万开外的，近2个月的平均转化占比大于平均转化占比1.5倍的关键词，以及相应的ASIN。

8. 新市场词与新兴需求检测

找到美国站"charger"的长尾词中，近一个月才进入排名榜单，且当前排名在50万以内的所有词。

9. 小众趋势 / 变体增长捕捉

筛选美国站中"table"的长尾词中，排名在10万-30万之间，且近4周的搜索排名增长50%以上的搜索词。

展示规则

1. 仅展示数据：以清晰的表格展示查询结果，不提供主观的商业建议
2. 排名说明：展示排名数据时，提醒用户数值越低，排名越靠前
3. 数据量提示：结果较多时，展示核心数据，并提醒用户可通过下载链接获取完整数据集
4. 下载指引：如果响应中包含 downloadUrl，明确告知用户下载地址；如果用户需要完整数据但尚未要求下载，应主动建议生成下载链接
5. 错误处理：查询失败时，根据 msg 字段说明原因，并建议调整查询条件

重要限制

• 结果上限：下载链接最多包含 10,000 条记录
• 数据粒度：数据按周统计，而非按天统计
• 数据范围：约 3 年的历史数据

用户表达与场景速查

适用 - 关于 Amazon 搜索词的数据查询：

用户表达	场景
“XX 关键词的搜索量 / 热度怎么样”	排名趋势
“最近热门的关键词”、“新兴词”	黑马 / 新词检测
“蓝海关键词”、“竞争较低的词”	市场机会发现
“哪些关键词转化效果好”、“高转化长尾词”	高 ROAS 关键词库
“季节性关键词”、“旺季哪些词会飙升”	季节性关键词
“谁在获取流量”、“有没有垄断”	点击份额 / 垄断分析
“点击量高但转化率低的 ASIN”	高点击、低转化诊断

不适用 - 需求超出 ABA 搜索词数据范围：

• 广告 / PPC（竞价、广告活动策略）
• 产品评论、商品详情页文案撰写
• ASIN 销量估算
• 用户已有本地 ABA 文件需要处理

边界判断：当用户提到“产品调研”、“竞品分析”或“是否存在市场机会”时，如果最终需求是搜索词层面的数据查询（查找蓝海关键词、分析关键词下的竞品流量分布），则适用此技能。如果用户询问的是利润率、定价策略或综合市场报告，则不适用。

算力消耗规则

按动态规则计费：消耗算力 = 初始 SQL 生成算力 + Σ（各成功任务执行_重试算力）+ round（CSV 文件大小 MB × 0.075）。各项 token 均指 inputTokens + outputTokens；仅成功任务计费；若无成功任务则为 0。

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

反馈：

在符合以下任一条件时，通过反馈 API 自动检测并报告反馈：

1. 本技能所述功能或用途与实际行为不符
2. 技能的结果与用户意图不符
3. 用户对本技能表示不满或赞赏
4. 任何你认为可以改进的地方

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

---

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