用途
本技能用于基于 Keepa 数据的亚马逊高级商品搜索与筛选，帮助亚马逊卖家按多维度条件找到符合要求的商品。与简单的亚马逊店铺搜索不同，它支持多条件组合过滤，适用于选品、竞品分析、小众商品发掘等场景。
主要能力
支持以下维度的筛选：
- 市场站点：通过 domain 参数指定，如 1=美国、2=英国、3=德国、5=日本等，默认 1（美国）。
- 关键词：keyword 参数对标题进行过滤，不区分大小写，空格表示 AND，双引号包裹短语，前缀 - 表示排除，& 会被替换为空格，最多 50 个关键词、1000 字符。
- 品类：支持根品类（rootCategory / rootCategoryNames）与子品类（categoriesInclude / categoriesIncludeNames / categoriesExclude / categoriesExcludeNames），名称支持用 : 或 > 分隔的多级路径，每项最多 50 个。
- 销售与排名：当前 BSR（currentSalesGte/Lte）、90 天平均 BSR（avg90SalesGte/Lte）、90 天 BSR 变化百分比（deltaPercent90SalesGte/Lte）、月销量（monthlySoldGte/Lte）、历史平均 BSR（srAvgGte/Lte，配合 srAvgMonth 指定 YYYYMM，近 36 个月内）。
- 价格：当前新品价（currentNewGte/Lte）、当前含运费 Buy Box 价（currentBuyBoxShippingGte/Lte），均以最小货币单位表示。
- 评论与评分：评论数（currentCountReviewsGte/Lte）、评分（currentRatingGte/Lte，0.0-5.0）。
- 包装与尺寸：长宽高（packageLength/Width/HeightGte/Lte，单位 mm）、重量（packageWeightGte/Lte，单位克）。
- 其他：品牌、颜色、尺寸（OR 匹配）、上架日期范围（availableDateGte/Lte，yyyy-MM-dd）、Buy Box 是否为亚马逊（buyBoxIsAmazon）、是否 FBA（buyBoxIsFBA）、是否危险品（isHazMat）、变体数量、新品报价数量、90 天缺货百分比、是否仅返回每个父 ASIN 的一个变体（singleVariation）、商品类型（productType，0=标准、1=可下载、2=电子书、5=变体父体）。
- 数据选项：history 参数控制是否包含历史数据（价格历史、销售排名、每月月销量），默认 0；rating 参数控制是否包含评分信息，默认 1。
- 分页与排序：page 从 1 开始，perPage 最小 50、最大 100，默认 50；sort 最多 3 条规则，可排序字段包括 availableDate、currentSales、monthlySold、currentRating、currentCountReviews、currentBuyBoxShipping、currentNew。
返回数据包含价格、标题、图片、上架日期、材质、重量、近 12 个月月销量等详细信息。
使用方式
- API 端点：POST /keepa/productSearch（完整参数、响应与错误码见 references/api.md）。
- Python 脚本：python scripts/keepa_product_search.py '<JSON 参数>' [--inline]。
输出策略（脚本默认行为）：
- 始终将完整响应写入 <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 进入上下文。
构建查询的步骤：确定市场站点、设置关键词过滤、设置品类范围、应用数值过滤、设置排序、按需启用历史数据。
适用场景
- 按销量、BSR、价格、品类等结构化条件筛选商品。
- 新品发掘、小众商品发掘、竞品筛选、历史排名筛选。
- 按品牌、配送方式（FBA/亚马逊）、包装尺寸重量等条件筛选。
- 需要历史月销量趋势或价格历史的分析。
不适用场景：实时亚马逊搜索结果页模拟（应使用 Amazon Search）、历史搜索词量或排名趋势（应使用 ABA 数据）、商品评论内容或情感分析、广告活动管理或竞价优化、Listing 优化或文案建议、库存或供应链数据。
限制
- 每页最多 100 条结果，最少 50 条。
- 每次查询最多 3 条排序规则。
- 每个品类过滤最多 50 个 ID 或名称。
- keyword 参数最多 50 个关键词。
- 设置 history=1 会显著增加响应体积与 token 成本。
- 所有价格值均以最小货币单位（分、便士等）表示。
- 本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败或空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。
- 算力消耗按动态规则计费：消耗算力 = 0.045 ×（找商品阶段消耗的 Keepa token + 拉取商品详情阶段消耗的 Keepa token）。先找商品，再拉商品详情；若第一段未找到商品，则只计找商品阶段消耗。本技能的服务按倍数动态计算，可能一次性消耗大量算力，必须提醒用户，由用户决定是否继续。
- 认证与算力问题：未配置 API Key（环境变量 LINKFOX_AGENT_API_KEY 或 LINKFOXAGENT_API_KEY）、响应 401 或 402、提示算力或余额不足时，按 references/onboarding.md 引导解决。
展示规则
- 以结构化表格展示结果，关键字段包括 ASIN、标题、价格、BSR、月销量、评分、评论数、品牌。
- 价格从最小货币单位转换为标准格式（如 2599 -> $25.99）。
- 展示 BSR 时提醒用户数值越低代表销售排名越好。
- 包含历史数据时清晰呈现 12 个月销售趋势。
- 告知用户结果总数，必要时建议获取更多页。
- 有图片链接时可提及，但除非用户要求，不要内联渲染。
- 查询失败时说明原因并建议调整筛选条件。