linkfox-sellersprite-product-search

SellerSprite 产品搜索

本技能将指导你如何通过 SellerSprite 产品数据库搜索、筛选和分析 Amazon 产品数据，帮助 Amazon 卖家依据数据做出选品决策。

核心概念

SellerSprite 产品搜索可访问内容丰富的 Amazon 产品数据库，并提供多种筛选维度。它支持实时数据（最近 30 天）以及月度历史快照，便于进行同比和环比比较。支持的 marketplace 代码仅限于：US、UK、DE、FR、JP、CA、IT、ES、MX 和 IN（与网关架构一致）。

BSR（Best Sellers Rank，畅销榜排名）：BSR 数值越低，表示该产品在所属类目中的销售表现越好。BSR 为 1 表示该产品是该类目的畅销品。当用户说“BSR 提升”时，表示数值降低；“BSR 下降”则表示数值升高。

数据快照：dataSnapshotMonth 参数用于控制要查询的时间段。使用 nearly（默认值）查询最近 30 天的实时数据，或使用 yyyyMM 字符串（例如 202412）查询历史月度快照。此参数适用于季节性分析和同比比较。

关键词匹配类型：按关键词搜索时，有三种匹配策略可供选择：

• 短语匹配（默认）：产品标题必须包含该关键词短语
• 模糊匹配：扩大匹配范围，包含相关词语
• 精确匹配：严格匹配完全一致的字符串

参数指南

搜索与筛选

参数	类型	描述	默认值
keyword	string	搜索关键词；请翻译为目标站点所用语言（例如 US 使用英语，DE 使用德语）	-
matchType	integer	1 = 短语匹配，2 = 模糊匹配，3 = 精确匹配	1
excludeKeywords	string	要从结果中排除的关键词	-
marketplace	string	站点代码（仅限以下允许值）：US、UK、DE、FR、JP、CA、IT、ES、MX、IN	US
nodeLabel	string	Amazon 类目名称	-
nodeIdPath	string	Amazon 类目节点 ID	-
filterSubNode	boolean	是否按子类目节点筛选（仅当设置了 nodeLabel 或 nodeIdPath 时生效）	-
dataSnapshotMonth	string	yyyyMM 格式的数据快照月份，或使用 nearly 查询最近 30 天的实时数据	nearly

价格与财务数据

参数	类型	描述
minPrice / maxPrice	number	价格范围筛选
minProfit / maxProfit	number	毛利率范围（1-100，单位：%）
minRevenue / maxRevenue	number	月收入范围
minFba / maxFba	number	FBA 费用范围

销量与排名

参数	类型	描述
minUnits / maxUnits	integer	月销量范围
minAmzUnit / maxAmzUnit	integer	子 ASIN 最近 30 天销量范围（仅查询最近 30 天类型的数据时可用，例如 dataSnapshotMonth: "nearly"）
minUnitsGrowthRate / maxUnitsGrowthRate	number	月销量增长率（%）
minBsr / maxBsr	integer	主类目 BSR 排名范围
minBsrGrowthRate / maxBsrGrowthRate	number	BSR 增长率（%）
minBsrGrowthCount / maxBsrGrowthCount	integer	BSR 增长次数
minSubNodeBsrRank / maxSubNodeBsrRank	integer	子类目 BSR 排名（需要 filterSubNode = true）

评论与评分

参数	类型	描述
minRating / maxRating	number	评分范围（0-5）；3.8-4.3 表示产品有改进机会
minRatings / maxRatings	integer	评分数量范围（0-10000）
minRatingsGrowthCount / maxRatingsGrowthCount	integer	月新增评分数量
minListingQualityScore / maxListingQualityScore	number	Listing 质量评分范围

产品属性

参数	类型	描述
minVariations / maxVariations	integer	变体数量范围
minWeights / maxWeights	number	重量范围
weightUnit	string	重量单位：g、kg、oz、lb（使用重量筛选条件时必填）
dimensionType	string	包装尺寸类型（特定市场代码）
minSellers / maxSellers	integer	卖家数量范围

徽章与配送

