linkfox-sif-keyword-summary

SIF 关键词流量来源汇总

本技能介绍如何查询和分析 Amazon 产品的关键词流量来源数据，帮助卖家了解关键词背后的流量结构，包括自然搜索、Sponsored Products（SP）广告、品牌广告、视频广告以及 Amazon 的各种推荐展示位。

核心概念

SIF 关键词汇总工具会针对给定关键词，返回出现在该关键词下的 ASIN 列表，以及每个 ASIN 按关键词划分的流量曝光明细和产品层面的跨渠道流量组合。它回答的是：哪些 ASIN 正在获取该关键词下的流量，以及流量来自哪些渠道？

分析的流量渠道：

• 自然搜索 — 自然搜索结果位置
• SP 广告（Sponsored Products） — 付费产品广告展示位（常规位置）
• 品牌广告（SB） — 搜索结果页顶部和底部的品牌广告展示位
• 视频广告（SBV） — Sponsored Brands 视频展示位
• SP 推荐位 — Trending now / Seen on social media / Customers frequently viewed / 4 stars and above
• Amazon's Choice（AC） — Amazon's Choice 徽章推荐
• 编辑推荐（ER） — 编辑精选推荐展示位
• 高评分（TR） — 高评分推荐展示位

两类评分字段（请务必区分，切勿混用）：

1. 产品层面字段（无前缀，例如 naturalSearchExposureScore）：该 ASIN 在所有关键词下的整体曝光情况。
2. 关键词层面字段（带 keyword… 前缀，例如 keywordNaturalExposureScore）：该 ASIN 在当前查询的单个关键词下的曝光情况。

参数指南

必填参数

参数	类型	说明
searchKeyword	string	要分析的搜索关键词。适用时，请将其翻译为目标站点使用的语言。最多 1000 个字符。

可选参数

参数	类型	默认值	说明
country	string	US	站点代码（支持 13 个，见下方列表）。
asins	string	（无）	以逗号分隔的 ASIN 筛选条件；如省略，则返回该关键词下出现的所有 ASIN。最多 1000 个字符。
condition	string	（无）	按特定流量来源筛选。每个请求只能指定一个值。参见下方的 Condition Filters。
last7d	boolean	true	使用最近 7 天的数据。设为 false 时，API 使用 startDate/endDate。
startDate	string	—	yyyy-MM-dd。在 last7d=false 时生效；如省略，则使用系统最近一个完整周的数据。
endDate	string	yyyy-MM-dd，与 startDate 配套使用。
sortBy	string	（默认）	排序字段。参见下方的 sortBy 部分。
pageNum	integer	1	分页页码。
pageSize	integer	100	每页结果数。最小值为 10，最大值为 100。
desc	boolean	true	按降序排序。

支持的站点

支持 13 个站点：US（美国）、UK（英国）、DE（德国）、CA（加拿大）、JP（日本）、FR（法国）、ES（西班牙）、IT（意大利）、MX（墨西哥）、AU（澳大利亚）、AE（阿联酋）、BR（巴西）、SA（沙特阿拉伯）。

默认站点为 US。不在此列表中的代码会被 API 模式校验拒绝。

条件筛选器

每个请求最多只能包含 一个 条件筛选器。标志型：

值	含义
nfPosition	自然搜索流量关键词
isSpAd	SP 广告关键词
isVedioAd	视频广告关键词
isBrandAd	品牌广告关键词
isPPCAd	PPC 广告关键词（所有付费广告类型）
isSearchRecommend	搜索推荐关键词
acAd	SP 推荐（Trending now / Customers frequently viewed / 等）

周期计数筛选器（.total 总计 / .in 新增）：

值	含义
totalPeriod.in	本周期新进入的流量关键词
nfKeywordCnt.total / nfKeywordCnt.in	有（新增）自然曝光的关键词
adKeywordCnt.total / adKeywordCnt.in	有（新增）广告曝光的关键词
allSpKeywordCnt.total / allSpKeywordCnt.in	（新增）SP 广告关键词（常规 + 推荐）
spKeywordCnt.total / spKeywordCnt.in	（新增）SP 常规关键词
recSpKeywordCnt.total / recSpKeywordCnt.in	（新增）SP 推荐关键词
allSbKeywordCnt.total / allSbKeywordCnt.in	（新增）SB 广告关键词
sbKeywordCnt.total / sbKeywordCnt.in	（新增）SB 常规关键词
sbvKeywordCnt.total / sbvKeywordCnt.in	（新增）SBV 关键词

sortBy

留空则使用系统默认值。有效值：

totalKeywordNum（关键词总数）、naturalKeywordNum、brandKeywordNum、vedioKeywordNum、acKeywordNum、erKeywordNum、trKeywordNum、sumScore（所有关键词的总曝光量）、totalNfScore、totalSpSocre（注意拼写）、totalBrandScore、totalVedioScore、totalAcScore、totalTrScore、totalErScore。

调用方式

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

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

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

使用示例

1. 关键词流量概览 查询美国站点某个关键词的流量来源细分：

searchKeyword: "wireless charger", country: "US"

2. 仅筛选自然搜索流量 仅查看某个关键词在自然搜索结果中出现的 ASIN：

