linkfox-keepa-product-search

Keepa 产品搜索

此技能将指导你如何使用 Keepa 丰富的产品数据库搜索和筛选 Amazon 商品，帮助 Amazon 卖家从多个维度找到符合特定条件的商品。

核心概念

此工具由 Keepa 数据提供支持，可用于高级 Amazon 商品搜索。与简单的 Amazon 商店搜索不同，它支持多条件筛选：类别、价格范围、月销量、BSR（Best Sellers Rank）、关键词匹配（正向和排除）、评论数量、评分、包装尺寸、重量、配送类型、历史销售排名等。它会返回详细的商品数据，包括价格、标题、图片、上架日期、材质、重量、过去 12 个月的月销量等。

BSR（Best Sellers Rank）：salesRank 值越低，销售表现越好。排名第 1 的商品是其类别中的畅销商品。用户说“热销商品”时，指的是 BSR 值较低的商品。

价格单位：价格以最小货币单位表示（例如，美元以美分计）。因此，$25.99 = 2599。构建查询和展示结果时，请务必进行换算。

类别名称：categoriesIncludeNames 参数支持多级类别路径，使用冒号 : 或 > 字符分隔。请自动将用户输入转换为正确格式。

参数

站点（必填）

参数	类型	必填	说明	默认值
domain	string	是	Amazon 站点 ID	-

Domain ID 对应关系：

ID	站点
1	Amazon.com（美国）
2	Amazon.co.uk（英国）
3	Amazon.de（德国）
4	Amazon.fr（法国）
5	Amazon.co.jp（日本）
6	Amazon.ca（加拿大）
8	Amazon.it（意大利）
9	Amazon.es（西班牙）
10	Amazon.in（印度）
11	Amazon.com.mx（墨西哥）

默认站点为 1（美国）。如果用户未指定站点，请使用 domain 1。

关键词筛选

参数	类型	说明
keyword	string	标题关键词筛选（不区分大小写；空格表示 AND；短语需用双引号括起；前缀加 - 表示排除；& 会替换为空格；最多 50 个关键词，最多 1000 个字符）

类别筛选

参数	类型	说明
rootCategory	array[int]	根类别 ID（最多 50 个）
rootCategoryNames	array[string]	根类别名称（最多 50 个）；仅在 rootCategory 为空时使用；系统会自动解析 ID
categoriesInclude	array[int]	要包含的子类别 ID（最多 50 个）
categoriesIncludeNames	array[string]	要包含的子类别名称（最多 50 个）；支持使用 : 或 > 分隔的完整类别路径
categoriesExclude	array[int]	要排除的子类别 ID（最多 50 个）
categoriesExcludeNames	array[string]	要排除的子类别名称（最多 50 个）；支持完整类别路径

销量与排名筛选

参数	类型	说明
currentSalesGte	integer	当前 BSR -- 最小值（数值越大，排名越差）
currentSalesLte	integer	当前 BSR -- 最大值（数值越小，排名越好）
avg90SalesGte	integer	90 天平均 BSR -- 最小值
avg90SalesLte	integer	90 天平均 BSR -- 最大值
deltaPercent90SalesGte	integer	90 天 BSR 变化百分比 -- 最小值
deltaPercent90SalesLte	integer	90 天 BSR 变化百分比 -- 最大值
monthlySoldGte	integer	月销量 -- 最小值
monthlySoldLte	integer	月销量 -- 最大值
srAvgGte	integer	历史平均 BSR -- 最小值（针对特定月份）
srAvgLte	integer	历史平均 BSR -- 最大值（针对特定月份）
srAvgMonth	string	历史 BSR 月份选择（格式：YYYYMM，限最近 36 个月内）

价格筛选

