linkfox-sorftime-amazon-product-query

Sorftime 产品搜索

此技能将指导你如何通过 Sorftime 从多个维度搜索和筛选 Amazon 商品，帮助 Amazon 卖家发现商品、分析竞争对手并探索市场机会。

核心概念

Sorftime 产品搜索支持多维度商品检索，提供 16 种查询类型，支持单条件查询或多个条件的 AND 组合，并可回溯查看自 2024 年 1 月起的月度历史快照。数据涵盖价格、BSR 排名、月销量、FBA 费用和利润分析。

主要区别：此工具用于跨商品搜索和筛选。如果你需要查看特定 ASIN 的详细趋势数据（销量／价格／BSR 历史），请改用 Sorftime 商品详情技能。

数据字段

响应数据涵盖以下类别（完整字段说明请参阅 references/api.md）：

• 基本信息：ASIN、标题、品牌、商品详情页 URL、图片（主图 + 列表图）、父 ASIN、变体数量、重量、尺寸
• 价格与利润：当前价格、促销价（优惠券后）、划线价、优惠券、FBA 费用（含详细明细）、平台费、利润金额与利润率
• 销量：月销量、月销售额、日销量、日销售额（值为 -1 表示无法估算）
• 排名：BSR 排名、类别、子类别排名
• 评分：评分、评分数量
• 商品详情页信息：上架日期、在线天数
• 卖家：Buybox 卖家名称／ID／国家、FBA 状态、卖家数量
• 商品详情页特征：A+ 内容、视频、品牌店铺

支持的商城

US（美国）、GB（英国）、DE（德国）、FR（法国）、IN（印度）、CA（加拿大）、JP（日本）、ES（西班牙）、IT（意大利）、MX（墨西哥）、AE（阿联酋）、AU（澳大利亚）、BR（巴西）、SA（沙特阿拉伯）

默认商城为 US。用户未指定商城时使用 us。

注意：Sorftime 使用小写代码（例如 us、gb、de），英国的代码为 gb（不是 uk）。

调用方式

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

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

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

如何构建查询

关键参数为 marketplace（必填）、queryMode、queryType 和 queryValue。查询系统包含两种模式和 16 种筛选类型，可灵活组合。

构建查询的原则

1. 始终指定商城：使用小写站点代码，例如 us、de、jp
2. 选择合适的查询模式：单一筛选条件使用 queryMode=1；多个筛选条件使用 queryMode=2，以 AND 逻辑组合
3. 使 queryType 与 queryValue 格式匹配：每种 queryType 都要求特定格式——请参阅下表。格式不匹配会导致错误
4. 注意价格单位：价格筛选（queryType=8）使用 smcurrency 单位（美元以美分计），因此 $19.99 = 1999
5. 适当使用开放区间：省略区间一端可设置开放区间——,1000 表示“最高为 1000”；100, 表示“100 或以上”
6. 使用 queryMonth 进行历史对比：格式为 yyyy-MM；与第二次不带 queryMonth 的调用结果对比，即可查看随时间的变化

查询类型（queryType，适用于 queryMode=1）

queryType	名称	queryValue 格式	示例
1	相似 ASIN	ASIN	B0CVM8TXHP
2	类目	NodeId	3743561
3	品牌	品牌名称	Anker
4	卖家名称	店铺名称	AnkerDirect
5	卖家 ID	SellerId	A294P4X9EWVXLJ
6	ABA 关键词	关键词	Power Bank
7	标题/属性匹配	关键词	10,000mAh 30W
8	价格范围	min,max（以美分为单位）	1,1000（=$0.01~$10）
9	月销量范围	min,max	100,1000
10	季节性产品	月份列表	1,2,3（1 月至 3 月为旺季）
11	上架日期范围	start,end（yyyy-MM-dd）	2024-06-01,2024-12-01
12	评分范围	min,max	3,5
13	评论数范围	min,max	10,500
14	排名范围	bsr_min,bsr_max;sub_min,sub_max	500,5000;1,100
15	配送方式	FBA / FBM	FBA,FBM
16	变体数量	min,max	1,50

重要：queryType=1（相似 ASIN）会查找与给定 ASIN 相似的产品，而不是该 ASIN 本身。若要查询单个产品的详情，请使用 Sorftime Product Detail 技能。

历史快照（queryMonth）