searchKeyword: "wireless charger", country: "US", condition: "nfPosition"

3. 分析 SP 广告竞争 查找针对某个关键词投放 SP 广告的 ASIN：

searchKeyword: "wireless charger", country: "US", condition: "isSpAd"

4. SP 推荐位 查找出现在 SP 推荐位（Trending now、Customers frequently viewed 等）的 ASIN：

searchKeyword: "wireless charger", country: "US", condition: "acAd"

5. 分析非美国站点的关键词 分析日本站点的流量来源（使用当地语言关键词）：

searchKeyword: "ワイヤレス充電器", country: "JP"

6. 聚焦特定竞争对手 ASIN 将结果限制在少量竞争 ASIN 内：

searchKeyword: "wireless charger", country: "US", asins: "B01NBNDC1T,B09VLJJPL6"

7. 自定义日期范围

searchKeyword: "wireless charger", country: "US", last7d: false, startDate: "2026-04-05", endDate: "2026-04-11"

8. 按整体 SP 曝光量对 ASIN 排名

searchKeyword: "wireless charger", country: "US", sortBy: "totalSpSocre", desc: true

9. 本周期新进入的流量关键词

searchKeyword: "wireless charger", country: "US", condition: "totalPeriod.in"

展示规则

1. 清晰呈现数据：以结构清晰的表格展示查询结果。按流量渠道曝光占比对数据分组，便于比较。
2. 区分产品级与关键词级评分：不要混用 naturalSearchExposureScore（产品整体）和 keywordNaturalExposureScore（仅针对当前关键词）。标注列名，明确数据的适用范围。
3. 突出关键占比：展示结果时，重点突出自然搜索曝光占比与付费广告曝光占比，帮助用户快速评估自然流量与付费流量的比例。
4. 翻译字段名称：使用便于用户理解的名称，而非原始 API 字段名（例如，使用“自然搜索曝光占比”，而不是“naturalSearchExposureRatio”）。
5. 结果数量提示：当结果较多（总数较高）时，展示核心数据，并提醒用户可以翻页查看更多结果。
6. 周期标注：比较曝光量或数量时，标注解析后的时间范围——默认使用 last7d；如果设置了自定义范围，则使用 startDate ~ endDate。同时在每一行显示 dataPeriodStartDate。
7. 错误处理：查询失败时，根据 msg 字段说明原因，并建议调整查询参数（例如，检查关键词拼写或商城代码）。
8. 百分比格式：以百分比形式显示曝光占比（例如，将 0.45 显示为“45%”），便于阅读。
9. 流量来源摘要：展示单个 ASIN 的数据时，简要总结流量构成（例如：“该产品 60% 的曝光来自自然搜索，25% 来自 SP 广告，15% 来自品牌广告”）；如果用户询问的是当前关键词，则优先使用关键词级字段。

重要限制

• 单一条件筛选：每次请求只能使用一个 condition 值。若要比较多个流量来源，请分别发起请求。
• 商城覆盖范围：仅支持 13 个商城——IN / NL / SE / PL / TR / SG 已不再支持。
• 关键词语言：为获得最佳结果，searchKeyword 应使用目标商城的语言。
• 结果上限：每页最多返回 100 条记录。
• 适用范围：此端点专注于按关键词查询 ASIN 流量；不会返回完整 ASIN 元数据、跨渠道关键词数量或变体汇总。对于这些数据，请使用 ASIN 流量来源工具。

用户表述与场景速查

适用——Amazon 关键词的流量来源与竞争结构分析：

用户表述	场景
“这个关键词的流量来自哪里？”	流量来源细分
“自然流量和付费流量各占多少？”	自然流量与付费流量占比分析
“哪些人在这个关键词下投放 SP 广告？”	SP 广告竞争分析（condition=isSpAd）
“哪些产品出现在 SP 推荐位？”	SP 推荐位查询（condition=acAd）
“哪些产品获得了 Amazon's Choice？”	AC 徽章分析（通过 amazonsChoiceExposureScore）
“这个关键词是否被广告主导？”	广告饱和度评估
“展示品牌广告竞争情况”	品牌广告格局分析
“竞争对手的关键词流量结构如何？”	竞争流量分析
“哪些产品获得了编辑推荐？”	ER 展示位分析
“比较这两个 ASIN 在此关键词下的表现”	ASIN 筛选：asins="B0A,B0B"
“3 月 8 日当周，这个关键词的流量情况”	自定义 startDate/endDate 时间范围
“本周期新进入的流量关键词”	新增筛选（condition=totalPeriod.in）

不适用——需求超出关键词流量来源分析范围：

• 当前周期和自定义时间范围以外的关键词历史排名趋势（请使用 ABA 数据工具）
• 广告竞价／预算优化
• 产品评论或商品详情内容
• 销量估算
• 完整的关键词搜索量时间曲线
• 所有关键词下的完整 ASIN 流量结构（请使用 SIF ASIN 流量来源工具）

算力消耗规则

消耗 9 算力。

用户会因算力消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对算力消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈：

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

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

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

---

如需获取更多高质量、专业的跨境电商技能，请设置 LinkFox Skills。