参数	类型	描述
currentNewGte	integer	当前新品价格——最低值（最小货币单位）
currentNewLte	integer	当前新品价格——最高值（最小货币单位）
currentBuyBoxShippingGte	integer	当前 Buy Box 含运费价格——最低值（最小货币单位）
currentBuyBoxShippingLte	integer	当前 Buy Box 含运费价格——最高值（最小货币单位）

评论与评分筛选

参数	类型	描述
currentCountReviewsGte	integer	评论数——最低值
currentCountReviewsLte	integer	评论数——最高值
currentRatingGte	number	评分——最低值（0.0-5.0）
currentRatingLte	number	评分——最高值（0.0-5.0）

包装与尺寸筛选

参数	类型	描述
packageLengthGte / packageLengthLte	integer	包装长度范围（mm）
packageWidthGte / packageWidthLte	integer	包装宽度范围（mm）
packageHeightGte / packageHeightLte	integer	包装高度范围（mm）
packageWeightGte / packageWeightLte	integer	包装重量范围（克）

其他筛选条件

参数	类型	描述
brand	array[string]	品牌名称（OR 匹配）
color	array[string]	颜色（OR 匹配）
size	array[string]	尺寸（OR 匹配）
availableDateGte / availableDateLte	string	商品上架日期范围（yyyy-MM-dd）
buyBoxIsAmazon	boolean	Buy Box 卖家是否为 Amazon
buyBoxIsFBA	boolean	Buy Box 是否由 FBA 配送
isHazMat	boolean	危险品标记
variationCountGte / variationCountLte	integer	变体数量范围
currentCountNewGte / currentCountNewLte	integer	新品报价数量范围
outOfStockPercentage90Gte / outOfStockPercentage90Lte	integer	90 天缺货百分比范围
singleVariation	boolean	每个父 ASIN 仅返回一个变体
productType	array[int]	商品类型：0=标准商品，1=可下载商品，2=电子书，5=变体父商品

数据选项

参数	类型	描述	默认值
history	integer	包含历史数据（价格历史、销售排名、每月月销量）	0（否）
rating	integer	包含评分信息	1（是）

分页与排序

参数	类型	描述	默认值
page	integer	页码（从 1 开始）	1
perPage	integer	每页结果数（最少 50，最多 100）	50
sort	array[object]	排序规则（最多 3 条）；每个对象：`{"fieldName": "...", "sortDirection": "asc	desc"}`

可排序字段：availableDate、currentSales、monthlySold、currentRating、currentCountReviews、currentBuyBoxShipping、currentNew

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-keepa-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. 确定市场：将用户的目标国家映射到正确的 domain ID 值
2. 设置关键词筛选条件：使用 keyword 按标题筛选，并设置正向和排除词
3. 设置类别范围：使用 categoriesIncludeNames 或 rootCategoryNames 按类别限定范围；将用户输入转换为正确的类别路径格式
4. 应用数值筛选条件：将销量、价格、BSR、评论数和评分要求映射到相应的 Gte/Lte 参数
5. 设置排序顺序：如果用户希望按销量、价格或评分排序，请配置 sort 数组
6. 启用历史数据：如果用户需要月销量趋势或价格历史，请将 history 设为 1

使用示例

1. 在美国市场搜索月销量超过 1000 的电子产品

{"domain": "1", "rootCategoryNames": ["Electronics"], "monthlySoldGte": 1000}

2. 查找价格在指定范围内且评分良好的产品

{"domain": "1", "currentBuyBoxShippingGte": 1500, "currentBuyBoxShippingLte": 5000, "currentRatingGte": 4.0, "keyword": "wireless charger"}

3. 查找过去 6 个月内上架且评论数较少的新产品

{"domain": "1", "availableDateGte": "2025-10-01", "currentCountReviewsLte": 50, "monthlySoldGte": 500}

4. 筛选 BSR 排名，用于竞争分析

{"domain": "1", "categoriesIncludeNames": ["Home & Kitchen"], "currentSalesLte": 5000, "sort": [{"fieldName": "monthlySold", "sortDirection": "desc"}]}