参数	类型	描述
badgeBestSeller	string	畅销商品徽章：Y / N / 空（全部）
badgeAmazonsChoice	string	Amazon's Choice 徽章：Y / N / 空（全部）
badgeNewRelease	string	新品徽章：Y / N / 空（全部）
fulfillment	string	配送类型：AMZ、FBA、FBM（多个值以逗号分隔）
showVariation	string	显示变体：Y / N（默认 N）

卖家与品牌

参数	类型	描述
sellerNation	string	卖家国家/地区代码（例如 US、CN、HK）；多个值以逗号分隔
includeSellers / excludeSellers	string	纳入 / 排除指定卖家
includeBrands / excludeBrands	string	纳入 / 排除指定品牌

商品列表与分页

参数	类型	描述	默认值
hideUnlistedProduct	boolean	隐藏已下架商品	true
listedWithinLastMonths	integer	最近 N 个月内上架（1、3、6、12 或 24）	-
page	integer	页码，从 1 开始；分页最多只能访问前 2,000 条记录	1
size	integer	每页结果数（10-100）；page * size 不得超过 2,000	20

排序

使用包含两个字段的 order 对象：

字段	类型	描述
field	string	排序字段：total_units、total_amount、bsr_rank、price、rating、reviews、profit、reviews_rate、available_date、questions、total_units_growth、total_amount_growth、reviews_increasement、bsr_rank_cv、bsr_rank_cr、amz_unit；如果要有意省略业务排序键（遵循网关架构），请使用 ""
desc	string	降序时为 "true"，升序时为 "false"

默认排序：按 total_units 降序。

可选网关 / 会话字段

如果托管环境提供了这些字段，可以将 chatId、uid、requestId 和 teamId 作为字符串传入（参见 references/api.md）。临时脚本调用无需提供。

调用方式

• API 端点：POST /sellersprite/productSearch（完整参数、响应和错误代码见 references/api.md）
• Python 脚本：python scripts/sellersprite_product_search.py '<JSON 参数>' [--inline]
• 成本限制：本工具会消耗算力；同一会话中相同参数组合默认只调用一次，脚本带有 24 小时本地缓存。失败或结果为空时，不得自动更换关键词、翻页或修改邮编连续尝试；如需继续检索，请先告知用户会产生额外消耗。

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-sellersprite-product-search-<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. 查找细分市场中的高销量产品 在美国站点搜索关键词 "yoga mat" 的产品，月销量超过 500 件，并按月销量降序排列。

{
  "keyword": "yoga mat",
  "marketplace": "US",
  "minUnits": 500,
  "order": {"field": "total_units", "desc": "true"}
}

2. 发掘竞争较小的新产品机会 查找美国站点最近上架（6 个月内）、评分少于 50 条且月收入超过 $5,000 的产品。

{
  "keyword": "desk organizer",
  "marketplace": "US",
  "listedWithinLastMonths": 6,
  "maxRatings": 50,
  "minRevenue": 5000,
  "order": {"field": "total_units", "desc": "true"}
}

3. 挖掘产品改进机会 查找评分在 3.8 到 4.3 之间（适合改进的区间）、月销量超过 300 件且属于特定类别的产品。

{
  "keyword": "phone case",
  "marketplace": "US",
  "minRating": 3.8,
  "maxRating": 4.3,
  "minUnits": 300,
  "order": {"field": "total_units", "desc": "true"}
}

4. 筛选高利润产品 查找毛利率超过 40%、价格在 $15 到 $50 之间且月销量至少 100 件的产品。

{
  "marketplace": "US",
  "minProfit": 40,
  "minPrice": 15,
  "maxPrice": 50,
  "minUnits": 100,
  "order": {"field": "profit", "desc": "true"}
}

5. 季节性同比比较 查询去年 12 月的快照数据，并与当前数据进行比较，为季节性产品规划提供依据。

{
  "keyword": "christmas lights",
  "marketplace": "US",
  "dataSnapshotMonth": "202412",
  "minUnits": 200,
  "order": {"field": "total_units", "desc": "true"}
}

6. 中国卖家的竞争格局 查找特定类别中由中国卖家销售且由 FBA 配送的高月销量产品。

{
  "keyword": "bluetooth speaker",
  "marketplace": "US",
  "sellerNation": "CN",
  "fulfillment": "FBA",
  "minUnits": 200,
  "order": {"field": "total_units", "desc": "true"}
}