设置 queryMonth（格式为 yyyy-MM）可查询过去某个月的产品数据快照。这样用户就能将历史价格、排名和销量与当前数据进行比较。

• 支持范围：2024 年 1 月至今（约 2 年）
• US、GB、DE 支持完整的“无限”回溯模式
• 其他站点回溯时仅支持 Top 100 产品
• AU、BR、IN 不支持回溯

常见场景的查询示例

1. 查找给定 ASIN 的竞品

queryMode: 1, queryType: 1, queryValue: B0CVM8TXHP, marketplace: us

2. 浏览某个类目的热门产品

queryMode: 1, queryType: 2, queryValue: 3743561, marketplace: us

3. 分析某个品牌的产品组合

queryMode: 1, queryType: 3, queryValue: Anker, marketplace: us

4. 按 ABA 关键词搜索

queryMode: 1, queryType: 6, queryValue: Power Bank, marketplace: us

5. 发掘季节性产品（第四季度旺季）

queryMode: 1, queryType: 10, queryValue: 10,11,12, marketplace: us

6. 比较历史数据与当前数据

queryMonth: 2024-11, queryMode: 1, queryType: 2, queryValue: 3743561, marketplace: us
-> Compare with current data (no queryMonth) to see price/sales changes

7. 多条件查询：销量良好的新 FBA 产品

queryMode: 2
queryValue: [{"QueryType":11,"Content":"2024-06-01,"},{"QueryType":9,"Content":"300,"},{"QueryType":15,"Content":"FBA"}]
marketplace: us

8. 查找低价高销量产品

queryMode: 2
queryValue: [{"QueryType":8,"Content":",2000"},{"QueryType":9,"Content":"500,"}]
marketplace: us

9. 查看某个卖家的产品组合

queryMode: 1, queryType: 4, queryValue: AnkerDirect, marketplace: us

显示规则

1. 仅呈现数据：使用清晰的表格展示查询结果，不提供主观的商业建议
2. 排名说明：展示排名数据时，提醒用户数值越低，排名越好
3. 分页提示：每页搜索结果最多返回 100 个产品，最多 200 页。如果结果较多，请展示重点信息并提醒用户进行分页查询
4. 销量估算说明：销量/收入字段中的 -1 表示“无法估算”——向用户解释这一点，不要直接显示 -1
5. 错误处理：查询失败时，根据 msg 字段解释原因，并建议调整查询条件

重要限制

• 分页：每页最多 100 个产品，最多 200 页
• 历史数据支持
• 非结构化数据：结果不支持通过 _dataQuery_executeDynamicQuery 进行二次分析
• 销量估算：非标准类目中的产品，销量字段可能返回 -1
• ABA 关键词搜索（queryType=6）：目前仅支持 ABA 关键词，不支持任意搜索词

用户表达与场景速查

适用 - 在 Amazon 上搜索和筛选产品：

用户说	场景
"找一下这个类目下卖得好的产品"	类目探索
"Anker品牌有哪些热销产品"	品牌分析
"这个ASIN的竞品有哪些"	竞品发现
"帮我找一些季节性产品"	季节性产品发现
"新品中月销量超过500的有哪些"	筛选产品发现
"去年双十一这个类目的价格快照"	历史快照对比
"这个卖家还卖了什么产品"	卖家产品组合
"帮我筛选利润率高于30%的FBA产品"	利润导向筛选
"月销量1000以上，评分4星以上的产品"	多条件筛选
"标题包含wireless charger的产品"	标题关键词搜索

不适用 - 超出产品搜索范围的需求：

• 特定 ASIN 的详细趋势／历史数据（使用 Sorftime Product Detail）
• ABA 搜索词排名数据（使用 ABA Data Explorer）
• 广告／PPC 策略
• 产品评论内容分析
• 专利或商标查询

范围判断：当用户提到“竞品分析”或“市场调研”时，如果他们需要按类目、品牌、价格区间等维度发现并比较产品，则本技能适用。如果他们需要特定 ASIN 的历史趋势曲线，则使用 Prt Detail 技能。如果他们需要关键词搜索量数据，则使用 ABA Data Explorer。

算力消耗规则

按动态规则计费：消耗算力 = Sorftime 内部查询次数 × 6。Sorftime 内部查询次数：不同查询条件所需的查询次数可能不同，具体次数由 Sorftime 决定。

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

反馈：

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

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

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

---

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