5. 查找销量良好的非 Amazon FBA 产品

{"domain": "1", "buyBoxIsAmazon": false, "buyBoxIsFBA": true, "monthlySoldGte": 300, "currentRatingGte": 4.0}

6. 查找便于运输的轻小型产品

{"domain": "1", "packageWeightLte": 500, "packageLengthLte": 200, "packageWidthLte": 150, "packageHeightLte": 100, "monthlySoldGte": 200}

7. 在日本市场搜索并包含历史数据

{"domain": "5", "keyword": "USB charger", "history": 1, "monthlySoldGte": 100}

8. 搜索特定品牌并排除危险品

{"domain": "1", "brand": ["Anker", "UGREEN"], "isHazMat": false, "sort": [{"fieldName": "monthlySold", "sortDirection": "desc"}]}

展示规则

1. 清晰呈现数据：使用结构清晰的表格展示搜索结果，并包含关键字段：ASIN、标题、价格、BSR、月销量、评分、评论数、品牌
2. 价格换算：将价格从最小货币单位换算为标准格式（例如，2599 -> $25.99）
3. 说明 BSR：展示 BSR 数据时，提醒用户数值越低，销售排名越好
4. 月销量历史：包含历史数据时，清晰展示 12 个月的销量趋势
5. 分页提示：告知用户结果总数，并建议在需要时获取后续页面
6. 图片链接：如果有图片 URL，请告知用户，但除非用户提出要求，否则不要尝试以内嵌形式渲染
7. 错误处理：查询失败时，说明原因并建议调整筛选条件

重要限制

• 结果上限：每页最多 100 条结果，最少 50 条
• 排序限制：每个查询最多 3 条排序规则
• 类别限制：每个筛选条件最多包含 50 个类别 ID 或名称
• 关键词限制：keyword 参数最多包含 50 个关键词
• 历史数据成本：设置 history=1 会显著增加响应大小和 token 成本
• 价格单位：所有价格值均以最小货币单位表示（美分、便士等）

用户表达与场景快速参考

适用——多条件 Amazon 商品搜索与筛选：

用户表达	场景
“查找月销量超过 X 的商品”	销量筛选
“搜索 XX 类目下的商品”	按类目发现商品
“BSR 低于 X 的商品”	销售排名筛选
“过去 N 个月内上架的新品”	发现新品
“价格在 $X 到 $Y 之间的商品”	价格范围筛选
“评分不错的 FBA 商品”	配送方式 + 评分筛选
“重量低于 X 克的轻量商品”	包装尺寸筛选
“XX 品牌的商品”	品牌定向搜索
“查看 XX 的历史销量数据”	历史销量分析
“高级商品筛选”“商品筛查”	多条件商品调研
“寻找利基商品”“查找竞争较小的商品”	竞争差距分析
“BSR 趋势”“销售排名历史”	历史排名筛选

不适用——超出商品搜索范围的需求：

• 实时模拟 Amazon 搜索结果页面（使用 Amazon Search）
• 历史搜索词搜索量或排名趋势（使用 ABA 数据）
• 商品评论内容或情感分析
• 广告活动管理或出价优化
• Listing 优化或文案建议
• 库存或供应链数据

边界判断：用户提到“商品调研”或“找商品”时，如果涉及按销量指标、BSR、价格、类目等结构化条件筛选，则适用此技能。如果用户想查看 Amazon 实际搜索页面中某个关键词的搜索结果，请改用 Amazon Search。如果用户需要搜索词分析，请使用 ABA 数据。

算力消耗规则

按动态规则计费：消耗算力 = 0.045 ×（找商品阶段消耗的 Keepa token + 拉取商品详情阶段消耗的 Keepa token）。先找商品，再拉取商品详情；若第一阶段未找到商品，则只计找商品阶段的消耗。

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

反馈：

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

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

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

---

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