7. Best Seller 和 Amazon's Choice 徽章持有产品 查找带有 Best Seller 徽章且销量表现强劲的产品。

{
  "keyword": "water bottle",
  "marketplace": "US",
  "badgeBestSeller": "Y",
  "order": {"field": "total_units", "desc": "true"}
}

8. 按销量增长率查找快速增长的产品 查找月销量增长率超过 50% 的产品。

{
  "keyword": "standing desk",
  "marketplace": "US",
  "minUnitsGrowthRate": 50,
  "order": {"field": "total_units_growth", "desc": "true"}
}

展示规则

1. 清晰呈现数据：将查询结果以结构清晰的表格展示。优先显示的关键列：ASIN、标题、价格、月销量、月收入、BSR 排名、评分、评分数、毛利率、配送类型
2. BSR 说明：显示 BSR 数据时，提醒用户数值越低，排名越好
3. 毛利率说明：毛利率以百分比表示。提醒用户，这是根据价格减去 FBA 费用和估算成本得出的估值
4. 分页注意事项：当总数超过当前返回页的大小时，告知用户结果总数，并建议仅在前 2,000 条记录内调整页码或每页数量。如果 total 超过 2,000，明确说明无法查询前 2,000 条以后的记录，并建议缩小筛选范围
5. 快照标注：显示历史快照数据时，明确标注数据所属时段（例如，“数据来自 2024 年 12 月快照”），以免与实时数据混淆
6. 错误处理：查询失败时，根据 message 字段说明原因，并建议调整查询条件
7. 重量单位提醒：用户提供重量筛选条件但未指定单位时，继续操作前先请用户确认重量单位（g、kg、oz 或 lb）
8. 关键词翻译：用户提供的关键词与目标站点所用语言不同时，将关键词翻译为相应语言并注明译文

重要限制

• 结果上限：每页返回 10-100 条记录，分页只能查询排序结果集中的前 2,000 条记录（page * size 不得超过 2,000）。若要查询此范围以外的记录，请缩小筛选范围
• 历史快照：仅提供过去的月度快照，不支持未来日期
• 必须指定重量单位：使用任何重量筛选条件时，还必须提供 weightUnit
• 子类别 BSR：仅当 filterSubNode 设置为 true 时，子类别 BSR 排名筛选条件才生效
• 上架时间仅支持指定枚举值：listedWithinLastMonths 参数仅接受以下值：1、3、6、12 或 24
• 子 ASIN 的 30 天销量筛选条件：minAmzUnit / maxAmzUnit 仅适用于最近 30 天类型的查询（通常为 dataSnapshotMonth: "nearly"）；不要将其用于历史 yyyyMM 快照

用户表达与场景快速参考

适用——Amazon 商品层面的数据查询：

用户表达	场景
“查找 XX 类目中销量高的商品”	细分商品搜索
“展示竞争较小的商品”“新品机会”	蓝海商品发现
“哪些商品利润率高？”	盈利能力筛选
“销量上升的商品”“热门商品”	增长趋势检测
“中国卖家有哪些商品卖得好？”	竞争格局分析
“近期上架且表现不错的商品”	新品追踪
“差评多但销量好的商品”	商品改进机会
“将这个类目与去年进行比较”	季节性 / 同比分析
“售价低于 $30、销量超过 1,000 的 FBA 商品”	多条件商品筛选
“XX 类目中的畅销商品”	基于徽章的商品发现

不适用——需求超出商品层面的搜索数据：

• ABA 搜索词 / 关键词分析（请改用 ABA Data Explorer）
• 广告 / PPC 广告活动数据
• 商品评论文本分析
• 商品详情页文案撰写或优化
• 供应商寻源或制造成本
• 物流和库存规划

判断边界：当用户提到“商品调研”或“市场分析”时，如果需求归结为根据销量、价格、BSR、评分和其他商品属性筛选 Amazon 商品，则适用此技能。如果用户询问关键词搜索量、搜索词排名或点击 / 转化份额数据，则 ABA Data Explorer 技能更合适。

算力消耗规则

消耗 15 算力。

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

反馈：

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

1. 此技能所述功能或用途与实际行为不符
2. 技能结果与用户意图不符
3. 用户对这项技能表达不满或称赞
4. 你认为有任何可改进之处

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

---

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